AgentSpaces for Groovy

This part builds a working Groovy agent in one script, runs two copies of it, and adds a second verb. A few words first, because the rest of the guide uses them:

• A peer is one running process in the fleet. Each Groovy script you start is a peer.
• A group is the set of peers that share data. Peers join a group by its founding text and a seed address.
• A space is a named, replicated collection inside a group. Every peer in the group sees the same space.
• An entry is one record in a space. In Groovy an entry is a record.
• A lease is how long an entry or a claim lives. When it lapses, the fabric drops it or gives it back.
• A take removes one entry from a space under a lease, so only one worker gets it.
• An agent is an object whose methods react to entries. Its return value becomes the next entry.
• A capability is a fleet service built on spaces, such as voting or aggregation.

You need Groovy 6.0.0 on JDK 21 or newer. The library is ai.badmonkey.agentspaces:agentspaces-groovy:0.5.0 on Maven Central. A script fetches it at run time with @Grab, so it needs no build file. SDKMAN installs Groovy 6 beside any older line you have:

The groovy launcher checks GROOVY_HOME against its own location. If SDKMAN's current Groovy is 5.x, point GROOVY_HOME at 6.0.0 and run that binary, or the script fails before it starts.

For a Maven or Gradle project, depend on ai.badmonkey.agentspaces:agentspaces-groovy:0.5.0 and org.apache.groovy:groovy:6.0.0. The artifacts are Java 21 bytecode.

The fleet { } block starts a peer. Its keywords are the same as the Spring Boot starter's YAML properties. This block listens on a port, founds or joins the group shop, and opens the space orders:

• The first peer has no seed, so it founds the group from the text shop-v1.
• A later peer names any running peer as its seed and joins the same group, because it uses the same founding text.
• The default mtls security profile secures every link, so the block has no security entry.

Declare entries as Groovy records. Groovy records are Java records, so a Java peer names and builds the same type. Put them under a package: the package gives them stable wire names, here shop.Order#v1 and shop.Shipment#v1.

<< writes an entry under the space's default lease. read(Type, timeout: ...) waits for a matching entry and returns an Optional. The Space API takes named arguments such as where:, lease:, and tags:; the Space API chapter lists every verb.

In Groovy an agent is one closure per verb. agent(name) { } describes it, bind hands it to the Java binder, and serve() keeps the peer running until Ctrl-C. Here is the whole peer in one file:

• @BaseScript FleetScript makes the file a peer. It adds fleet, agent, bind, space, and serve to the script.
• The take clause names the cue type, the space, a 30 second lease, and the return type.
• The closure's return value is written back to the space as the next entry.

Save the file as fulfiller.groovy and start two copies. The first founds the group on port 7701. The second takes port 7702, the first as its seed, and an item to order:

The first run downloads the library through Grape, which can take a minute. The second instance prints the shipment:

Either instance can take the order, because both run the same agent. To see a crash recovered, add println "shipping ${order.orderId()}" and Thread.sleep(10000) at the top of the closure, start both, and run kill -9 on whichever prints shipping. The survivor finishes the order after the 30 second lease lapses. You wrote no retry code.

A take consumes its cue. A notify clause sees every matching entry and leaves it in the space. One agent can hold both, each with its own where: filter. Outside a script, import agent from Agents:

• The take handles tasks of priority 1 and consumes them.
• The notify handles tasks of priority 2. It returns a list, so it writes two entries, and Tagged.of attaches the tag kind=fork to one of them.
• produces: declares the types the clause writes. The agent's card, the description other peers read, lists them.

The other clauses follow the same shape: bid, ballot, onDecision, orderedTake, onEstimate, propose, join, and reduce. The vote example uses ballot.

• The Key features part covers the two DSLs, the class form, await, and the hosts.
• The developer guide's Groovy section summarizes this guide for Java readers, and its appendix explains how the DSLs reach the Java binder.
• Each verb's rules are in the developer guide: take, notify, bid, and ballot.

A script whose base class is FleetScript is a whole peer. Grape resolves the @Grab line, so the file runs with groovy file.groovy and no build. The base class gives the script these calls:

