sealbridge 0.0.1 → 0.2.0

package/dist/packages/runtime/dist/session.d.ts

@@ -0,0 +1,323 @@
+import type { Json, KeyPair, Schema, TaskManifest, Signed, SignedAgentCard, SignedEnvelope, CapabilityToken, BudgetSpec, OpenPolicy, RevocationList, Invite, SignedRevocationNotice } from '@acp/core';
+import { type AuditBundle, type AuditEntry } from '@acp/ledger';
+import type { RelayClientSecurityOptions, RelayTransport, RelayConnectionStatus } from '@acp/relay';
+import type { AgentAdapter, ProgressPayload, ProtocolEnvelope } from './adapter.js';
+import type { ApprovalProvider, WorkerAcceptancePolicy } from './approval-providers.js';
+import type { ToolBackend, ToolDefinition } from './mcp.js';
+import { VerificationEngine } from './verifier.js';
+import type { VerificationResult } from './verifier.js';
+import { PeerRejectedError } from './session-audit.js';
+import type { SessionTimeoutOptions } from './session-timeouts.js';
+export type { SessionTimeoutOptions } from './session-timeouts.js';
+export interface WorkspaceCleanupFailure {
+    taskId: string;
+    workspaceDir: string;
+    code: string;
+}
+export interface SessionResult {
+    taskId: string;
+    state: 'SETTLED' | 'CANCELLED';
+    deliverable: Json | null;
+    bundle: AuditBundle;
+    verification?: VerificationResult;
+}
+/** Daemon workers stay finite unless the owner raises the cap. */
+export declare const DEFAULT_MAX_CONCURRENT_TASKS = 8;
+export interface WorkerNodeOptions extends WorkerAcceptancePolicy, SessionTimeoutOptions {
+    /** Startup invite and signed card lifetime in seconds. Default 86400 (24 hours). */
+    inviteTtlSeconds?: number;
+    /** Shared host state, independent of requester and worker identity. */
+    dailyLimit?: {
+        path: string;
+        maxTasks: number;
+    };
+    /** Explicit admission policy. Defaults to invite-only. */
+    accessMode?: 'invite-only' | 'open';
+    openPolicy?: OpenPolicy;
+    owner: KeyPair;
+    relay: RelayTransport | string;
+    relayUrl?: string;
+    adapter: AgentAdapter;
+    name?: string;
+    agentDid?: string;
+    /** Controls agentDid when it is not owner.did. Required to sign the delegation. */
+    agentKey?: KeyPair;
+    approvalProvider?: ApprovalProvider;
+    /** Bilateral audit path; enables adjacent task checkpoints when inboxPath is absent. */
+    auditPath?: string;
+    /** Append accepted messages as private JSONL; also enables adjacent task checkpoints. */
+    inboxPath?: string;
+    /** Best-effort notification after a successful inbox append; never awaited. */
+    onInboxRecord?: (record: string) => void | Promise<void>;
+    tools?: Record<string, ToolDefinition>;
+    toolBackend?: ToolBackend;
+    revocation?: RevocationList;
+    /** Residual workspace after bounded cleanup retries. Defaults to a console warning. */
+    onWorkspaceCleanupError?: (failure: WorkspaceCleanupFailure) => void | Promise<void>;
+    onStatus?: (status: RelayConnectionStatus, error?: Error) => void;
+    onEvent?: (event: string, taskId: string, error?: ErrorDiagnostic) => void;
+    /** Opt in to loopback and RFC1918 relays. Network invites stay blocked by default. */
+    allowPrivateRelay?: boolean;
+    lookup?: RelayClientSecurityOptions['lookup'];
+    /**
+     * Accept cleartext session envelopes. Default false: PROPOSE and later frames
+     * throw UNENCRYPTED_ENVELOPE_REJECTED unless they were encrypted to this owner.
+     */
+    allowUnencryptedEnvelopes?: boolean;
+}
+export declare class WorkerNode {
+    readonly options: WorkerNodeOptions;
+    readonly relay: RelayTransport;
+    readonly agentCard: SignedAgentCard;
+    readonly approvalProvider: ApprovalProvider;
+    readonly acceptance: WorkerAcceptancePolicy;
+    private completed;
+    private activeTasks;
+    private readonly taskJournal?;
+    private reconciled;
+    private readonly proposalTimes;
+    private readonly mailboxes;
+    private readonly forwardedQueue;
+    private readonly forwardedWaiters;
+    readonly controller: AbortController;
+    lastResult?: SessionResult;
+    /** Notices learned from the relay inbox. Always present, even without options.revocation. */
+    private readonly inboxRevocations;
+    /** Capability notices whose issuer is not yet matched to a verified chain. */
+    private readonly pendingCapabilities;
+    /** Chains that passed verifyCapabilityChain, so a later REVOKE can hit callTool. */
+    private readonly liveChains;
+    /** Inbox registry composed with options.revocation when the caller passed one. */
+    readonly revocation: RevocationList;
+    constructor(options: WorkerNodeOptions);
+    invite(expiresInSeconds?: number): string;
+    register(): Promise<void>;
+    stop(): void;
+    /** Public registration is opt-in, including for PolicyAutoApprovalProvider. */
+    private publishes;
+    private get concurrentLimit();
+    private rateBudget;
+    /** Count a PROPOSE from this requester. Returns a reason when the window is full. */
+    private consumeRate;
+    /** Budget, allowlist, and rate checks that can be decided before execution starts. */
+    private intakeRejection;
+    private status?;
+    private listenerStatus;
+    private listen;
+    start(options?: {
+        once?: boolean;
+        signal?: AbortSignal;
+    }): Promise<SessionResult | undefined>;
+    private notifyOutcome;
+    private reconcileTasks;
+    private sealedTaskResult;
+    private recoverProposal;
+    private deliver;
+    /** Local signed diagnostics are separate from the bilateral hash-chain ledger. */
+    private reportRejection;
+    private beginTask;
+    /** Keep reading the shared inbox until a single task finishes, without dropping its peer's mail. */
+    private pumpUntil;
+    runOnce(signal?: AbortSignal): Promise<SessionResult>;
+    private executeTask;
+    /**
+     * Hide REVOKE envelopes from task reads. start, runOnce, and pumpUntil all
+     * receive through this relay, so a FIFO head of one or more REVOKE messages
+     * is applied before the following PROPOSE is observed.
+     */
+    private isRequesterBoundFrame;
+    private revocationAwareRelay;
+    /** True when the envelope was a REVOKE and must not be treated as a proposal. */
+    private consumeRevocation;
+    private ingestRevocation;
+    private recordNotice;
+    private assertInviteActive;
+    /**
+     * Before ACCEPT, every verified capability chain is checked against revocation
+     * notices. A notice is stored and applied only when its issuer signed that
+     * token or an ancestor in a chain that has passed verifyCapabilityChain.
+     * An unverified chain, including one whose payload.issuer was rewritten,
+     * cannot promote a pending notice into the registry.
+     */
+    private assertCapabilitiesActive;
+    private verifiedEntries;
+    private promotePending;
+    private verifiedChainRevoked;
+    /**
+     * Pending and stored notices apply only when their issuer controls this
+     * verified token. A bare target-id hit from another issuer does not.
+     */
+    private capabilityTargetRevoked;
+    private listedNotices;
+    private rememberChains;
+    private verifiedLiveEntries;
+    private capabilityNoticeAuthorized;
+    private sameCapabilityTarget;
+}
+export interface ErrorDetail {
+    field: string;
+    expected: string;
+    actual: string;
+    hint: string;
+}
+export interface ErrorDiagnostic {
+    code: string;
+    detail?: ErrorDetail;
+}
+export interface RequesterClientOptions extends SessionTimeoutOptions {
+    owner: KeyPair;
+    relay?: RelayTransport | string;
+    approvalProvider?: ApprovalProvider;
+    verificationEngine?: VerificationEngine;
+    auditPath?: string;
+    allowPrivateRelay?: boolean;
+    /** DNS resolver used before a string relay URL is dialed. */
+    lookup?: RelayClientSecurityOptions['lookup'];
+    /**
+     * Accept cleartext session envelopes. Default false: ACCEPT, PROGRESS, DELIVER,
+     * and the other session frames throw UNENCRYPTED_ENVELOPE_REJECTED.
+     */
+    allowUnencryptedEnvelopes?: boolean;
+}
+export interface DelegateOptions extends SessionTimeoutOptions {
+    to: string;
+    discover?: {
+        skillId?: string;
+        taskType?: string;
+    };
+    relay?: RelayTransport | string;
+    title: string;
+    description: string;
+    input: Json;
+    outputSchema?: Schema;
+    budget?: Partial<BudgetSpec>;
+    manifest?: TaskManifest;
+    auditPath?: string;
+    signal?: AbortSignal;
+    capabilities?: TaskManifest['permissions']['grantedCapabilities'];
+    /**
+     * Chains to send on PROPOSE. When omitted, chains are minted from
+     * grantedCapabilities. Supply them to revoke a known token id before send.
+     */
+    capabilityChains?: CapabilityToken[][];
+    minimumIsolationLevel?: string;
+    onProgress?: (progress: ProgressPayload, envelope: ProtocolEnvelope<ProgressPayload>) => void | Promise<void>;
+}
+export interface DelegateWorkerTarget {
+    workerDid: string;
+    inviteToken?: string | Signed<Invite>;
+    relayUrl?: string;
+}
+export interface DelegateReceipt {
+    workerDid: string;
+    taskId: string;
+    outputDigest: string;
+    deliverable: Json;
+    bundle: AuditBundle;
+    accepted: boolean;
+}
+/** Locally verified delivery whose bilateral checkpoint did not finish. Never an audit bundle. */
+export interface IncompleteDelegateReceipt extends Omit<DelegateReceipt, 'bundle'> {
+    checkpointComplete: false;
+    delivery: SignedEnvelope;
+    verification: VerificationResult;
+    entries: AuditEntry[];
+    completionError: string;
+}
+/** Completion failure preserves local verification without claiming a sealed checkpoint. */
+export declare class IncompleteSettlementError extends Error {
+    readonly incompleteReceipt: IncompleteDelegateReceipt;
+    readonly code?: string;
+    readonly detail?: ErrorDetail;
+    readonly recovery?: PeerRejectedError['recovery'];
+    constructor(incompleteReceipt: IncompleteDelegateReceipt, cause: unknown);
+}
+export interface DelegateMultiResult {
+    mode: 'race' | 'quorum';
+    status: 'SETTLED';
+    deliverable: Json;
+    outputDigest: string;
+    taskIds: string[];
+    winners: Array<{
+        workerDid: string;
+        taskId: string;
+        outputDigest: string;
+    }>;
+    receipts: DelegateReceipt[];
+    incompleteReceipts: IncompleteDelegateReceipt[];
+    cancelled: string[];
+}
+export interface DelegateMultiOptions extends SessionTimeoutOptions {
+    workers: DelegateWorkerTarget[];
+    mode: 'race' | 'quorum';
+    quorumSize?: number;
+    /** Completion grace for delivered sessions after a winner is selected. Default 45000 ms. */
+    completionTimeoutMs?: number;
+    title: string;
+    description: string;
+    input: Json;
+    outputSchema?: Schema;
+    budget?: Partial<BudgetSpec>;
+    capabilities?: DelegateOptions['capabilities'];
+    minimumIsolationLevel?: string;
+    signal?: AbortSignal;
+    onProgress?: DelegateOptions['onProgress'];
+    auditPath?: string;
+}
+export interface DeliverRevocationOptions {
+    relay: RelayTransport | string;
+    from: KeyPair;
+    recipientDid: string;
+    notice: SignedRevocationNotice;
+    /** Routing id carried in the envelope header. Defaults to the revocation id. */
+    taskId?: string;
+    seq?: number;
+    /** Encrypt the notice to recipientDid. Default true. */
+    encrypt?: boolean;
+    allowPrivateRelay?: boolean;
+    lookup?: RelayClientSecurityOptions['lookup'];
+}
+/**
+ * Queue a signed REVOKE envelope on a worker inbox.
+ * The payload is a SignedRevocationNotice. Encryption is on unless encrypt is false,
+ * so an offline worker reads the notice in FIFO order before a later PROPOSE.
+ */
+export declare function deliverRevocation(options: DeliverRevocationOptions): Promise<SignedEnvelope>;
+export declare class RequesterClient {
+    readonly options: RequesterClientOptions;
+    readonly approvalProvider: ApprovalProvider;
+    constructor(options: RequesterClientOptions);
+    /**
+     * Send an encrypted REVOKE for an invite or capability to a worker inbox.
+     * `to` is a worker DID or an acp-invite token. The notice is signed by this client.
+     */
+    sendRevocation(options: {
+        to: string;
+        relay?: RelayTransport | string;
+        targetType?: 'invite' | 'capability';
+        targetId?: string;
+        reason?: string;
+        notice?: SignedRevocationNotice;
+        taskId?: string;
+        encrypt?: boolean;
+    }): Promise<SignedEnvelope>;
+    delegate(options: DelegateOptions, hooks?: {
+        onProgress?: DelegateOptions['onProgress'];
+        /** @internal Multi-delegation stops cancelling execution once DELIVER is recorded. */
+        onDelivered?: () => void;
+    }): Promise<SessionResult>;
+    delegateMulti(options: DelegateMultiOptions): Promise<DelegateMultiResult>;
+}
+export declare function buildTaskManifest(options: {
+    ownerDid: string;
+    workerDid: string;
+    agentDid?: string;
+    skillId?: string;
+    taskType?: string;
+    title: string;
+    description: string;
+    outputSchema?: Schema;
+    budget?: Partial<BudgetSpec>;
+    taskTimeoutMs?: number;
+    capabilities?: TaskManifest['permissions']['grantedCapabilities'];
+}): TaskManifest;