@nanobpm/agentic 0.1.0 → 0.4.0

package/src/protocol/conformance/frames.ts

@@ -101,15 +101,43 @@ export const GOLDEN_FRAMES: readonly GoldenFrame[] = [
     hex: "4e4101010600000065000000187b226f70223a2272656164222c2273696e6365223a31327d",
   },
   {
-    name: "relay-chunk-bulk",
+    name: "relay-produce-bulk",
     direction: "worker->hub",
     frame: {
       lane: "bulk",
       family: "relay",
       seq: 5,
-      payload: { stream: "job-1223", offset: 2048, chunk: "hello world\n" },
+      payload: { op: "produce", stream: "job-1223", incarnation: 1, chunk: "hello world\n" },
     },
-    hex: "4e41010207000000050000003b7b2273747265616d223a226a6f622d31323233222c226f6666736574223a323034382c226368756e6b223a2268656c6c6f20776f726c645c6e227d",
+    hex: "4e41010207000000050000004c7b226f70223a2270726f64756365222c2273747265616d223a226a6f622d31323233222c22696e6361726e6174696f6e223a312c226368756e6b223a2268656c6c6f20776f726c645c6e227d",
+  },
+  {
+    name: "relay-subscribe-control",
+    direction: "worker->hub",
+    frame: {
+      lane: "control",
+      family: "relay",
+      seq: 6,
+      payload: { op: "subscribe", stream: "job-1223", from: 0, credit: 1024 },
+    },
+    hex: "4e41010007000000060000003d7b226f70223a22737562736372696265222c2273747265616d223a226a6f622d31323233222c2266726f6d223a302c22637265646974223a313032347d",
+  },
+  {
+    name: "relay-credit-control",
+    direction: "worker->hub",
+    frame: { lane: "control", family: "relay", seq: 7, payload: { op: "credit", credit: 512 } },
+    hex: "4e41010007000000070000001c7b226f70223a22637265646974222c22637265646974223a3531327d",
+  },
+  {
+    name: "relay-subscribed-ack-control",
+    direction: "hub->worker",
+    frame: {
+      lane: "control",
+      family: "relay",
+      seq: 8,
+      payload: { op: "subscribed", stream: "job-1223", gap: false, nextOffset: 2048 },
+    },
+    hex: "4e4101000700000008000000457b226f70223a2273756273637269626564222c2273747265616d223a226a6f622d31323233222c22676170223a66616c73652c226e6578744f6666736574223a323034387d",
   },
   {
     name: "relay-seq-max-bulk",
@@ -130,7 +158,7 @@ export const GOLDEN_FRAMES: readonly GoldenFrame[] = [
   },
   {
     name: "unicode-payload-relay",
-    direction: "worker->hub",
+    direction: "hub->worker",
     frame: {
       lane: "bulk",
       family: "relay",

package/src/protocol/index.ts

@@ -77,6 +77,10 @@ export {
   type BlackboardPayload,
   type BlackboardOp,
   type RelayPayload,
+  type RelayProducePayload,
+  type RelaySubscribePayload,
+  type RelayCreditPayload,
+  type RelaySubscribedPayload,
   type PayloadError,
   type PayloadValidationResult,
 } from "./payloads.ts";

package/src/protocol/payloads.test.ts

@@ -69,13 +69,43 @@ test("blackboard files must be an array of only strings when present", () => {
   if (!mixed.ok) assert.ok(mixed.errors.some((e) => e.code === "bad-files"));
 });
 
-test("relay requires stream, non-negative integer offset, and string chunk", () => {
+test("relay delivery chunk (no op) requires stream, non-negative integer offset, and string chunk", () => {
   assert.ok(validatePayload("relay", { stream: "s", offset: 0, chunk: "" }).ok);
   assert.ok(!validatePayload("relay", { stream: "s", offset: -1, chunk: "" }).ok);
   assert.ok(!validatePayload("relay", { stream: "s", offset: 1.5, chunk: "" }).ok);
   assert.ok(!validatePayload("relay", { stream: "", offset: 0, chunk: "" }).ok);
 });
 
+test("relay produce control frame requires stream, non-negative integer incarnation, and string chunk", () => {
+  assert.ok(validatePayload("relay", { op: "produce", stream: "s", incarnation: 0, chunk: "hi" }).ok);
+  assert.ok(validatePayload("relay", { op: "produce", stream: "s", incarnation: 1786690000000, chunk: "" }).ok);
+  const badInc = validatePayload("relay", { op: "produce", stream: "s", incarnation: -1, chunk: "" });
+  assert.ok(!badInc.ok);
+  if (!badInc.ok) assert.ok(badInc.errors.some((e) => e.code === "bad-incarnation"));
+  assert.ok(!validatePayload("relay", { op: "produce", stream: "s", incarnation: 1.5, chunk: "" }).ok);
+  // The legacy bug: a produce frame missing `incarnation` (the old { stream, offset, chunk } shape) is rejected.
+  assert.ok(!validatePayload("relay", { op: "produce", stream: "s", offset: 0, chunk: "" }).ok);
+  assert.ok(!validatePayload("relay", { op: "produce", stream: "", incarnation: 0, chunk: "" }).ok);
+});
+
+test("relay subscribe/credit/subscribed control frames validate their fields", () => {
+  assert.ok(validatePayload("relay", { op: "subscribe", stream: "s" }).ok);
+  assert.ok(validatePayload("relay", { op: "subscribe", stream: "s", from: 2, credit: 1024 }).ok);
+  assert.ok(!validatePayload("relay", { op: "subscribe", stream: "s", from: -1 }).ok);
+  assert.ok(!validatePayload("relay", { op: "subscribe", stream: "s", credit: 1.5 }).ok);
+  assert.ok(validatePayload("relay", { op: "credit", credit: 512 }).ok);
+  assert.ok(!validatePayload("relay", { op: "credit", credit: -1 }).ok);
+  assert.ok(validatePayload("relay", { op: "subscribed", stream: "s", gap: false, nextOffset: 8 }).ok);
+  assert.ok(!validatePayload("relay", { op: "subscribed", stream: "s", gap: "no", nextOffset: 8 }).ok);
+  assert.ok(!validatePayload("relay", { op: "subscribed", stream: "s", gap: true, nextOffset: -1 }).ok);
+});
+
+test("relay rejects an unknown op", () => {
+  const bad = validatePayload("relay", { op: "explode", stream: "s" });
+  assert.ok(!bad.ok);
+  if (!bad.ok) assert.ok(bad.errors.some((e) => e.code === "bad-op"));
+});
+
 test("deregister accepts optional string reason and rejects non-string reason", () => {
   assert.ok(validatePayload("deregister", { instance: "w" }).ok);
   assert.ok(validatePayload("deregister", { instance: "w", reason: "shutdown" }).ok);

package/src/protocol/payloads.ts

@@ -53,12 +53,60 @@ export interface BlackboardPayload {
   readonly since?: number;
 }
 
+/**
+ * The `relay` family multiplexes two roles on one message family:
+ *
+ *  - CONTROL frames a peer sends the hub: a producer's {@link RelayProducePayload}
+ *    (`op: "produce"`), and a consumer's {@link RelaySubscribePayload} /
+ *    {@link RelayCreditPayload}.
+ *  - DELIVERY frames the hub sends a consumer: a data chunk ({@link RelayPayload},
+ *    no `op`) and a resume ack ({@link RelaySubscribedPayload}, `op: "subscribed"`).
+ *
+ * {@link RelayPayload} is the DELIVERY data chunk specifically (`{ stream, offset,
+ * chunk }`, no `op`) — the hub assigns the authoritative `offset` from its ring.
+ * A producer must NOT send this shape; it sends {@link RelayProducePayload}.
+ */
 export interface RelayPayload {
   readonly stream: string;
   readonly offset: number;
   readonly chunk: string;
 }
 
+/** A producer appends bytes to a stream. `incarnation` is the producer's
+ * generation, stamped so the hub can fence a stale predecessor (a retried job on
+ * a fresh runner takes over with a strictly higher incarnation). The hub assigns
+ * the offset — a producer never carries one. */
+export interface RelayProducePayload {
+  readonly op: "produce";
+  readonly stream: string;
+  readonly incarnation: number;
+  readonly chunk: string;
+}
+
+/** A consumer subscribes to a stream, optionally resuming from `from` with an
+ * initial `credit` budget. */
+export interface RelaySubscribePayload {
+  readonly op: "subscribe";
+  readonly stream: string;
+  readonly from?: number;
+  readonly credit?: number;
+}
+
+/** A consumer replenishes its flow-control budget. */
+export interface RelayCreditPayload {
+  readonly op: "credit";
+  readonly credit: number;
+}
+
+/** The hub's ack to a subscribe: `gap` is true when `from` predated the retained
+ * ring (bytes were missed), `nextOffset` is where delivery resumes. */
+export interface RelaySubscribedPayload {
+  readonly op: "subscribed";
+  readonly stream: string;
+  readonly gap: boolean;
+  readonly nextOffset: number;
+}
+
 export interface PayloadError {
   readonly code: string;
   readonly message: string;
@@ -76,6 +124,10 @@ function nonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.length > 0;
 }
 
+function nonNegInt(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
 function validateRegister(p: Record<string, unknown>, errors: PayloadError[]): void {
   if (!nonEmptyString(p.instance)) {
     errors.push({ code: "bad-instance", message: "register.instance must be a non-empty string" });
@@ -150,14 +202,65 @@ function validateBlackboard(p: Record<string, unknown>, errors: PayloadError[]):
 }
 
 function validateRelay(p: Record<string, unknown>, errors: PayloadError[]): void {
-  if (!nonEmptyString(p.stream)) {
-    errors.push({ code: "bad-stream", message: "relay.stream must be a non-empty string" });
-  }
-  if (typeof p.offset !== "number" || !Number.isInteger(p.offset) || p.offset < 0) {
-    errors.push({ code: "bad-offset", message: "relay.offset must be a non-negative integer" });
+  const op = p.op;
+  // No `op`: a DELIVERY data chunk (hub -> consumer) — `{ stream, offset, chunk }`.
+  if (op === undefined) {
+    if (!nonEmptyString(p.stream)) {
+      errors.push({ code: "bad-stream", message: "relay.stream must be a non-empty string" });
+    }
+    if (!nonNegInt(p.offset)) {
+      errors.push({ code: "bad-offset", message: "relay.offset must be a non-negative integer" });
+    }
+    if (typeof p.chunk !== "string") {
+      errors.push({ code: "bad-chunk", message: "relay.chunk must be a string" });
+    }
+    return;
   }
-  if (typeof p.chunk !== "string") {
-    errors.push({ code: "bad-chunk", message: "relay.chunk must be a string" });
+  // Otherwise an op-tagged CONTROL/ack frame.
+  switch (op) {
+    case "produce":
+      if (!nonEmptyString(p.stream)) {
+        errors.push({ code: "bad-stream", message: "relay.produce.stream must be a non-empty string" });
+      }
+      if (!nonNegInt(p.incarnation)) {
+        errors.push({ code: "bad-incarnation", message: "relay.produce.incarnation must be a non-negative integer" });
+      }
+      if (typeof p.chunk !== "string") {
+        errors.push({ code: "bad-chunk", message: "relay.produce.chunk must be a string" });
+      }
+      return;
+    case "subscribe":
+      if (!nonEmptyString(p.stream)) {
+        errors.push({ code: "bad-stream", message: "relay.subscribe.stream must be a non-empty string" });
+      }
+      if ("from" in p && !nonNegInt(p.from)) {
+        errors.push({ code: "bad-from", message: "relay.subscribe.from must be a non-negative integer when present" });
+      }
+      if ("credit" in p && !nonNegInt(p.credit)) {
+        errors.push({ code: "bad-credit", message: "relay.subscribe.credit must be a non-negative integer when present" });
+      }
+      return;
+    case "credit":
+      if (!nonNegInt(p.credit)) {
+        errors.push({ code: "bad-credit", message: "relay.credit.credit must be a non-negative integer" });
+      }
+      return;
+    case "subscribed":
+      if (!nonEmptyString(p.stream)) {
+        errors.push({ code: "bad-stream", message: "relay.subscribed.stream must be a non-empty string" });
+      }
+      if (typeof p.gap !== "boolean") {
+        errors.push({ code: "bad-gap", message: "relay.subscribed.gap must be a boolean" });
+      }
+      if (!nonNegInt(p.nextOffset)) {
+        errors.push({ code: "bad-next-offset", message: "relay.subscribed.nextOffset must be a non-negative integer" });
+      }
+      return;
+    default:
+      errors.push({
+        code: "bad-op",
+        message: `relay.op must be one of produce|subscribe|credit|subscribed, got ${String(op)}`,
+      });
   }
 }
 

package/src/session/acp/client.test.ts

@@ -0,0 +1,222 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { ActivationKey } from "../adapter.ts";
+import { openInMemorySession } from "../backend.ts";
+import type { SessionEvent } from "../events.ts";
+import { AcpSessionClient, type SessionEventSink } from "./client.ts";
+import { startFakeAcpAgent } from "./fake-agent.ts";
+import { AcpConnection } from "./jsonrpc.ts";
+import { inMemoryTransportPair } from "./transport.ts";
+
+const KEY: ActivationKey = { processInstanceKey: "pik-1", elementId: "implement-task" };
+const CWD = "/work/repo";
+
+function seqIds(prefix: string): () => string {
+  let n = 0;
+  return () => `${prefix}-${n++}`;
+}
+
+function collector(): { sink: SessionEventSink; events: SessionEvent[] } {
+  const events: SessionEvent[] = [];
+  return { events, sink: { emit: (event) => events.push(event) } };
+}
+
+function connectClient(
+  script: Parameters<typeof startFakeAcpAgent>[1],
+  sink: SessionEventSink,
+): { client: AcpSessionClient; closeAgent: () => void } {
+  const { client: clientTransport, agent: agentTransport } = inMemoryTransportPair();
+  const agent = startFakeAcpAgent(agentTransport, script);
+  const client = new AcpSessionClient(new AcpConnection(clientTransport), sink, { newEventId: seqIds("e") });
+  return { client, closeAgent: () => agent.close() };
+}
+
+function connectClientWithAgent(
+  script: Parameters<typeof startFakeAcpAgent>[1],
+  sink: SessionEventSink,
+): { client: AcpSessionClient; agent: AcpConnection; closeAgent: () => void } {
+  const { client: clientTransport, agent: agentTransport } = inMemoryTransportPair();
+  const agent = startFakeAcpAgent(agentTransport, script);
+  const client = new AcpSessionClient(new AcpConnection(clientTransport), sink, { newEventId: seqIds("e") });
+  return { client, agent, closeAgent: () => agent.close() };
+}
+
+test("initialize surfaces durable-resume:true when the agent advertises loadSession", async () => {
+  const { sink } = collector();
+  const { client } = connectClient({ loadSession: true }, sink);
+  const probe = await client.initialize();
+  assert.equal(probe.loadSession, true);
+  assert.equal(probe.durableResume, true);
+  assert.equal(probe.protocolVersion, 1);
+});
+
+test("initialize surfaces durable-resume:false when the agent lacks loadSession", async () => {
+  const { sink } = collector();
+  const { client } = connectClient({ loadSession: false }, sink);
+  const probe = await client.initialize();
+  assert.equal(probe.loadSession, false);
+  assert.equal(probe.durableResume, false);
+});
+
+test("a driven session normalises the update stream into canonical events on the authoritative log", async () => {
+  const { backend, log } = openInMemorySession(KEY, 1);
+  const { client: clientTransport, agent: agentTransport } = inMemoryTransportPair();
+  startFakeAcpAgent(agentTransport, {
+    loadSession: true,
+    promptUpdates: [
+      { sessionUpdate: "agent_message_chunk", messageId: "m1", content: { type: "text", text: "Hello " } },
+      { sessionUpdate: "agent_message_chunk", messageId: "m1", content: { type: "text", text: "world" } },
+      { sessionUpdate: "tool_call", toolCallId: "t1", title: "grep", status: "pending", rawInput: { q: "foo" } },
+      { sessionUpdate: "tool_call_update", toolCallId: "t1", status: "completed", rawOutput: { hits: 3 } },
+      { sessionUpdate: "agent_message_chunk", messageId: "m2", content: { type: "text", text: "Done" } },
+    ],
+    promptStopReason: "end_turn",
+  });
+  const client = new AcpSessionClient(new AcpConnection(clientTransport), backend, { newEventId: seqIds("e") });
+
+  await client.initialize();
+  await client.newSession({ cwd: CWD });
+  const result = await client.prompt("please search");
+
+  assert.equal(result.stopReason, "end_turn");
+  const logged = log.replay(KEY, 0);
+  assert.deepEqual(
+    logged.map((e) => ({ type: e.type, offset: e.offset })),
+    [
+      { type: "assistant", offset: 0 },
+      { type: "tool-call", offset: 1 },
+      { type: "tool-result", offset: 2 },
+      { type: "assistant", offset: 3 },
+    ],
+    "chunks coalesce into whole messages; the tool lifecycle becomes tool-call + tool-result",
+  );
+
+  const [assistant, toolCall, toolResult, done] = logged;
+  assert.equal(assistant.type === "assistant" && assistant.text, "Hello world");
+  assert.equal(toolCall.type === "tool-call" && toolCall.name, "grep");
+  assert.deepEqual(toolCall.type === "tool-call" ? toolCall.args : null, { q: "foo" });
+  assert.equal(toolResult.type === "tool-result" && toolResult.ok, true);
+  assert.deepEqual(toolResult.type === "tool-result" ? toolResult.result : null, { hits: 3 });
+  assert.equal(done.type === "assistant" && done.text, "Done");
+
+  // The producer owns a single unbroken causal chain across the whole stream.
+  assert.equal(assistant.parentId, null);
+  assert.equal(toolCall.parentId, assistant.id);
+  assert.equal(toolResult.parentId, toolCall.id);
+  assert.equal(done.parentId, toolResult.id);
+});
+
+test("restore replays prior history via session/load, then the agent continues", async () => {
+  const { backend, log } = openInMemorySession(KEY, 1);
+  const { client: clientTransport, agent: agentTransport } = inMemoryTransportPair();
+  startFakeAcpAgent(agentTransport, {
+    loadSession: true,
+    loadUpdates: [
+      { sessionUpdate: "user_message_chunk", content: { type: "text", text: "prior question" } },
+      { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "prior answer" } },
+    ],
+    promptUpdates: [{ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "continued" } }],
+  });
+  const client = new AcpSessionClient(new AcpConnection(clientTransport), backend, { newEventId: seqIds("e") });
+
+  const probe = await client.initialize();
+  assert.equal(probe.durableResume, true);
+
+  const restored = await client.restore("sess-existing", { cwd: CWD });
+  assert.deepEqual(
+    restored.map((e) => e.type),
+    ["user", "assistant"],
+    "session/load replays the prior turn as normalised events",
+  );
+  assert.equal(client.sessionId, "sess-existing");
+
+  await client.prompt("carry on");
+  const logged = log.replay(KEY, 0);
+  assert.deepEqual(logged.map((e) => e.type), ["user", "assistant", "assistant"]);
+  const last = logged[2];
+  assert.equal(last.type === "assistant" && last.text, "continued");
+  // The resumed turn continues the same causal chain as the restored history.
+  assert.equal(last.parentId, logged[1].id);
+});
+
+test("consecutive same-message chunks coalesce; a new messageId starts a new event", async () => {
+  const { sink, events } = collector();
+  const { client: clientTransport, agent: agentTransport } = inMemoryTransportPair();
+  startFakeAcpAgent(agentTransport, {
+    promptUpdates: [
+      { sessionUpdate: "agent_message_chunk", messageId: "a", content: { type: "text", text: "one " } },
+      { sessionUpdate: "agent_message_chunk", messageId: "a", content: { type: "text", text: "two" } },
+      { sessionUpdate: "agent_message_chunk", messageId: "b", content: { type: "text", text: "three" } },
+    ],
+  });
+  const client = new AcpSessionClient(new AcpConnection(clientTransport), sink, { newEventId: seqIds("e") });
+  await client.initialize();
+  await client.newSession({ cwd: CWD });
+  await client.prompt("go");
+
+  assert.deepEqual(
+    events.map((e) => (e.type === "assistant" ? e.text : e.type)),
+    ["one two", "three"],
+  );
+});
+
+test("session/update addressed to a different session id is ignored", async () => {
+  const { sink, events } = collector();
+  const { client, agent } = connectClientWithAgent(
+    {
+      sessionId: "sess-mine",
+      promptUpdates: [{ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "mine" } }],
+      promptStopReason: "end_turn",
+    },
+    sink,
+  );
+  await client.initialize();
+  await client.newSession({ cwd: CWD });
+  // A stray update for a *different* session must not enter this session's stream.
+  agent.notify("session/update", {
+    sessionId: "sess-other",
+    update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text: "leak" } },
+  });
+  await client.prompt("hi");
+
+  assert.deepEqual(
+    events.map((e) => (e.type === "assistant" ? e.text : e.type)),
+    ["mine"],
+    "only the update addressed to sess-mine is ingested; the sess-other leak is dropped",
+  );
+});
+
+test("prompt before a session is established throws", async () => {
+  const { sink } = collector();
+  const { client } = connectClient({}, sink);
+  await client.initialize();
+  await assert.rejects(() => client.prompt("hi"), /active session/);
+});
+
+test("default permission handler selects the allow-flavoured option", async () => {
+  const { sink } = collector();
+  const { client, agent } = connectClientWithAgent({}, sink);
+  await client.initialize();
+  const outcome = await agent.request("session/request_permission", {
+    options: [
+      { optionId: "reject", kind: "reject_once" },
+      { optionId: "ok", kind: "allow_once" },
+    ],
+  });
+  assert.deepEqual(outcome, { outcome: { outcome: "selected", optionId: "ok" } });
+});
+
+test("default permission handler cancels when no allow-flavoured option is offered", async () => {
+  const { sink } = collector();
+  const { client, agent } = connectClientWithAgent({}, sink);
+  await client.initialize();
+  // No option's kind starts with "allow" — the handler must cancel, not select the
+  // first (possibly deny) option by ordering.
+  const outcome = await agent.request("session/request_permission", {
+    options: [
+      { optionId: "reject", kind: "reject_once" },
+      { optionId: "reject-all", kind: "reject_always" },
+    ],
+  });
+  assert.deepEqual(outcome, { outcome: { outcome: "cancelled" } });
+});