@poppykit/client 0.5.0 → 0.6.1

package/dist/operations.js

@@ -0,0 +1,261 @@
+import { randomBytes } from 'node:crypto';
+import { canonical, id as parseId, object, parseJson, retryAfterMilliseconds, validateJson } from './protocol/wire.js';
+import { approvalHeader, approvalMetaKey, captureApiOperationRequest, operationRequest, operationExpiry, parseBusinessOperation, requestFingerprint, supportsOperations } from './protocol/operations.js';
+export class OperationClientError extends Error {
+    code;
+    constructor(code) {
+        super('Business operation ' + code);
+        this.code = code;
+    }
+}
+export function createOperationClient(options) {
+    const now = options.now ?? Date.now;
+    const sending = new Map();
+    const token = () => randomBytes(24).toString('base64url');
+    function sameContext(a, b) {
+        return a.companyId === b.companyId && a.clientId === b.clientId && a.userId === b.userId && a.authority === b.authority;
+    }
+    async function context(requireSupport = false) {
+        const value = await options.context();
+        if (requireSupport && !value.operations)
+            throw new OperationClientError('not_negotiated');
+        return value;
+    }
+    async function withAttempt(id, action) {
+        const current = await context();
+        return options.store.transaction(id, slot => {
+            if (!slot.record || slot.record.version !== 1)
+                throw new OperationClientError('unknown_attempt');
+            if (!sameContext(slot.record.context, current))
+                throw new OperationClientError('owner_changed');
+            return action(slot.record);
+        });
+    }
+    async function receive(id, request, value, headers) {
+        parseId(id, 'attempt_id');
+        const current = await context(true), operation = parseBusinessOperation(value), binding = operationRequest(request);
+        return options.store.transaction(id, slot => {
+            if (slot.record) {
+                const old = slot.record;
+                if (old.version !== 1)
+                    throw new OperationClientError('unsupported_version');
+                if (!sameContext(old.context, current))
+                    throw new OperationClientError('owner_changed');
+                if (canonical(old.operation) === canonical(operation) && requestFingerprint(old.request) === requestFingerprint(binding))
+                    return structuredClone(old);
+                if (old.operation.operation_id === operation.operation_id && old.operation.revision === operation.revision)
+                    throw new OperationClientError('revision_changed');
+                if (['uncertain', 'completed'].includes(old.phase))
+                    throw new OperationClientError('attempt_uncertain');
+            }
+            const record = { version: 1, id, context: current, request: binding, operation, phase: operationExpiry(operation.expires_at) <= now() ? 'expired' : 'pending_consent', messageId: token(), ...(headers ? { headers } : {}) };
+            if (slot.record)
+                record.previousDecisions = [...(slot.record.previousDecisions ?? []), { revision: slot.record.operation.revision, phase: slot.record.phase }];
+            slot.record = record;
+            return structuredClone(record);
+        });
+    }
+    return {
+        receive,
+        async receiveApi(id, request, response) {
+            if (response.status !== 403)
+                throw new OperationClientError('not_operation');
+            const body = object(parseJson(await response.clone().text()));
+            if (body.error !== 'approval_required')
+                throw new OperationClientError('not_operation');
+            const headers = [...request.headers].filter(([key]) => !['authorization', 'poppy-session', 'poppy-approval', 'dpop', 'cookie', 'idempotency-key'].includes(key));
+            return receive(id, await captureApiOperationRequest(request), body.operation, headers);
+        },
+        async receiveMcp(id, request, result) {
+            const body = object(result);
+            if (body.isError !== true)
+                throw new OperationClientError('not_operation');
+            return receive(id, request, object(body.structuredContent).operation);
+        },
+        async receiveConversation(id, request, message) {
+            const body = object(message);
+            if (body.role !== 'company')
+                throw new OperationClientError('not_operation');
+            return receive(id, request, body.operation);
+        },
+        async recover(after, limit = 100) {
+            const result = [];
+            for (const id of await options.store.pending(after, limit)) {
+                try {
+                    result.push(await withAttempt(id, record => structuredClone(record)));
+                }
+                catch (error) {
+                    if (!(error instanceof OperationClientError))
+                        throw error;
+                    result.push({ id, error: error.code });
+                }
+            }
+            return result;
+        },
+        get(id) { return withAttempt(id, record => structuredClone(record)); },
+        async requestConsent(id) {
+            await context(true);
+            const selected = await withAttempt(id, record => {
+                if (record.phase !== 'pending_consent')
+                    throw new OperationClientError('consent_not_pending');
+                if (operationExpiry(record.operation.expires_at) <= now()) {
+                    record.phase = 'expired';
+                    return structuredClone(record);
+                }
+                record.phase = 'consenting';
+                record.consentToken = token();
+                return structuredClone(record);
+            });
+            if (selected.phase === 'expired')
+                return selected;
+            let answer;
+            try {
+                const differences = await options.checkTerms(structuredClone(selected.request), structuredClone(selected.operation));
+                if (!Array.isArray(differences) || differences.some(value => typeof value !== 'string'))
+                    throw new OperationClientError('invalid_terms_check');
+                answer = await options.consent.confirm({ attemptId: id, companyId: selected.context.companyId, companyName: selected.context.companyName, summary: selected.operation.summary, ...(selected.operation.terms ? { terms: structuredClone(selected.operation.terms) } : {}), differences });
+                if (answer !== 'approve' && answer !== 'decline')
+                    throw new OperationClientError('invalid_consent');
+            }
+            catch {
+                throw new OperationClientError('consent_interrupted');
+            }
+            return withAttempt(id, record => {
+                if (record.phase !== 'consenting' || record.consentToken !== selected.consentToken)
+                    throw new OperationClientError('consent_withdrawn');
+                delete record.consentToken;
+                record.phase = operationExpiry(record.operation.expires_at) <= now() ? 'expired' : answer === 'approve' ? 'approved' : 'declined';
+                return structuredClone(record);
+            });
+        },
+        /** Explicitly dismiss the old UI first. Its late callback is fenced; a fresh answer is required. */
+        resumeConsent(id) {
+            return withAttempt(id, record => { if (record.phase !== 'consenting')
+                throw new OperationClientError('consent_not_interrupted'); delete record.consentToken; record.phase = 'pending_consent'; return structuredClone(record); });
+        },
+        withdraw(id) {
+            for (const controller of sending.get(id) ?? [])
+                controller.abort();
+            return withAttempt(id, record => {
+                if (record.phase === 'uncertain') {
+                    record.withdrawalRequested = true;
+                    return structuredClone(record);
+                }
+                if (!['pending_consent', 'consenting', 'approved'].includes(record.phase))
+                    throw new OperationClientError('already_sent');
+                delete record.consentToken;
+                record.phase = 'withdrawn';
+                return structuredClone(record);
+            });
+        },
+        async retry(id) {
+            await context(true);
+            const controller = new AbortController(), active = sending.get(id) ?? new Set();
+            active.add(controller);
+            sending.set(id, active);
+            try {
+                const selected = await withAttempt(id, record => {
+                    if (record.withdrawalRequested)
+                        throw new OperationClientError('approval_withdrawn');
+                    if (!['approved', 'uncertain'].includes(record.phase))
+                        throw new OperationClientError('not_approved');
+                    if (record.retryAt && record.retryAt > now())
+                        throw new OperationClientError('retry_later');
+                    if (record.phase === 'approved' && operationExpiry(record.operation.expires_at) <= now()) {
+                        record.phase = 'expired';
+                        return structuredClone(record);
+                    }
+                    // Commit before dispatch. Crash/timeout recovery retains this exact approval, request and message ID.
+                    record.phase = 'uncertain';
+                    return structuredClone(record);
+                });
+                if (selected.phase === 'expired')
+                    return selected;
+                let outcome;
+                try {
+                    controller.signal.throwIfAborted();
+                    await withAttempt(id, record => { if (record.withdrawalRequested)
+                        controller.abort(); });
+                    controller.signal.throwIfAborted();
+                    outcome = await options.send(selected, { operation_id: selected.operation.operation_id, revision: selected.operation.revision }, controller.signal);
+                }
+                catch {
+                    return withAttempt(id, record => structuredClone(record));
+                }
+                return withAttempt(id, record => {
+                    if (record.phase === 'completed')
+                        return structuredClone(record);
+                    if (outcome.kind === 'completed') {
+                        validateJson(outcome.result);
+                        record.result = structuredClone(outcome.result);
+                        record.phase = 'completed';
+                    }
+                    else if (outcome.retryAfterMs !== undefined)
+                        record.retryAt = Math.min(Number.MAX_SAFE_INTEGER, now() + outcome.retryAfterMs);
+                    return structuredClone(record);
+                });
+            }
+            finally {
+                active.delete(controller);
+                if (!active.size)
+                    sending.delete(id);
+            }
+        },
+        /** Trusted host lookup of actual business state; an operation returned on retry is not reconciliation. */
+        async reconcile(id, lookup) {
+            const selected = await withAttempt(id, record => { if (record.phase !== 'uncertain')
+                throw new OperationClientError('not_uncertain'); return structuredClone(record); });
+            const outcome = await lookup(selected);
+            return withAttempt(id, record => {
+                if (record.phase === 'completed')
+                    return structuredClone(record);
+                if (outcome.kind === 'completed') {
+                    validateJson(outcome.result);
+                    record.result = structuredClone(outcome.result);
+                    record.phase = 'completed';
+                }
+                return structuredClone(record);
+            });
+        },
+    };
+}
+export function approvedApiRequest(attempt, approval, signal) {
+    if (attempt.request.channel !== 'api')
+        throw new OperationClientError('wrong_channel');
+    const headers = new Headers(attempt.headers);
+    headers.delete('idempotency-key');
+    headers.set('poppy-approval', approvalHeader(approval));
+    return new Request(attempt.request.url, { method: attempt.request.method, headers, signal, body: attempt.request.body === null ? null : Buffer.from(attempt.request.body, 'base64'), redirect: 'manual' });
+}
+export function approvedMcpParams(attempt, approval) {
+    if (attempt.request.channel !== 'mcp')
+        throw new OperationClientError('wrong_channel');
+    return { name: attempt.request.name, arguments: structuredClone(attempt.request.arguments), _meta: { [approvalMetaKey]: approval } };
+}
+export function approvedConversationMessage(attempt, approval) {
+    if (attempt.request.channel !== 'conversation')
+        throw new OperationClientError('wrong_channel');
+    return { id: attempt.messageId, author: { type: 'agent' }, approval };
+}
+/** Adapters must use verified SDK channel targets and current authorization; a conversation acceptance is still pending work. */
+export function createOperationSender(channels) {
+    return async (attempt, approval, signal) => {
+        if (attempt.request.channel === 'api') {
+            const response = await channels.api(approvedApiRequest(attempt, approval, signal), attempt.context);
+            if (response.status === 202 || !response.ok) {
+                await response.body?.cancel();
+                return { kind: 'pending', retryAfterMs: retryAfterMilliseconds(response.headers.get('retry-after'), Date.now()) };
+            }
+            return { kind: 'completed', result: { status: response.status, headers: [...response.headers].filter(([name]) => !['set-cookie', 'authorization', 'poppy-session', 'dpop'].includes(name)), body: Buffer.from(await response.arrayBuffer()).toString('base64') } };
+        }
+        if (attempt.request.channel === 'mcp') {
+            const result = await channels.mcp(attempt.request.url, approvedMcpParams(attempt, approval), signal, attempt.context);
+            if (result.isError === true)
+                return { kind: 'pending' };
+            return { kind: 'completed', result };
+        }
+        await channels.conversation(attempt.request, approvedConversationMessage(attempt, approval), signal, attempt.context);
+        return { kind: 'pending' };
+    };
+}
+export { supportsOperations };

