@loomwork/plugin-a2a 0.0.0-stage → 0.1.0

package/dist/A2APeerClient.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.A2APeerClient = void 0;
+exports.fetchAgentCard = fetchAgentCard;
+const classify_1 = require("@loomwork/classify");
+const core_1 = require("@loomwork/core");
+const core_2 = require("@loomwork/core");
+const zod_1 = require("zod");
+const A2AClientEffect_1 = require("./A2AClientEffect");
+const A2AEffect_1 = require("./A2AEffect");
+const peerInputSchema = zod_1.z.object({
+    prompt: zod_1.z.string(),
+    context: zod_1.z.unknown().optional(),
+});
+// `content` validates BOTH shapes because one schema backs both flag settings.
+// It is the runtime contract; the conditional type is what narrows it per caller.
+const peerOutputSchema = zod_1.z.object({
+    content: zod_1.z.union([
+        zod_1.z.string(),
+        zod_1.z.object({ __loomTainted: zod_1.z.object({ origin: zod_1.z.string() }), value: zod_1.z.string() }),
+    ]),
+    raw: zod_1.z.unknown(),
+});
+/** Fetch a remote agent's AgentCard from its well-known discovery endpoint. */
+async function fetchAgentCard(url, headers = {}) {
+    const resp = await fetch(`${url}/.well-known/agent.json`, {
+        headers: { accept: "application/json", ...headers },
+    });
+    if (!resp.ok) {
+        throw new Error(`A2A discovery failed ${resp.status}: ${await resp.text()}`);
+    }
+    return (await resp.json());
+}
+class A2APeerClient {
+    config;
+    card;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Fetch and cache the remote AgentCard. */
+    async discover() {
+        if (this.card === undefined) {
+            this.card = await fetchAgentCard(this.config.url, this.config.headers);
+        }
+        return this.card;
+    }
+    /** Discover the peer and build its Loom tool definition + effect (no registration). */
+    async map() {
+        const card = await this.discover();
+        const toolId = this.config.toolId ?? slug(card.name);
+        const effect = this.buildEffect(toolId);
+        const definition = (0, core_1.tool$)({
+            id: toolId,
+            name: card.name,
+            description: describe(card),
+            kind: "a2a",
+            // R22 (ADR 0125 D7) — built from a REMOTE agent card: tool search must not rank or show its text.
+            origin: "remote",
+            ...(this.config.trustDescriptions === true && { trustJsonSchemaText: true }),
+            // loom's own static schema (not the card's): its `.describe()` text is loom-authored, so it is kept.
+            schemaOrigin: "local",
+            inputSchema: peerInputSchema,
+            outputSchema: peerOutputSchema,
+        });
+        return { card, definition, effect };
+    }
+    /**
+     * Discover the peer, register it as an effect, and return the tool definition.
+     * Pass a registry to also expose the peer to the planner/intent layer.
+     */
+    async registerInto(effectRuntime, registry) {
+        const { card, definition, effect } = await this.map();
+        effectRuntime.register(definition.id, effect);
+        if (registry !== undefined) {
+            const remoteAgent = (0, core_2.agent$)({
+                id: definition.id,
+                name: card.name,
+                ...(card.description !== undefined && { description: card.description }),
+                tools: [definition],
+                version: card.version,
+                capabilities: card.capabilities,
+                skills: card.skills,
+            });
+            registry.register(remoteAgent, toRegisteredCard(card));
+        }
+        return definition;
+    }
+    /** Adapter effect: friendly input -> A2ATask -> underlying client -> flattened output. */
+    buildEffect(toolId) {
+        const clientOptions = {
+            ...(this.config.headers !== undefined && { headers: this.config.headers }),
+            ...(this.config.timeoutMs !== undefined && { timeoutMs: this.config.timeoutMs }),
+            ...(this.config.pollIntervalMs !== undefined && {
+                pollIntervalMs: this.config.pollIntervalMs,
+            }),
+        };
+        const client = (0, A2AClientEffect_1.createA2AClientEffect)(this.config.url, clientOptions);
+        return new A2AEffect_1.A2AEffect(async (input, ctx) => {
+            const task = {
+                // Deterministic id derived from the execution so replays stay stable.
+                // A transient call stamped as an execution (ctx.decide's scope) shares
+                // (executionId, stepId) with its siblings; callKey keeps their ids distinct.
+                id: `${ctx.executionId}:${ctx.stepId}${ctx.callKey !== undefined ? `:${ctx.callKey}` : ""}`,
+                message: { role: "user", parts: [{ type: "text", text: input.prompt }] },
+                ...(input.context !== undefined && { metadata: { context: input.context } }),
+            };
+            const result = await client.execute(task, ctx);
+            const content = artifactText(result);
+            // Taint at INGRESS — the wrapper IS the step output, so it is what
+            // STEP_COMPLETED records and what a replay hands back. The cast is the
+            // one place the conditional return type cannot be proved structurally.
+            if (this.config.taintResults !== true) {
+                return { content, raw: result };
+            }
+            const origin = `a2a:${toolId}`;
+            const { artifacts, error, ...state } = result;
+            return {
+                content: (0, classify_1.tainted)(content, origin),
+                raw: {
+                    ...state,
+                    ...(artifacts !== undefined && { artifacts: (0, classify_1.tainted)(artifacts, origin) }),
+                    ...(error !== undefined && { error: (0, classify_1.tainted)(error, origin) }),
+                },
+            };
+        });
+    }
+}
+exports.A2APeerClient = A2APeerClient;
+/** Flatten all text parts across all artifacts of a completed/failed A2A result. */
+function artifactText(result) {
+    if (result.error !== undefined) {
+        return result.error;
+    }
+    return (result.artifacts ?? [])
+        .flatMap((artifact) => artifact.parts.map((part) => part.text))
+        .join("\n");
+}
+/** Build an LLM-facing tool description from the card's summary and skills. */
+function describe(card) {
+    const base = card.description ?? card.name;
+    if (card.skills.length === 0) {
+        return base;
+    }
+    const skills = card.skills.map((s) => s.name).join(", ");
+    return `${base} (skills: ${skills})`;
+}
+function toRegisteredCard(card) {
+    return {
+        name: card.name,
+        ...(card.description !== undefined && { description: card.description }),
+        url: card.url,
+        version: card.version,
+        capabilities: card.capabilities,
+        skills: card.skills.map((s) => ({
+            id: s.id,
+            name: s.name,
+            ...(s.description !== undefined && { description: s.description }),
+        })),
+    };
+}
+function slug(name) {
+    return (name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "") || "a2a-peer");
+}
+//# sourceMappingURL=A2APeerClient.js.map

