@loomwork/plugin-a2a 0.0.0-stage → 0.1.0

package/dist/AgentExecutor.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoomAgentExecutor = void 0;
+exports.hasActor = hasActor;
+exports.principalNamespace = principalNamespace;
+exports.executionStatusToA2A = executionStatusToA2A;
+exports.toTaskResult = toTaskResult;
+const node_crypto_1 = require("node:crypto");
+/** R12 — does this principal carry the minimum identity a per-caller namespace needs? */
+function hasActor(principal) {
+    return typeof principal.actor === "string" && principal.actor.trim().length > 0;
+}
+/**
+ * R12 — a stable, opaque key for a principal; the namespace its tasks live in. Two callers with
+ * different identity can never address each other's execution ids, because the id the runtime
+ * sees embeds this key. Tenant + actor + onBehalfOf are the identity; a delegation token is not
+ * (it is a credential, and rotating it must not orphan the caller's tasks).
+ */
+function principalNamespace(principal) {
+    if (principal === undefined)
+        return "anonymous";
+    // Fail closed: `PrincipalChain` makes every field optional and allows extras, so a principal
+    // identifying callers by another field (`{ sub }`) would hash to ONE shared namespace and hand
+    // every such caller each other's tasks. An actor is the minimum identity.
+    if (!hasActor(principal)) {
+        throw new Error("principalNamespace: the principal has no non-empty string `actor` — it cannot be given a per-caller task namespace");
+    }
+    const identity = JSON.stringify([
+        principal.tenant ?? null,
+        principal.actor ?? null,
+        principal.onBehalfOf ?? null,
+    ]);
+    return (0, node_crypto_1.createHash)("sha256").update(identity).digest("hex").slice(0, 24);
+}
+function scopedId(call, clientId, namespaceOf) {
+    const ns = call.principal !== undefined ? namespaceOf(call.principal) : (call.namespace ?? "anonymous");
+    return `a2a.${ns}.${clientId}`;
+}
+/** Strip the `a2a.<namespace>.` prefix back off an execution id. */
+function clientIdOf(executionId) {
+    const m = /^a2a\.[^.]*\.(.*)$/s.exec(executionId);
+    return m?.[1] ?? executionId;
+}
+/** Map a Loom execution status onto an A2A task status. */
+function executionStatusToA2A(status) {
+    switch (status) {
+        case "completed":
+            return "completed";
+        case "failed":
+            return "failed";
+        case "running":
+        case "suspended":
+            return "working";
+        default:
+            return "submitted";
+    }
+}
+/** Fold a terminal/interim ExecutionState into the A2A task result shape. */
+function toTaskResult(taskId, state) {
+    const a2aStatus = executionStatusToA2A(state.status);
+    const result = { id: taskId, status: a2aStatus };
+    if (a2aStatus === "completed") {
+        const output = state.variables._output;
+        result.artifacts = [
+            {
+                parts: [
+                    { type: "text", text: typeof output === "string" ? output : JSON.stringify(output) },
+                ],
+            },
+        ];
+    }
+    else if (a2aStatus === "failed") {
+        result.error = String(state.variables._error ?? "unknown error");
+    }
+    return result;
+}
+/**
+ * The single adapter: drives one Loom flow as an A2A agent. It is STATELESS —
+ * `get` rebuilds status from the durable log via `runtime.loadState` rather than
+ * holding a live handle, so the server can be horizontally scaled or restarted
+ * without losing in-flight tasks (the same statelessness the remote-worker model
+ * relies on).
+ */
+class LoomAgentExecutor {
+    runtime;
+    flow;
+    options;
+    constructor(runtime, flow, options = {}) {
+        this.runtime = runtime;
+        this.flow = flow;
+        this.options = options;
+    }
+    idFor(call, clientId) {
+        return this.options.namespaceByPrincipal === true
+            ? scopedId(call, clientId, principalNamespace)
+            : clientId;
+    }
+    async submit(task, call = {}) {
+        const prompt = task.message.parts.map((p) => p.text).join("\n");
+        const identity = call.principal !== undefined ? { principal: call.principal } : {};
+        const handle = await this.runtime.start(this.flow, { prompt }, {
+            ...((task.id || this.options.namespaceByPrincipal === true) && {
+                executionId: this.idFor(call, task.id || (0, node_crypto_1.randomUUID)()),
+            }),
+            ...identity,
+        });
+        // Under namespacing the caller only ever sees the id it chose (or was minted).
+        return {
+            id: this.options.namespaceByPrincipal === true
+                ? clientIdOf(handle.executionId)
+                : handle.executionId,
+        };
+    }
+    async get(taskId, call = {}) {
+        const identity = call.principal !== undefined ? { principal: call.principal } : {};
+        const state = await this.runtime.loadState(this.idFor(call, taskId), identity);
+        return state ? toTaskResult(taskId, state) : null;
+    }
+    async provideInput(taskId, event, call = {}) {
+        const identity = call.principal !== undefined ? { principal: call.principal } : {};
+        const handle = await this.runtime.resume(this.idFor(call, taskId), event, identity);
+        return { id: taskId };
+    }
+}
+exports.LoomAgentExecutor = LoomAgentExecutor;
+//# sourceMappingURL=AgentExecutor.js.map

