@atalk/sdk 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/workrooms.d.ts

@@ -0,0 +1,329 @@
+import { decryptMandateTerms, type AppendWorkroomEvent, type AttachmentDescriptor, type MandateUseDecision, type MandateUseRequest, type PublicPeer, type SignedMandate, type SignedMandateCommitment, type SignedMandateRevocation, type SignedWorkroomApprovalDecision, type SignedWorkroomReceipt, type Workroom, type WorkroomContentPayload, type WorkroomDescriptor, type WorkroomEncryptedEnvelope, type WorkroomEventMembershipSnapshot, type WorkroomMember, type WorkroomRoutingMatch, type WorkroomThread } from "@atalk/protocol";
+import type { AgentCredentials } from "./credential-store.js";
+import type { AgentAttachmentFileInput, AgentAttachmentInput, AttachmentTransferOptions } from "./agent.js";
+import type { AgentRuntimeState, WorkroomEventFailureState } from "./runtime-state-store.js";
+interface WorkroomMembership extends WorkroomMember {
+    id: string;
+    workroomId: string;
+    addedByPeerId: string;
+    idempotencyKey: string;
+}
+interface WorkroomRecord extends Workroom {
+    currentKeyEpoch: number;
+    descriptorHash: string;
+    idempotencyKey: string;
+}
+interface WorkroomThreadRecord extends WorkroomThread {
+    headerHash?: string;
+    idempotencyKey: string;
+}
+interface WorkroomMandateRecord {
+    mandateId: string;
+    revision: number;
+    workroomId?: string;
+    principalPeerId: string;
+    actorPeerId: string;
+    issuedByPeerId: string;
+    validFrom: string;
+    validUntil: string;
+    termsHash: string;
+    encryptedTermsHash: string;
+    encryptedTermsEnvelope: Parameters<typeof decryptMandateTerms>[0]["envelope"];
+    signedCommitment: SignedMandateCommitment;
+    issuerSigningPublicKey: string;
+}
+interface WorkroomMandateView {
+    mandate: WorkroomMandateRecord;
+    revocation?: {
+        signedRevocation: SignedMandateRevocation;
+        revokerSigningPublicKey: string;
+    };
+}
+interface WorkroomApprovalDecisionRecord {
+    signedDecision: SignedWorkroomApprovalDecision;
+    signingPublicKey: string;
+}
+interface WorkroomApprovalView {
+    requestId: string;
+    workroomId: string;
+    sourceEventId: string;
+    requestedByPeerId: string;
+    requiredApprovals: number;
+    eligiblePeerIds: string[];
+    requestCiphertextHash: string;
+    requestEnvelope: WorkroomEncryptedEnvelope;
+    expiresAt?: string;
+    status: "pending" | "approved" | "rejected" | "expired";
+    decisions: WorkroomApprovalDecisionRecord[];
+}
+export interface WorkroomDetail {
+    workroom: WorkroomRecord;
+    /** Locally verified and decrypted; never returned in plaintext by the relay. */
+    descriptor: WorkroomDescriptor;
+    membership: WorkroomMembership;
+    members: Array<{
+        membership: WorkroomMembership;
+        peer: PublicPeer | null;
+    }>;
+    threads: WorkroomThreadRecord[];
+    latestMandates: WorkroomMandateView[];
+    approvals: WorkroomApprovalView[];
+    latestReceiptHash: string | null;
+    events?: WorkroomEventRecord[];
+    nextAfterSequence?: number | null;
+}
+interface WorkroomEventRecord {
+    sequence: number;
+    event: AppendWorkroomEvent;
+    membershipSnapshot?: WorkroomEventMembershipSnapshot[];
+    projection?: WorkroomEventProjection;
+}
+export interface DecryptedWorkroomEvent extends WorkroomEventRecord {
+    actor: PublicPeer;
+    content: WorkroomContentPayload;
+    /** Exact autonomous context derived after canonical routing validation. */
+    routing: WorkroomRoutingMatch;
+    /** Compatibility alias for routing.directedToMe. */
+    directedToMe: boolean;
+}
+export type WorkroomEventProjection = {
+    kind: "plan";
+    id: string;
+    version: number;
+} | {
+    kind: "artifact_version";
+    id: string;
+    artifactId: string;
+    artifactVersion: number;
+    attachmentIds: string[];
+} | {
+    kind: "deliverable";
+    id: string;
+    artifactId: string;
+    artifactVersionId: string;
+} | {
+    kind: "cost";
+    id: string;
+} | {
+    kind: "approval_request";
+    id: string;
+    requiredApprovals: number;
+    eligiblePeerIds: string[];
+    expiresAt?: string;
+};
+export interface WorkroomPublishOptions {
+    eventId?: string;
+    idempotencyKey?: string;
+    projection?: WorkroomEventProjection;
+    maxAttempts?: number;
+}
+export interface WorkroomPollOptions {
+    limit?: number;
+    signal?: AbortSignal;
+    maxAttempts?: number;
+    /** Processing failures are retried durably before the event is quarantined. */
+    maxEventFailures?: number;
+    /** Observability hook; cursor/dead-letter state is persisted before invocation. */
+    onEventQuarantined?: (failure: WorkroomEventFailureState) => void | Promise<void>;
+}
+export interface WorkroomEventPage {
+    events: DecryptedWorkroomEvent[];
+    nextAfterSequence: number | null;
+}
+export interface MandatedActionInput {
+    workroomId: string;
+    threadId: string;
+    /** UUID used to make approval requests, effects and receipts retry-safe. */
+    operationId: string;
+    mandateId?: string;
+    action: string;
+    rationale?: string;
+    summary?: string;
+    target?: {
+        type: string;
+        label: string;
+        reference?: string;
+    };
+    effect?: string;
+    financialImpact?: {
+        currency: string;
+        amountMinor: number;
+        kind: "exact" | "maximum";
+    };
+    dataCategories?: string[];
+    participantPeerIds?: string[];
+    tool?: MandateUseRequest["tool"];
+    dataAccesses?: MandateUseRequest["dataAccesses"];
+    spend?: MandateUseRequest["spend"];
+    spendUsedMinorByLimit?: MandateUseRequest["spendUsedMinorByLimit"];
+    volumeUsed?: MandateUseRequest["volumeUsed"];
+    volumeDelta?: MandateUseRequest["volumeDelta"];
+    delegationDepth?: number;
+    principalApprovedDelegation?: boolean;
+    metEndConditionIds?: string[];
+}
+export interface MandatedPublicationInput extends Omit<MandatedActionInput, "action"> {
+    payload: WorkroomContentPayload;
+    publish?: WorkroomPublishOptions;
+}
+export interface MandatedFilePublicationInput extends Omit<MandatedActionInput, "action" | "volumeDelta"> {
+    path: string;
+    name?: string;
+    mimeType?: string;
+    title?: string;
+    description?: string;
+    artifactType?: string;
+    artifactId?: string;
+    artifactVersion?: number;
+    mentions?: Extract<WorkroomContentPayload, {
+        kind: "artifact_version";
+    }>["mentions"];
+    transfer?: AttachmentTransferOptions;
+}
+export type MandateGuardResult = {
+    status: "permitted";
+    mandate: SignedMandate;
+} | {
+    status: "requires_approval";
+    decision: Extract<MandateUseDecision, {
+        status: "requires_approval";
+    }>;
+    requestIds: string[];
+} | {
+    status: "denied";
+    decision: Extract<MandateUseDecision, {
+        status: "denied";
+    }>;
+};
+export interface MandatedEffectResult<T> {
+    value: T;
+    costs?: Array<Extract<WorkroomContentPayload, {
+        kind: "cost";
+    }>>;
+}
+export type MandatedExecutionResult<T> = {
+    status: "executed";
+    value: T;
+    receipt: SignedWorkroomReceipt;
+} | Exclude<MandateGuardResult, {
+    status: "permitted";
+}>;
+interface WorkroomClientDependencies {
+    request<T>(path: string, init?: RequestInit): Promise<T>;
+    credentials(): AgentCredentials;
+    runtimeState(): AgentRuntimeState;
+    mutateRuntimeState(mutator: (state: AgentRuntimeState) => void): Promise<void>;
+    uploadPart(scope: {
+        workroomId: string;
+    }, id: string, bytes: Uint8Array, transfer?: AttachmentTransferOptions): Promise<void>;
+    deletePart(id: string): Promise<void>;
+    downloadAttachment(descriptor: AttachmentDescriptor): Promise<Uint8Array>;
+    downloadAttachmentTo(descriptor: AttachmentDescriptor, path: string, transfer?: AttachmentTransferOptions): Promise<string>;
+}
+/** E2EE task client. The relay sees signed ciphertext and routing projections only. */
+export declare class WorkroomClient {
+    private readonly dependencies;
+    private executionTail;
+    constructor(dependencies: WorkroomClientDependencies);
+    list(cursor?: string, limit?: number): Promise<{
+        workrooms: WorkroomDetail[];
+        nextCursor: string | null;
+    }>;
+    get(workroomId: string, afterSequence?: number, eventLimit?: number): Promise<WorkroomDetail>;
+    /**
+     * Polls from the last durably acknowledged sequence and invokes the agent
+     * handler only for events explicitly directed to this identity. Undirected
+     * events are still authenticated and consumed so shared Task conversation
+     * traffic cannot accidentally start a model turn. A handler failure does not
+     * advance the cursor, so the same directed event is retried after restart.
+     */
+    poll(workroomId: string, handler: (event: DecryptedWorkroomEvent) => void | Promise<void>, options?: WorkroomPollOptions): Promise<number>;
+    /**
+     * Reads every authenticated event without advancing the autonomous handler
+     * cursor. This is the explicit operator/audit surface; never use it as a
+     * model-trigger loop because it includes traffic addressed to other agents.
+     */
+    readAuditEvents(workroomId: string, afterSequence?: number, limit?: number, signal?: AbortSignal): Promise<WorkroomEventPage>;
+    /** Durable processing failures that were skipped so later Task work can continue. */
+    listQuarantinedEvents(workroomId?: string): WorkroomEventFailureState[];
+    /** Long-polls using the durable cursor until aborted. */
+    watch(workroomId: string, handler: (event: DecryptedWorkroomEvent) => void | Promise<void>, options?: WorkroomPollOptions & {
+        intervalMs?: number;
+    }): Promise<void>;
+    publish(workroomId: string, threadId: string, candidate: WorkroomContentPayload, options?: WorkroomPublishOptions): Promise<WorkroomEventRecord>;
+    message(workroomId: string, threadId: string, body: string, mentions?: Extract<WorkroomContentPayload, {
+        kind: "message";
+    }>["mentions"]): Promise<WorkroomEventRecord>;
+    activity(workroomId: string, threadId: string, activityType: string, summary: string, mentions?: Extract<WorkroomContentPayload, {
+        kind: "activity";
+    }>["mentions"]): Promise<WorkroomEventRecord>;
+    plan(workroomId: string, threadId: string, payload: Omit<Extract<WorkroomContentPayload, {
+        kind: "plan";
+    }>, "version" | "kind">, options?: WorkroomPublishOptions): Promise<WorkroomEventRecord>;
+    artifactVersion(workroomId: string, threadId: string, payload: Omit<Extract<WorkroomContentPayload, {
+        kind: "artifact_version";
+    }>, "version" | "kind">, options?: WorkroomPublishOptions): Promise<WorkroomEventRecord>;
+    deliverable(workroomId: string, threadId: string, payload: Omit<Extract<WorkroomContentPayload, {
+        kind: "deliverable";
+    }>, "version" | "kind">, options?: WorkroomPublishOptions): Promise<WorkroomEventRecord>;
+    /**
+     * Preferred publication boundary for agent runtimes. It derives the same
+     * action names as the app, checks the current signed mandate twice, and
+     * records durable counters plus a signed receipt after publication.
+     */
+    publishMandated(input: MandatedPublicationInput): Promise<MandatedExecutionResult<WorkroomEventRecord>>;
+    /** Permission-aware local decryption for files supplied to an external agent. */
+    downloadAttachmentToMandated(input: Omit<MandatedActionInput, "action"> & {
+        descriptor: AttachmentDescriptor;
+        path: string;
+        transfer?: AttachmentTransferOptions;
+    }): Promise<MandatedExecutionResult<string>>;
+    /** Guard, upload and publish one encrypted Task file as a single runtime operation. */
+    submitFileMandated(input: MandatedFilePublicationInput): Promise<MandatedExecutionResult<{
+        descriptor: AttachmentDescriptor;
+        artifactId: string;
+        artifactVersion: number;
+        artifactVersionId: string;
+        record: WorkroomEventRecord;
+    }>>;
+    uploadAttachment(input: AgentAttachmentInput & {
+        workroomId: string;
+    }): Promise<AttachmentDescriptor>;
+    uploadAttachmentFile(input: AgentAttachmentFileInput & {
+        workroomId: string;
+    }): Promise<AttachmentDescriptor>;
+    downloadAttachment(descriptor: AttachmentDescriptor): Promise<Uint8Array>;
+    downloadAttachmentTo(descriptor: AttachmentDescriptor, path: string, transfer?: AttachmentTransferOptions): Promise<string>;
+    guardMandateUse(input: MandatedActionInput, createApproval?: boolean): Promise<MandateGuardResult>;
+    /**
+     * Revalidates immediately before the callback. Callbacks must use operationId
+     * as their external idempotency key so a crash cannot duplicate side effects.
+     */
+    executeMandatedAction<T>(input: MandatedActionInput, effect: (context: {
+        operationId: string;
+        mandate: SignedMandate;
+    }) => Promise<MandatedEffectResult<T>>): Promise<MandatedExecutionResult<T>>;
+    private openDetail;
+    private decryptEvent;
+    private readEventPage;
+    private readRawEventPage;
+    private quarantineLegacyEvent;
+    private recordEventFailure;
+    private clearEventFailure;
+    private commitEventCursor;
+    private openMandate;
+    private verifiedApprovals;
+    private ensureApprovalRequests;
+    private appendExecutionReceipt;
+    private withDurableUsage;
+    private recordDurableUsage;
+    private serializedExecution;
+    private retry;
+}
+/** @internal Approval identity is bound to the complete proposed operation, not only its action name. */
+export declare function approvalRequestId(input: MandatedActionInput, signed: SignedMandate, thresholdId: string): string;
+/** Stable action identifiers emitted by the app's agent-permission editor. */
+export declare function defaultWorkroomAction(kind: WorkroomContentPayload["kind"]): string;
+/** Returns why autonomous execution must stop, independent of encrypted mandate terms. */
+export declare function workroomStopReason(workroom: Pick<Workroom, "status" | "deadline">, now?: number): "completed" | "cancelled" | "expired" | "deadline" | undefined;
+export {};