package/dist/A2APeerClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"A2APeerClient.js","sourceRoot":"","sources":["../src/A2APeerClient.ts"],"names":[],"mappings":";;;AAsIA,wCAWC;AAhJD,iDAA6C;AAC7C,yCAAuC;AAEvC,yCAAwC;AAExC,6BAAwB;AACxB,uDAA0D;AAE1D,2CAAwC;AA6GxC,MAAM,eAAe,GAAG,OAAC,CAAC,MAAM,CAAC;IAC/B,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAChC,CAA4B,CAAC;AAE9B,+EAA+E;AAC/E,kFAAkF;AAClF,MAAM,gBAAgB,GAAG,OAAC,CAAC,MAAM,CAAC;IAChC,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC;QACf,OAAC,CAAC,MAAM,EAAE;QACV,OAAC,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,OAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;KACjF,CAAC;IACF,GAAG,EAAE,OAAC,CAAC,OAAO,EAAE;CACjB,CAAC,CAAC;AAEH,+EAA+E;AACxE,KAAK,UAAU,cAAc,CAClC,GAAW,EACX,UAAkC,EAAE;IAEpC,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,yBAAyB,EAAE;QACxD,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE;KACpD,CAAC,CAAC;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAc,CAAC;AAC1C,CAAC;AAED,MAAa,aAAa;IAGK;IAFrB,IAAI,CAAwB;IAEpC,YAA6B,MAA6B;QAA7B,WAAM,GAAN,MAAM,CAAuB;IAAG,CAAC;IAE9D,4CAA4C;IAC5C,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,GAAG;QACP,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAExC,MAAM,UAAU,GAAG,IAAA,YAAK,EAAyC;YAC/D,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC;YAC3B,IAAI,EAAE,KAAK;YACX,kGAAkG;YAClG,MAAM,EAAE,QAAQ;YAChB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,KAAK,IAAI,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC;YAC5E,qGAAqG;YACrG,YAAY,EAAE,OAAO;YACrB,WAAW,EAAE,eAAe;YAC5B,YAAY,EAAE,gBAAkE;SACjF,CAAC,CAAC;QAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAChB,aAA4B,EAC5B,QAA6B;QAE7B,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QACtD,aAAa,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAE9C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,WAAW,GAAG,IAAA,aAAM,EAAC;gBACzB,EAAE,EAAE,UAAU,CAAC,EAAE;gBACjB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;gBACxE,KAAK,EAAE,CAAC,UAAU,CAAC;gBACnB,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,YAAY,EAAE,IAAI,CAAC,YAAY;gBAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;aACpB,CAAC,CAAC;YACH,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,0FAA0F;IAClF,WAAW,CAAC,MAAc;QAChC,MAAM,aAAa,GAAqB;YACtC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAC1E,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YAChF,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS,IAAI;gBAC9C,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;aAC3C,CAAC;SACH,CAAC;QACF,MAAM,MAAM,GAAG,IAAA,uCAAqB,EAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;QAErE,OAAO,IAAI,qBAAS,CAClB,KAAK,EAAE,KAAmB,EAAE,GAAkB,EAAqC,EAAE;YACnF,MAAM,IAAI,GAAY;gBACpB,sEAAsE;gBACtE,uEAAuE;gBACvE,6EAA6E;gBAC7E,EAAE,EAAE,GAAG,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC3F,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;gBACxE,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;aAC7E,CAAC;YAEF,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC/C,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;YACrC,mEAAmE;YACnE,uEAAuE;YACvE,uEAAuE;YACvE,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;gBACtC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAA8B,CAAC;YAC9D,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,MAAM,EAAE,CAAC;YAC/B,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;YAC9C,OAAO;gBACL,OAAO,EAAE,IAAA,kBAAO,EAAC,OAAO,EAAE,MAAM,CAAC;gBACjC,GAAG,EAAE;oBACH,GAAG,KAAK;oBACR,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAA,kBAAO,EAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;oBACzE,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,IAAA,kBAAO,EAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;iBAC9D;aAC0B,CAAC;QAChC,CAAC,CACF,CAAC;IACJ,CAAC;CACF;AA1GD,sCA0GC;AAED,oFAAoF;AACpF,SAAS,YAAY,CAAC,MAAqB;IACzC,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;SAC5B,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SAC9D,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,+EAA+E;AAC/E,SAAS,QAAQ,CAAC,IAAe;IAC/B,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,IAAI,CAAC;IAC3C,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzD,OAAO,GAAG,IAAI,aAAa,MAAM,GAAG,CAAC;AACvC,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAe;IACvC,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QACxE,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9B,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,GAAG,CAAC,CAAC,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;SACnE,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,SAAS,IAAI,CAAC,IAAY;IACxB,OAAO,CACL,IAAI;SACD,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,UAAU,CACzC,CAAC;AACJ,CAAC"}

