@adonis-agora/agent 0.60.1 → 0.62.0

package/dist/src/a2a/protocol.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The slice of A2A 1.0 (HTTP+JSON binding) this surface speaks: the message shapes, the AIP-193 error
+ * envelope, and the request validation PACT §4.1 asks for. Hand-rolled rather than schema-validated —
+ * `zod` is an optional peer, and the rules are few and exact.
+ */
+export declare const A2A_CONTENT_TYPE = "application/a2a+json";
+export type A2aRole = 'ROLE_USER' | 'ROLE_AGENT';
+export interface A2aTextPart {
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/** A structured part (A2A `DataPart`): what an action did, for the personal agent to relay. */
+export interface A2aDataPart {
+    data: unknown;
+    mediaType?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface A2aMessage {
+    messageId: string;
+    contextId?: string;
+    taskId?: string;
+    role: A2aRole;
+    parts: (A2aTextPart | A2aDataPart)[];
+    metadata?: Record<string, unknown>;
+}
+export interface A2aTask {
+    id: string;
+    contextId: string;
+    status: {
+        state: 'TASK_STATE_AUTH_REQUIRED';
+        message: A2aMessage;
+    };
+    metadata?: Record<string, unknown>;
+}
+/** What `message:send` answers: a message (an ordinary turn) or a task (step-up). */
+export type A2aSendResult = {
+    message: A2aMessage;
+} | {
+    task: A2aTask;
+};
+/** The A2A error reasons PACT §6 uses, with their HTTP status and google.rpc status. */
+declare const REASONS: {
+    readonly INVALID_PARAMS: {
+        readonly httpStatus: 400;
+        readonly status: 'INVALID_ARGUMENT';
+    };
+    readonly CONTENT_TYPE_NOT_SUPPORTED: {
+        readonly httpStatus: 400;
+        readonly status: 'INVALID_ARGUMENT';
+    };
+    readonly UNSUPPORTED_OPERATION: {
+        readonly httpStatus: 400;
+        readonly status: 'FAILED_PRECONDITION';
+    };
+    readonly PUSH_NOTIFICATION_NOT_SUPPORTED: {
+        readonly httpStatus: 400;
+        readonly status: 'FAILED_PRECONDITION';
+    };
+    readonly TASK_NOT_FOUND: {
+        readonly httpStatus: 404;
+        readonly status: 'NOT_FOUND';
+    };
+    readonly INTERNAL: {
+        readonly httpStatus: 500;
+        readonly status: 'INTERNAL';
+    };
+};
+export type A2aErrorReason = keyof typeof REASONS;
+/** An A2A error — answered as the AIP-193 envelope, never as a bare status. */
+export declare class A2aError extends Error {
+    readonly reason: A2aErrorReason;
+    constructor(reason: A2aErrorReason, message: string);
+    get httpStatus(): number;
+    toJSON(): {
+        error: {
+            code: 400 | 404 | 500;
+            status: "FAILED_PRECONDITION" | "INTERNAL" | "INVALID_ARGUMENT" | "NOT_FOUND";
+            message: string;
+            details: {
+                '@type': string;
+                reason: "CONTENT_TYPE_NOT_SUPPORTED" | "INTERNAL" | "INVALID_PARAMS" | "PUSH_NOTIFICATION_NOT_SUPPORTED" | "TASK_NOT_FOUND" | "UNSUPPORTED_OPERATION";
+                domain: string;
+            }[];
+        };
+    };
+}
+/** A validated `message:send` request: the user's text and the ids the turn is addressed by. */
+export interface SendMessageInput {
+    messageId: string;
+    contextId?: string;
+    text: string;
+}
+/**
+ * Parse and validate a `SendMessageRequest` body (PACT §4.1). `configuration` and `metadata` are
+ * accepted and ignored. Order matters where the conformance suite pins it: a `taskId` is
+ * `TASK_NOT_FOUND` even on an otherwise valid message.
+ */
+export declare function parseSendMessage(raw: string): SendMessageInput;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/src/a2a/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/a2a/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,YAAY,CAAC;AAEjD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,CAAC,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE;QAAE,KAAK,EAAE,0BAA0B,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG;IAAE,OAAO,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE,wFAAwF;AACxF,QAAA,MAAM,OAAO;aACX,cAAc;iBAAI,UAAU,EAAE,GAAG;iBAAE,MAAM,EAAE,kBAAkB;;aAC7D,0BAA0B;iBAAI,UAAU,EAAE,GAAG;iBAAE,MAAM,EAAE,kBAAkB;;aACzE,qBAAqB;iBAAI,UAAU,EAAE,GAAG;iBAAE,MAAM,EAAE,qBAAqB;;aACvE,+BAA+B;iBAAI,UAAU,EAAE,GAAG;iBAAE,MAAM,EAAE,qBAAqB;;aACjF,cAAc;iBAAI,UAAU,EAAE,GAAG;iBAAE,MAAM,EAAE,WAAW;;aACtD,QAAQ;iBAAI,UAAU,EAAE,GAAG;iBAAE,MAAM,EAAE,UAAU;;CACvC,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,OAAO,CAAC;AAElD,+EAA+E;AAC/E,qBAAa,QAAS,SAAQ,KAAK;IAE/B,QAAQ,CAAC,MAAM,EAAE,cAAc;IADjC,YACW,MAAM,EAAE,cAAc,EAC/B,OAAO,EAAE,MAAM,EAGhB;IAED,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,MAAM;;;;;;;;;;;MAgBL;CACF;AAMD,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAoD9D"}

package/dist/src/a2a/protocol.js

@@ -0,0 +1,106 @@
+/**
+ * The slice of A2A 1.0 (HTTP+JSON binding) this surface speaks: the message shapes, the AIP-193 error
+ * envelope, and the request validation PACT §4.1 asks for. Hand-rolled rather than schema-validated —
+ * `zod` is an optional peer, and the rules are few and exact.
+ */
+export const A2A_CONTENT_TYPE = 'application/a2a+json';
+/** The A2A error reasons PACT §6 uses, with their HTTP status and google.rpc status. */
+const REASONS = {
+    INVALID_PARAMS: { httpStatus: 400, status: 'INVALID_ARGUMENT' },
+    CONTENT_TYPE_NOT_SUPPORTED: { httpStatus: 400, status: 'INVALID_ARGUMENT' },
+    UNSUPPORTED_OPERATION: { httpStatus: 400, status: 'FAILED_PRECONDITION' },
+    PUSH_NOTIFICATION_NOT_SUPPORTED: { httpStatus: 400, status: 'FAILED_PRECONDITION' },
+    TASK_NOT_FOUND: { httpStatus: 404, status: 'NOT_FOUND' },
+    INTERNAL: { httpStatus: 500, status: 'INTERNAL' },
+};
+/** An A2A error — answered as the AIP-193 envelope, never as a bare status. */
+export class A2aError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+    get httpStatus() {
+        return REASONS[this.reason].httpStatus;
+    }
+    toJSON() {
+        const { httpStatus, status } = REASONS[this.reason];
+        return {
+            error: {
+                code: httpStatus,
+                status,
+                message: this.message,
+                details: [
+                    {
+                        '@type': 'type.googleapis.com/google.rpc.ErrorInfo',
+                        reason: this.reason,
+                        domain: 'a2a-protocol.org',
+                    },
+                ],
+            },
+        };
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse and validate a `SendMessageRequest` body (PACT §4.1). `configuration` and `metadata` are
+ * accepted and ignored. Order matters where the conformance suite pins it: a `taskId` is
+ * `TASK_NOT_FOUND` even on an otherwise valid message.
+ */
+export function parseSendMessage(raw) {
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        throw new A2aError('INVALID_PARAMS', 'Request body is not valid JSON');
+    }
+    if (!isRecord(body) || !isRecord(body.message)) {
+        throw new A2aError('INVALID_PARAMS', 'Missing message');
+    }
+    const message = body.message;
+    if (message.taskId !== undefined) {
+        throw new A2aError('TASK_NOT_FOUND', 'Task not found');
+    }
+    if (typeof message.messageId !== 'string' || message.messageId === '') {
+        throw new A2aError('INVALID_PARAMS', 'messageId is required');
+    }
+    if (message.contextId !== undefined && typeof message.contextId !== 'string') {
+        throw new A2aError('INVALID_PARAMS', 'contextId must be a string');
+    }
+    if (message.role !== 'ROLE_USER') {
+        throw new A2aError('INVALID_PARAMS', 'role must be ROLE_USER');
+    }
+    if (!Array.isArray(message.parts) || message.parts.length === 0) {
+        throw new A2aError('INVALID_PARAMS', 'parts must not be empty');
+    }
+    const texts = [];
+    for (const part of message.parts) {
+        if (!isRecord(part)) {
+            throw new A2aError('INVALID_PARAMS', 'Invalid part');
+        }
+        if (typeof part.text === 'string') {
+            texts.push(part.text);
+        }
+        else if ('raw' in part || 'url' in part || 'data' in part) {
+            throw new A2aError('CONTENT_TYPE_NOT_SUPPORTED', 'Only text parts are supported');
+        }
+        else {
+            throw new A2aError('INVALID_PARAMS', 'Invalid part');
+        }
+    }
+    const text = texts.join('\n').trim();
+    if (text === '') {
+        throw new A2aError('INVALID_PARAMS', 'Message text is blank');
+    }
+    return {
+        messageId: message.messageId,
+        ...(message.contextId !== undefined && message.contextId !== ''
+            ? { contextId: message.contextId }
+            : {}),
+        text,
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/src/a2a/protocol.js.map

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

package/dist/src/a2a/runtime.d.ts

@@ -0,0 +1,6 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/** The request handler the A2A server middleware delegates to; `false` = not an A2A request. */
+export type A2aRequestHandler = (ctx: HttpContext) => Promise<boolean>;
+export declare function setA2aHandler(handler: A2aRequestHandler | null): void;
+export declare function getA2aHandler(): A2aRequestHandler | null;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/src/a2a/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/a2a/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AASvE,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAErE;AAED,wBAAgB,aAAa,IAAI,iBAAiB,GAAG,IAAI,CAExD"}

package/dist/src/a2a/runtime.js

@@ -0,0 +1,13 @@
+/**
+ * Set by the A2A provider at boot, read by the server middleware per request. A module singleton
+ * because the server middleware is instantiated by the framework from a lazy import, with no way
+ * to hand it constructor arguments.
+ */
+let current = null;
+export function setA2aHandler(handler) {
+    current = handler;
+}
+export function getA2aHandler() {
+    return current;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/a2a/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/a2a/runtime.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,IAAI,OAAO,GAA6B,IAAI,CAAC;AAE7C,MAAM,UAAU,aAAa,CAAC,OAAiC;IAC7D,OAAO,GAAG,OAAO,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/a2a/server_middleware.d.ts

@@ -0,0 +1,13 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+/**
+ * Server middleware that answers A2A requests before the router runs — so before the bodyparser,
+ * the session and CSRF. That is deliberate: A2A is stateless and authenticated by the personal
+ * agent's signed JWT, PACT requires authenticating BEFORE the body is read (a malformed body without
+ * a token is a 401, not a parse error), and its bodies are JSON whatever `Content-Type` they carry.
+ * Everything that is not under the A2A prefix passes straight through.
+ */
+export default class A2aServerMiddleware {
+    handle(ctx: HttpContext, next: NextFn): Promise<any>;
+}
+//# sourceMappingURL=server_middleware.d.ts.map

package/dist/src/a2a/server_middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_middleware.d.ts","sourceRoot":"","sources":["../../../src/a2a/server_middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAGxD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IAChC,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,gBAM1C;CACF"}

package/dist/src/a2a/server_middleware.js

@@ -0,0 +1,18 @@
+import { getA2aHandler } from './runtime.js';
+/**
+ * Server middleware that answers A2A requests before the router runs — so before the bodyparser,
+ * the session and CSRF. That is deliberate: A2A is stateless and authenticated by the personal
+ * agent's signed JWT, PACT requires authenticating BEFORE the body is read (a malformed body without
+ * a token is a 401, not a parse error), and its bodies are JSON whatever `Content-Type` they carry.
+ * Everything that is not under the A2A prefix passes straight through.
+ */
+export default class A2aServerMiddleware {
+    async handle(ctx, next) {
+        const handler = getA2aHandler();
+        if (handler !== null && (await handler(ctx))) {
+            return;
+        }
+        return next();
+    }
+}
+//# sourceMappingURL=server_middleware.js.map

package/dist/src/a2a/server_middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server_middleware.js","sourceRoot":"","sources":["../../../src/a2a/server_middleware.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,mBAAmB;IACtC,KAAK,CAAC,MAAM,CAAC,GAAgB,EAAE,IAAY;QACzC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAChC,IAAI,OAAO,KAAK,IAAI,IAAI,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC7C,OAAO;QACT,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC;CACF"}

package/dist/src/a2a/store.d.ts

@@ -0,0 +1,79 @@
+import type { LucidClientLike, LucidRawRunner } from '../stores/lucid.js';
+/**
+ * A2A conversation state the agent tables do not carry: who a `contextId` belongs to, and the reply
+ * each `messageId` got (PACT §4.2, §4.3).
+ *
+ * A context belongs to a brand (the exposed agent) and to one personal-agent user — the pair
+ * `(agent issuer, sub)`. Once a turn in it has run under a delegation, it is also bound to that
+ * account: a token for another account is refused there, so one conversation never mixes two users'
+ * data (§5.5).
+ */
+export interface A2aContext {
+    /** The `contextId` — the agent thread's id. */
+    id: string;
+    /** The exposed agent (the "brand" in `/a2a/{brand}`). */
+    brand: string;
+    agentIssuer: string;
+    agentSub: string;
+    /** The account a delegated turn ran as; `null` until one does. */
+    accountRef: string | null;
+}
+/** Where a `messageId` stands: never seen (now claimed), still running, or answered. */
+export type MessageClaim = {
+    status: 'claimed';
+} | {
+    status: 'pending';
+} | {
+    status: 'done';
+    reply: unknown;
+};
+export interface A2aStore {
+    getContext(id: string): Promise<A2aContext | null>;
+    createContext(context: A2aContext): Promise<void>;
+    /**
+     * Bind the context to `accountRef` unless it is already bound. `true` when it is now bound to
+     * `accountRef` (either way), `false` when it was bound to someone else.
+     */
+    bindAccount(id: string, accountRef: string): Promise<boolean>;
+    /** Claim `messageId` in the context — atomically, so two deliveries of one message run once. */
+    claimMessage(contextId: string, messageId: string): Promise<MessageClaim>;
+    /** Store the reply a claimed message got, for its retries. */
+    completeMessage(contextId: string, messageId: string, reply: unknown): Promise<void>;
+    /** Drop a claim whose turn failed, so a retry runs it again instead of finding nothing. */
+    releaseMessage(contextId: string, messageId: string): Promise<void>;
+}
+/** Process-local {@link A2aStore} — tests and single-instance dev. */
+export declare class InMemoryA2aStore implements A2aStore {
+    #private;
+    getContext(id: string): Promise<A2aContext | null>;
+    createContext(context: A2aContext): Promise<void>;
+    bindAccount(id: string, accountRef: string): Promise<boolean>;
+    claimMessage(contextId: string, messageId: string): Promise<MessageClaim>;
+    completeMessage(contextId: string, messageId: string, reply: unknown): Promise<void>;
+    releaseMessage(contextId: string, messageId: string): Promise<void>;
+}
+export declare const A2A_TABLES: {
+    readonly contexts: 'agent_a2a_context';
+    readonly messages: 'agent_a2a_message';
+};
+/**
+ * `CREATE TABLE IF NOT EXISTS` DDL for the two A2A tables — same portable dialect as the agent
+ * tables (quoted identifiers, epoch-ms `BIGINT`, `TEXT` JSON). The message table's primary key IS the
+ * idempotency lock: two deliveries of one `messageId` race on the insert and one loses.
+ */
+export declare function a2aTableStatements(): string[];
+/** Create the A2A tables if missing. Idempotent. */
+export declare function ensureA2aTables(db: LucidRawRunner): Promise<void>;
+/** {@link A2aStore} over Lucid (any of SQLite / Postgres / MySQL). */
+export declare class LucidA2aStore implements A2aStore {
+    #private;
+    private readonly db;
+    constructor(db: LucidClientLike);
+    getContext(id: string): Promise<A2aContext | null>;
+    createContext(context: A2aContext): Promise<void>;
+    bindAccount(id: string, accountRef: string): Promise<boolean>;
+    claimMessage(contextId: string, messageId: string): Promise<MessageClaim>;
+    completeMessage(contextId: string, messageId: string, reply: unknown): Promise<void>;
+    releaseMessage(contextId: string, messageId: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/src/a2a/store.d.ts.map

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

package/dist/src/a2a/store.js

@@ -0,0 +1,151 @@
+/** Process-local {@link A2aStore} — tests and single-instance dev. */
+export class InMemoryA2aStore {
+    #contexts = new Map();
+    #messages = new Map();
+    async getContext(id) {
+        const found = this.#contexts.get(id);
+        return found ? { ...found } : null;
+    }
+    async createContext(context) {
+        this.#contexts.set(context.id, { ...context });
+    }
+    async bindAccount(id, accountRef) {
+        const context = this.#contexts.get(id);
+        if (!context)
+            return false;
+        if (context.accountRef === null)
+            context.accountRef = accountRef;
+        return context.accountRef === accountRef;
+    }
+    async claimMessage(contextId, messageId) {
+        const key = `${contextId}\n${messageId}`;
+        const found = this.#messages.get(key);
+        if (!found) {
+            this.#messages.set(key, { done: false });
+            return { status: 'claimed' };
+        }
+        return found.done ? { status: 'done', reply: found.reply } : { status: 'pending' };
+    }
+    async completeMessage(contextId, messageId, reply) {
+        this.#messages.set(`${contextId}\n${messageId}`, { done: true, reply });
+    }
+    async releaseMessage(contextId, messageId) {
+        this.#messages.delete(`${contextId}\n${messageId}`);
+    }
+}
+export const A2A_TABLES = {
+    contexts: 'agent_a2a_context',
+    messages: 'agent_a2a_message',
+};
+/**
+ * `CREATE TABLE IF NOT EXISTS` DDL for the two A2A tables — same portable dialect as the agent
+ * tables (quoted identifiers, epoch-ms `BIGINT`, `TEXT` JSON). The message table's primary key IS the
+ * idempotency lock: two deliveries of one `messageId` race on the insert and one loses.
+ */
+export function a2aTableStatements() {
+    const t = A2A_TABLES;
+    return [
+        `CREATE TABLE IF NOT EXISTS "${t.contexts}" (
+      "id" VARCHAR(255) PRIMARY KEY NOT NULL,
+      "brand" VARCHAR(255) NOT NULL,
+      "agent_issuer" VARCHAR(2048) NOT NULL,
+      "agent_sub" VARCHAR(255) NOT NULL,
+      "account_ref" VARCHAR(255) NULL,
+      "created_at" BIGINT NOT NULL
+    )`,
+        `CREATE TABLE IF NOT EXISTS "${t.messages}" (
+      "context_id" VARCHAR(255) NOT NULL,
+      "message_id" VARCHAR(255) NOT NULL,
+      "reply" TEXT NULL,
+      "created_at" BIGINT NOT NULL,
+      PRIMARY KEY ("context_id", "message_id")
+    )`,
+    ];
+}
+/** Create the A2A tables if missing. Idempotent. */
+export async function ensureA2aTables(db) {
+    for (const statement of a2aTableStatements()) {
+        await db.rawQuery(statement);
+    }
+}
+/** {@link A2aStore} over Lucid (any of SQLite / Postgres / MySQL). */
+export class LucidA2aStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getContext(id) {
+        const row = await this.db.from(A2A_TABLES.contexts).where('id', id).first();
+        if (!row)
+            return null;
+        return {
+            id: String(row.id),
+            brand: String(row.brand),
+            agentIssuer: String(row.agent_issuer),
+            agentSub: String(row.agent_sub),
+            accountRef: row.account_ref == null ? null : String(row.account_ref),
+        };
+    }
+    async createContext(context) {
+        await this.db.table(A2A_TABLES.contexts).insert({
+            id: context.id,
+            brand: context.brand,
+            agent_issuer: context.agentIssuer,
+            agent_sub: context.agentSub,
+            account_ref: context.accountRef,
+            created_at: Date.now(),
+        });
+    }
+    async bindAccount(id, accountRef) {
+        await this.db
+            .from(A2A_TABLES.contexts)
+            .where('id', id)
+            .whereNull('account_ref')
+            .update({ account_ref: accountRef });
+        // Re-read rather than trust the update count: a concurrent bind to the SAME account also wins.
+        const context = await this.getContext(id);
+        return context?.accountRef === accountRef;
+    }
+    async claimMessage(contextId, messageId) {
+        try {
+            await this.db.table(A2A_TABLES.messages).insert({
+                context_id: contextId,
+                message_id: messageId,
+                reply: null,
+                created_at: Date.now(),
+            });
+            return { status: 'claimed' };
+        }
+        catch (error) {
+            const row = await this.#message(contextId, messageId);
+            if (!row)
+                throw error;
+            return row.reply == null
+                ? { status: 'pending' }
+                : { status: 'done', reply: JSON.parse(String(row.reply)) };
+        }
+    }
+    async completeMessage(contextId, messageId, reply) {
+        await this.db
+            .from(A2A_TABLES.messages)
+            .where('context_id', contextId)
+            .where('message_id', messageId)
+            .update({ reply: JSON.stringify(reply) });
+    }
+    async releaseMessage(contextId, messageId) {
+        await this.db
+            .from(A2A_TABLES.messages)
+            .where('context_id', contextId)
+            .where('message_id', messageId)
+            .whereNull('reply')
+            .delete();
+    }
+    #message(contextId, messageId) {
+        return this.db
+            .from(A2A_TABLES.messages)
+            .where('context_id', contextId)
+            .where('message_id', messageId)
+            .first();
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/src/a2a/store.js.map

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

package/dist/src/a2a/turn.d.ts

@@ -0,0 +1,80 @@
+import type { AgentService } from '../agent-service.js';
+import type { Actor } from '../types.js';
+/**
+ * What an A2A turn does with an `action` call that parks for approval:
+ *  - `'approve-delegated'` (default) — approve it when the caller's delegation grants one of the
+ *    tool's roles: the user approved that scope on their own account page, which IS the consent the
+ *    in-app approval stands for. Anything else is rejected. An independent proposal
+ *    (`actionApprovalMode: 'independent'`) is decided the same way once the run ends, and the turn
+ *    waits for it to execute, so the reply never claims an action that did not happen.
+ *  - `'reject'` — reject every action; personal agents only read.
+ */
+export type A2aActionPolicy = 'approve-delegated' | 'reject';
+export interface A2aTurnInput {
+    actor: Actor;
+    text: string;
+    agentName: string;
+    /** Continue this thread; omitted → a new (transient) one. */
+    threadId?: string;
+    /** Scopes the caller's delegation grants; `null` without a delegation. */
+    delegatedScopes: string[] | null;
+    actions: A2aActionPolicy;
+    /** Give up (and cancel the run) after this long. */
+    timeoutMs: number;
+    /** Called once the run started, with the thread it runs in — before its frames are read. */
+    onStarted?: (threadId: string) => Promise<void>;
+}
+export interface A2aTurnAction {
+    tool: string;
+    argsHash: string;
+    /** The delegated scopes that authorized it. */
+    scopes: string[];
+}
+/**
+ * An independent proposal that executed during the turn: the app's own summary of it (the
+ * confirmation it would have shown the person) and what the tool returned.
+ */
+export interface A2aTurnOutcome {
+    tool: string;
+    status: 'succeeded';
+    summary: {
+        title: string;
+        detail?: string;
+    };
+    result?: unknown;
+}
+export interface A2aTurnResult {
+    threadId: string;
+    text: string;
+    /** Scopes the agent asked the user for (`request_permission`); `null` when it asked for none. */
+    permission: string[] | null;
+    /** Tools that RAN under a delegated scope (reads and approved actions) — what a receipt lists. */
+    actions: A2aTurnAction[];
+    /** Approved proposals that executed — the reply carries each as a data part. */
+    outcomes: A2aTurnOutcome[];
+    /** Why the run failed, when it did. */
+    error: string | null;
+}
+/**
+ * What runs an A2A turn: start it, read its frames, settle what it parks on. `AgentService` (the
+ * agent provider's) is one; an app with its own runtime — a `runAgentLoop` built per request, say —
+ * writes an adapter with the same shape (`defineA2aConfig({ service })`).
+ */
+export interface A2aTurnService extends Pick<AgentService, 'chat' | 'subscribe' | 'approve' | 'reject' | 'skip' | 'cancel'>, Partial<Pick<AgentService, 'decideActionProposal' | 'listActionProposals'>> {
+    /**
+     * The roles a tool declares — what an approval and a receipt match the delegated scopes against.
+     * Omitted → the shared `ToolRegistry`. An app whose registry is built per turn answers it here.
+     */
+    toolRoles?(toolName: string): string[] | undefined;
+}
+/**
+ * Run one A2A turn to completion and read its outcome off the stream. A2A's `message:send` is
+ * synchronous (PACT §4.2), so the run's frames are consumed here until the stream ends: text is the
+ * reply, an approval is decided on the spot by {@link A2aActionPolicy}, a question set is skipped
+ * (there is no human on this side to answer it — the agent proceeds on its own assumptions), and a
+ * `request_permission` call becomes a step-up.
+ */
+export declare function runA2aTurn(service: A2aTurnService, 
+/** The roles a tool declares (see {@link A2aTurnService.toolRoles}). */
+toolRoles: (toolName: string) => string[] | undefined, input: A2aTurnInput): Promise<A2aTurnResult>;
+//# sourceMappingURL=turn.d.ts.map

package/dist/src/a2a/turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.d.ts","sourceRoot":"","sources":["../../../src/a2a/turn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,QAAQ,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5B,kGAAkG;IAClG,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,gFAAgF;IAChF,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,uCAAuC;IACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,cACf,SAAQ,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC,EACzF,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,sBAAsB,GAAG,qBAAqB,CAAC,CAAC;IAC7E;;;OAGG;IACH,SAAS,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CACpD;AAWD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc;AACvB,wEAAwE;AACxE,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,EAAE,GAAG,SAAS,EACrD,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,aAAa,CAAC,CAgMxB"}