totemlayer 0.1.20 → 0.1.24

package/bin/sdk/index.d.ts

@@ -0,0 +1,298 @@
+import { createLocalInspector, InspectionError } from "./inspector.js";
+import type { ActionProposal, AssistantActionCheck, AssistantActionCheckList, AssistantActionReceiptResult, AssistantCheckOptions } from "./action-types.js";
+import type { MissionCoordinationUpdate, MissionSessionReport, Agent, AssistantContext, AssistantMissionPermissions, Attachment, Chat, ChatCommand, ChatDetail, ChatEvent, ChatRun, RuntimeHeartbeat, Conversation, ListenOptions, ListMessages, ListMissions, ListTasks, Message, MessageContent, MessageHandler, Metadata, MissionArtifact, MissionDetail, MissionEvent, MissionEventInput, MissionSummary, MissionWorkItem, Page, Pagination, RequestOptions, RepoClaim, RepoClaimState, RepositoryCoordination, SearchAgents, SendMessage, Subscription, Task, TaskState, TotemOptions, WriteOptions } from "./types.js";
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./actions.js";
+export { idempotencyKey } from "./transport.js";
+export declare class Totem {
+    #private;
+    constructor(options: TotemOptions);
+    static connect(options: TotemOptions): Promise<ConnectedAgent>;
+    connect(): Promise<ConnectedAgent>;
+    agent(options?: RequestOptions): Promise<Agent>;
+    assistant: {
+        context: (options?: RequestOptions) => Promise<AssistantContext>;
+        checks: {
+            create: (missionId: string, input: {
+                workItemId: string;
+                leaseToken: string;
+                action: ActionProposal;
+            }, options: AssistantCheckOptions) => Promise<AssistantActionCheck>;
+            list: (missionId: string, workItemId: string, options?: RequestOptions) => Promise<AssistantActionCheckList>;
+            recordReceipt: (missionId: string, suiteId: string, input: {
+                workItemId: string;
+            }, options?: RequestOptions) => Promise<AssistantActionReceiptResult>;
+        };
+        permissions: (missionId: string, options?: RequestOptions) => Promise<AssistantMissionPermissions>;
+    };
+    resolve(address: string, options?: RequestOptions): Promise<Agent>;
+    agents: {
+        search: (query?: SearchAgents, options?: RequestOptions) => Promise<Page<Agent>>;
+        iterate: (query?: SearchAgents, options?: RequestOptions) => AsyncIterable<Agent>;
+    };
+    attachments: {
+        upload: (name: string, mediaType: string, bytes: Uint8Array, options?: RequestOptions) => Promise<Attachment>;
+        download: (id: string, options?: RequestOptions) => Promise<{
+            bytes: Uint8Array;
+            mediaType: string;
+            name: string;
+            sha256: string | null;
+        }>;
+    };
+    messages: {
+        send: (input: SendMessage, options?: WriteOptions) => Promise<Message>;
+        list: (query?: ListMessages, options?: RequestOptions) => Promise<Page<Message>>;
+        iterate: (query?: ListMessages, options?: RequestOptions) => AsyncIterable<Message>;
+        get: (id: string, options?: RequestOptions) => Promise<Message>;
+        reply: (id: string, text: string, options?: WriteOptions & {
+            metadata?: Metadata;
+            attachments?: string[];
+        }) => Promise<Message>;
+        replyContent: (id: string, content: MessageContent, options?: WriteOptions) => Promise<Message>;
+        ack: (id: string, options?: RequestOptions) => Promise<Message>;
+    };
+    send(input: SendMessage, options?: WriteOptions): Promise<Message>;
+    send(to: string, text: string, options?: WriteOptions): Promise<Message>;
+    conversations: {
+        create: (input: {
+            with: string;
+            metadata?: Metadata;
+        }, options?: RequestOptions) => Promise<ConversationHandle>;
+        list: (query?: Pagination, options?: RequestOptions) => Promise<Page<Conversation>>;
+        get: (id: string, options?: RequestOptions) => Promise<Conversation>;
+        messages: (id: string, query?: Pagination, options?: RequestOptions) => Promise<Page<Message>>;
+    };
+    startConversation(input: {
+        with: string;
+        metadata?: Metadata;
+    }, options?: RequestOptions): Promise<ConversationHandle>;
+    missions: {
+        list: (options?: RequestOptions) => Promise<MissionSummary[]>;
+        listPage: (query?: ListMissions, options?: RequestOptions) => Promise<Page<MissionSummary>>;
+        iterate: (query?: ListMissions, options?: RequestOptions) => AsyncIterable<MissionSummary>;
+        get: (id: string, options?: RequestOptions) => Promise<MissionDetail>;
+        coordination: (id: string, version?: string, options?: RequestOptions) => Promise<MissionCoordinationUpdate>;
+        sessions: {
+            report: (id: string, input: MissionSessionReport, options?: RequestOptions) => Promise<{
+                sessionId: string;
+                sequence: number;
+            }>;
+        };
+        workItems: (id: string, options?: RequestOptions) => Promise<MissionWorkItem[]>;
+        /** Empty data can still have a nextCursor: readiness is checked after scanning candidates. */
+        workItemsPage: (id: string, query?: Pagination, options?: RequestOptions) => Promise<Page<MissionWorkItem>>;
+        iterateWorkItems: (id: string, query?: Pagination, options?: RequestOptions) => AsyncIterable<MissionWorkItem>;
+        assign: (id: string, input: {
+            ownerMemberId: string;
+            objective: string;
+            requiredOutput: string;
+            dependsOnIds?: string[];
+            parentWorkItemId: string;
+            metadata?: Metadata;
+        }, options?: WriteOptions) => Promise<MissionWorkItem>;
+        claim: (id: string, workItemId: string, options?: WriteOptions) => Promise<{
+            workItem: MissionWorkItem;
+            leaseToken: string;
+            leaseExpiresAt: string;
+        }>;
+        renew: (id: string, workItemId: string, leaseToken: string, options?: RequestOptions) => Promise<{
+            workItem: MissionWorkItem;
+            leaseExpiresAt: string;
+        }>;
+        complete: (id: string, workItemId: string, input: {
+            leaseToken: string;
+            result?: Metadata;
+            artifact?: Pick<MissionArtifact, "kind" | "title"> & {
+                summary?: string;
+                uri?: string;
+                contentText?: string;
+                metadata?: Metadata;
+            };
+            event?: MissionEventInput;
+        }, options?: WriteOptions) => Promise<{
+            workItem: MissionWorkItem;
+            artifact?: MissionArtifact;
+        }>;
+        reserveEffect: (id: string, input: {
+            workItemId: string;
+            action: string;
+            resource: string;
+            leaseToken: string;
+            estimatedCostCents?: number;
+            parameters?: Metadata;
+        }, options?: WriteOptions) => Promise<{
+            id: string;
+            state: string;
+            action: string;
+            resource: string;
+        }>;
+        listEffects: (id: string, workItemId: string, options?: RequestOptions) => Promise<Array<{
+            id: string;
+            workItemId: string;
+            action: string;
+            resource: string;
+            state: string;
+            estimatedCostCents: number;
+            actualCostCents: number | null;
+            parameters?: Metadata | null;
+            receipt?: Metadata | null;
+            externalRef?: string | null;
+            createdAt: string;
+            updatedAt: string;
+        }>>;
+        dispatchEffect: (id: string, effectId: string, leaseToken: string, options?: RequestOptions) => Promise<{
+            effect: {
+                id: string;
+                state: string;
+            };
+            launchPermitted: true;
+        }>;
+        settleEffect: (id: string, effectId: string, input: {
+            state: "succeeded" | "failed" | "uncertain";
+            actualCostCents?: number;
+            receipt?: Metadata;
+        }, options?: RequestOptions) => Promise<{
+            id: string;
+            state: string;
+        }>;
+        events: {
+            list: (id: string, query?: Pagination, options?: RequestOptions) => Promise<Page<MissionEvent>>;
+            iterate: (id: string, query?: Pagination, options?: RequestOptions) => AsyncIterable<MissionEvent>;
+            post: (id: string, input: MissionEventInput, options?: WriteOptions) => Promise<MissionEvent>;
+            ack: (id: string, eventId: string, options?: RequestOptions) => Promise<MissionEvent>;
+        };
+    };
+    chats: {
+        list: (query?: Pagination, options?: RequestOptions) => Promise<Page<Chat>>;
+        get: (id: string, options?: RequestOptions & Pagination & {
+            before?: string;
+        }) => Promise<ChatDetail>;
+        /** Publish as the authenticated agent; this never creates a human command. */
+        updates: (id: string, text: string, options?: WriteOptions) => Promise<ChatEvent>;
+    };
+    chatCommands: {
+        list: (query?: Pagination, options?: RequestOptions) => Promise<Page<ChatCommand>>;
+        claim: (id: string, options?: RequestOptions) => Promise<{
+            run: ChatRun;
+            leaseToken: string;
+        }>;
+        renew: (id: string, leaseToken: string, options?: RequestOptions) => Promise<{
+            run: ChatRun;
+        }>;
+        complete: (id: string, input: {
+            leaseToken: string;
+            text: string;
+        }, options?: WriteOptions) => Promise<{
+            event: ChatEvent;
+            run: ChatRun;
+        }>;
+        fail: (id: string, input: {
+            leaseToken: string;
+            error: string;
+        }, options?: RequestOptions) => Promise<{
+            run: ChatRun;
+        }>;
+    };
+    runtime: {
+        start: (input: {
+            runId: string;
+            provider: string;
+            hostKind?: "local" | "hosted";
+        }, options?: RequestOptions) => Promise<{
+            runId: string;
+            state: string;
+            ready: boolean;
+        }>;
+        probe: (runId: string, options?: RequestOptions) => Promise<{
+            runId: string;
+            challenge: string;
+            completed: boolean;
+            protocol: string;
+        }>;
+        replyProbe: (input: {
+            runId: string;
+            reply: string;
+        }, options?: RequestOptions) => Promise<{
+            runId: string;
+            state: string;
+            ready: boolean;
+        }>;
+        heartbeat: (input?: {
+            label?: string;
+            runId?: string;
+            state?: "starting" | "online" | "offline" | "error";
+            errorCode?: string;
+        }, options?: RequestOptions) => Promise<RuntimeHeartbeat>;
+    };
+    tasks: {
+        create: (input: SendMessage, options?: WriteOptions) => Promise<Task>;
+        get: (id: string, options?: RequestOptions) => Promise<Task>;
+        list: (query?: ListTasks, options?: RequestOptions) => Promise<Page<Task>>;
+        iterate: (query?: ListTasks, options?: RequestOptions) => AsyncIterable<Task>;
+        postUpdate: (id: string, text: string, options?: WriteOptions) => Promise<Message>;
+        update: (id: string, input: {
+            state: Exclude<TaskState, "submitted" | "canceled">;
+            artifacts?: Task["artifacts"];
+            expectedVersion?: number;
+        }, options?: RequestOptions) => Promise<Task>;
+        cancel: (id: string, options?: RequestOptions) => Promise<Task>;
+    };
+    repositories: {
+        getTask: (taskId: string, options?: RequestOptions) => Promise<RepositoryCoordination>;
+        claim: (taskId: string, input: {
+            branch: string;
+            paths: string[];
+            expectedVersion?: number;
+        }, options?: RequestOptions) => Promise<RepoClaim>;
+        update: (taskId: string, input: {
+            state: Exclude<RepoClaimState, "planned">;
+            headCommit?: string;
+            pullRequestUrl?: string;
+            expectedVersion: number;
+        }, options?: RequestOptions) => Promise<RepoClaim>;
+    };
+    github: {
+        repositories: (options?: RequestOptions) => Promise<Array<{
+            repository: string;
+            repositoryId: string;
+            installationId: string;
+        }>>;
+        openPullRequest: (taskId: string, input: {
+            title: string;
+            body?: string;
+        }, options?: RequestOptions) => Promise<{
+            pullRequestUrl: string;
+            claim: RepoClaim;
+        }>;
+    };
+}
+export declare class ConversationHandle {
+    #private;
+    readonly id: string;
+    readonly conversation: Conversation;
+    constructor(totem: Totem, conversation: Conversation, recipient: string);
+    send(text: string, options?: WriteOptions): Promise<Message>;
+    messages(query?: Pagination, options?: RequestOptions): Promise<Page<Message>>;
+}
+export declare class ConnectedAgent {
+    #private;
+    readonly identity: Agent;
+    readonly address: string;
+    readonly client: Totem;
+    constructor(client: Totem, identity: Agent);
+    get lastError(): Error | undefined;
+    send(input: SendMessage, options?: WriteOptions): Promise<Message>;
+    send(to: string, text: string, options?: WriteOptions): Promise<Message>;
+    startConversation(input: {
+        with: string;
+        metadata?: Metadata;
+    }): Promise<ConversationHandle>;
+    on(event: "message", handler: MessageHandler, options?: ListenOptions): Subscription;
+    stop(): Promise<void>;
+}
+/** Compatibility name for callers who prefer `new TotemAgent({ address, apiKey })`. */
+export declare class TotemAgent extends Totem {
+}
+export { createLocalInspector, InspectionError };
+export type { LocalInspector, LocalInspectorOptions, InspectionOptions, InspectionReceipt, InspectionKind, } from "./inspector.js";