package/dist/AgentExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentExecutor.js","sourceRoot":"","sources":["../src/AgentExecutor.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { A2AEffect } from "./A2AEffect";
+export { createA2AClientEffect } from "./A2AClientEffect";
+export type { A2AClientOptions } from "./A2AClientEffect";
+export { A2APeerClient, fetchAgentCard } from "./A2APeerClient";
+export type { A2APeerConfig, A2APeerInput, A2APeerOutput, A2APeerOutputFor, MappedA2APeer, PeerAgentRegistrar, TaintedA2APeerOutput, } from "./A2APeerClient";
+export { createA2AServer } from "./A2AServer";
+export type { A2AServerOptions, A2AServer } from "./A2AServer";
+export { LoomAgentExecutor, principalNamespace, executionStatusToA2A, toTaskResult, type AgentExecutor, type ExecutorCall, type LoomAgentExecutorOptions, } from "./AgentExecutor";
+export { toAgentCard } from "./toAgentCard";
+export type { ToAgentCardOptions } from "./toAgentCard";
+export type { AgentCard, AgentSkill, A2AMessage, A2AMessagePart, A2ATask, A2ATaskStatus, A2ATaskResult, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAChE,YAAY,EACV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,wBAAwB,GAC9B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EACV,SAAS,EACT,UAAU,EACV,UAAU,EACV,cAAc,EACd,OAAO,EACP,aAAa,EACb,aAAa,GACd,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAgentCard = exports.toTaskResult = exports.executionStatusToA2A = exports.principalNamespace = exports.LoomAgentExecutor = exports.createA2AServer = exports.fetchAgentCard = exports.A2APeerClient = exports.createA2AClientEffect = exports.A2AEffect = void 0;
+var A2AEffect_1 = require("./A2AEffect");
+Object.defineProperty(exports, "A2AEffect", { enumerable: true, get: function () { return A2AEffect_1.A2AEffect; } });
+var A2AClientEffect_1 = require("./A2AClientEffect");
+Object.defineProperty(exports, "createA2AClientEffect", { enumerable: true, get: function () { return A2AClientEffect_1.createA2AClientEffect; } });
+var A2APeerClient_1 = require("./A2APeerClient");
+Object.defineProperty(exports, "A2APeerClient", { enumerable: true, get: function () { return A2APeerClient_1.A2APeerClient; } });
+Object.defineProperty(exports, "fetchAgentCard", { enumerable: true, get: function () { return A2APeerClient_1.fetchAgentCard; } });
+var A2AServer_1 = require("./A2AServer");
+Object.defineProperty(exports, "createA2AServer", { enumerable: true, get: function () { return A2AServer_1.createA2AServer; } });
+var AgentExecutor_1 = require("./AgentExecutor");
+Object.defineProperty(exports, "LoomAgentExecutor", { enumerable: true, get: function () { return AgentExecutor_1.LoomAgentExecutor; } });
+Object.defineProperty(exports, "principalNamespace", { enumerable: true, get: function () { return AgentExecutor_1.principalNamespace; } });
+Object.defineProperty(exports, "executionStatusToA2A", { enumerable: true, get: function () { return AgentExecutor_1.executionStatusToA2A; } });
+Object.defineProperty(exports, "toTaskResult", { enumerable: true, get: function () { return AgentExecutor_1.toTaskResult; } });
+var toAgentCard_1 = require("./toAgentCard");
+Object.defineProperty(exports, "toAgentCard", { enumerable: true, get: function () { return toAgentCard_1.toAgentCard; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAClB,qDAA0D;AAAjD,wHAAA,qBAAqB,OAAA;AAE9B,iDAAgE;AAAvD,8GAAA,aAAa,OAAA;AAAE,+GAAA,cAAc,OAAA;AAUtC,yCAA8C;AAArC,4GAAA,eAAe,OAAA;AAExB,iDAQyB;AAPvB,kHAAA,iBAAiB,OAAA;AACjB,mHAAA,kBAAkB,OAAA;AAClB,qHAAA,oBAAoB,OAAA;AACpB,6GAAA,YAAY,OAAA;AAKd,6CAA4C;AAAnC,0GAAA,WAAW,OAAA"}

package/dist/toAgentCard.d.ts

@@ -0,0 +1,11 @@
+import type { AgentDefinition } from "@loomwork/core";
+import type { AgentCard } from "./types";
+export interface ToAgentCardOptions {
+    url?: string;
+    version?: string;
+    capabilities?: {
+        streaming?: boolean;
+    };
+}
+export declare function toAgentCard(agent: AgentDefinition, opts?: ToAgentCardOptions): AgentCard;
+//# sourceMappingURL=toAgentCard.d.ts.map

package/dist/toAgentCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toAgentCard.d.ts","sourceRoot":"","sources":["../src/toAgentCard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAIzC,MAAM,WAAW,kBAAkB;IAIjC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,YAAY,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACxC;AAOD,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,GAAE,kBAAuB,GAAG,SAAS,CAS5F"}

package/dist/toAgentCard.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toAgentCard = toAgentCard;
+// Derive the public A2A AgentCard from an agent definition. name/description come
+// straight from the definition; skills/capabilities/version are read from the
+// (optional) card metadata authored on agent$, falling back to opts then to sane
+// defaults. This is the single source of truth that removes the hand-written,
+// drift-prone card objects.
+function toAgentCard(agent, opts = {}) {
+    return {
+        name: agent.name,
+        description: agent.description ?? "",
+        url: opts.url ?? `loom+inproc://${agent.id}`,
+        version: agent.version ?? opts.version ?? "1.0.0",
+        capabilities: agent.capabilities ?? opts.capabilities ?? { streaming: false },
+        skills: agent.skills ?? [],
+    };
+}
+//# sourceMappingURL=toAgentCard.js.map

package/dist/toAgentCard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toAgentCard.js","sourceRoot":"","sources":["../src/toAgentCard.ts"],"names":[],"mappings":";;AAqBA,kCASC;AAdD,kFAAkF;AAClF,8EAA8E;AAC9E,iFAAiF;AACjF,8EAA8E;AAC9E,4BAA4B;AAC5B,SAAgB,WAAW,CAAC,KAAsB,EAAE,OAA2B,EAAE;IAC/E,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;QACpC,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,iBAAiB,KAAK,CAAC,EAAE,EAAE;QAC5C,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO;QACjD,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,YAAY,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE;QAC7E,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,EAAE;KAC3B,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+export interface AgentSkill {
+    id: string;
+    name: string;
+    description?: string;
+    inputModes?: string[];
+    outputModes?: string[];
+}
+export interface AgentCard {
+    name: string;
+    description?: string;
+    url: string;
+    version: string;
+    capabilities: {
+        streaming?: boolean;
+    };
+    skills: AgentSkill[];
+}
+export interface A2AMessagePart {
+    type: "text";
+    text: string;
+}
+export interface A2AMessage {
+    role: "user" | "agent";
+    parts: A2AMessagePart[];
+}
+export interface A2ATask {
+    id: string;
+    message: A2AMessage;
+    metadata?: Record<string, unknown>;
+}
+export type A2ATaskStatus = "submitted" | "working" | "completed" | "failed";
+export interface A2ATaskResult {
+    id: string;
+    status: A2ATaskStatus;
+    artifacts?: Array<{
+        name?: string;
+        parts: A2AMessagePart[];
+    }>;
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtC,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC,CAAC;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@loomwork/plugin-a2a",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Agent-to-Agent (A2A) protocol client and server for Loom workflows",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./cards": {
+      "types": "./cards.d.ts",
+      "require": "./dist/toAgentCard.js",
+      "default": "./dist/toAgentCard.js"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.23.8",
+    "@loomwork/classify": "^0.1.0",
+    "@loomwork/core": "^0.1.0",
+    "@loomwork/effect-runtime": "^0.1.0",
+    "@loomwork/workflow-runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8",
+    "@loomwork/event-runtime": "0.1.0",
+    "@loomwork/snapshot-runtime": "0.1.0",
+    "@loomwork/llm": "0.1.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "plugins/a2a"
+  },
+  "files": [
+    "dist",
+    "src",
+    "cards.d.ts",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }

package/src/A2AClientEffect.ts

@@ -0,0 +1,109 @@
+import type { EffectContext } from "@loomwork/effect-runtime";
+import { A2AEffect } from "./A2AEffect";
+import type { A2ATask, A2ATaskResult, A2ATaskStatus } from "./types";
+
+export interface A2AClientOptions {
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+  pollIntervalMs?: number;
+}
+
+export function createA2AClientEffect(
+  agentUrl: string,
+  options: A2AClientOptions = {}
+): A2AEffect<A2ATask, A2ATaskResult> {
+  const { timeoutMs = 60_000, pollIntervalMs = 500, headers = {} } = options;
+
+  return new A2AEffect<A2ATask, A2ATaskResult>(async (task: A2ATask, _ctx: EffectContext) => {
+    const baseHeaders = { "content-type": "application/json", ...headers };
+
+    const sendResp = await fetch(`${agentUrl}/tasks/send`, {
+      method: "POST",
+      headers: baseHeaders,
+      body: JSON.stringify(task),
+    });
+
+    if (!sendResp.ok) {
+      throw new Error(`A2A send error ${sendResp.status}: ${await sendResp.text()}`);
+    }
+
+    const sentBody: unknown = await sendResp.json();
+    // A malformed answer (not an object at all — e.g. a bare JSON string) used to reach the
+    // `"status" in sent` check below and throw a bare, unhelpful `TypeError`. Fail with a
+    // message in the style of the other A2A errors instead.
+    if (typeof sentBody !== "object" || sentBody === null) {
+      throw new Error("A2A send error: malformed answer");
+    }
+    const sent = sentBody as { id?: unknown; status?: unknown } & Partial<A2ATaskResult>;
+    // A peer that answers `/tasks/send` with the finished task (a synchronous agent — e.g. a
+    // thin shim whose send handler runs the graph and returns its artifact) has already given
+    // the result. Polling for it again cost every such call a full `pollIntervalMs` sleep plus
+    // a second request, and failed outright against a peer that does not keep the task (L18).
+    // A send that returns only `{ id }` (loom's own server: 202) is polled as before.
+    if (typeof sent.status === "string" && terminalStatuses.has(sent.status as A2ATaskStatus)) {
+      // A terminal task with no `id` is as malformed as one with no id at all — the caller
+      // can't reconcile it against the task it just submitted.
+      if (typeof sent.id !== "string") {
+        throw new Error("A2A send error: malformed answer");
+      }
+      return sent as A2ATaskResult;
+    }
+    if (typeof sent.id !== "string") {
+      throw new Error("A2A send error: malformed answer");
+    }
+    const taskId = sent.id;
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+      await sleep(pollIntervalMs);
+
+      const statusResp = await fetch(`${agentUrl}/tasks/${encodeTaskIdSegment(taskId)}`, {
+        headers: baseHeaders,
+      });
+      if (!statusResp.ok) {
+        throw new Error(`A2A status error ${statusResp.status}: ${await statusResp.text()}`);
+      }
+
+      const result = (await statusResp.json()) as A2ATaskResult;
+
+      if (result.status === "completed" || result.status === "failed") {
+        return result;
+      }
+    }
+
+    throw new Error(`A2A task ${taskId} timed out after ${timeoutMs}ms`);
+  });
+}
+
+const terminalStatuses = new Set<A2ATaskStatus>(["completed", "failed"]);
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Escape only the characters that are unsafe in a SINGLE path segment: `/` (would otherwise
+ * split the segment — this is what stops a `../admin`-style id from being collapsed by URL
+ * dot-segment normalization into a request for a different route), `?` and `#` (would start a
+ * query string / fragment), and a literal `%` (would corrupt the escape sequence itself on
+ * decode). Everything else — INCLUDING `:` — is left byte-identical to the pre-encoding wire
+ * format.
+ *
+ * `:` matters because every loom task id contains one (`A2APeerClient` sets
+ * `task.id = `${executionId}:${stepId}``, plus `:${callKey}` for a decider-scope call, and `TenantScoped` uses `:` as its own separator). A
+ * full `encodeURIComponent` here would send `exec%3Astep` — a NEW client talking to an OLD
+ * `A2AServer` (or any third-party peer) that does not `decodeURIComponent` the path segment
+ * would then 404 every poll during a rolling upgrade. `A2AServer`'s `GET /tasks/:id` route still
+ * `decodeURIComponent`s the segment on the way in, which is a no-op for an id with no `%` in it
+ * and round-trips one of the escaped characters above, so both old- and new-server peers resolve
+ * the same id from the same request.
+ *
+ * Trade-off accepted deliberately: an id containing a literal `%` cannot be resolved by an old,
+ * non-decoding server (it would look up the literal `...%25...` instead of the real id) — but no
+ * loom-issued task id contains one.
+ */
+function encodeTaskIdSegment(id: string): string {
+  return id.replace(/[/?#%]/g, (c) => encodeURIComponent(c));
+}
+
+export { terminalStatuses };

package/src/A2AEffect.ts

@@ -0,0 +1,16 @@
+import type { Effect, EffectContext } from "@loomwork/effect-runtime";
+
+/**
+ * The effect that fronts a call to an agent-to-agent peer. Its kind, `"a2a"`, names this
+ * plugin's protocol; the kernel treats it as an ordinary custom kind (advisory metadata only,
+ * ADR 0115). Moved here from `@loomwork/effect-runtime`, which keeps a deprecated copy for one minor.
+ */
+export class A2AEffect<TIn = unknown, TOut = unknown> implements Effect<TIn, TOut> {
+  readonly kind = "a2a" as const;
+
+  constructor(private readonly fn: (input: TIn, ctx: EffectContext) => Promise<TOut>) {}
+
+  execute(input: TIn, ctx: EffectContext): Promise<TOut> {
+    return this.fn(input, ctx);
+  }
+}