package/dist/A2AServer.d.ts

@@ -0,0 +1,78 @@
+import * as http from "node:http";
+import type { PrincipalChain } from "@loomwork/effect-runtime";
+import type { RegisteredFlow, WorkflowRuntime } from "@loomwork/workflow-runtime";
+import type { AgentCard } from "./types";
+export interface A2AServerOptions {
+    port?: number;
+    /**
+     * R12 — the interface to bind. Default `"127.0.0.1"` (loopback only): a server is reachable
+     * from this machine and nothing else until you widen it deliberately (`"0.0.0.0"`, `"::"`, or
+     * a specific interface address). Binding all interfaces was the old default.
+     */
+    host?: string;
+    /**
+     * R12 — the URL the agent card advertises, when it differs from the bind address (a server bound
+     * to `"0.0.0.0"` would otherwise advertise `localhost`, which no remote peer can reach). Set it
+     * to the externally reachable base URL (reverse proxy / load balancer). Default: derived from
+     * `host` and the bound port.
+     */
+    publicUrl?: string;
+    /**
+     * R12 — authenticate AND identify the caller in one step: return the caller's
+     * {@link PrincipalChain}, or `undefined` to refuse the request (401). Derive it from connection
+     * facts only (verified bearer token, mTLS peer) — never from the task body. This is the
+     * recommended gate: it also scopes task ownership to the principal (see below).
+     *
+     * The principal MUST carry a non-empty string `actor` (task ownership is keyed on it); any other
+     * principal is refused with 401 and a one-time warning. When both this and
+     * {@link resolvePrincipal} are set, THIS wins and `resolvePrincipal` is ignored.
+     */
+    authenticate?: (req: http.IncomingMessage) => PrincipalChain | undefined | Promise<PrincipalChain | undefined>;
+    /**
+     * Gate the task routes (`POST /tasks/send`, `GET /tasks/:id`). Return `true` to allow. The
+     * agent-card route stays open. A boolean carries no identity, so every caller that passes it
+     * shares ONE task namespace unless `resolvePrincipal`/`authenticate` says who they are.
+     *
+     * R12 — the server REFUSES TO BE CREATED with neither `authenticate` nor `authorize` unless
+     * {@link insecure} is `true`.
+     */
+    authorize?: (req: http.IncomingMessage) => boolean | Promise<boolean>;
+    /**
+     * R12 — explicit opt-out of authentication: any caller that can reach the socket can submit
+     * tasks. Logs a loud warning at creation. Intended for local demos and tests; combine with the
+     * loopback default. Refused when {@link strict} is set.
+     */
+    insecure?: boolean;
+    /**
+     * R12 — `defineConfig`'s `security.strict`. Under strict the server is a config error unless it
+     * authenticates AND resolves a principal; `insecure: true` is refused; and a caller that
+     * resolves to no principal is refused (401). DEFAULTS from the runtime you pass
+     * (`workflowRuntime.requiresPrincipal`), so a strict runtime makes the server strict without
+     * this flag; set it explicitly to override.
+     */
+    strict?: boolean;
+    /** Where the insecure-mode warning goes. Default `console.warn`. */
+    warn?: (message: string) => void;
+    /**
+     * R3 — the AUTHENTICATED principal behind a request, derived from the same connection facts
+     * `authorize` checked (mTLS peer, verified bearer token, signed header) — NEVER from the task
+     * body. Applied to the runtime call for every task route (`/tasks/send`, `GET /tasks/:id`).
+     * Without it every task is anonymous, which a runtime that fails closed (`security.strict`)
+     * refuses (`ExecutionDeniedError`): an A2A server is an edge, and under strict an edge must
+     * say who is calling. Returning `undefined` for a request means "anonymous".
+     */
+    resolvePrincipal?: (req: http.IncomingMessage) => PrincipalChain | undefined | Promise<PrincipalChain | undefined>;
+    /**
+     * Called with the real error behind a 500, alongside the `errorId` the caller was given.
+     * The response itself carries no internal detail, so this is the only place it surfaces —
+     * wire it to your logger or the detail is simply lost.
+     */
+    onError?: (errorId: string, err: unknown) => void;
+}
+export interface A2AServer {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    readonly url: string;
+}
+export declare function createA2AServer(workflowRuntime: WorkflowRuntime, flow: RegisteredFlow, agentCard: Omit<AgentCard, "url">, options?: A2AServerOptions): A2AServer;
+//# sourceMappingURL=A2AServer.d.ts.map

