@jr2/agent-protocol 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/agent-protocol",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "The jr2 Orchestrator↔Agent wire: defineEvent and nothing else.",
   "license": "MIT",
   "private": false,
@@ -43,6 +43,6 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --test"
+    "test": "node --test --test-global-setup=../../scripts/test-tmpdir.ts"
   }
 }

package/src/define-event.ts

@@ -10,17 +10,21 @@ import { z } from "zod";
 
 /**
  * How delivering the event resolves for the caller (ADR-0006):
- * - `ack`      fire-and-acknowledge; the caller does not wait on a meaningful result.
- * - `deferred` the result is held open until the Machine answers (solicited down-channel).
- * - `poll`     the caller pulls queued down-channel messages (cooperative steer checkpoint).
+ * - `ack`  the pick is delivered and answered. A pick that moves the workflow to work inside the
+ *          Agent's state is answered when that work is done (ADR-0024): the answer is the Machine's,
+ *          never a schema on the pick, so no pick declares an output.
+ * - `poll` the caller pulls queued down-channel messages (cooperative steer checkpoint). Reserved,
+ *          not built (ADR-0013).
  */
-export type EventSemantics = "ack" | "deferred" | "poll";
+export type EventSemantics = "ack" | "poll";
 
 /**
- * Who may deliver the event (ADR-0015). The invoking actor kind is the primary router — an
- * an Agent's menu draws audience ∈ {agent, any}, a `gate` draws {external, any} — so this tag
- * exists to RESTRICT: tag the security-sensitive events (`approve: "external"` guarantees no
- * agent state can ever offer it) and leave the rest at the `"any"` default.
+ * Who may deliver the event, stated BY KIND (ADR-0015): `agent` (an Agent's pick), `external` (a
+ * Gate's caller), `any` (both). Leave it UNSET for the default: each writing of the event — each
+ * `on` key — belongs to the party that its state, or the nearest state above it, invokes (an Agent
+ * slot, a `gate`, or both); with none above, both. Set it only to give a pick to the other party
+ * (`submit: "any"` lets an in-Turn Gate's caller send the Agent's pick) or to hold a root pick back
+ * (`report_blocked: "agent"`; `approve: "external"` guarantees no Agent state can offer it).
  */
 export type EventAudience = "agent" | "external" | "any";
 
@@ -34,9 +38,8 @@ export type EventDef<Name extends string = string, Input extends z.ZodObject = z
   /** Input schema — a flat tagged object, never a `oneOf` (ADR-0006 encoding rule). */
   readonly input: Input;
   readonly semantics: EventSemantics;