• fleet { } starts the peer, once per script. It also takes a YAML path, YAML text, or a map. With no argument it reads --yaml <path>, then the AGENTSPACES_CONFIG variable, then agentspaces.yaml.
• agent(name) { } builds an agent and bind binds it. bind also takes any object with the Java annotations.
• space(name) and content() return the joined group's space and content swarm.
• serve() blocks until SIGINT or stop().

When the script body ends, FleetScript unbinds the agents and closes the peer. An in-flight take then lapses at its lease, which is how the fleet recovers a crashed worker. Use @Grab for development, and pin the version. For production, ship a built jar or a Maven or Gradle project, because a script runs whatever a repository serves.

Every fleet DSL keyword is a starter property under agentspaces.* in camel case. A block is a nested object, and a repeated keyword appends to a list. There are two aliases and no other sugar:

• A millisecond property takes a duration string under its short name: tick '250ms' sets tick-millis.
• The singular of a list property adds one element: group('research') { } and space 'tasks'.

The DSL emits the same tree as the YAML. This block and this YAML give equal trees in the project's tests:

An unknown keyword fails and names the level, the nearest keywords, and the known ones. Fleet.start { } starts a peer from the DSL outside a script, and Fleet.start(Path), Fleet.start(String), and Fleet.start(Map) take the other forms. The starter properties are the full keyword list.

You can write an agent in two ways, and both publish the same card.

• The agent DSL: agent(name) { } with one clause per verb, as in the first agent. Each clause names the cue type, the verb's attributes as named arguments, and a closure body. Use it for scripts, tests, and agents assembled at run time.
• The class form: a Groovy class carrying the Java annotations, dynamic or @CompileStatic. Use it for anything that ships in a jar or runs under a host.

This class is example 21's planner. Every Finding written to tasks by another worker becomes a Plan:

Closures become agents only through an annotated method. A map of closures coerced to an annotated interface binds, because the binder reads annotations through interfaces, and the agent DSL is built on exactly that. A class whose only members are closure properties binds nothing.

Traits and @Delegate to an annotated interface bind as well.

FleetChecker is a type-checking extension for @CompileStatic and @TypeChecked code. Turn it on with @CompileStatic(extensions = 'ai.badmonkey.agentspaces.groovy.FleetChecker'), as the planner above does. It turns mistakes the binder would refuse at bind time into compile errors, in the binder's own words:

The checker also lets the fleet DSL compile statically, because its keywords resolve at run time. The checker's tests hold one row per refusal.

Every blocking verb and client wait has an Async twin that returns a CompletableFuture on a virtual thread. Groovy 6's await takes it unchanged, and await(a, b) waits for several at once:

Inside a bound clause, AsyncScope.withScope fans out and awaits the children. If one child fails, the scope cancels the other, the body throws, and the take's lease lapses:

A cancelled twin's blocking call still runs to its own timeout, so keep fan-out timeouts short.

The second artifact, agentspaces-groovy-concurrent, builds on Groovy 6's groovy.concurrent toolkit, which Groovy marks incubating. It adds a channel fed by one space subscription for for await, a broadcast to several subscribers, Selects.firstOf over channels, and dataflow variables such as votes.decisionVar(id). Closing a channel unsubscribes, and a channel closes itself when its lease would lapse unless you renew it.

The Groovy library reimplements nothing. It adds Groovy idioms over the Java runtime and binder, so a Groovy peer has every verb, capability, security profile, and transport a Java peer has. A bid, for example, is the Java @BidFunction on a Groovy class. The bids space uses the AUCTION strategy (strategy 'AUCTION' in its space block), so the take claims an entry only after the bid function priced it:

Transports and security come from the same keywords as the starter, such as transport { tls { } } and security { profile 'mtls' }. See Security and Peering for the choices.

A peer started by Fleet.start or fleet { } has no Spring context, so a few starter features need another route:

• The fleet console and the A2A gateway: console { enabled } and a2a { enabled } fail and name the starter. Run the agents under the Spring Boot host to serve them.
• The ordered log: capabilities { orderedLog() } is refused, because the ordered log runs over a fixed member set. Wire it by hand with OrderedTakes.over(...) and group.ordered(name, ordered).
• BeaconLocator beans and PeerNodeCustomizers: the runtime joins with each group's seeds, multicast when enabled, and the default bootstrap chain.

A Groovy class with the annotations is an ordinary bean to both hosts. The Spring Boot starter enrolls it with @SpaceAgent from ai.badmonkey.agentspaces.spring, dynamic or @CompileStatic, and the Groovy extension methods work on the injected spaces:

The Micronaut library enrolls a @Singleton with @SpaceAgent from ai.badmonkey.agentspaces.micronaut. Add micronaut-inject-groovy so Micronaut processes the Groovy beans:

Both hosts configure the peer from their own agentspaces.* properties. The hosts directory holds both apps and their tests. mvn -B -ntp verify -Phosts builds them; the Micronaut host needs JDK 25. The Spring Boot and Micronaut chapters cover each host.

These are the problems a newcomer hits first:

• GROOVY_HOME. The launcher refuses to start when GROOVY_HOME names another Groovy line. Point it at 6.0.0 as in Install.
• Grape reads your local Maven repository first. A stale or half-built 0.5.0 jar in ~/.m2/repository takes precedence over Maven Central. Rebuild it with mvn install, or delete it.
• **Pin the @Grab version**, and keep every ai.badmonkey.agentspaces artifact in one script at the same version.
• **example-02-research-fleet is not on Maven Central.** Install it from a core checkout (mvn -q install -DskipTests), or declare your own records in the script.
• **Records belong under a package** so their wire names are stable and other peers can match them.
• **await is a keyword** in Groovy 6 and binds looser than member access. Write (await x).size(), or assign first. Never name a helper method await.
• **all() returns an unmodifiable list.** Use toSorted, and never sort it in place.
• A filter closure runs locally. read(Task) { priority > 2 } filters on this replica after the template matched. take accepts where: and tags: only.
• **dev-local** signs frames over plain loopback TCP. Use it on a laptop, never on a shared network; production fleets use mtls.

Example 21 puts Groovy peers on example 02's research fleet, whose Java peers write ResearchTask entries and collect Finding entries. The script worker below takes tasks; the planner turns each finding into a plan. Example 02's peers speak plain TCP, so the script uses the dev-local profile: use it on a laptop, never on a shared network.

The founding text matches example 02's, so both derive the same group. To run it by hand, install the core from a checkout (mvn -q install -DskipTests), start example 02's coordinator there, and start the worker from examples/groovy-fleet:

The coordinator writes six tasks and prints each finding with the worker that produced it. The fleet test runs the Java coordinator, this worker, the planner, and a Java caller that invokes the script's card in one build: mvn -B -ntp verify -Pexamples from the project root. The source is in examples/groovy-fleet.

The intake script turns CSV rows into tasks, collects the findings over a channel with for await, and writes a Markdown report. It uses groovy-csv and groovy-markdown, two modules Groovy 6.0 marks incubating, and the concurrent bridge.

• The script opens the channel before it writes, so it misses no finding.
• space('tasks') is the FleetScript call for the joined group's space.
• The loop ends when every topic has a finding, then closes the channel, which unsubscribes.

With the coordinator and the worker from the previous example running, start the intake on its own port from examples/groovy-fleet, where topics.csv lives:

The full script is intake.groovy.

Two peers each bind a reviewer whose ballot clause judges every proposal under the ship: prefix. The proposer asks for the decision first, as a future, proposes with a quorum of two, and awaits the result. Voting is a capability: VoteClient proposes and tallies over the group's votes space.

• Fleet.start { } starts each peer in the same JVM on a free loopback port. freePort() is a test helper.
• The second peer seeds from the first, so both join it-fleet.
• The tally shows one ballot from each peer.

The same test class also runs the take-and-reply flow and the crashed-worker recovery. It needs no network and no model key:

The source is ReadmeExamplesTest.groovy. The Clojure guide shows the other JVM language over the same binder.