package/dist/postgres-runtime.js

@@ -35,6 +35,9 @@ export async function postgresMigration(schema) {
 export async function migratePostgres(pool, schema) {
     schemaName(schema);
     const client = await pool.connect();
+    let connectionError;
+    const onError = (error) => { connectionError = error; };
+    client.on('error', onError);
     try {
         await client.query('BEGIN');
         await client.query("SET LOCAL statement_timeout='5s'");
@@ -50,11 +53,12 @@ export async function migratePostgres(pool, schema) {
         await client.query('COMMIT');
     }
     catch (error) {
-        await client.query('ROLLBACK');
+        await client.query('ROLLBACK').catch((failure) => { connectionError = failure; });
         throw error;
     }
     finally {
-        client.release();
+        client.release(connectionError);
+        client.removeListener('error', onError);
     }
 }
 function scopeActive(context) {
@@ -144,6 +148,9 @@ export class PostgresRuntime {
             }
         }
         const client = await this.pool.connect(), context = { client, active: true, locks: new Set(), state: { serial: 0, active: true }, childActive: false };
+        let connectionError;
+        const onError = (error) => { connectionError = error; context.state.active = false; };
+        client.on('error', onError);
         try {
             await client.query('BEGIN');
             await client.query("SET LOCAL statement_timeout='5s'");
@@ -161,13 +168,14 @@ export class PostgresRuntime {
         }
         catch (error) {
             context.state.active = false;
-            await client.query('ROLLBACK').catch(() => { });
+            await client.query('ROLLBACK').catch((failure) => { connectionError = failure; });
             throw error;
         }
         finally {
             context.active = false;
             context.state.active = false;
-            client.release();
+            client.release(connectionError);
+            client.removeListener('error', onError);
         }
     }
     connection() {

package/dist/postgres.d.ts

@@ -1,3 +1,4 @@
+import type { BusinessAttemptStore } from './operations.js';
 import type { Pool } from 'pg';
 import type { ClientAuthState } from './auth/client-auth.js';
 import type { AuthSelection, AuthStore } from './auth/store.js';
@@ -37,3 +38,13 @@ export declare class PostgresConversationStore implements ConversationStore {
     advanceCheckpoint(key: ConversationKey, row: ConsumerCheckpoint, from: readonly (string | undefined)[]): Promise<void>;
     resetCheckpoint(key: ConversationKey, conversation: string, name: string): Promise<void>;
 }
+export declare class PostgresBusinessAttemptStore implements BusinessAttemptStore {
+    readonly namespace: string;
+    private readonly db;
+    constructor(pool: Pool, namespace: string);
+    close(): Promise<void>;
+    pending(after: string | undefined, limit: number): Promise<string[]>;
+    transaction<T>(id: string, action: (slot: {
+        record?: import('./operations.js').BusinessAttempt;
+    }) => T): Promise<T>;
+}

package/dist/postgres.js

@@ -27,7 +27,7 @@ export class PostgresAuthStore {
             for (const row of await this.db.query(`SELECT id,body FROM poppy_client.records WHERE ns=$1 AND kind=$2 ${where}`, [this.namespace, table, ...values]))
                 state[table][row.id] = JSON.parse(row.body);
         };
-        if (state.version === 1) {
+        if (state.version === 1 || state.version === 2) {
             for (const table of tables)
                 await rows(table, '');
             upgradeClientAuthState(state);
@@ -38,12 +38,16 @@ export class PostgresAuthStore {
             for (const table of tables)
                 state[table] = {};
         }
-        if (state.version !== 2)
+        if (state.version !== 3)
             throw new Error('unsupported auth state version');
         if ('issuer' in selection)
             await one('identities', selection.issuer);
         else {
-            if ('connectionId' in selection)
+            if ('account' in selection) {
+                await one('identities', selection.account.issuer);
+                await rows('connections', "AND body::jsonb->>'issuer'=$3 AND body::jsonb->>'userId'=$4", [selection.account.issuer, selection.account.userId]);
+            }
+            else if ('connectionId' in selection)
                 await one('connections', selection.connectionId);
             else if ('operationId' in selection)
                 await one('operations', selection.operationId);
@@ -53,6 +57,9 @@ export class PostgresAuthStore {
                 await rows('connections', '');
             for (const operation of Object.values(state.operations))
                 await one('connections', operation.connectionId);
+            const linked = new Set([...Object.values(state.connections).map(row => row.grantId), ...Object.values(state.operations).map(row => row.grantId)].filter((id) => id !== null));
+            for (const grantId of linked)
+                await rows('connections', "AND body::jsonb->>'grantId'=$3", [grantId]);
             for (const connection of Object.values(state.connections)) {
                 if (connection.grantId)
                     await one('grants', connection.grantId);
@@ -156,3 +163,33 @@ export class PostgresConversationStore {
     }
     resetCheckpoint(key, conversation, name) { return this.db.run(async () => { const values = this.checkpointValues(key, conversation, name); await this.db.lock(JSON.stringify(['checkpoint', ...values])); await this.db.query('DELETE FROM poppy_client.checkpoints WHERE ns=$1 AND connection=$2 AND issuer=$3 AND endpoint=$4 AND conversation=$5 AND name=$6', values); }); }
 }
+export class PostgresBusinessAttemptStore {
+    namespace;
+    db;
+    constructor(pool, namespace) {
+        this.namespace = namespace;
+        this.db = new PostgresRuntime(pool, 'poppy_client');
+    }
+    close() { return this.db.close(); }
+    pending(after, limit) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('business recovery limit');
+        return this.db.run(async () => (await this.db.query("SELECT id FROM poppy_client.records WHERE ns=$1 AND kind='business_attempts' AND id COLLATE \"C\">$2 AND body::jsonb->>'phase' IN ('pending_consent','consenting','approved','uncertain') ORDER BY id COLLATE \"C\" LIMIT $3", [this.namespace, after ?? '', limit])).map(row => row.id));
+    }
+    transaction(id, action) {
+        return this.db.run(async () => {
+            await this.db.lock(JSON.stringify([this.namespace, 'business_attempts', id]));
+            const row = (await this.db.query("SELECT body FROM poppy_client.records WHERE ns=$1 AND kind='business_attempts' AND id=$2", [this.namespace, id]))[0];
+            const slot = { record: row ? JSON.parse(row.body) : undefined };
+            if (slot.record && slot.record.version !== 1)
+                throw new Error('unsupported business attempt version');
+            const result = synchronous(action(slot));
+            if (slot.record) {
+                if (slot.record.version !== 1 || slot.record.id !== id)
+                    throw new TypeError('business attempt binding');
+                await this.db.query("INSERT INTO poppy_client.records(ns,kind,id,body) VALUES($1,'business_attempts',$2,$3) ON CONFLICT(ns,kind,id) DO UPDATE SET body=excluded.body", [this.namespace, id, json(slot.record)]);
+            }
+            return result;
+        });
+    }
+}

package/dist/protocol/operations.d.ts

@@ -0,0 +1,51 @@
+import type { JsonObject } from './wire.js';
+export interface BusinessOperation {
+    operation_id: string;
+    revision: string;
+    summary: string;
+    terms?: JsonObject;
+    expires_at: string;
+    [key: string]: unknown;
+}
+export interface OperationApproval {
+    operation_id: string;
+    revision: string;
+    [key: string]: unknown;
+}
+export declare const operationsV2: {
+    readonly version: "2";
+};
+export declare function supportsOperations(document: {
+    extensions?: unknown;
+}): boolean;
+export declare function parseBusinessOperation(value: unknown): BusinessOperation;
+/** RFC3339 permits a leap second; JavaScript Date.parse does not. */
+export declare function operationExpiry(value: string): number;
+export declare function parseOperationApproval(value: unknown): OperationApproval;
+export declare function parseApprovalHeader(value: string | null): OperationApproval | undefined;
+export declare function approvalHeader(value: OperationApproval): string;
+export declare const approvalMetaKey = "personalagentprotocol.org/approval";
+export declare function mcpApproval(params: unknown): OperationApproval | undefined;
+export type OperationRequest = {
+    channel: 'api';
+    method: string;
+    url: string;
+    body: string | null;
+} | {
+    channel: 'mcp';
+    url: string;
+    name: string;
+    arguments: JsonObject;
+} | {
+    channel: 'conversation';
+    endpoint: string;
+    conversationId: string;
+};
+export declare function operationRequest(value: OperationRequest): OperationRequest;
+export declare function requestFingerprint(value: OperationRequest): string;
+export declare function operationRequiredResponse(operation: BusinessOperation): Response;
+export declare function operationToolError(operation: BusinessOperation): JsonObject;
+/** Base64 preserves exact API body bytes. Bind the complete URL, including its query. */
+export declare function captureApiOperationRequest(request: Request): Promise<Extract<OperationRequest, {
+    channel: 'api';
+}>>;

package/dist/protocol/operations.js

@@ -0,0 +1,98 @@
+import { parse, serialize, getMember } from '@agentsig/structured-fields';
+import { canonical, id, object, string, ValidationError } from './wire.js';
+import { secureUrl } from '../network/transport.js';
+export const operationsV2 = { version: '2' };
+export function supportsOperations(document) {
+    const extensions = document.extensions;
+    return !!extensions && typeof extensions === 'object' && !Array.isArray(extensions)
+        && extensions.operations?.version === '2';
+}
+export function parseBusinessOperation(value) {
+    const operation = object(value, 'operation');
+    id(operation.operation_id, 'operation.operation_id');
+    id(operation.revision, 'operation.revision');
+    string(operation.summary, 'operation.summary');
+    if ('terms' in operation)
+        object(operation.terms, 'operation.terms');
+    const date = string(operation.expires_at, 'operation.expires_at');
+    const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|[+-](\d{2}):(\d{2}))$/.exec(date);
+    if (!match)
+        throw new ValidationError('operation.expires_at');
+    const [, y, m, d, h, min, s, oh = '0', om = '0'] = match;
+    const monthEnd = new Date(0);
+    monthEnd.setUTCFullYear(+y, +m, 0);
+    const days = monthEnd.getUTCDate();
+    if (+m < 1 || +m > 12 || +d < 1 || +d > days || +h > 23 || +min > 59 || +s > 60 || +oh > 23 || +om > 59 || !Number.isFinite(operationExpiry(date)))
+        throw new ValidationError('operation.expires_at');
+    return structuredClone(operation);
+}
+/** RFC3339 permits a leap second; JavaScript Date.parse does not. */
+export function operationExpiry(value) {
+    return /:60(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/.test(value)
+        ? Date.parse(value.replace(/:60(?=\.\d+|[Zz]|[+-])/, ':59')) + 1000 : Date.parse(value);
+}
+export function parseOperationApproval(value) {
+    const approval = object(value, 'approval');
+    id(approval.operation_id, 'approval.operation_id');
+    id(approval.revision, 'approval.revision');
+    return { ...approval };
+}
+export function parseApprovalHeader(value) {
+    if (value === null)
+        return;
+    try {
+        const dictionary = parse(value, 'dictionary');
+        const text = (name) => { const member = getMember(dictionary, name); return member?.kind === 'item' && member.bare.kind === 'string' ? member.bare.value : undefined; };
+        return parseOperationApproval({ operation_id: text('operation_id'), revision: text('revision') });
+    }
+    catch {
+        return;
+    } // Invalid Structured Fields are ignored as a whole (RFC 9651 section 2.2).
+}
+export function approvalHeader(value) {
+    const approval = parseOperationApproval(value);
+    return serialize({ kind: 'dictionary', entries: [
+            ['operation_id', { kind: 'item', bare: { kind: 'string', value: approval.operation_id }, parameters: [] }],
+            ['revision', { kind: 'item', bare: { kind: 'string', value: approval.revision }, parameters: [] }],
+        ] });
+}
+export const approvalMetaKey = 'personalagentprotocol.org/approval';
+export function mcpApproval(params) {
+    const meta = object(params, 'params')._meta;
+    if (meta === undefined)
+        return;
+    const value = object(meta, '_meta')[approvalMetaKey];
+    return value === undefined ? undefined : parseOperationApproval(value);
+}
+export function operationRequest(value) {
+    object(value, 'operation.request');
+    if (value.channel === 'api') {
+        secureUrl(value.url);
+        if (!/^[A-Z]+$/.test(value.method) || !(value.body === null || typeof value.body === 'string'))
+            throw new ValidationError('operation.request');
+    }
+    else if (value.channel === 'mcp') {
+        secureUrl(value.url);
+        string(value.name, 'tool.name');
+        object(value.arguments, 'tool.arguments');
+    }
+    else if (value.channel === 'conversation') {
+        secureUrl(value.endpoint);
+        id(value.conversationId, 'conversation_id');
+    }
+    else
+        throw new ValidationError('operation.channel');
+    return structuredClone(value);
+}
+export function requestFingerprint(value) { return canonical(operationRequest(value)); }
+export function operationRequiredResponse(operation) {
+    return Response.json({ error: 'approval_required', operation: parseBusinessOperation(operation) }, { status: 403, headers: { 'Cache-Control': 'no-store' } });
+}
+export function operationToolError(operation) {
+    const parsed = parseBusinessOperation(operation);
+    return { isError: true, content: [{ type: 'text', text: parsed.summary }], structuredContent: { operation: parsed } };
+}
+/** Base64 preserves exact API body bytes. Bind the complete URL, including its query. */
+export async function captureApiOperationRequest(request) {
+    return { channel: 'api', method: request.method, url: request.url, body: request.body === null ? null : Buffer.from(await request.clone().arrayBuffer()).toString('base64') };
+}

package/dist/protocol/session.d.ts

@@ -0,0 +1,28 @@
+import type { MetadataResolver } from '../network/discovery.js';
+export interface SessionClaims {
+    iss: string;
+    aud: string;
+    sid: string;
+    sub: string;
+    agent_id?: string;
+    htm: string;
+    htu: string;
+    iat: number;
+    jti: string;
+    ath?: string;
+}
+export interface VerifiedSession extends SessionClaims {
+    delegationExpiresAt: number;
+}
+export declare function sessionRequestUrl(value: string): string;
+export declare function parseSessionClaims(value: unknown): SessionClaims;
+/** Verifies identity only. The resource must separately admit/continue the client_id + sid under its store fence. */
+export declare function verifySessionJwt(jwt: string | null, expected: {
+    companyId: string;
+    method: string;
+    url: string;
+    nowMs: number;
+    metadata: MetadataResolver;
+    accessToken?: string;
+    tokenClientId?: string;
+}): Promise<VerifiedSession>;