-  readonly audience: EventAudience;
-  /** Result schema for `deferred` events (the held tool result the Machine answers with). */
-  readonly output?: z.ZodType;
+  /** Absent: each writing's state decides who may send it (see {@link EventAudience}). */
+  readonly audience?: EventAudience;
 };
 
 /**
@@ -58,6 +61,18 @@ export type EventFrom<D extends EventDef> =
 // `workspace.*`).
 const NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
+/**
+ * The field the Orchestrator writes on every event a party delivers into a Machine: its
+ * {@link Sender} (ADR-0011, ADR-0015). Plain data on the event, so it rides the mailbox, a delayed
+ * event the run host persists, and a restore. Only the Orchestrator writes it: no def may declare
+ * it, and a caller that posts it is refused. The Machine's own events (`raise`, `sendTo` itself, a
+ * child's `sendParent`) carry none.
+ */
+export const SENDER_KEY = "sender";
+
+/** Who delivered an event: an Agent by its slot, or a Gate by its invoke id (ADR-0015). */
+export type Sender = { readonly party: "agent" | "gate"; readonly id: string };
+
 /** Define one control event. Pure — returns a frozen def; registration happens nowhere. */
 export function defineEvent<const Name extends string, Input extends z.ZodObject>(def: {
   name: Name;
@@ -65,9 +80,8 @@ export function defineEvent<const Name extends string, Input extends z.ZodObject
   input: Input;
   /** Default: `ack`. */
   semantics?: EventSemantics;
-  /** Default: `any` — restrict only the security-sensitive events (ADR-0015). */
+  /** Default: unset — each writing's state decides (see {@link EventAudience}). */
   audience?: EventAudience;
-  output?: z.ZodType;
 }): EventDef<Name, Input> {
   if (!NAME_RE.test(def.name)) {
     throw new Error(
@@ -75,12 +89,22 @@ export function defineEvent<const Name extends string, Input extends z.ZodObject
         `(it becomes an MCP tool name and an xstate event type)`,
     );
   }
-  if (def.semantics === "deferred" && !def.output) {
+  if (SENDER_KEY in def.input.shape) {
+    throw new Error(
+      `defineEvent: "${def.name}" declares \`${SENDER_KEY}\` in its input — the Orchestrator writes that field ` +
+        `on every delivered event (who sent it); name the payload field something else`,
+    );
+  }
+  // Retired (ADR-0006): a pick's answer is the Machine's — the last reply since the pick, or what an
+  // `answer` action sets (ADR-0024) — so a schema on the pick would promise a shape nothing keeps.
+  const loose = def as { semantics?: unknown; output?: unknown };
+  if (loose.semantics === "deferred" || loose.output !== undefined) {
     throw new Error(
-      `defineEvent: "${def.name}" is deferred but has no output schema — a deferred event's result IS its output`,
+      `defineEvent: "${def.name}" declares ${loose.output !== undefined ? "an `output`" : "`deferred`"}, which is retired — ` +
+        `every pick is answered when the work it started is done, and the answer is the Machine's, not the def's`,
     );
   }
-  return Object.freeze({ semantics: "ack" as const, audience: "any" as const, ...def });
+  return Object.freeze({ semantics: "ack" as const, ...def });
 }
 
 /** Duck-type guard for manifest validation (defs are plain data, not branded). */
@@ -102,13 +126,11 @@ export function isEventDef(value: unknown): value is EventDef {
  * Workflow: a nested Machine is reached by `import` and never carries the name `jr2 run` addresses
  * (ADR-0049), so naming it a workflow here would misreport where the bad def lives.
  *
- * `deferred` and `poll` are RESERVED, not implemented (ADR-0013): the wire leaves room for them —
- * a surface listing ships each def's `semantics`, a delivery returns an addressable receipt — but
- * nothing answers a held call today, and how a Machine should is deliberately undesigned (there is
- * no consumer to design it against, and flue's 60s MCP timeout means the answer will be
- * poll-with-progress rather than a held socket). Registering one therefore FAILS here. Quietly
- * downgrading it to `ack` would be worse than useless: the Agent would be handed a tool whose
- * contract — "this call returns the Machine's answer" — is a lie.
+ * `poll` is RESERVED, not implemented (ADR-0013): the wire leaves room for it — a surface listing
+ * ships each def's `semantics` — but nothing drains a steer inbox today. Registering one therefore
+ * FAILS here. Quietly downgrading it to `ack` would hand the Agent a tool whose contract is a lie.
+ * (A pick whose answer waits on the Machine's work needs no semantics of its own: every `ack` pick
+ * is answered at Rest, ADR-0024.)
  */
 export function eventMap(machine: string, events: readonly unknown[]): Map<string, EventDef> {
   const map = new Map<string, EventDef>();
@@ -120,8 +142,8 @@ export function eventMap(machine: string, events: readonly unknown[]): Map<strin
     if (def.semantics !== "ack") {
       throw new Error(
         `machine "${machine}": event "${def.name}" is \`${def.semantics}\`, which is reserved but ` +
-          `NOT IMPLEMENTED (ADR-0013). Only \`ack\` events can be delivered today; there is nothing to ` +
-          `answer a held call with, and degrading it to \`ack\` would hand the Agent a lying tool contract.`,
+          `NOT IMPLEMENTED (ADR-0013). Only \`ack\` events can be delivered today; nothing drains a ` +
+          `steer inbox, and degrading it to \`ack\` would hand the Agent a lying tool contract.`,
       );
     }
     map.set(def.name, def);

package/src/examples.ts

@@ -3,9 +3,9 @@
 // a workflow's own `jr2Setup({ events })` list (ADR-0015). ADR-0006's "standard library" framing
 // is retired: nothing in jr2 consumes these by name.
 //
-// All `ack` — outcomes an Agent reports and moves on from. The other two semantics (`deferred`,
-// `poll`) are reserved and NOT implemented (ADR-0013), so machine-build refuses one; an example
-// that could not be used in a workflow would be a trap, not a starting point.
+// All `ack`, as every pick is. The other semantics (`poll`) is reserved and NOT implemented
+// (ADR-0013), so machine-build refuses it; an example that could not be used in a workflow would
+// be a trap, not a starting point.
 
 import { z } from "zod";
 import { defineEvent } from "./define-event.ts";