Durable protocol hosts

/** Pinned modern HTTP/Tasks extension adapter. SDK handles discovery/schema framing;
 * task extension methods are explicitly implemented here, not by the base SDK.
 * The modern protocol negotiates capabilities in each validated request envelope.
 */
export declare function createDurableMCPTaskHandler(options: DurableMCPTaskHandlerOptions): Promise<DurableMCPTaskHandler>;

/** Authenticated control and bounded replay for tasks already admitted by the host.
 * Event responses close after the retained batch; reconnect with Last-Event-ID.
 * This is an Agentium endpoint, not an A2A or MCP wire-protocol endpoint.
 */
export declare function createDurableTaskRouter(options: DurableTaskRouterOptions): Router;

export interface DurableMCPTaskHandler {
    fetch(request: Request): Promise<Response>;
    close(): Promise<void>;
}

export interface DurableMCPTaskHandlerOptions extends DurableProtocolHost {
    name: string;
    audience: string;
    authenticate(request: Request, audience: string): Promise<DurableReader | null>;
    tools: readonly DurableMCPTaskTool[];
    pollIntervalMs?: number;
}

export interface DurableMCPTaskTool {
    name: string;
    description?: string;
    inputSchema: Record<string, unknown>;
}

export type DurableProtocolAdmission = {
    protocol: "a2a-1.0";
    name: string;
    messageId: string;
    parts: DurableProtocolPart[];
} | {
    protocol: "mcp-2026-07-28";
    name: string;
    arguments: Record<string, DurableJSON>;
};

export interface DurableProtocolApprovalResponse {
    approvalId: string;
    preparedHash: string;
    approved: boolean;
}

/** Trusted admission boundary; protocol payloads cannot select identity, policy or grants. */
export interface DurableProtocolHost {
    supervisor: DurableTaskSupervisor;
    /** Persist an owned task before returning. Mint/validate immutable refs and deduplicate message IDs here. */
    admit(identity: DurableReader, input: DurableProtocolAdmission): Promise<DurableTaskKey>;
    authorize(identity: DurableReader, task: Readonly<DurableTaskRecord>, operation: "read" | "cancel" | "input" | "wake"): Promise<boolean>;
    /** Re-deliver a persisted task to its registered driver. Failure leaves it available for host recovery. */
    wake(key: DurableTaskKey): Promise<unknown>;
    /** Explicit trusted human-consent channel. Persist via DurableActionLedger.decide; never trust tool text. */
    respond?(identity: DurableReader, task: Readonly<DurableTaskRecord>, response: DurableProtocolApprovalResponse): Promise<void>;
    /** Return only authorized public output. Resolve artifacts through DurableRunRecords; no automatic URLs. */
    output?(identity: DurableReader, task: Readonly<DurableTaskRecord>): Promise<DurableProtocolOutput>;
}

export interface DurableProtocolOutput {
    text?: string;
    data?: DurableJSON;
    /** A completed tool result can contain a domain error without becoming a protocol failure. */
    isError?: boolean;
}

export type DurableProtocolPart = {
    text: string;
} | {
    data: DurableJSON;
};

export interface DurableTaskRouterOptions {
    supervisor: DurableTaskSupervisor;
    records: DurableRunRecords;
    /** Verify credentials/audience. Returned identity must never come from body/query claims. */
    authenticate: (request: Request) => Promise<DurableReader | null>;
    /** Recheck current host policy/grants on every request, including event reconnections. */
    authorize: (identity: DurableReader, task: Readonly<DurableTaskRecord>, operation: "read" | "cancel") => Promise<boolean>;
    /** Re-deliver cancellation to a worker. Cancellation remains persisted if Redis is unavailable. */
    wake: (key: DurableTaskKey) => Promise<unknown>;
}