totemlayer 0.1.21 → 0.1.24

package/bin/network-runtime.mjs

@@ -608,7 +608,25 @@ export async function runRuntime(settings) {
   const directory = join(settings.stateDir ?? join(homedir(), ".totem", "runtime"), scope);
   const release = await runtimeLock(directory);
   const journal = new Journal(directory);
+  const runId = settings.runId ?? randomUUID();
+  const verify = typeof client.runtime?.start === "function";
+  if (settings.verifyReadiness && !verify) {
+    await release();
+    throw Object.assign(new Error("Upgrade the Totem SDK to test and authorize this listener."), {
+      code: "READINESS_UNSUPPORTED",
+    });
+  }
+  if (verify && settings.codexThreadId) {
+    await release();
+    throw Object.assign(
+      new Error(
+        "Existing Codex chat queueing cannot verify a controlled receive/wake/reply round trip. Configure the isolated Codex adapter instead.",
+      ),
+      { code: "READINESS_UNSUPPORTED" },
+    );
+  }
   let heartbeat;
+  let probeFailed = false;
   let inbox;
   let humanDone = false;
   let fatalError;
@@ -618,14 +636,15 @@ export async function runRuntime(settings) {
     await readFile(new URL("../package.json", import.meta.url), "utf8"),
   ).version;
   const report = (error, context = {}) => {
+    const reconnecting = !context.messageId && transientNetworkError(error);
     diagnostics = {
-      phase: "blocked",
+      phase: reconnecting ? "reconnecting" : "blocked",
       errorCode: runtimeErrorCode(error),
       ...(typeof context.messageId === "string" ? { messageId: context.messageId } : {}),
     };
     if (settings.once) process.exitCode = 1;
     emit({
-      type: "runtime_error",
+      type: reconnecting ? "runtime_reconnecting" : "runtime_error",
       ...context,
       error: {
         code: error.code ?? "RUNTIME_FAILED",
@@ -641,10 +660,56 @@ export async function runRuntime(settings) {
     });
   };
   try {
+    if (verify) {
+      await client.runtime.start(
+        {
+          runId,
+          provider: settings.provider === "ollama" ? "ollama-local" : settings.provider,
+          hostKind: settings.hostKind ?? "local",
+        },
+        { signal },
+      );
+      try {
+        const probe = await client.runtime.probe(runId, { signal });
+        if (
+          probe.runId !== runId ||
+          probe.protocol !== "totem-readiness-v1" ||
+          !/^[a-f0-9]{64}$/.test(probe.challenge)
+        )
+          throw new Error("The readiness challenge is invalid.");
+        if (!probe.completed) {
+          const answer = await generate({
+            client,
+            identity,
+            journal,
+            key: `readiness:${runId}:${probe.challenge}`,
+            text: `Controlled readiness check. Reply with exactly TOTEM_READY:${probe.challenge} and no other text. No tools, files, external actions or business work are authorized.`,
+            history: [],
+            settings: { ...settings, system: "", allowAgents: [], modelTimeoutMs: 30000 },
+            signal,
+            allowTools: false,
+          });
+          await client.runtime.replyProbe({ runId, reply: String(answer).trim() }, { signal });
+        }
+        emit({ type: "runtime_ready", data: { runId, provider: settings.provider, ready: true } });
+      } catch (error) {
+        probeFailed = true;
+        await client.runtime
+          .heartbeat({ runId, state: "error", errorCode: "READINESS_PROBE_FAILED" }, { signal })
+          .catch(() => {});
+        throw Object.assign(
+          new Error(
+            "The bounded receive/wake/reply check failed. Check the selected adapter and its authorization, then restart this listener.",
+          ),
+          { code: "READINESS_PROBE_FAILED", cause: error },
+        );
+      }
+    }
     const beat = async () => {
       const result = await client.runtime.heartbeat(
         {
           label: `${settings.provider}:${settings.model}`.slice(0, 100),
+          ...(verify ? { runId, state: "online" } : {}),
           ...(diagnosticsSupported
             ? {
                 diagnostics: {
@@ -672,7 +737,7 @@ export async function runRuntime(settings) {
         } catch (error) {
           if (signal.aborted) break;
           report(error);
-          if (error.status === 401 || error.status === 403) {
+          if (error.status === 401 || error.status === 403 || error.code === "RUNTIME_SUPERSEDED") {
             fatalError = error;
             shutdown.abort();
             break;
@@ -688,6 +753,7 @@ export async function runRuntime(settings) {
         model: settings.model,
         allowedAgents: settings.allowAgents,
         inspection: settings.inspector.mode,
+        ready: verify,
       },
     });
     diagnostics = { phase: "waiting" };
@@ -700,8 +766,17 @@ export async function runRuntime(settings) {
       once: settings.once,
       onPollError: (error) => report(error),
       shouldContinue: () => !settings.once || !humanDone,
-      messages: (signal) =>
-        client.messages.iterate({ direction: "inbound", unread: true, limit: 100 }, { signal }),
+      messages: async function* (signal) {
+        for await (const message of client.messages.iterate(
+          { direction: "inbound", unread: true, limit: 100 },
+          { signal },
+        ))
+          yield message;
+        if (diagnostics.phase === "reconnecting") {
+          diagnostics = { phase: "waiting" };
+          emit({ type: "runtime_resumed" });
+        }
+      },
       eligible: async (message) => {
         const blocker = await journal.read(`message-blocker:${message.id}`);
         // Older runtimes persisted inspector outages as permanent blockers.
@@ -713,13 +788,22 @@ export async function runRuntime(settings) {
           diagnostics = { phase: "working", messageId: message.id };
           emit({ type: "message_started", data: { messageId: message.id } });
           if (settings.codexThreadId) {
-            const delivery = await queueCodexChatMessage({ settings, client, identity, journal, message, signal });
+            const delivery = await queueCodexChatMessage({
+              settings,
+              client,
+              identity,
+              journal,
+              message,
+              signal,
+            });
             if (delivery.state === "uncertain") {
               report({ code: "AGENT_OUTCOME_UNCERTAIN" }, { messageId: message.id });
             } else {
               diagnostics = { phase: "waiting" };
-              emit({ type: delivery.state === "confirmed" ? "message_handled" : "chat_queued",
-                data: { messageId: message.id, threadId: settings.codexThreadId } });
+              emit({
+                type: delivery.state === "confirmed" ? "message_handled" : "chat_queued",
+                data: { messageId: message.id, threadId: settings.codexThreadId },
+              });
             }
             return;
           }
@@ -871,7 +955,8 @@ export async function runRuntime(settings) {
         let leaseError;
         const renewal = (async () => {
           while (!commandSignal.aborted) {
-            await pause(30000, commandSignal);
+            // Observe human interruption promptly without repeating provider execution.
+            await pause(5000, commandSignal);
             try {
               await client.chatCommands.renew(command.id, claim.leaseToken, {
                 signal: commandSignal,
@@ -980,6 +1065,10 @@ export async function runRuntime(settings) {
     shutdown.abort();
     await heartbeat;
     await inbox;
+    if (verify && !probeFailed)
+      await client.runtime
+        .heartbeat({ runId, state: "offline" }, { signal: AbortSignal.timeout(2000) })
+        .catch(() => {});
     await release();
     emit({ type: "runtime_stopped", data: { agent: identity.address } });
   }

package/bin/runtime-diagnostics.mjs

@@ -32,6 +32,10 @@ export const RUNTIME_ERROR_CODES = new Set([
   "AGENT_IDENTITY_MISMATCH",
   "MODEL_ERROR",
   "MAX_STEPS",
+  "READINESS_UNSUPPORTED",
+  "READINESS_PROBE_FAILED",
+  "RUNTIME_AUTHORIZATION_REJECTED",
+  "RUNTIME_SUPERSEDED",
   "INTERNAL_ERROR",
 ]);
 export function runtimeErrorCode(error) {

package/bin/runtime-installation.mjs

@@ -251,6 +251,7 @@ export async function installRuntimeService(runtime, env = process.env, options
     "TOTEM_INSPECTOR_MODEL",
     "TOTEM_INSPECTOR_TIMEOUT_MS",
     "TOTEM_PROVIDER",
+    "TOTEM_RUNTIME_HOST_KIND",
     "TOTEM_MODEL",
     "TOTEM_BASE_URL",
     "TOTEM_AGENT_ID",

package/bin/sdk/action-types.d.ts

@@ -0,0 +1,236 @@
+import type { JsonValue, RequestOptions, TotemOptions } from "./types.js";
+export interface TotemActionsOptions extends Omit<TotemOptions, "apiKey" | "address"> {
+    /** Explicitly separate scoped Action Checks credential; never a Network tn_ key. */
+    actionChecksApiKey: string;
+}
+export interface AssistantCheckOptions extends RequestOptions {
+    /** Same scoped credential used by the separate TotemActions client. */
+    actionChecksApiKey: string;
+}
+export interface AssistantActionCheck {
+    suite: ActionCheckSuite;
+    /** Use this exact returned action for grant issuance and execution. */
+    action: ActionProposal;
+    missionId: string;
+    workItemId: string;
+    executionAuthorized: false;
+    checksUrl: string;
+}
+export interface AssistantActionReceipt {
+    id: string;
+    outcome: ActionExecutionReceipt["outcome"];
+    reconciliationState: ActionExecutionReceipt["reconciliationStatus"];
+    executorAdapter: string;
+    completedAt: string | null;
+}
+export interface AssistantActionCheckList {
+    checks: Array<{
+        id: string;
+        /** Original private handoff suite, verified through immutable rerun lineage. */
+        handoffSuiteId?: string;
+        actionDigest: string;
+        status: ActionCheckSuite["status"];
+        conclusion: ActionSuiteConclusion | null;
+        expiresAt: string;
+        staleAt: string | null;
+        executionReceipts: AssistantActionReceipt[];
+        checksUrl: string;
+    }>;
+}
+export interface AssistantActionReceiptResult {
+    receipt: AssistantActionReceipt & {
+        receiptDigest: string;
+    };
+    missionId: string;
+    workItemId: string;
+}
+export type ActionSideEffectClass = "READ_ONLY" | "DATA_EGRESS" | "EXTERNAL_COMMUNICATION" | "FINANCIAL" | "DESTRUCTIVE" | "AUTHORITY_CHANGE" | "SECURITY_OPERATION";
+export type ActionReversibility = "REVERSIBLE" | "COMPENSATABLE" | "IRREVERSIBLE" | "UNKNOWN";
+export type ActionDataClassification = "PUBLIC" | "INTERNAL" | "CONFIDENTIAL" | "PERSONAL" | "FINANCIAL" | "AUTHENTICATION" | "SOURCE_CODE" | "SECRET";
+export type ActionExecutorAdapter = "NOOP_READ" | "LOOPBACK_ECHO" | "FAKE_LEDGER" | "TEMP_FIXTURE_DELETE" | "SUPPLYCO_QUOTE" | "CREDENTIAL_ISSUER" | "RECEIVER_API_KEY" | "CREDENTIAL_VERIFY";
+export interface ActionFinancialContext {
+    actionType: "PAYMENT" | "PURCHASE" | "TRANSFER" | "REFUND" | "WITHDRAWAL" | "DEPOSIT" | "TRADE" | "SUBSCRIPTION" | "INVOICE_PAYMENT" | "CRYPTO" | "QUOTE_REQUEST";
+    movesValue: boolean;
+    amount: number | null;
+    currency: string | null;
+    sourceAccount: string | null;
+    beneficiary: string | null;
+    destinationAccount: string | null;
+    beneficiaryIsNew: boolean | null;
+    reversible: boolean | null;
+}
+/** Exact proposed action. The server derives tenant authority from the scoped credential. */
+export interface ActionProposal {
+    version: "1";
+    /** Totem identity-agent ID from assistant.context().agent.identityAgentId. */
+    agentId: string;
+    credentialId?: string | null;
+    automationRunId?: string | null;
+    toolName: string;
+    actionType: string;
+    sideEffectClass: ActionSideEffectClass;
+    executorAdapter: ActionExecutorAdapter;
+    target: {
+        resourceType: string;
+        resourceId?: string | null;
+        ownedTemporaryFixture?: boolean;
+    };
+    destination?: {
+        protocol: "local:" | "http:" | "https:";
+        host: string;
+        port?: number | null;
+        path: string;
+        tenant?: string | null;
+        redirects?: "DENY" | "SAME_ORIGIN";
+    } | null;
+    data: {
+        classifications?: ActionDataClassification[];
+        fields?: string[];
+        payload?: JsonValue;
+        minimized?: boolean;
+        byteLength?: number | null;
+    };
+    financial?: ActionFinancialContext | null;
+    reversibility: ActionReversibility;
+    justification: string;
+    provenance: Array<{
+        kind: "AUTHENTICATED_USER" | "TRUSTED_POLICY" | "INTERNAL_DATA" | "TOOL_OUTPUT" | "WEB_CONTENT" | "EMAIL" | "MESSAGE" | "OTHER_AGENT" | "UNTRUSTED_TEXT";
+        /** A caller-provided flag is advisory; the server derives source trust. */
+        trusted: boolean;
+        reference?: string | null;
+        content?: string | null;
+    }>;
+    idempotencyKey: string;
+    executionAttemptId: string;
+    expiresAt: string;
+    payload?: JsonValue;
+}
+export type ActionCheckConclusion = "PASS" | "WARN" | "REQUIRE_APPROVAL" | "BLOCK" | "ERROR" | "SKIPPED";
+export type ActionSuiteConclusion = "ALLOW" | "ALLOW_WITH_WARNINGS" | "REQUIRES_APPROVAL" | "BLOCK" | "ERROR";
+export type ActionRiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+export interface ActionExecutionReceipt {
+    id: string;
+    outcome: "SUCCEEDED" | "FAILED" | "UNKNOWN" | "COMPENSATED";
+    executorAdapter: string;
+    externalResponseSummary: string | null;
+    idempotencyStatus: "RECORDED";
+    reconciliationStatus: "NOT_REQUIRED" | "PENDING" | "CONFIRMED" | "FAILED";
+    compensationStatus: "RECORDED" | "NOT_REQUIRED";
+    createdAt: string;
+    executedAt: string | null;
+    completedAt: string | null;
+}
+/** Redacted server view; do not reconstruct an executable action from this projection. */
+export interface ActionCheckSuite {
+    id: string;
+    status: "QUEUED" | "RUNNING" | "COMPLETED" | "STALE";
+    conclusion: ActionSuiteConclusion | null;
+    riskLevel: ActionRiskLevel;
+    explanation: string | null;
+    policyVersion: string;
+    requiredProviders: string[];
+    actionDigest: string;
+    createdAt: string;
+    updatedAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    expiresAt: string;
+    staleAt: string | null;
+    staleReason: string | null;
+    supersededBySuiteId: string | null;
+    action: {
+        id: string;
+        agentId: string;
+        agent: {
+            id: string;
+            name: string;
+        } | null;
+        toolName: string;
+        actionType: string;
+        sideEffectClass: ActionSideEffectClass;
+        target: {
+            resourceType: string;
+            resourceId: string | null;
+        };
+        destination: {
+            protocol: string;
+            host: string;
+            port: number | null;
+            path: string;
+            tenant: string | null;
+        } | null;
+        dataClassifications: JsonValue;
+        financial: {
+            actionType: string;
+            movesValue: boolean | null;
+            amount: number | null;
+            currency: string | null;
+            beneficiary: string | null;
+            destinationAccount: string | null;
+        } | null;
+        reversibility: ActionReversibility;
+        justification: string;
+        expiresAt: string;
+    };
+    runs: Array<{
+        id: string;
+        providerName: string;
+        providerVersion: string;
+        required: boolean;
+        status: "QUEUED" | "RUNNING" | "COMPLETED" | "TIMED_OUT";
+        conclusion: ActionCheckConclusion | null;
+        reasonCode: string | null;
+        summary: string | null;
+        findings: Array<{
+            id: string;
+            severity: "INFO" | ActionRiskLevel;
+            category: string;
+            reasonCode: string;
+            explanation: string;
+            fieldReference: string | null;
+            sensitiveFingerprint: string | null;
+            remediation: string | null;
+            evidenceSource: string;
+            confidence: number;
+        }>;
+        startedAt: string | null;
+        completedAt: string | null;
+        timedOutAt: string | null;
+    }>;
+    approval: {
+        id: string;
+        status: "APPROVED" | "REJECTED" | "REVOKED" | "EXPIRED";
+        reason: string | null;
+        approver: {
+            id: string;
+            name?: string | null;
+            email?: string;
+        };
+        createdAt: string;
+        expiresAt: string;
+        rejectedAt: string | null;
+        revokedAt: string | null;
+    } | null;
+    grant: {
+        id: string;
+        status: "ACTIVE" | "CONSUMED" | "REVOKED" | "EXPIRED";
+        createdAt: string;
+        expiresAt: string;
+        consumedAt: string | null;
+        invalidatedAt: string | null;
+    } | null;
+    receipt: ActionExecutionReceipt | null;
+    confirmationPhrase: string | null;
+    demoAction: ActionProposal | null;
+}
+export interface ActionExecutionGrant {
+    /** One-use secret, bound to the checked action and issuing principal. */
+    token: string;
+    expiresAt: string;
+    suite: ActionCheckSuite;
+}
+export interface CheckedExecutionResult {
+    suite: ActionCheckSuite;
+    receipt: ActionExecutionReceipt | null;
+    receiptId: string;
+}

package/bin/sdk/actions.d.ts

@@ -0,0 +1,19 @@
+import type { RequestOptions } from "./types.js";
+import type { ActionCheckSuite, ActionExecutionGrant, ActionProposal, CheckedExecutionResult, TotemActionsOptions } from "./action-types.js";
+export * from "./action-types.js";
+/**
+ * Separately authenticated Action Checks client. Human approval stays in Totem's UI.
+ * Writes are never automatically replayed, even when the action has an idempotency key.
+ * After an ambiguous execution failure, use get() to inspect the receipt before proceeding.
+ */
+export declare class TotemActions {
+    #private;
+    constructor(options: TotemActionsOptions);
+    create(action: ActionProposal, options?: RequestOptions): Promise<ActionCheckSuite>;
+    get(suiteId: string, options?: RequestOptions): Promise<ActionCheckSuite>;
+    issueGrant(suiteId: string, action: ActionProposal, options?: RequestOptions): Promise<ActionExecutionGrant>;
+    execute(suiteId: string, input: {
+        action: ActionProposal;
+        grant: string;
+    }, options?: RequestOptions): Promise<CheckedExecutionResult>;
+}

package/bin/sdk/errors.d.ts

@@ -0,0 +1,30 @@
+export declare class TotemError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, options: {
+        code: string;
+        status?: number;
+        requestId?: string;
+        retryAfterSeconds?: number;
+        cause?: unknown;
+    });
+}
+export declare class TotemAuthenticationError extends TotemError {
+}
+export declare class TotemPermissionError extends TotemError {
+}
+export declare class TotemNotFoundError extends TotemError {
+}
+export declare class TotemConflictError extends TotemError {
+}
+export declare class TotemRateLimitError extends TotemError {
+}
+export declare class TotemTimeoutError extends TotemError {
+}
+export declare class TotemNetworkError extends TotemError {
+}
+export declare class TotemCanceledError extends TotemError {
+}
+export declare function apiError(status: number, body: unknown, requestId?: string): TotemError;

package/bin/sdk/errors.js

@@ -2,12 +2,14 @@ export class TotemError extends Error {
     code;
     status;
     requestId;
+    retryAfterSeconds;
     constructor(message, options) {
         super(message, { cause: options.cause });
         this.name = new.target.name;
         this.code = options.code;
         this.status = options.status;
         this.requestId = options.requestId;
+        this.retryAfterSeconds = options.retryAfterSeconds;
     }
 }
 export class TotemAuthenticationError extends TotemError {
@@ -50,5 +52,16 @@ export function apiError(status, body, requestId) {
                     : status === 429
                         ? TotemRateLimitError
                         : TotemError;
-    return new Constructor(message, { code, status, requestId: id });
+    const details = "details" in error ? error.details : undefined;
+    const retryAfter = details && typeof details === "object" && "retryAfterSeconds" in details
+        ? details.retryAfterSeconds
+        : undefined;
+    const retryAfterSeconds = status === 429 &&
+        typeof retryAfter === "number" &&
+        Number.isSafeInteger(retryAfter) &&
+        retryAfter > 0 &&
+        retryAfter <= 86400
+        ? retryAfter
+        : undefined;
+    return new Constructor(message, { code, status, requestId: id, retryAfterSeconds });
 }