package/dist/A2AServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"A2AServer.d.ts","sourceRoot":"","sources":["../src/A2AServer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElF,OAAO,KAAK,EAAW,SAAS,EAAE,MAAM,SAAS,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,CACb,GAAG,EAAE,IAAI,CAAC,eAAe,KACtB,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACtE;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtE;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,CACjB,GAAG,EAAE,IAAI,CAAC,eAAe,KACtB,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACtE;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAyCD,wBAAgB,eAAe,CAC7B,eAAe,EAAE,eAAe,EAChC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,EACjC,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CAkLX"}

package/dist/A2AServer.js

@@ -0,0 +1,239 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createA2AServer = createA2AServer;
+const node_crypto_1 = require("node:crypto");
+const http = __importStar(require("node:http"));
+const core_1 = require("@loomwork/core");
+const AgentExecutor_1 = require("./AgentExecutor");
+// Cap request bodies so an unauthenticated caller can't OOM the process by streaming a
+// huge (or endless) body into memory before parse. Matches the isolate broker's 10 MB cap.
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+// `task.id` becomes the executionId, which is embedded in event ids and carried in the
+// Postgres NOTIFY payload (itself capped at ~8 KB). Generous for a ULID or a UUID.
+const MAX_TASK_ID_LENGTH = 200;
+function parseBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                req.destroy();
+                reject(new core_1.BadRequestError(`request body exceeds ${MAX_BODY_BYTES} bytes`));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            try {
+                const raw = Buffer.concat(chunks);
+                resolve(JSON.parse(raw.toString("utf-8")));
+            }
+            catch {
+                // The caller's own malformed JSON — safe to name, and useless to hide.
+                reject(new core_1.BadRequestError("request body is not valid JSON"));
+            }
+        });
+        req.on("error", (err) => reject(err));
+    });
+}
+function json(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(payload);
+}
+function createA2AServer(workflowRuntime, flow, agentCard, options = {}) {
+    const port = options.port ?? 3001;
+    const host = options.host ?? "127.0.0.1";
+    const authenticated = options.authenticate !== undefined || options.authorize !== undefined;
+    const strict = options.strict ?? workflowRuntime.requiresPrincipal === true;
+    if (strict) {
+        if (options.insecure === true) {
+            throw new Error("createA2AServer: `insecure: true` is refused under security.strict — authenticate callers.");
+        }
+        if (options.authenticate === undefined && options.resolvePrincipal === undefined) {
+            throw new Error("createA2AServer: security.strict requires `authenticate` (or `resolvePrincipal`) — every task must carry the caller's principal.");
+        }
+    }
+    if (!authenticated && options.insecure !== true) {
+        throw new Error("createA2AServer: refusing to create an unauthenticated server. Supply `authenticate` (recommended) or `authorize`, or pass `insecure: true` to opt out explicitly.");
+    }
+    if (!authenticated) {
+        (options.warn ?? ((m) => console.warn(m)))(`[loom] WARNING: A2A server is running with insecure: true — NO authentication; any caller that can reach ${host}:${port} can submit and read tasks.`);
+    }
+    const urlHost = host === "0.0.0.0" || host === "::" ? "localhost" : host.includes(":") ? `[${host}]` : host;
+    let resolvedUrl = `http://${urlHost}:${port}`;
+    const warn = options.warn ?? ((m) => console.warn(m));
+    let warnedNoActor = false;
+    // The whole A2A layer is this one adapter; the server just moves bytes to it. Task ids are
+    // namespaced by principal (R12): the client's id is only a label within its own namespace.
+    const executor = new AgentExecutor_1.LoomAgentExecutor(workflowRuntime, flow, { namespaceByPrincipal: true });
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            const url = req.url ?? "/";
+            const method = req.method ?? "GET";
+            try {
+                if (method === "GET" && url === "/.well-known/agent.json") {
+                    json(res, 200, { ...agentCard, url: options.publicUrl ?? resolvedUrl });
+                    return;
+                }
+                // Gate the task routes when an authorizer is wired; the agent card stays open.
+                if (options.authorize !== undefined && url !== "/.well-known/agent.json") {
+                    if (!(await options.authorize(req))) {
+                        json(res, 401, { error: "unauthorized" });
+                        return;
+                    }
+                }
+                // R12 — authenticate: identity or refusal.
+                let principal;
+                if (options.authenticate !== undefined) {
+                    principal = await options.authenticate(req);
+                    if (principal === undefined) {
+                        json(res, 401, { error: "unauthorized" });
+                        return;
+                    }
+                }
+                // R3 — who is calling, resolved once per request, after `authorize`.
+                principal ??= await options.resolvePrincipal?.(req);
+                // R12 — fail closed: a principal that cannot be given its own namespace (no actor) must
+                // not be pooled with other such callers; under strict an unidentified caller is refused.
+                if (principal !== undefined && !(0, AgentExecutor_1.hasActor)(principal)) {
+                    if (!warnedNoActor) {
+                        warnedNoActor = true;
+                        warn("[loom] A2A server: refusing a caller whose principal has no non-empty string `actor` — `authenticate`/`resolvePrincipal` must return an `actor` (task ownership is keyed on it).");
+                    }
+                    json(res, 401, { error: "unauthorized" });
+                    return;
+                }
+                if (principal === undefined && strict) {
+                    json(res, 401, { error: "unauthorized" });
+                    return;
+                }
+                // The task namespace: the principal when known; one shared bucket for callers that were
+                // authorized but not identified; "anonymous" under `insecure`.
+                const call = {
+                    ...(principal !== undefined && { principal }),
+                    ...(principal === undefined && authenticated && { namespace: "authorized" }),
+                };
+                if (method === "POST" && url === "/tasks/send") {
+                    const task = (await parseBody(req));
+                    // `task.id` becomes the executionId VERBATIM, so it is screened here rather than
+                    // only deep in the kernel — a rejected id should read as a 400 from the adapter,
+                    // not surface as a 500 from the runtime.
+                    if (typeof task?.id !== "string" || task.id.length === 0) {
+                        json(res, 400, { error: "task.id must be a non-empty string" });
+                        return;
+                    }
+                    // The kernel reserves `__loom_*` for its own control streams (retention lifecycle,
+                    // erasure). An execution created there both corrupts that audit trail and becomes
+                    // invisible to every enumerator, so retention never reclaims it.
+                    if (task.id.startsWith("__loom_")) {
+                        json(res, 400, { error: 'task.id must not use the reserved "__loom_" prefix' });
+                        return;
+                    }
+                    // Bound it: the id is embedded in every event id and travels in the Postgres
+                    // NOTIFY payload, which is itself capped — an unbounded id turns into failing
+                    // appends rather than a rejected request.
+                    if (task.id.length > MAX_TASK_ID_LENGTH) {
+                        json(res, 400, { error: `task.id exceeds ${MAX_TASK_ID_LENGTH} characters` });
+                        return;
+                    }
+                    const { id } = await executor.submit(task, call);
+                    json(res, 202, { id });
+                    return;
+                }
+                const taskMatch = /^\/tasks\/([^/]+)$/.exec(url);
+                if (method === "GET" && taskMatch !== null) {
+                    const rawTaskId = taskMatch[1];
+                    if (rawTaskId === undefined) {
+                        json(res, 400, { error: "missing task id" });
+                        return;
+                    }
+                    // The path segment is percent-encoded on the wire (a client MUST encode an id
+                    // containing `/` or other reserved characters, or URL normalization upstream of this
+                    // server — e.g. `fetch`'s own dot-segment collapsing — could otherwise turn an id like
+                    // `../admin` into a request for a different route entirely). Decode it back to the
+                    // real task id before it reaches the executor.
+                    let taskId;
+                    try {
+                        taskId = decodeURIComponent(rawTaskId);
+                    }
+                    catch {
+                        json(res, 400, { error: "task id is not validly percent-encoded" });
+                        return;
+                    }
+                    const result = await executor.get(taskId, call);
+                    if (result === null) {
+                        json(res, 404, { error: `task ${taskId} not found` });
+                        return;
+                    }
+                    json(res, 200, result);
+                    return;
+                }
+                json(res, 404, { error: "not found" });
+            }
+            catch (err) {
+                const exposed = (0, core_1.exposeError)(err, node_crypto_1.randomUUID);
+                if (exposed.internal !== undefined) {
+                    options.onError?.(exposed.body.errorId, exposed.internal);
+                }
+                json(res, exposed.status, exposed.body);
+            }
+        })();
+    });
+    return {
+        get url() {
+            return resolvedUrl;
+        },
+        start() {
+            return new Promise((resolve) => {
+                server.listen(port, host, () => {
+                    const addr = server.address();
+                    if (addr !== null && typeof addr === "object") {
+                        resolvedUrl = `http://${urlHost}:${addr.port}`;
+                    }
+                    resolve();
+                });
+            });
+        },
+        stop() {
+            return new Promise((resolve, reject) => {
+                server.close((err) => (err !== undefined ? reject(err) : resolve()));
+            });
+        },
+    };
+}
+//# sourceMappingURL=A2AServer.js.map