package/bin/sdk/index.js

@@ -1,4 +1,5 @@
 import { TotemError } from "./errors.js";
+import { createLocalInspector, InspectionError } from "./inspector.js";
 import { idempotencyKey, sleep, Transport } from "./transport.js";
 import { assertInputFields, assistantCheckOptions, signalOnlyOptions } from "./request-options.js";
 export * from "./types.js";
@@ -112,6 +113,11 @@ export class Totem {
             },
             idempotencyKey: options.idempotencyKey ?? `sdk:reply:${id}`,
         })).data,
+        replyContent: async (id, content, options = {}) => (await this.#transport.request("POST", `/messages/${encodeURIComponent(id)}/reply`, {
+            ...options,
+            body: { content },
+            idempotencyKey: options.idempotencyKey ?? idempotencyKey(),
+        })).data,
         ack: async (id, options) => (await this.#transport.request("POST", `/messages/${encodeURIComponent(id)}/ack`, {
             ...options,
             body: {},
@@ -155,8 +161,20 @@ export class Totem {
                 artifacts: result.data.artifacts,
                 events: result.data.events,
                 budget: result.data.budget,
+                coordination: result.data.coordination,
             };
         },
+        coordination: async (id, version, options) => (await this.#transport.request("GET", `/missions/${encodeURIComponent(id)}/coordination`, {
+            ...options,
+            query: { version },
+        })).data,
+        sessions: {
+            report: async (id, input, options) => (await this.#transport.request("POST", `/missions/${encodeURIComponent(id)}/sessions`, {
+                ...options,
+                body: input,
+                retrySafe: true,
+            })).data,
+        },
         workItems: async (id, options) => (await this.#transport.request("GET", `/missions/${encodeURIComponent(id)}/work-items`, options)).data.workItems,
         /** Empty data can still have a nextCursor: readiness is checked after scanning candidates. */
         workItemsPage: async (id, query = {}, options) => {
@@ -223,6 +241,9 @@ export class Totem {
         fail: async (id, input, options) => (await this.#transport.request("POST", `/chat-commands/${encodeURIComponent(id)}/fail`, { ...options, body: input, retrySafe: true })).data,
     };
     runtime = {
+        start: async (input, options) => (await this.#transport.request("POST", "/runtime/start", { ...options, body: input, retrySafe: true })).data,
+        probe: async (runId, options) => (await this.#transport.request("GET", "/runtime/probe", { ...options, query: { runId } })).data,
+        replyProbe: async (input, options) => (await this.#transport.request("POST", "/runtime/probe", { ...options, body: input, retrySafe: true })).data,
         heartbeat: async (input = {}, options) => (await this.#transport.request("POST", "/runtime/heartbeat", {
             ...options,
             body: input,
@@ -317,6 +338,8 @@ export class ConnectedAgent {
         if (!Number.isFinite(interval) || interval < 10)
             throw new TotemError("pollIntervalMs must be at least 10.", { code: "INVALID_CONFIG" });
         const controller = new AbortController();
+        const inspector = options.inspector ?? createLocalInspector();
+        const blocked = new Set();
         const report = (cause) => {
             this.#lastError = cause instanceof Error ? cause : new Error(String(cause));
             try {
@@ -332,22 +355,42 @@ export class ConnectedAgent {
                     for await (const message of this.client.messages.iterate({ direction: "inbound", unread: true, limit: 100 }, { signal: controller.signal })) {
                         if (controller.signal.aborted)
                             break;
-                        const incoming = {
-                            ...message,
-                            text: message.content.type === "text"
-                                ? message.content.text
-                                : JSON.stringify(message.content.data),
-                            reply: (text, writeOptions = {}) => this.client.messages.reply(message.id, text, {
-                                ...writeOptions,
-                                idempotencyKey: writeOptions.idempotencyKey ?? `reply:${message.id}:0`,
-                            }),
-                            ack: () => this.client.messages.ack(message.id),
-                        };
+                        if (blocked.has(message.id))
+                            continue;
                         try {
+                            if (message.content.type === "encrypted")
+                                throw new TotemError("Use E2eeTotem and pinned endpoint keys to process encrypted messages.", { code: "E2EE_CLIENT_REQUIRED" });
+                            await inspector.assertAllowed("input", { content: message.content, metadata: message.metadata ?? {} }, { signal: controller.signal });
+                            const files = message.attachments ?? [];
+                            const ids = new Set(files.map((file) => file.id));
+                            if (message.content.type === "text" &&
+                                message.content.attachments?.some((id) => !ids.has(id)))
+                                throw new InspectionError("INSPECTION_UNSUPPORTED_FILE");
+                            for (const file of files) {
+                                const downloaded = await this.client.attachments.download(file.id, {
+                                    signal: controller.signal,
+                                });
+                                await inspector.inspectFile(file.name, file.mediaType, downloaded.bytes, {
+                                    signal: controller.signal,
+                                });
+                            }
+                            const incoming = {
+                                ...message,
+                                text: message.content.type === "text"
+                                    ? message.content.text
+                                    : JSON.stringify(message.content.data),
+                                reply: (text, writeOptions = {}) => inspector.runAction({ id: message.id, text }, (input) => this.client.messages.reply(input.id, input.text, {
+                                    ...writeOptions,
+                                    idempotencyKey: writeOptions.idempotencyKey ?? `reply:${message.id}:0`,
+                                }), { signal: controller.signal }),
+                                ack: () => this.client.messages.ack(message.id),
+                            };
                             await handler(incoming);
                             await incoming.ack();
                         }
                         catch (error) {
+                            if (error instanceof InspectionError && error.code !== "INSPECTION_UNAVAILABLE")
+                                blocked.add(message.id);
                             report(error);
                         }
                     }
@@ -385,3 +428,4 @@ export class ConnectedAgent {
 /** Compatibility name for callers who prefer `new TotemAgent({ address, apiKey })`. */
 export class TotemAgent extends Totem {
 }
+export { createLocalInspector, InspectionError };

package/bin/sdk/inspector.d.ts

@@ -0,0 +1,40 @@
+/** Customer-side screening. A passing inspection is never an authorization grant. */
+export type InspectionKind = "input" | "tool-result" | "output" | "action" | "file";
+export type InspectionCode = "INSPECTION_BLOCKED" | "INSPECTION_UNAVAILABLE" | "INSPECTION_LIMIT" | "INSPECTION_UNSUPPORTED_FILE";
+export declare class InspectionError extends Error {
+    readonly code: InspectionCode;
+    readonly status = 422;
+    constructor(code: InspectionCode);
+}
+export interface InspectionOptions {
+    /** Trusted original user intent; never replace this with a peer's instructions. */
+    task?: string;
+    signal?: AbortSignal;
+}
+export interface InspectionReceipt {
+    version: 1;
+    policy: "totem-local-v1";
+    kind: InspectionKind;
+    mode: "rules" | "rules+classifier";
+    /** SHA-256 of the entire kind, task, and value actually screened. No plaintext. */
+    digest: string;
+}
+export interface LocalInspectorOptions {
+    maxBytes?: number;
+    classifier?: {
+        /** Exact loopback OpenAI-compatible chat endpoint. Redirects are prohibited. */
+        endpoint: string;
+        model: string;
+        timeoutMs?: number;
+    };
+    /** Customer-controlled transport, primarily for isolated tests. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface LocalInspector {
+    readonly mode: InspectionReceipt["mode"];
+    assertAllowed(kind: InspectionKind, value: unknown, options?: InspectionOptions): Promise<InspectionReceipt>;
+    inspectFile(name: string, mediaType: string, bytes: Uint8Array, options?: InspectionOptions): Promise<InspectionReceipt>;
+    /** Execute only the immutable argument snapshot that passed inspection. */
+    runAction<T, R>(value: T, operation: (inspected: T) => Promise<R>, options?: InspectionOptions): Promise<R>;
+}
+export declare function createLocalInspector(options?: LocalInspectorOptions): LocalInspector;

package/bin/sdk/request-options.d.ts

@@ -0,0 +1,13 @@
+import type { RequestOptions } from "./types.js";
+export declare function requireActionChecksKey(apiKey: string): string;
+export declare function assistantCheckOptions(options: RequestOptions & {
+    actionChecksApiKey: string;
+}): {
+    headers: {
+        "X-Totem-Action-Key": string;
+    };
+    signal?: AbortSignal;
+};
+export declare function assertInputFields(input: object, allowed: string[]): void;
+/** These APIs derive caller identity from credentials, never from caller options. */
+export declare function signalOnlyOptions(options?: RequestOptions): RequestOptions;

package/bin/sdk/transport.d.ts

@@ -0,0 +1,24 @@
+import type { RequestOptions, TotemOptions } from "./types.js";
+export declare function idempotencyKey(): string;
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+export declare class Transport {
+    #private;
+    constructor(options: TotemOptions, api?: {
+        basePath: "/api/action-checks";
+        responseEnvelope: "object";
+    } | undefined);
+    request<T>(method: "GET" | "POST" | "PATCH", path: string, options?: RequestOptions & {
+        body?: unknown;
+        query?: object;
+        idempotencyKey?: string;
+        retrySafe?: boolean;
+        binaryBody?: Uint8Array;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    download(path: string, options?: RequestOptions): Promise<{
+        bytes: Uint8Array;
+        mediaType: string;
+        name: string;
+        sha256: string | null;
+    }>;
+}