Add canonical examples and recipes

Add missing canonical Java examples, port the recipe modules, wire Spotless into CI, and move the provisioned credential integration test to the client test module.

Closes #9

Closes #10

Closes #12

Closes #13

Author: nficano

.github/workflows/ci.yml

@@ -52,10 +52,13 @@ jobs:
       - name: Validate Gradle wrapper
         uses: gradle/actions/wrapper-validation@v4
 
+      - name: Check formatting (Spotless)
+        run: ./gradlew spotlessCheck --no-daemon
+
       - name: Build
         run: ./gradlew build --no-daemon --stacktrace
 
-      - name: Run all 10 examples
+      - name: Run all runnable examples and recipes
         run: |
           ./gradlew --no-daemon --stacktrace \
             :examples:submit-and-stream:run \
@@ -67,7 +70,23 @@ jobs:
             :examples:list-jobs:run \
             :examples:lease-expires-at:run \
             :examples:idempotent-retry:run \
-            :examples:custom-auth:run
+            :examples:custom-auth:run \
+            :examples:provisioned-credentials:run \
+            :examples:ack-backpressure:run \
+            :examples:delegate:run \
+            :examples:spring-boot:run \
+            :examples:jakarta:run \
+            :examples:lease-violation:run \
+            :examples:progress:run \
+            :examples:resume:run \
+            :examples:stdio:run \
+            :examples:subscribe:run \
+            :examples:tracing:run \
+            :examples:vendor-extensions:run \
+            :recipes:email-vendor-leases:run \
+            :recipes:mcp-skill:run \
+            :recipes:multi-agent-budget:run \
+            :recipes:stream-resume:run
 
       - name: Upload test reports
         if: always()

arcp-client/src/main/java/dev/arcp/client/ArcpClient.java

@@ -94,6 +94,8 @@ public final class ArcpClient implements AutoCloseable, Flow.Subscriber<Envelope
     private volatile @Nullable SessionId sessionId;
     private volatile @Nullable Session session;
     private volatile boolean closed;