package/dist/A2AServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"A2AServer.js","sourceRoot":"","sources":["../src/A2AServer.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6HA,0CAuLC;AApTD,6CAAyC;AACzC,gDAAkC;AAClC,yCAA8D;AAG9D,mDAA8D;AAiF9D,uFAAuF;AACvF,2FAA2F;AAC3F,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACxC,uFAAuF;AACvF,mFAAmF;AACnF,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,SAAS,SAAS,CAAC,GAAyB;IAC1C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAiB,EAAE,CAAC;QAChC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAiB,EAAE,EAAE;YACnC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;YACrB,IAAI,IAAI,GAAG,cAAc,EAAE,CAAC;gBAC1B,GAAG,CAAC,OAAO,EAAE,CAAC;gBACd,MAAM,CAAC,IAAI,sBAAe,CAAC,wBAAwB,cAAc,QAAQ,CAAC,CAAC,CAAC;gBAC5E,OAAO;YACT,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YACjB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAClC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAY,CAAC,CAAC;YACxD,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;gBACvE,MAAM,CAAC,IAAI,sBAAe,CAAC,gCAAgC,CAAC,CAAC,CAAC;YAChE,CAAC;QACH,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,IAAI,CAAC,GAAwB,EAAE,MAAc,EAAE,IAAa;IACnE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACrC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC9D,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC;AAED,SAAgB,eAAe,CAC7B,eAAgC,EAChC,IAAoB,EACpB,SAAiC,EACjC,UAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IAClC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IACzC,MAAM,aAAa,GAAG,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC;IAC5F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC,iBAAiB,KAAK,IAAI,CAAC;IAC5E,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,4FAA4F,CAC7F,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACjF,MAAM,IAAI,KAAK,CACb,kIAAkI,CACnI,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,CAAC,aAAa,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,oKAAoK,CACrK,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAChD,4GAA4G,IAAI,IAAI,IAAI,6BAA6B,CACtJ,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GACX,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9F,IAAI,WAAW,GAAG,UAAU,OAAO,IAAI,IAAI,EAAE,CAAC;IAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,aAAa,GAAG,KAAK,CAAC;IAE1B,2FAA2F;IAC3F,2FAA2F;IAC3F,MAAM,QAAQ,GAAG,IAAI,iCAAiB,CAAC,eAAe,EAAE,IAAI,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9F,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,GAAyB,EAAE,GAAwB,EAAQ,EAAE;QAC7F,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;YAC3B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC;YAEnC,IAAI,CAAC;gBACH,IAAI,MAAM,KAAK,KAAK,IAAI,GAAG,KAAK,yBAAyB,EAAE,CAAC;oBAC1D,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,GAAG,SAAS,EAAE,GAAG,EAAE,OAAO,CAAC,SAAS,IAAI,WAAW,EAAE,CAAC,CAAC;oBACxE,OAAO;gBACT,CAAC;gBAED,+EAA+E;gBAC/E,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,GAAG,KAAK,yBAAyB,EAAE,CAAC;oBACzE,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;wBACpC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;wBAC1C,OAAO;oBACT,CAAC;gBACH,CAAC;gBAED,2CAA2C;gBAC3C,IAAI,SAAqC,CAAC;gBAC1C,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;oBACvC,SAAS,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;oBAC5C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;wBAC5B,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;wBAC1C,OAAO;oBACT,CAAC;gBACH,CAAC;gBACD,qEAAqE;gBACrE,SAAS,KAAK,MAAM,OAAO,CAAC,gBAAgB,EAAE,CAAC,GAAG,CAAC,CAAC;gBACpD,wFAAwF;gBACxF,yFAAyF;gBACzF,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,IAAA,wBAAQ,EAAC,SAAS,CAAC,EAAE,CAAC;oBACpD,IAAI,CAAC,aAAa,EAAE,CAAC;wBACnB,aAAa,GAAG,IAAI,CAAC;wBACrB,IAAI,CACF,kLAAkL,CACnL,CAAC;oBACJ,CAAC;oBACD,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;oBAC1C,OAAO;gBACT,CAAC;gBACD,IAAI,SAAS,KAAK,SAAS,IAAI,MAAM,EAAE,CAAC;oBACtC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;oBAC1C,OAAO;gBACT,CAAC;gBACD,wFAAwF;gBACxF,+DAA+D;gBAC/D,MAAM,IAAI,GAAG;oBACX,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;oBAC7C,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,aAAa,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC;iBAC7E,CAAC;gBAEF,IAAI,MAAM,KAAK,MAAM,IAAI,GAAG,KAAK,aAAa,EAAE,CAAC;oBAC/C,MAAM,IAAI,GAAG,CAAC,MAAM,SAAS,CAAC,GAAG,CAAC,CAAY,CAAC;oBAC/C,iFAAiF;oBACjF,iFAAiF;oBACjF,yCAAyC;oBACzC,IAAI,OAAO,IAAI,EAAE,EAAE,KAAK,QAAQ,IAAI,IAAI,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBACzD,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC,CAAC;wBAChE,OAAO;oBACT,CAAC;oBACD,mFAAmF;oBACnF,kFAAkF;oBAClF,iEAAiE;oBACjE,IAAI,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;wBAClC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,oDAAoD,EAAE,CAAC,CAAC;wBAChF,OAAO;oBACT,CAAC;oBACD,6EAA6E;oBAC7E,8EAA8E;oBAC9E,0CAA0C;oBAC1C,IAAI,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;wBACxC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,mBAAmB,kBAAkB,aAAa,EAAE,CAAC,CAAC;wBAC9E,OAAO;oBACT,CAAC;oBACD,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBACjD,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;oBACvB,OAAO;gBACT,CAAC;gBAED,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACjD,IAAI,MAAM,KAAK,KAAK,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;oBAC3C,MAAM,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;oBAC/B,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;wBAC5B,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,CAAC,CAAC;wBAC7C,OAAO;oBACT,CAAC;oBACD,8EAA8E;oBAC9E,qFAAqF;oBACrF,uFAAuF;oBACvF,mFAAmF;oBACnF,+CAA+C;oBAC/C,IAAI,MAAc,CAAC;oBACnB,IAAI,CAAC;wBACH,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;oBACzC,CAAC;oBAAC,MAAM,CAAC;wBACP,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,wCAAwC,EAAE,CAAC,CAAC;wBACpE,OAAO;oBACT,CAAC;oBACD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;oBAChD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;wBACpB,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,QAAQ,MAAM,YAAY,EAAE,CAAC,CAAC;wBACtD,OAAO;oBACT,CAAC;oBACD,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;oBACvB,OAAO;gBACT,CAAC;gBAED,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,IAAA,kBAAW,EAAC,GAAG,EAAE,wBAAU,CAAC,CAAC;gBAC7C,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;oBACnC,OAAO,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAiB,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;gBACtE,CAAC;gBACD,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,GAAG;YACL,OAAO,WAAW,CAAC;QACrB,CAAC;QACD,KAAK;YACH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;gBAC7B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;oBAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC9B,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;wBAC9C,WAAW,GAAG,UAAU,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;oBACjD,CAAC;oBACD,OAAO,EAAE,CAAC;gBACZ,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;QACD,IAAI;YACF,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC/E,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/AgentExecutor.d.ts

@@ -0,0 +1,89 @@
+import type { ExecutionState } from "@loomwork/core";
+import type { PrincipalChain } from "@loomwork/effect-runtime";
+import type { RegisteredFlow, ResumeEvent, WorkflowRuntime } from "@loomwork/workflow-runtime";
+import type { A2ATask, A2ATaskResult, A2ATaskStatus } from "./types";
+/**
+ * The A2A task lifecycle, expressed as a small executor interface. Its states map
+ * one-to-one onto Loom's execution states, so the entire A2A layer reduces to a
+ * single adapter over the runtime:
+ *
+ *   submit / working   → runtime.start → running
+ *   input-required     → SuspendError / status "suspended" (approval / agent-surface form)
+ *   provideInput       → runtime.resume(executionId, resumeEvent)
+ *   completed / failed → terminal ExecutionState
+ *
+ * A transport (the in-house HTTP server below, or an external @a2a-js/sdk server)
+ * only has to move bytes to/from this interface.
+ */
+export interface AgentExecutor {
+    submit(task: A2ATask, call?: ExecutorCall): Promise<{
+        id: string;
+    }>;
+    /** Poll a task's status/result. `null` ⇒ unknown task (→ 404). */
+    get(taskId: string, call?: ExecutorCall): Promise<A2ATaskResult | null>;
+    /** Deliver the input an `input-required` (suspended) task is waiting on. */
+    provideInput(taskId: string, event: ResumeEvent, call?: ExecutorCall): Promise<{
+        id: string;
+    }>;
+}
+/**
+ * R3 — per-call context from the transport. `principal` is the AUTHENTICATED identity of whoever
+ * made the request (resolved by the transport from its connection, never from the task body);
+ * the executor applies it to the runtime call so a runtime that fails closed (`security.strict`)
+ * authorizes the task as that caller. Absent ⇒ anonymous, which such a runtime refuses.
+ */
+export interface ExecutorCall {
+    principal?: PrincipalChain;
+    /**
+     * R12 — the task namespace when no principal identifies the caller (e.g. a boolean `authorize`
+     * gate). Ignored when `principal` is present (the principal's identity wins). Only meaningful
+     * on an executor created with `namespaceByPrincipal`.
+     */
+    namespace?: string;
+}
+export interface LoomAgentExecutorOptions {
+    /**
+     * R12 — scope task ids to the caller. The execution id the runtime sees is
+     * `a2a.<namespace of caller>.<client task id>`: a caller can only ever name executions in its
+     * OWN namespace, so it cannot read, resume or collide with another caller's task by guessing
+     * or choosing an id (the lookup simply lands on a different, nonexistent execution). The
+     * client-visible id stays the one it chose. Default `false` for direct (in-process) use of the
+     * executor, where the id is the embedder's own; the HTTP server turns it on.
+     */
+    namespaceByPrincipal?: boolean;
+}
+/** R12 — does this principal carry the minimum identity a per-caller namespace needs? */
+export declare function hasActor(principal: PrincipalChain): boolean;
+/**
+ * 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).
+ */
+export declare function principalNamespace(principal: PrincipalChain | undefined): string;
+/** Map a Loom execution status onto an A2A task status. */
+export declare function executionStatusToA2A(status: string): A2ATaskStatus;
+/** Fold a terminal/interim ExecutionState into the A2A task result shape. */
+export declare function toTaskResult(taskId: string, state: ExecutionState): A2ATaskResult;
+/**
+ * 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).
+ */
+export declare class LoomAgentExecutor implements AgentExecutor {
+    private readonly runtime;
+    private readonly flow;
+    private readonly options;
+    constructor(runtime: WorkflowRuntime, flow: RegisteredFlow, options?: LoomAgentExecutorOptions);
+    private idFor;
+    submit(task: A2ATask, call?: ExecutorCall): Promise<{
+        id: string;
+    }>;
+    get(taskId: string, call?: ExecutorCall): Promise<A2ATaskResult | null>;
+    provideInput(taskId: string, event: ResumeEvent, call?: ExecutorCall): Promise<{
+        id: string;
+    }>;
+}
+//# sourceMappingURL=AgentExecutor.d.ts.map

package/dist/AgentExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentExecutor.d.ts","sourceRoot":"","sources":["../src/AgentExecutor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC/F,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpE,kEAAkE;IAClE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACxE,4EAA4E;IAC5E,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChG;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,yFAAyF;AACzF,wBAAgB,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,OAAO,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CAgBhF;AAkBD,2DAA2D;AAC3D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAYlE;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,aAAa,CAgBjF;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IAEnD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAFP,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,wBAA6B;IAGzD,OAAO,CAAC,KAAK;IAMP,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAsBvE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAM3E,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAK3B"}