+    private final @Nullable String resumeToken;
+    private final @Nullable Long lastEventSeq;
 
     private ArcpClient(Builder b) {
         this.transport = Objects.requireNonNull(b.transport, "transport");
@@ -106,6 +108,8 @@ private ArcpClient(Builder b) {
         this.scheduler = b.scheduler != null ? b.scheduler
                 : Executors.newScheduledThreadPool(1, r -> Thread.ofPlatform()
                         .name("arcp-client-scheduler", 0).daemon(true).unstarted(r));
+        this.resumeToken = b.resumeToken;
+        this.lastEventSeq = b.lastEventSeq;
     }
 
     public static Builder builder(Transport transport) {
@@ -116,7 +120,7 @@ public static Builder builder(Transport transport) {
     public CompletableFuture<Session> connect() {
         transport.incoming().subscribe(this);
         SessionHello hello = new SessionHello(
-                info, auth, Capabilities.of(requestedFeatures), null, null);
+                info, auth, Capabilities.of(requestedFeatures), resumeToken, lastEventSeq);
         send(Message.Type.SESSION_HELLO, hello, null, null, null, null);
         return sessionFuture;
     }
@@ -204,6 +208,20 @@ public void close() {
         scheduler.shutdownNow();
     }
 
+    /** Returns the highest event sequence number seen from the server, or -1 if none. */
+    public long lastSeenSeq() {
+        return lastSeenSeq.get();
+    }
+
+    /** Returns the active session after {@link #connect()} completes. */
+    public Session session() {
+        Session current = session;
+        if (current == null) {
+            throw new IllegalStateException("client is not connected");
+        }
+        return current;
+    }
+
     @Override
     public void onSubscribe(Flow.Subscription s) {
         this.subscription = s;
@@ -481,6 +499,8 @@ public static final class Builder {
         private boolean autoAck = true;
         private Duration ackInterval = Duration.ofMillis(200);
         private @Nullable ScheduledExecutorService scheduler;
+        private @Nullable String resumeToken;
+        private @Nullable Long lastEventSeq;
 
         Builder(Transport transport) {
             this.transport = transport;
@@ -526,6 +546,21 @@ public Builder scheduler(ScheduledExecutorService s) {
             return this;
         }
 
+        /** Resume a prior session by supplying the token received in {@link Session#resumeToken()}. */
+        public Builder resumeToken(String token) {
+            this.resumeToken = token;
+            return this;
+        }
+
+        /**
+         * Resume from a known event sequence number (§6.3). Used together with
+         * {@link #resumeToken(String)} to re-subscribe to events the client may have missed.
+         */
+        public Builder lastEventSeq(long seq) {
+            this.lastEventSeq = seq;
+            return this;
+        }
+
         public ArcpClient build() {
             return new ArcpClient(this);
         }

…edentialProvisioningIntegrationTest.java …edentialProvisioningIntegrationTest.javaarcp-runtime/src/test/java/dev/arcp/runtime/credentials/CredentialProvisioningIntegrationTest.java renamed to arcp-client/src/test/java/dev/arcp/client/credentials/CredentialProvisioningIntegrationTest.java arcp-runtime/src/test/java/dev/arcp/runtime/credentials/CredentialProvisioningIntegrationTest.java renamed to arcp-client/src/test/java/dev/arcp/client/credentials/CredentialProvisioningIntegrationTest.java

@@ -1,4 +1,4 @@
-package dev.arcp.runtime.credentials;
+package dev.arcp.client.credentials;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -20,6 +20,9 @@
 import dev.arcp.core.transport.MemoryTransport;
 import dev.arcp.runtime.ArcpRuntime;
 import dev.arcp.runtime.agent.JobOutcome;
+import dev.arcp.runtime.credentials.CredentialProvisioner;
+import dev.arcp.runtime.credentials.InMemoryCredentialRevocationStore;
+import dev.arcp.runtime.credentials.IssuedCredential;
 import java.time.Duration;
 import java.time.Instant;
 import java.util.EnumSet;

build.gradle.kts

@@ -1,3 +1,7 @@
+plugins {
+    id("com.diffplug.spotless") version "6.25.0" apply false
+}
+
 allprojects {
     group = "dev.arcp"
     version = "1.0.0-SNAPSHOT"
@@ -38,6 +42,13 @@ subprojects {
                 charSet = "UTF-8"
             }
         }
+        apply(plugin = "com.diffplug.spotless")
+        configure<com.diffplug.gradle.spotless.SpotlessExtension> {
+            java {
+                googleJavaFormat()
+                removeUnusedImports()
+            }
+        }
     }
 
     // Shared publishing metadata. Per-subproject build files still own the

examples/ack-backpressure/build.gradle.kts

@@ -0,0 +1,18 @@
+plugins { application }
+
+application {
+    mainClass.set("dev.arcp.examples.ackbackpressure.Main")
+    applicationDefaultJvmArgs = listOf("-ea")
+}
+
+java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }
+
+tasks.withType<JavaCompile>().configureEach {
+    options.release.set(21)
+    options.encoding = "UTF-8"
+}
+
+dependencies {
+    implementation(project(":arcp"))
+    runtimeOnly(libs.slf4j.simple)
+}

examples/ack-backpressure/src/main/java/dev/arcp/examples/ackbackpressure/Main.java

@@ -0,0 +1,77 @@
+package dev.arcp.examples.ackbackpressure;
+
+import com.fasterxml.jackson.databind.node.JsonNodeFactory;
+import dev.arcp.client.ArcpClient;
+import dev.arcp.client.JobHandle;
+import dev.arcp.core.capabilities.Feature;
+import dev.arcp.core.events.EventBody;
+import dev.arcp.core.events.StatusEvent;
+import dev.arcp.core.transport.MemoryTransport;
+import dev.arcp.runtime.ArcpRuntime;
+import dev.arcp.runtime.agent.JobOutcome;
+import java.time.Duration;
+import java.util.EnumSet;
+import java.util.concurrent.Flow;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+/**
+ * Demonstrates manual ack/back-pressure: client opts out of auto-ack,
+ * counts events itself, then sends a single explicit ack at the end.
+ */
+public final class Main {
+    public static void main(String[] args) throws Exception {
+        MemoryTransport[] pair = MemoryTransport.pair();
+        ArcpRuntime runtime = ArcpRuntime.builder()
+                .agent("ticker", "1.0.0", (input, ctx) -> {
+                    for (int i = 1; i <= 20; i++) {
+                        ctx.emit(new StatusEvent("tick-" + i, null));
+                    }
+                    return JobOutcome.Success.inline(input.payload());
+                })
+                .build();
+        runtime.accept(pair[0]);
+
+        AtomicInteger received = new AtomicInteger();
+
+        try (ArcpClient client = ArcpClient.builder(pair[1])
+                .autoAck(false)
+                .features(EnumSet.allOf(Feature.class))
+                .build()) {
+            client.connect(Duration.ofSeconds(5));
+
+            JobHandle handle = client.submit(
+                    ArcpClient.jobSubmit("ticker@1.0.0", JsonNodeFactory.instance.objectNode()));
+
+            handle.events().subscribe(new Flow.Subscriber<>() {
+                @Override
+                public void onSubscribe(Flow.Subscription s) {
+                    s.request(Long.MAX_VALUE);
+                }
+
+                @Override
+                public void onNext(EventBody body) {
+                    received.incrementAndGet();
+                }
+
+                @Override
+                public void onError(Throwable throwable) {}
+
+                @Override
+                public void onComplete() {}
+            });
+
+            handle.result().get(5, TimeUnit.SECONDS);
+
+            // Allow event delivery to finish.
+            Thread.sleep(200);
+
+            assert received.get() == 20 : "expected 20 events, got " + received.get();
+
+            // Explicit ack after processing all events.
+            client.ack(client.lastSeenSeq());
+            System.out.println("OK ack-backpressure");
+        }
+        runtime.close();
+    }
+}

examples/bun/README.md

@@ -0,0 +1,7 @@
+# Bun
+
+Bun is not a Java runtime target. The Java SDK covers the same transport and
+protocol behavior through the `stdio`, `jakarta`, and `spring-boot` examples.
+
+This directory exists to document the TypeScript SDK's Bun example as not
+applicable for the Java SDK.

examples/delegate/build.gradle.kts

@@ -0,0 +1,18 @@
+plugins { application }
+
+application {
+    mainClass.set("dev.arcp.examples.delegate.Main")
+    applicationDefaultJvmArgs = listOf("-ea")
+}
+
+java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }
+
+tasks.withType<JavaCompile>().configureEach {
+    options.release.set(21)
+    options.encoding = "UTF-8"
+}
+
+dependencies {
+    implementation(project(":arcp"))
+    runtimeOnly(libs.slf4j.simple)
+}

examples/delegate/src/main/java/dev/arcp/examples/delegate/Main.java

@@ -0,0 +1,90 @@
+package dev.arcp.examples.delegate;
+
+import com.fasterxml.jackson.databind.node.JsonNodeFactory;
+import dev.arcp.client.ArcpClient;
+import dev.arcp.client.JobHandle;
+import dev.arcp.core.events.DelegateEvent;
+import dev.arcp.core.events.EventBody;
+import dev.arcp.core.ids.JobId;
+import dev.arcp.core.transport.MemoryTransport;
+import dev.arcp.runtime.ArcpRuntime;
+import dev.arcp.runtime.agent.JobOutcome;
+import java.time.Duration;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Flow;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Demonstrates manual delegation: the parent agent emits a DelegateEvent; the client detects it
+ * and spawns the child job explicitly (the Java runtime does not auto-spawn children).
+ */
+public final class Main {
+    public static void main(String[] args) throws Exception {
+        MemoryTransport[] pair = MemoryTransport.pair();
+        ArcpRuntime runtime =
+                ArcpRuntime.builder()
+                        .agent(
+                                "parent",
+                                "1.0.0",
+                                (input, ctx) -> {
+                                    ctx.emit(new DelegateEvent(JobId.generate(), "child@1.0.0"));
+                                    return JobOutcome.Success.inline(input.payload());
+                                })
+                        .agent(
+                                "child",
+                                "1.0.0",
+                                (input, ctx) -> JobOutcome.Success.inline(input.payload()))
+                        .build();
+        runtime.accept(pair[0]);
+
+        try (ArcpClient client = ArcpClient.builder(pair[1]).build()) {
+            client.connect(Duration.ofSeconds(5));
+
+            CompletableFuture<JobHandle> childFuture = new CompletableFuture<>();
+
+            JobHandle parentHandle =
+                    client.submit(
+                            ArcpClient.jobSubmit(
+                                    "parent@1.0.0", JsonNodeFactory.instance.objectNode()));
+
+            parentHandle
+                    .events()
+                    .subscribe(
+                            new Flow.Subscriber<>() {
+                                @Override
+                                public void onSubscribe(Flow.Subscription s) {
+                                    s.request(Long.MAX_VALUE);
+                                }
+
+                                @Override
+                                public void onNext(EventBody body) {
+                                    if (body instanceof DelegateEvent) {
+                                        try {
+                                            childFuture.complete(
+                                                    client.submit(
+                                                            ArcpClient.jobSubmit(
+                                                                    "child@1.0.0",
+                                                                    JsonNodeFactory.instance
+                                                                            .objectNode())));
+                                        } catch (Exception e) {
+                                            childFuture.completeExceptionally(e);
+                                        }
+                                    }
+                                }
+
+                                @Override
+                                public void onError(Throwable t) {
+                                    childFuture.completeExceptionally(t);
+                                }
+
+                                @Override
+                                public void onComplete() {}
+                            });
+
+            parentHandle.result().get(5, TimeUnit.SECONDS);
+            childFuture.get(5, TimeUnit.SECONDS).result().get(5, TimeUnit.SECONDS);
+            System.out.println("OK delegate");
+        }
+        runtime.close();
+    }
+}

examples/jakarta/build.gradle.kts

@@ -0,0 +1,22 @@
+plugins { application }
+
+application {
+    mainClass.set("dev.arcp.examples.jakarta.Main")
+    applicationDefaultJvmArgs = listOf("-ea")
+}
+
+java { toolchain { languageVersion.set(JavaLanguageVersion.of(21)) } }
+
+tasks.withType<JavaCompile>().configureEach {
+    options.release.set(21)
+    options.encoding = "UTF-8"
+}
+
+dependencies {
+    implementation(project(":arcp-middleware-jakarta"))
+    implementation(project(":arcp-client"))
+    implementation(libs.jetty.server)
+    implementation(libs.jetty.ee10.servlet)
+    implementation(libs.jetty.ee10.websocket.jakarta.server)
+    runtimeOnly(libs.slf4j.simple)
+}