totemlayer 0.1.44 → 0.1.59

package/bin/platform-client.mjs

@@ -1,5 +1,5 @@
-import { join, dirname, isAbsolute, extname } from "node:path";
-import { existsSync } from "node:fs";
+import { delimiter, join, dirname, isAbsolute, extname } from "node:path";
+import { accessSync, constants, existsSync, statSync } from "node:fs";
 
 const INHERITED_ENVIRONMENT = new Set(
   [
@@ -71,7 +71,29 @@ export function powershellInvocation(script, environment = process.env) {
 // PowerShell resolves both native executables and npm's .cmd shims. Only a
 // base64-encoded JSON argument array is interpolated into the script, so a
 // Windows path can never become shell syntax.
-export function installedClientInvocation(command, args, environment = process.env) {
+function executableFile(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function installedClientInvocation(command, args, environment = process.env, options = {}) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "win32") {
+    const isExecutable = options.isExecutable ?? executableFile;
+    if (
+      platform === "darwin" && command === "codex" &&
+      !(environment.PATH ?? "/usr/bin:/bin").split(delimiter)
+        .some((directory) => isExecutable(join(directory || ".", command)))
+    ) {
+      const bundled = "/Applications/ChatGPT.app/Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex";
+      if (isExecutable(bundled)) return { command: bundled, args };
+    }
+    return { command, args };
+  }
   // Native executables inherit the pipe directly. For npm clients, launch the
   // installed JavaScript entrypoint with Node rather than a .cmd/PowerShell
   // pipeline, which can leave stdin open indefinitely on Windows.

package/bin/provider-detection.mjs

@@ -21,10 +21,7 @@ export async function detectInstalledProvider(environment = process.env, options
   for (const client of ["codex", "claude"]) {
     try {
       const args = client === "codex" ? ["login", "status"] : ["auth", "status"];
-      const invocation =
-        process.platform === "win32"
-          ? installedClientInvocation(client, args, environment)
-          : { command: client, args };
+      const invocation = installedClientInvocation(client, args, environment, options);
       const result = await execute(invocation.command, invocation.args, {
         env: localClientEnvironment(environment),
         timeout: 5000,

package/bin/runtime-diagnostics.mjs

@@ -53,6 +53,7 @@ export const RUNTIME_ERROR_CODES = new Set([
   "INVALID_COMMUNICATION_POLICY",
   "INBOX_CAPACITY_REACHED",
   "WORK_RATE_LIMITED",
+  "CHAT_PROMPT_RATE_LIMITED",
   "INTERNAL_ERROR",
   "HARNESS_SETUP_REQUIRED",
   "HARNESS_UNSUPPORTED",

package/bin/sdk/index.d.ts

@@ -1,6 +1,6 @@
 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, NetworkActivityPage, NetworkActionInput, NetworkActionRequest, NetworkProtectedAction } from "./types.js";
+import type { MissionCoordinationUpdate, MissionSessionReport, Agent, AgentMemory, AgentMemoryHistory, AgentMemorySearch, AgentProfileInput, 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, NetworkActivityPage, NetworkActionInput, NetworkActionRequest, NetworkProtectedAction } from "./types.js";
 export * from "./types.js";
 export * from "./errors.js";
 export * from "./actions.js";
@@ -11,8 +11,29 @@ export declare class Totem {
     static connect(options: TotemOptions): Promise<ConnectedAgent>;
     connect(): Promise<ConnectedAgent>;
     agent(options?: RequestOptions): Promise<Agent>;
+    profiles: {
+        create: (input: AgentProfileInput, options?: RequestOptions) => Promise<Agent & {
+            identityAgentId: string;
+        }>;
+    };
+    memory: {
+        search: (query?: AgentMemorySearch, options?: RequestOptions) => Promise<AgentMemoryHistory>;
+        get: (options?: RequestOptions) => Promise<AgentMemory>;
+        update: (input: {
+            notes: string;
+            workingMemory: string;
+            expectedVersion: number;
+            automatic?: boolean;
+            forgetIds?: string[];
+            reinforceIds?: string[];
+        }, options?: RequestOptions) => Promise<AgentMemory>;
+    };
+    /** Read durable approval and work updates from the authenticated agent's harness. */
     activity: {
-        list: (query?: { cursor?: string; limit?: number }, options?: RequestOptions) => Promise<NetworkActivityPage>;
+        list: (query?: {
+            cursor?: string;
+            limit?: number;
+        }, options?: RequestOptions) => Promise<NetworkActivityPage>;
     };
     /** Native Network authorization. Human approval remains in the receiving owner's conversation. */
     actions: {
@@ -77,8 +98,7 @@ export declare class Totem {
         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;
+        reply: (id: string, text: string, options?: WriteOptions & Pick<SendMessage, "metadata" | "authorization" | "ttlSeconds"> & {
             attachments?: string[];
         }) => Promise<Message>;
         replyContent: (id: string, content: MessageContent, options?: WriteOptions) => Promise<Message>;
@@ -227,11 +247,24 @@ export declare class Totem {
         }>;
     };
     runtime: {
-        activations: (options?: RequestOptions) => Promise<{ data: Array<{ id: string; state: string; ready: boolean }> }>;
-        reportActivation: (input: { id: string; state: "starting" | "ready" | "blocked" | "paused"; errorCode?: "READINESS_UNSUPPORTED" | "LISTENER_START_FAILED" | "AUTHORIZATION_REJECTED" }, options?: RequestOptions) => Promise<{ recorded: boolean }>;
+        activations: (options?: RequestOptions) => Promise<{
+            data: Array<{
+                id: string;
+                state: string;
+                ready: boolean;
+            }>;
+        }>;
+        reportActivation: (input: {
+            id: string;
+            state: "starting" | "ready" | "blocked" | "paused";
+            errorCode?: "READINESS_UNSUPPORTED" | "LISTENER_START_FAILED" | "AUTHORIZATION_REJECTED";
+        }, options?: RequestOptions) => Promise<{
+            recorded: boolean;
+        }>;
         start: (input: {
             runId: string;
             provider: string;
+            automatic?: boolean;
             hostKind?: "local" | "hosted";
         }, options?: RequestOptions) => Promise<{
             runId: string;
@@ -243,6 +276,7 @@ export declare class Totem {
             challenge: string;
             completed: boolean;
             protocol: string;
+            provider?: string | null;
         }>;
         replyProbe: (input: {
             runId: string;
@@ -255,6 +289,7 @@ export declare class Totem {
         heartbeat: (input?: {
             label?: string;
             runId?: string;
+            listenerKind?: "mcp";
             state?: "starting" | "online" | "offline" | "error" | "blocked" | "reconnecting";
             errorCode?: string;
         }, options?: RequestOptions) => Promise<RuntimeHeartbeat>;
@@ -316,6 +351,15 @@ export declare class ConnectedAgent {
     readonly address: string;
     readonly client: Totem;
     constructor(client: Totem, identity: Agent);
+    get listenerStatus(): {
+        state: string;
+        listenerReady: boolean;
+        executionAuthorized: false;
+        runId?: string;
+        code?: string;
+        automatic?: boolean;
+        hostKind?: "local" | "hosted";
+    };
     get lastError(): Error | undefined;
     send(input: SendMessage, options?: WriteOptions): Promise<Message>;
     send(to: string, text: string, options?: WriteOptions): Promise<Message>;

package/bin/sdk/index.js

@@ -1 +1 @@
-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";export*from"./errors.js";export*from"./actions.js";import{idempotencyKey as idempotencyKey2}from"./transport.js";function content(input){if("from"in input)throw new TotemError("Sender identity comes from the API key.",{code:"INVALID_MESSAGE"});return input.content??{type:"text",text:input.text??input.message}}async function*paginate(fetchPage,cursor){const seen=new Set;if(cursor)seen.add(cursor);do{const page=await fetchPage(cursor);for(const item of page.data)yield item;cursor=page.nextCursor??void 0;if(cursor&&seen.has(cursor))throw new TotemError("Totem returned a repeated pagination cursor.",{code:"INVALID_RESPONSE"});if(cursor)seen.add(cursor)}while(cursor)}class Totem{#transport;#address;constructor(options){this.#transport=new Transport(options);this.#address=options.address?.trim().toLowerCase()}static async connect(options){return new Totem(options).connect()}async connect(){const identity=await this.agent();if(this.#address&&this.#address!==identity.address.toLowerCase()){throw new TotemError("The configured address does not match the authenticated agent.",{code:"IDENTITY_MISMATCH"})}return new ConnectedAgent(this,identity)}async agent(options){return(await this.#transport.request("GET","/agents/me",options)).data}activity={list:(query={},options)=>this.#transport.request("GET","/activity",{...signalOnlyOptions(options),query})};actions={list:(query={},options)=>this.#transport.request("GET","/actions",{...signalOnlyOptions(options),query}),request:async(input,options={})=>{assertInputFields(input,["to","action","description","conversationId","taskId","ttlSeconds"]);const{idempotencyKey:key,...requestOptions}=options;return(await this.#transport.request("POST","/actions",{...signalOnlyOptions(requestOptions),body:input,idempotencyKey:key??idempotencyKey()})).data},get:async(id,options)=>(await this.#transport.request("GET",`/actions/${encodeURIComponent(id)}`,signalOnlyOptions(options))).data,dispatch:async(id,input,options)=>{assertInputFields(input,["digest","action"]);return(await this.#transport.request("POST",`/actions/${encodeURIComponent(id)}/dispatch`,{...signalOnlyOptions(options),body:input})).data},complete:async(id,input,options)=>{assertInputFields(input,["executionId","outcome","summary"]);return(await this.#transport.request("POST",`/actions/${encodeURIComponent(id)}/complete`,{...signalOnlyOptions(options),body:input,retrySafe:true})).data},cancel:async(id,options)=>(await this.#transport.request("POST",`/actions/${encodeURIComponent(id)}/cancel`,{...signalOnlyOptions(options),retrySafe:true})).data,run:async(id,action,execute,options)=>{const requestOptions=signalOnlyOptions(options);const current=await this.actions.get(id,requestOptions);const dispatched=await this.actions.dispatch(id,{action,digest:current.digest},requestOptions);if(!dispatched.executionAuthorized||!dispatched.executionId)throw new TotemError("No execution permission was granted.",{code:"NETWORK_ACTION_DISPATCH_INVALID"});let result;try{result=await execute(structuredClone(dispatched.action),dispatched.executionId)}catch(cause){try{await this.actions.complete(id,{executionId:dispatched.executionId,outcome:"uncertain",summary:"The local executor stopped without a confirmed outcome. Inspect before repeating any effect."})}catch{}throw new TotemError("Action outcome uncertain. Inspect it; do not repeat.",{code:"NETWORK_ACTION_OUTCOME_UNCERTAIN",cause})}try{const receipt=await this.actions.complete(id,{executionId:dispatched.executionId,outcome:"succeeded",summary:result.summary},requestOptions);return{value:result.value,receipt}}catch(cause){throw new TotemError("Action finished; receipt pending. Reconcile it without reexecuting.",{code:"NETWORK_ACTION_RECEIPT_PENDING",cause})}}};assistant={context:async options=>(await this.#transport.request("GET","/assistant/context",signalOnlyOptions(options))).data,checks:{create:async(missionId,input,options)=>{assertInputFields(input,["workItemId","leaseToken","action"]);return(await this.#transport.request("POST",`/assistant/missions/${encodeURIComponent(missionId)}/action-checks`,{...assistantCheckOptions(options),body:input})).data},list:async(missionId,workItemId,options)=>(await this.#transport.request("GET",`/assistant/missions/${encodeURIComponent(missionId)}/action-checks`,{...signalOnlyOptions(options),query:{workItemId}})).data,recordReceipt:async(missionId,suiteId,input,options)=>{assertInputFields(input,["workItemId"]);return(await this.#transport.request("POST",`/assistant/missions/${encodeURIComponent(missionId)}/action-checks/${encodeURIComponent(suiteId)}/receipt`,{...signalOnlyOptions(options),body:input})).data}},permissions:async(missionId,options)=>(await this.#transport.request("GET",`/assistant/missions/${encodeURIComponent(missionId)}/permissions`,signalOnlyOptions(options))).data};async resolve(address,options){return(await this.#transport.request("GET",`/resolve/${encodeURIComponent(address)}`,options)).data}agents={search:(query={},options)=>this.#transport.request("GET","/agents/search",{...options,query}),iterate:(query={},options)=>paginate(cursor=>this.agents.search({...query,cursor},options),query.cursor)};attachments={upload:async(name,mediaType,bytes,options={})=>{if(!bytes.byteLength||bytes.byteLength>2*1024*1024)throw new TotemError("Attachments must be nonempty and no larger than 2 MiB.",{code:"ATTACHMENT_SIZE_INVALID"});return(await this.#transport.request("POST","/attachments",{...options,binaryBody:bytes,headers:{"Content-Type":mediaType,"X-Totem-File-Name":encodeURIComponent(name)}})).data},download:(id,options)=>this.#transport.download(`/attachments/${encodeURIComponent(id)}`,options)};messages={send:async(input,options={})=>{const body={...input,content:content(input)};delete body.text;delete body.message;return(await this.#transport.request("POST","/messages",{...options,body,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data},list:(query={},options)=>this.#transport.request("GET","/messages",{...options,query}),iterate:(query={},options)=>paginate(cursor=>this.messages.list({...query,cursor},options),query.cursor),get:async(id,options)=>(await this.#transport.request("GET",`/messages/${encodeURIComponent(id)}`,options)).data,reply:async(id,text,options={})=>(await this.#transport.request("POST",`/messages/${encodeURIComponent(id)}/reply`,{...options,body:{content:{type:"text",text,...options.attachments?{attachments:options.attachments}:{}},...options.metadata?{metadata:options.metadata}:{}},idempotencyKey:options.idempotencyKey??`sdk:reply:${id}`})).data,replyContent:async(id,content2,options={})=>(await this.#transport.request("POST",`/messages/${encodeURIComponent(id)}/reply`,{...options,body:{content:content2},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,ack:async(id,options)=>(await this.#transport.request("POST",`/messages/${encodeURIComponent(id)}/ack`,{...options,body:{},retrySafe:true})).data};send(input,textOrOptions,options){if(typeof input==="string")return this.messages.send({to:input,text:textOrOptions},options);return this.messages.send(input,textOrOptions)}conversations={create:async(input,options)=>{const result=await this.#transport.request("POST","/conversations",{...options,body:input});return new ConversationHandle(this,result.data,input.with)},list:(query={},options)=>this.#transport.request("GET","/conversations",{...options,query}),get:async(id,options)=>(await this.#transport.request("GET",`/conversations/${encodeURIComponent(id)}`,options)).data,messages:(id,query={},options)=>this.#transport.request("GET",`/conversations/${encodeURIComponent(id)}/messages`,{...options,query})};startConversation(input,options){return this.conversations.create(input,options)}missions={list:async options=>(await this.#transport.request("GET","/missions",options)).data.missions,listPage:async(query={},options)=>{const page=await this.#transport.request("GET","/missions",{...options,query});return{data:page.data.missions,nextCursor:page.nextCursor??null}},iterate:(query={},options)=>paginate(cursor=>this.missions.listPage({...query,cursor},options),query.cursor),get:async(id,options)=>{const result=await this.#transport.request("GET",`/missions/${encodeURIComponent(id)}`,options);return{...result.data.mission,members:result.data.members,workItems:result.data.workItems,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,workItemsPage:async(id,query={},options)=>{const page=await this.#transport.request("GET",`/missions/${encodeURIComponent(id)}/work-items`,{...options,query});return{data:page.data.workItems,nextCursor:page.nextCursor??null}},iterateWorkItems:(id,query={},options)=>paginate(cursor=>this.missions.workItemsPage(id,{...query,cursor},options),query.cursor),assign:async(id,input,options={})=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,claim:async(id,workItemId,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items/${encodeURIComponent(workItemId)}/claim`,{...options,body:{}})).data,renew:async(id,workItemId,leaseToken,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items/${encodeURIComponent(workItemId)}/renew`,{...options,body:{leaseToken},retrySafe:true})).data,complete:async(id,workItemId,input,options={})=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items/${encodeURIComponent(workItemId)}/complete`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,reserveEffect:async(id,input,options={})=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/effects`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,listEffects:async(id,workItemId,options)=>(await this.#transport.request("GET",`/missions/${encodeURIComponent(id)}/effects`,{...options,query:{workItemId}})).data.effects,dispatchEffect:async(id,effectId,leaseToken,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/effects/${encodeURIComponent(effectId)}/dispatch`,{...options,body:{leaseToken}})).data,settleEffect:async(id,effectId,input,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/effects/${encodeURIComponent(effectId)}/settle`,{...options,body:input,retrySafe:true})).data,events:{list:(id,query={},options)=>this.#transport.request("GET",`/missions/${encodeURIComponent(id)}/events`,{...options,query}),iterate:(id,query={},options)=>paginate(cursor=>this.missions.events.list(id,{...query,cursor},options),query.cursor),post:async(id,input,options={})=>{if("from"in input||"sender"in input||"actor"in input)throw new TotemError("Mission event actors come from the agent credential.",{code:"INVALID_EVENT"});return(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/events`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data},ack:async(id,eventId,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/events/${encodeURIComponent(eventId)}/ack`,{...options,body:{},retrySafe:true})).data}};chats={list:(query={},options)=>this.#transport.request("GET","/chats",{...options,query}),get:async(id,options={})=>(await this.#transport.request("GET",`/chats/${encodeURIComponent(id)}`,{signal:options.signal,query:{cursor:options.cursor,before:options.before,limit:options.limit}})).data,updates:async(id,text,options={})=>(await this.#transport.request("POST",`/chats/${encodeURIComponent(id)}/updates`,{...options,body:{text},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data};chatCommands={list:(query={},options)=>this.#transport.request("GET","/chat-commands",{...options,query}),claim:async(id,options)=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/claim`,{...options,body:{}})).data,renew:async(id,leaseToken,options)=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/renew`,{...options,body:{leaseToken},retrySafe:true})).data,complete:async(id,input,options={})=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/complete`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,fail:async(id,input,options)=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/fail`,{...options,body:input,retrySafe:true})).data};runtime={activations:async options=>(await this.#transport.request("GET","/runtime/activations",options)).data,reportActivation:async(input,options)=>(await this.#transport.request("POST","/runtime/activations",{...options,body:input,retrySafe:true})).data,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,retrySafe:true})).data};tasks={create:async(input,options={})=>(await this.#transport.request("POST","/tasks",{...options,body:{to:input.to,content:content(input),conversationId:input.conversationId,metadata:input.metadata,ttlSeconds:input.ttlSeconds,authorization:input.authorization},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,get:async(id,options)=>(await this.#transport.request("GET",`/tasks/${encodeURIComponent(id)}`,options)).data,list:(query={},options)=>this.#transport.request("GET","/tasks",{...options,query}),iterate:(query={},options)=>paginate(cursor=>this.tasks.list({...query,cursor},options),query.cursor),postUpdate:async(id,text,options={})=>(await this.#transport.request("POST",`/tasks/${encodeURIComponent(id)}/messages`,{...options,body:{content:{type:"text",text}},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,update:async(id,input,options)=>(await this.#transport.request("PATCH",`/tasks/${encodeURIComponent(id)}`,{...options,body:input})).data,cancel:async(id,options)=>(await this.#transport.request("POST",`/tasks/${encodeURIComponent(id)}/cancel`,{...options,body:{}})).data};repositories={getTask:async(taskId,options)=>(await this.#transport.request("GET",`/tasks/${encodeURIComponent(taskId)}/repository`,options)).data,claim:async(taskId,input,options)=>(await this.#transport.request("POST",`/tasks/${encodeURIComponent(taskId)}/repository`,{...options,body:input})).data,update:async(taskId,input,options)=>(await this.#transport.request("PATCH",`/tasks/${encodeURIComponent(taskId)}/repository`,{...options,body:input})).data};github={repositories:async options=>(await this.#transport.request("GET","/github/repositories",options)).data,openPullRequest:async(taskId,input,options)=>(await this.#transport.request("POST",`/github/pull-requests?taskId=${encodeURIComponent(taskId)}`,{...options,body:input})).data}}class ConversationHandle{id;conversation;#totem;#recipient;constructor(totem,conversation,recipient){this.#totem=totem;this.conversation=conversation;this.id=conversation.id;this.#recipient=recipient}send(text,options){return this.#totem.messages.send({to:this.#recipient,text,conversationId:this.id},options)}messages(query={},options){return this.#totem.conversations.messages(this.id,query,options)}}class ConnectedAgent{identity;address;client;#subscription;#lastError;constructor(client,identity){this.client=client;this.identity=identity;this.address=identity.address}get lastError(){return this.#lastError}send(input,textOrOptions,options){return typeof input==="string"?this.client.send(input,textOrOptions,options):this.client.send(input,textOrOptions)}startConversation(input){return this.client.startConversation(input)}on(event,handler,options={}){if(event!=="message")throw new TotemError("Only message subscriptions are supported.",{code:"INVALID_EVENT"});if(this.#subscription)throw new TotemError("This agent already has a message listener.",{code:"ALREADY_LISTENING"});const interval=options.pollIntervalMs??1e3;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{options.onError?.(this.#lastError)}catch{}};const done=(async()=>{while(!controller.signal.aborted){try{for await(const message of this.client.messages.iterate({direction:"inbound",unread:true,limit:100},{signal:controller.signal})){if(controller.signal.aborted)break;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)}}}catch(error){if(!controller.signal.aborted)report(error)}if(!controller.signal.aborted){try{await sleep(interval,controller.signal)}catch{}}}})();const subscription={done,stop:async()=>{controller.abort();await done;if(this.#subscription===subscription)this.#subscription=void 0}};this.#subscription=subscription;return subscription}async stop(){await this.#subscription?.stop()}}class TotemAgent extends Totem{}export{ConnectedAgent,ConversationHandle,InspectionError,Totem,TotemAgent,createLocalInspector,idempotencyKey2 as idempotencyKey};
+import{TotemError}from"./errors.js";import{createAutomaticNetworkListener,DEFAULT_LISTENER_POLL_MS}from"./listener.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";export*from"./errors.js";export*from"./actions.js";import{idempotencyKey as idempotencyKey2}from"./transport.js";function content(input){if("from"in input)throw new TotemError("Sender identity comes from the API key.",{code:"INVALID_MESSAGE"});return input.content??{type:"text",text:input.text??input.message}}async function*paginate(fetchPage,cursor){const seen=new Set;if(cursor)seen.add(cursor);do{const page=await fetchPage(cursor);for(const item of page.data)yield item;cursor=page.nextCursor??void 0;if(cursor&&seen.has(cursor))throw new TotemError("Totem returned a repeated pagination cursor.",{code:"INVALID_RESPONSE"});if(cursor)seen.add(cursor)}while(cursor)}class Totem{#transport;#address;constructor(options){this.#transport=new Transport(options);this.#address=options.address?.trim().toLowerCase()}static async connect(options){return new Totem(options).connect()}async connect(){const identity=await this.agent();if(this.#address&&this.#address!==identity.address.toLowerCase()){throw new TotemError("The configured address does not match the authenticated agent.",{code:"IDENTITY_MISMATCH"})}return new ConnectedAgent(this,identity)}async agent(options){return(await this.#transport.request("GET","/agents/me",options)).data}profiles={create:async(input,options)=>{assertInputFields(input,["name","localPart","description","creationContext"]);return(await this.#transport.request("POST","/agent-profiles",{...signalOnlyOptions(options),body:input})).data}};memory={search:async(query={},options)=>{assertInputFields(query,["query","includeHistory","before","limit"]);return(await this.#transport.request("GET","/memory/search",{...signalOnlyOptions(options),query})).data},get:async options=>(await this.#transport.request("GET","/memory",signalOnlyOptions(options))).data,update:async(input,options)=>{assertInputFields(input,["notes","workingMemory","expectedVersion","reinforceIds","automatic","forgetIds"]);return(await this.#transport.request("PATCH","/memory",{...signalOnlyOptions(options),body:input,retrySafe:true})).data}};activity={list:(query={},options)=>this.#transport.request("GET","/activity",{...signalOnlyOptions(options),query})};actions={list:(query={},options)=>this.#transport.request("GET","/actions",{...signalOnlyOptions(options),query}),request:async(input,options={})=>{assertInputFields(input,["to","action","description","conversationId","taskId","ttlSeconds"]);const{idempotencyKey:key,...requestOptions}=options;return(await this.#transport.request("POST","/actions",{...signalOnlyOptions(requestOptions),body:input,idempotencyKey:key??idempotencyKey()})).data},get:async(id,options)=>(await this.#transport.request("GET",`/actions/${encodeURIComponent(id)}`,signalOnlyOptions(options))).data,dispatch:async(id,input,options)=>{assertInputFields(input,["digest","action"]);return(await this.#transport.request("POST",`/actions/${encodeURIComponent(id)}/dispatch`,{...signalOnlyOptions(options),body:input})).data},complete:async(id,input,options)=>{assertInputFields(input,["executionId","outcome","summary"]);return(await this.#transport.request("POST",`/actions/${encodeURIComponent(id)}/complete`,{...signalOnlyOptions(options),body:input,retrySafe:true})).data},cancel:async(id,options)=>(await this.#transport.request("POST",`/actions/${encodeURIComponent(id)}/cancel`,{...signalOnlyOptions(options),retrySafe:true})).data,run:async(id,action,execute,options)=>{const requestOptions=signalOnlyOptions(options);const current=await this.actions.get(id,requestOptions);const dispatched=await this.actions.dispatch(id,{action,digest:current.digest},requestOptions);if(!dispatched.executionAuthorized||!dispatched.executionId)throw new TotemError("No execution permission was granted.",{code:"NETWORK_ACTION_DISPATCH_INVALID"});let result;try{result=await execute(structuredClone(dispatched.action),dispatched.executionId)}catch(cause){try{await this.actions.complete(id,{executionId:dispatched.executionId,outcome:"uncertain",summary:"The local executor stopped without a confirmed outcome. Inspect before repeating any effect."})}catch{}throw new TotemError("Action outcome uncertain. Inspect it; do not repeat.",{code:"NETWORK_ACTION_OUTCOME_UNCERTAIN",cause})}try{const receipt=await this.actions.complete(id,{executionId:dispatched.executionId,outcome:"succeeded",summary:result.summary},requestOptions);return{value:result.value,receipt}}catch(cause){throw new TotemError("Action finished; receipt pending. Reconcile it without reexecuting.",{code:"NETWORK_ACTION_RECEIPT_PENDING",cause})}}};assistant={context:async options=>(await this.#transport.request("GET","/assistant/context",signalOnlyOptions(options))).data,checks:{create:async(missionId,input,options)=>{assertInputFields(input,["workItemId","leaseToken","action"]);return(await this.#transport.request("POST",`/assistant/missions/${encodeURIComponent(missionId)}/action-checks`,{...assistantCheckOptions(options),body:input})).data},list:async(missionId,workItemId,options)=>(await this.#transport.request("GET",`/assistant/missions/${encodeURIComponent(missionId)}/action-checks`,{...signalOnlyOptions(options),query:{workItemId}})).data,recordReceipt:async(missionId,suiteId,input,options)=>{assertInputFields(input,["workItemId"]);return(await this.#transport.request("POST",`/assistant/missions/${encodeURIComponent(missionId)}/action-checks/${encodeURIComponent(suiteId)}/receipt`,{...signalOnlyOptions(options),body:input})).data}},permissions:async(missionId,options)=>(await this.#transport.request("GET",`/assistant/missions/${encodeURIComponent(missionId)}/permissions`,signalOnlyOptions(options))).data};async resolve(address,options){return(await this.#transport.request("GET",`/resolve/${encodeURIComponent(address)}`,options)).data}agents={search:(query={},options)=>this.#transport.request("GET","/agents/search",{...options,query}),iterate:(query={},options)=>paginate(cursor=>this.agents.search({...query,cursor},options),query.cursor)};attachments={upload:async(name,mediaType,bytes,options={})=>{if(!bytes.byteLength||bytes.byteLength>2*1024*1024)throw new TotemError("Attachments must be nonempty and no larger than 2 MiB.",{code:"ATTACHMENT_SIZE_INVALID"});return(await this.#transport.request("POST","/attachments",{...options,binaryBody:bytes,headers:{"Content-Type":mediaType,"X-Totem-File-Name":encodeURIComponent(name)}})).data},download:(id,options)=>this.#transport.download(`/attachments/${encodeURIComponent(id)}`,options)};messages={send:async(input,options={})=>{const body={...input,content:content(input)};delete body.text;delete body.message;return(await this.#transport.request("POST","/messages",{...options,body,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data},list:(query={},options)=>this.#transport.request("GET","/messages",{...options,query}),iterate:(query={},options)=>paginate(cursor=>this.messages.list({...query,cursor},options),query.cursor),get:async(id,options)=>(await this.#transport.request("GET",`/messages/${encodeURIComponent(id)}`,options)).data,reply:async(id,text,options={})=>(await this.#transport.request("POST",`/messages/${encodeURIComponent(id)}/reply`,{...options,body:{content:{type:"text",text,...options.attachments?{attachments:options.attachments}:{}},...options.metadata?{metadata:options.metadata}:{},...options.authorization?{authorization:options.authorization}:{},...options.ttlSeconds===void 0?{}:{ttlSeconds:options.ttlSeconds}},idempotencyKey:options.idempotencyKey??`sdk:reply:${id}`})).data,replyContent:async(id,content2,options={})=>(await this.#transport.request("POST",`/messages/${encodeURIComponent(id)}/reply`,{...options,body:{content:content2},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,ack:async(id,options)=>(await this.#transport.request("POST",`/messages/${encodeURIComponent(id)}/ack`,{...options,body:{},retrySafe:true})).data};send(input,textOrOptions,options){if(typeof input==="string")return this.messages.send({to:input,text:textOrOptions},options);return this.messages.send(input,textOrOptions)}conversations={create:async(input,options)=>{const result=await this.#transport.request("POST","/conversations",{...options,body:input});return new ConversationHandle(this,result.data,input.with)},list:(query={},options)=>this.#transport.request("GET","/conversations",{...options,query}),get:async(id,options)=>(await this.#transport.request("GET",`/conversations/${encodeURIComponent(id)}`,options)).data,messages:(id,query={},options)=>this.#transport.request("GET",`/conversations/${encodeURIComponent(id)}/messages`,{...options,query})};startConversation(input,options){return this.conversations.create(input,options)}missions={list:async options=>(await this.#transport.request("GET","/missions",options)).data.missions,listPage:async(query={},options)=>{const page=await this.#transport.request("GET","/missions",{...options,query});return{data:page.data.missions,nextCursor:page.nextCursor??null}},iterate:(query={},options)=>paginate(cursor=>this.missions.listPage({...query,cursor},options),query.cursor),get:async(id,options)=>{const result=await this.#transport.request("GET",`/missions/${encodeURIComponent(id)}`,options);return{...result.data.mission,members:result.data.members,workItems:result.data.workItems,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,workItemsPage:async(id,query={},options)=>{const page=await this.#transport.request("GET",`/missions/${encodeURIComponent(id)}/work-items`,{...options,query});return{data:page.data.workItems,nextCursor:page.nextCursor??null}},iterateWorkItems:(id,query={},options)=>paginate(cursor=>this.missions.workItemsPage(id,{...query,cursor},options),query.cursor),assign:async(id,input,options={})=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,claim:async(id,workItemId,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items/${encodeURIComponent(workItemId)}/claim`,{...options,body:{}})).data,renew:async(id,workItemId,leaseToken,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items/${encodeURIComponent(workItemId)}/renew`,{...options,body:{leaseToken},retrySafe:true})).data,complete:async(id,workItemId,input,options={})=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/work-items/${encodeURIComponent(workItemId)}/complete`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,reserveEffect:async(id,input,options={})=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/effects`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,listEffects:async(id,workItemId,options)=>(await this.#transport.request("GET",`/missions/${encodeURIComponent(id)}/effects`,{...options,query:{workItemId}})).data.effects,dispatchEffect:async(id,effectId,leaseToken,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/effects/${encodeURIComponent(effectId)}/dispatch`,{...options,body:{leaseToken}})).data,settleEffect:async(id,effectId,input,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/effects/${encodeURIComponent(effectId)}/settle`,{...options,body:input,retrySafe:true})).data,events:{list:(id,query={},options)=>this.#transport.request("GET",`/missions/${encodeURIComponent(id)}/events`,{...options,query}),iterate:(id,query={},options)=>paginate(cursor=>this.missions.events.list(id,{...query,cursor},options),query.cursor),post:async(id,input,options={})=>{if("from"in input||"sender"in input||"actor"in input)throw new TotemError("Mission event actors come from the agent credential.",{code:"INVALID_EVENT"});return(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/events`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data},ack:async(id,eventId,options)=>(await this.#transport.request("POST",`/missions/${encodeURIComponent(id)}/events/${encodeURIComponent(eventId)}/ack`,{...options,body:{},retrySafe:true})).data}};chats={list:(query={},options)=>this.#transport.request("GET","/chats",{...options,query}),get:async(id,options={})=>(await this.#transport.request("GET",`/chats/${encodeURIComponent(id)}`,{signal:options.signal,query:{cursor:options.cursor,before:options.before,limit:options.limit}})).data,updates:async(id,text,options={})=>(await this.#transport.request("POST",`/chats/${encodeURIComponent(id)}/updates`,{...options,body:{text},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data};chatCommands={list:(query={},options)=>this.#transport.request("GET","/chat-commands",{...options,query}),claim:async(id,options)=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/claim`,{...options,body:{}})).data,renew:async(id,leaseToken,options)=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/renew`,{...options,body:{leaseToken},retrySafe:true})).data,complete:async(id,input,options={})=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/complete`,{...options,body:input,idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,fail:async(id,input,options)=>(await this.#transport.request("POST",`/chat-commands/${encodeURIComponent(id)}/fail`,{...options,body:input,retrySafe:true})).data};runtime={activations:async options=>(await this.#transport.request("GET","/runtime/activations",options)).data,reportActivation:async(input,options)=>(await this.#transport.request("POST","/runtime/activations",{...options,body:input,retrySafe:true})).data,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,retrySafe:true})).data};tasks={create:async(input,options={})=>(await this.#transport.request("POST","/tasks",{...options,body:{to:input.to,content:content(input),conversationId:input.conversationId,metadata:input.metadata,ttlSeconds:input.ttlSeconds,authorization:input.authorization},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,get:async(id,options)=>(await this.#transport.request("GET",`/tasks/${encodeURIComponent(id)}`,options)).data,list:(query={},options)=>this.#transport.request("GET","/tasks",{...options,query}),iterate:(query={},options)=>paginate(cursor=>this.tasks.list({...query,cursor},options),query.cursor),postUpdate:async(id,text,options={})=>(await this.#transport.request("POST",`/tasks/${encodeURIComponent(id)}/messages`,{...options,body:{content:{type:"text",text}},idempotencyKey:options.idempotencyKey??idempotencyKey()})).data,update:async(id,input,options)=>(await this.#transport.request("PATCH",`/tasks/${encodeURIComponent(id)}`,{...options,body:input})).data,cancel:async(id,options)=>(await this.#transport.request("POST",`/tasks/${encodeURIComponent(id)}/cancel`,{...options,body:{}})).data};repositories={getTask:async(taskId,options)=>(await this.#transport.request("GET",`/tasks/${encodeURIComponent(taskId)}/repository`,options)).data,claim:async(taskId,input,options)=>(await this.#transport.request("POST",`/tasks/${encodeURIComponent(taskId)}/repository`,{...options,body:input})).data,update:async(taskId,input,options)=>(await this.#transport.request("PATCH",`/tasks/${encodeURIComponent(taskId)}/repository`,{...options,body:input})).data};github={repositories:async options=>(await this.#transport.request("GET","/github/repositories",options)).data,openPullRequest:async(taskId,input,options)=>(await this.#transport.request("POST",`/github/pull-requests?taskId=${encodeURIComponent(taskId)}`,{...options,body:input})).data}}class ConversationHandle{id;conversation;#totem;#recipient;constructor(totem,conversation,recipient){this.#totem=totem;this.conversation=conversation;this.id=conversation.id;this.#recipient=recipient}send(text,options){return this.#totem.messages.send({to:this.#recipient,text,conversationId:this.id},options)}messages(query={},options){return this.#totem.conversations.messages(this.id,query,options)}}class ConnectedAgent{identity;address;client;#subscription;#lastError;#receiver;constructor(client,identity){this.client=client;this.identity=identity;this.address=identity.address;this.#receiver=createAutomaticNetworkListener({client,expectedAgentId:identity.id,notify:(_logger,data)=>{const status=data;if(status.code)this.#lastError=new TotemError("The automatic listener needs attention.",{code:status.code})}});this.#receiver.start()}get listenerStatus(){return this.#receiver.status()}get lastError(){return this.#lastError}send(input,textOrOptions,options){return typeof input==="string"?this.client.send(input,textOrOptions,options):this.client.send(input,textOrOptions)}startConversation(input){return this.client.startConversation(input)}on(event,handler,options={}){if(event!=="message")throw new TotemError("Only message subscriptions are supported.",{code:"INVALID_EVENT"});if(this.#subscription)throw new TotemError("This agent already has a message listener.",{code:"ALREADY_LISTENING"});const interval=options.pollIntervalMs??DEFAULT_LISTENER_POLL_MS;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{options.onError?.(this.#lastError)}catch{}};const done=(async()=>{while(!controller.signal.aborted){try{for await(const message of this.client.messages.iterate({direction:"inbound",unread:true,limit:100},{signal:controller.signal})){if(controller.signal.aborted)break;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)}}}catch(error){if(!controller.signal.aborted)report(error)}if(!controller.signal.aborted){try{await sleep(interval,controller.signal)}catch{}}}})();const subscription={done,stop:async()=>{controller.abort();await done;if(this.#subscription===subscription)this.#subscription=void 0}};this.#subscription=subscription;return subscription}async stop(){await Promise.all([this.#subscription?.stop(),this.#receiver.stop()])}}class TotemAgent extends Totem{}export{ConnectedAgent,ConversationHandle,InspectionError,Totem,TotemAgent,createLocalInspector,idempotencyKey2 as idempotencyKey};

package/bin/sdk/listener.d.ts

@@ -0,0 +1,57 @@
+import type { Totem } from "./index.js";
+export declare const DEFAULT_LISTENER_POLL_MS = 5000;
+export type ListenerStatus = {
+    state: string;
+    listenerReady: boolean;
+    executionAuthorized: false;
+    runId?: string;
+    code?: string;
+    automatic?: boolean;
+    hostKind?: "local" | "hosted";
+};
+export type ListenerOptions = {
+    client: Totem;
+    authorize?: (signal: AbortSignal) => Promise<unknown>;
+    enabled?: () => Promise<boolean>;
+    notify: (logger: string, data: unknown, id?: string) => void | Promise<void>;
+    hostKind?: "local" | "hosted";
+    pollMs?: number;
+    cursors?: {
+        cursor?: string;
+        messageCursor?: string;
+    };
+    signal?: AbortSignal;
+    expectedAgentId?: string;
+};
+/** The same durable feed is used by tools and the connection-owned receiver. */
+export declare function readTotemActivity(client: Totem, { cursor, messageCursor, limit, }: {
+    cursor?: string;
+    messageCursor?: string;
+    limit?: number;
+}, signal: AbortSignal): Promise<{
+    activity: import("./types.js").NetworkActivityPage;
+    messages: {
+        cursor: string;
+        data: import("./types.js").Message[];
+        nextCursor?: string | null;
+        blocked?: Array<{
+            sequence: string;
+        }>;
+    };
+    executionAuthorized: boolean;
+}>;
+/** Lives with the active host connection. Never invokes a model or acknowledges work. */
+export declare function createAutomaticNetworkListener({ client, authorize, enabled, notify, hostKind, pollMs, cursors, signal, expectedAgentId, }: ListenerOptions): {
+    start(): void;
+    stop(): Promise<void>;
+    status(): {
+        state: string;
+        listenerReady: boolean;
+        executionAuthorized: false;
+        runId?: string;
+        code?: string;
+        automatic?: boolean;
+        hostKind?: "local" | "hosted";
+    };
+    done(): Promise<void>;
+};

package/bin/sdk/listener.js

@@ -0,0 +1 @@
+import{sleep}from"./transport.js";const DEFAULT_LISTENER_POLL_MS=5e3;async function readTotemActivity(client,{cursor,messageCursor,limit=25},signal){const[activity,messagesPage]=await Promise.all([client.activity.list({cursor,limit},{signal}),client.messages.list({direction:"all",cursor:messageCursor,limit},{signal})]);const messages=messagesPage;const scanned=[...messages.data,...messages.blocked??[]];const last=scanned.reduce((value,row)=>BigInt(row.sequence)>BigInt(value)?row.sequence:value,messageCursor??"0");return{activity,messages:{...messages,cursor:last},executionAuthorized:false}}function createAutomaticNetworkListener({client,authorize=async()=>{},enabled=async()=>true,notify,hostKind="local",pollMs=DEFAULT_LISTENER_POLL_MS,cursors={},signal,expectedAgentId}){const abort=new AbortController;let pending;let runId;let state={state:"disconnected",listenerReady:false,executionAuthorized:false};let position={...cursors};const options={signal:abort.signal};signal?.addEventListener("abort",()=>abort.abort(),{once:true});if(signal?.aborted)abort.abort();async function status(next){if(state.state===next.state&&state.runId===next.runId)return;state={listenerReady:false,executionAuthorized:false,...next};await notify("totem.listener",state)}async function loop(){try{if(!await enabled()){await status({state:"paused"});return}while(!abort.signal.aborted){let delay=pollMs;try{if(!await enabled()){await status({state:"paused"});break}await authorize(abort.signal);if(!runId){const identity=await client.agent(options);if(expectedAgentId&&identity.id!==expectedAgentId||!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(identity.id)||!["PRODUCTION","SANDBOX"].includes(identity.environment))throw Object.assign(new Error("Unverified agent identity"),{code:"AGENT_IDENTITY_MISMATCH",status:403});const started=await client.runtime.start({runId:globalThis.crypto.randomUUID(),provider:"mcp",hostKind,automatic:true},options);runId=started.runId;const probe=await client.runtime.probe(runId,options);if(probe.provider!=="mcp")throw Object.assign(new Error("Preserve the supervised runtime"),{code:"LISTENER_ALREADY_ACTIVE"});if(!probe.completed)await client.runtime.replyProbe({runId,reply:`TOTEM_READY:${probe.challenge}`},options)}await client.runtime.heartbeat({runId,state:"online",listenerKind:"mcp"},options);await status({state:"listening",listenerReady:true,runId,automatic:true,hostKind});const page=await readTotemActivity(client,position,abort.signal);if(page.activity.data.length||page.messages.data.length||page.messages.blocked?.length){await notify("totem.activity",page,`${page.activity.cursor}:${page.messages.cursor}`)}position={cursor:page.activity.cursor,messageCursor:page.messages.cursor};if(page.activity.nextCursor||page.messages.nextCursor)delay=0}catch(caught){const error=caught;if(abort.signal.aborted)break;if([401,403].includes(error.status??0)||error.code==="AGENT_IDENTITY_MISMATCH"){await status({state:"authorization_rejected",code:error.code});break}runId=void 0;const paused=["LISTENER_PAUSED","LISTENER_STOPPED"].includes(error.code??"");await status({state:paused?"paused":error.code==="LISTENER_ALREADY_ACTIVE"?"managed":"reconnecting",code:error.code??"NETWORK_ERROR"});delay=Math.max(pollMs,Math.min(3e4,(error.retryAfterSeconds??5)*1e3))}await sleep(delay,abort.signal)}}catch(caught){const error=caught;if(!abort.signal.aborted)state={state:"disconnected",listenerReady:false,executionAuthorized:false,code:error.code??"MCP_TRANSPORT_CLOSED"}}finally{state={...state,state:["listening","disconnected"].includes(state.state)?"disconnected":state.state,listenerReady:false}}}return{start(){pending??=loop()},async stop(){abort.abort();await pending},status(){return{...state}},async done(){await pending}}}export{DEFAULT_LISTENER_POLL_MS,createAutomaticNetworkListener,readTotemActivity};

package/bin/sdk/types.d.ts

@@ -1,3 +1,39 @@
+export interface AgentMemoryControls {
+  enabled: boolean;
+  knowledgeRetentionDays: number;
+  workingRetentionDays: number;
+}
+export interface AgentMemoryEntry {
+  id: string;
+  section: "notes" | "workingMemory";
+  text: string;
+  reinforcedAt: string;
+  pinned: boolean;
+  expiresAt: string | null;
+  sourceKey?: string;
+  sourceEventId?: string;
+}
+
+export interface AgentMemory {
+  agentId: string;
+  notes: string;
+  workingMemory: string;
+  version: number;
+  updatedAt: string | null;
+  updatedBy: string | null;
+  controls: AgentMemoryControls;
+  entries: AgentMemoryEntry[];
+  forgottenCount: number;
+  active: { pendingMessages: number; queuedChats: number; openTasks: number };
+}
+
+export interface AgentProfileInput {
+  name: string;
+  localPart: string;
+  description?: string;
+  creationContext: { background?: string; decisions?: string; nextSteps?: string };
+}
+
 export type Metadata = Record<string, unknown>;
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
@@ -22,6 +58,8 @@ export interface AgentRuntimeStatus {
 }
 
 export interface Agent {
+  /** Own authenticated identity only; automatically loaded at connection. */
+  memory?: AgentMemory;
   /** Absent from public discovery; a connected MCP client alone is not a ready listener. */
   runtime?: AgentRuntimeStatus;
     actionMode?: "ask_me" | "full_access";
@@ -652,6 +690,7 @@ export type MessageHandler = (message: IncomingMessage) => void | Promise<void>;
 export interface ListenOptions {
     /** Customer-side policy. Screens message/file plaintext before invoking the handler. */
     inspector?: import("./inspector.js").LocalInspector;
+    /** Healthy inbox checks default to 5000 ms; an explicit host override is preserved. */
     pollIntervalMs?: number;
     /** Receives handler and transport failures; polling continues afterward. */
     onError?: (error: Error) => void;
@@ -703,6 +742,8 @@ export interface ChatDetail {
     previousCursor?: string | null;
 }
 export interface RuntimeHeartbeat {
+  listenerReady?: boolean;
+  listenerKind?: "mcp" | "runtime";
     operationalStatesSupported?: boolean;
     ready?: boolean;
     state?: string;
@@ -726,3 +767,24 @@ export interface NetworkActivityPage extends Page<NetworkActivity> {
   actionMode: "ask_me" | "full_access";
   actionModeVersion: number;
 }
+
+export interface AgentMemorySearch {
+  query?: string;
+  includeHistory?: boolean;
+  before?: number;
+  limit?: number;
+}
+export interface AgentMemoryHistory {
+  data: Array<{
+    id: string;
+    version: number;
+    notes: string;
+    workingMemory: string;
+    source: string;
+    sourceEventId: string | null;
+    createdAt: string;
+    current: boolean;
+    excerpt: string;
+  }>;
+  nextCursor: string | null;
+}

package/bin/startup-diagnostics.mjs

@@ -0,0 +1,168 @@
+// Public diagnostics contain fixed descriptions only. Never log exception messages,
+// provider output, command arguments, paths, or credentials from a failed startup.
+export const HOST_APPROVAL_RECOVERY =
+  "Stop retrying. Ask the owner to inspect this command in the host app's approval or automatic review controls. If no approval path is available, contact the host's support with the denial. Resume once after the owner resolves it; do not bypass the policy or change agents.";
+
+const causes = {
+  HOST_APPROVAL_DENIED: [
+    "The host denied approval to execute the startup command.",
+    HOST_APPROVAL_RECOVERY,
+    false,
+  ],
+  EADDRINUSE: [
+    "The listener could not bind because its port or socket is already in use.",
+    "Inspect the process using the configured port or socket; stop a duplicate listener or choose an available endpoint before starting this profile again.",
+  ],
+  EACCES: [
+    "The operating system denied access to a startup resource.",
+    "Check the owner's access to the executable, private state directory, and configured port; repair the specific permission before restarting.",
+  ],
+  EPERM: [
+    "The operating system denied the startup operation.",
+    "Inspect the host's process and filesystem restrictions and have the owner resolve the denied operation before restarting.",
+  ],
+  ENOENT: [
+    "A required startup executable or file was not found.",
+    "Check the selected executable and private configuration paths; install or restore the missing resource before restarting.",
+  ],
+  ECONNREFUSED: [
+    "The configured service refused the connection.",
+    "Start the configured model or service and check its endpoint before restarting this profile.",
+  ],
+  ENOTFOUND: [
+    "The configured service hostname could not be resolved.",
+    "Check the configured hostname and network DNS, then restart this profile.",
+  ],
+  ETIMEDOUT: [
+    "The startup connection timed out.",
+    "Check the service endpoint and network availability before restarting this profile.",
+  ],
+  RUN_TIMEOUT: [
+    "The executor did not finish the controlled readiness reply before its deadline.",
+    "Check the selected executor and model availability before restarting this profile.",
+  ],
+  PROVIDER_AUTH_REQUIRED: [
+    "The selected inference provider credential is missing or unavailable.",
+    "Restore the selected provider credential in this host's secret environment before restarting. Never copy another agent's key.",
+  ],
+  RUNTIME_AUTHORIZATION_REJECTED: [
+    "Totem rejected the profile's credential or access.",
+    "Reauthorize this agent with totem login --reauthorize. Never copy another agent's key.",
+  ],
+  AGENT_IDENTITY_MISMATCH: [
+    "The authenticated agent does not match the saved profile.",
+    "Inspect this profile's agent and origin; reconnect the intended agent without replacing another agent's configuration.",
+  ],
+  ISOLATION_UNAVAILABLE: [
+    "The selected executor's required process isolation is unavailable.",
+    "Repair the supported isolation backend on this host before restarting; do not disable containment.",
+  ],
+  PRIVACY_BOUNDARY_UNAVAILABLE: [
+    "The executor's required privacy boundary is unavailable.",
+    "Repair the configured privacy boundary before restarting; do not bypass it.",
+  ],
+  AGENT_AUTH_REQUIRED: [
+    "The selected agent client is not authenticated.",
+    "Sign in to the selected client on this host, then explicitly start this profile once.",
+  ],
+  AGENT_QUOTA_EXCEEDED: [
+    "The selected agent provider rejected startup because its usage quota is exhausted.",
+    "Inspect the selected provider's usage limits and resume once capacity is available.",
+  ],
+  AGENT_CLI_INCOMPATIBLE: [
+    "The installed agent CLI does not support the required startup contract.",
+    "Install a supported version of the selected client, then start this profile once.",
+  ],
+  HARNESS_SETUP_REQUIRED: [
+    "The selected host has not completed its native receiver setup.",
+    "Complete the selected host's supported setup and inspect its approval controls before starting this profile.",
+  ],
+  READINESS_UNSUPPORTED: [
+    "The installed adapter cannot verify the controlled readiness check.",
+    "Update the selected adapter to a version that supports receive, wake, and reply verification before claiming readiness.",
+  ],
+  AGENT_NOT_INSTALLED: [
+    "The selected agent executable is not installed or cannot be located.",
+    "Install the selected agent client and check this host's executable path before restarting.",
+  ],
+  AGENT_START_FAILED: [
+    "The executor process could not be launched.",
+    "Check that the selected executable exists and the owner can run it on this host.",
+  ],
+  AGENT_EXIT_FAILED: [
+    "The executor exited with a nonzero status during startup.",
+    "Inspect the selected executor's local diagnostics and sign-in state before restarting; do not share credentials or raw provider output.",
+  ],
+  INVALID_AGENT_RESULT: [
+    "The executor returned an invalid readiness response.",
+    "Check the selected adapter's response format and configured model before restarting.",
+  ],
+  READINESS_CHALLENGE_FAILED: [
+    "Totem could not supply a valid controlled readiness challenge.",
+    "Check Totem connectivity and the installed receiver version before restarting this profile.",
+  ],
+  READINESS_GENERATION_FAILED: [
+    "The selected executor failed while generating the controlled readiness reply; it supplied no recognized cause.",
+    "Inspect the selected executor's local diagnostics and authorization before restarting this profile.",
+  ],
+  READINESS_REPLY_REJECTED: [
+    "Totem did not accept the controlled readiness reply.",
+    "Check that the selected executor returns the exact readiness challenge response and that the runtime session is current before restarting.",
+  ],
+  READINESS_REPLY_INVALID: [
+    "The executor did not return the exact controlled readiness response.",
+    "Check the selected adapter's output contract and repeat the readiness check once after repair.",
+  ],
+  READINESS_EXPIRED: [
+    "The controlled readiness challenge expired before it completed.",
+    "Check executor latency and start a fresh runtime session to obtain a new challenge.",
+  ],
+  RUNTIME_SUPERSEDED: [
+    "Another runtime session owns this connection credential.",
+    "Inspect the existing listener and use its session; stop it explicitly before replacing it. Do not start duplicate workers.",
+  ],
+  BACKGROUND_START_TIMEOUT: [
+    "The background worker did not confirm startup before its deadline.",
+    "Inspect totem status for this profile and the selected executor's local diagnostics before starting it again.",
+  ],
+  STARTUP_CAUSE_UNAVAILABLE: [
+    "Startup failed without a recognized underlying cause.",
+    "Inspect this profile with totem status and the selected executor's local diagnostics before restarting. Share error codes, not credentials or raw provider output.",
+  ],
+};
+
+const known = (code) => typeof code === "string" && Object.hasOwn(causes, code);
+
+export function startupDiagnostic(error) {
+  const chain = [];
+  const seen = new Set();
+  for (
+    let item = error;
+    item && typeof item === "object" && chain.length < 8 && !seen.has(item);
+    item = item.cause
+  ) {
+    seen.add(item);
+    chain.push(item);
+  }
+  const denied = chain.some(
+    (item) =>
+      ["HOST_APPROVAL_DENIED", "APPROVAL_DENIED", "POLICY_DENIED"].includes(item.code) ||
+      /(?:rejected:\s*)?blocked by policy|automatic (?:approval )?review rejected|approval (?:was )?denied/i.test(
+        String(item.message ?? ""),
+      ),
+  );
+  const match = chain
+    .toReversed()
+    .find((item) => known(item.code) || known(item.causeCode) || [401, 403].includes(item.status));
+  const causeCode = denied
+    ? "HOST_APPROVAL_DENIED"
+    : match
+      ? known(match.code)
+        ? match.code
+        : known(match.causeCode)
+          ? match.causeCode
+          : "RUNTIME_AUTHORIZATION_REJECTED"
+      : "STARTUP_CAUSE_UNAVAILABLE";
+  const [cause, recovery, retryable = true] = causes[causeCode];
+  return { causeCode, cause, recovery, retryable };
+}

package/bin/totem.mjs

@@ -239,9 +239,9 @@ function compactDigest(value) {
 function help() {
   writeBrand();
   writeHelpBody(`Start here
-  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-0.1.44.tgz
+  Install once          npm install --global https://totemlayer.com/downloads/totemlayer-0.1.59.tgz
   Confirm installation totem --version
-  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-0.1.44.tgz totem --help
+  Run one-off           npx --yes --package https://totemlayer.com/downloads/totemlayer-0.1.59.tgz totem --help
 
 Connect once and receive messages and approved Mission work
   Select Codex, Claude, a local model, or an owner-configured CLI/HTTP agent.
@@ -255,7 +255,9 @@ Agent messaging and local runtime
   totem network --help
   totem network run --provider qwen-local --model qwen3.5-9b
 
-Connect an AI app through MCP
+Connect any AI agent or personal assistant through MCP
+  totem mcp config
+  totem mcp config --transport stdio --key-file /absolute/path/to/agent.key
   totem mcp
 
 Authorization handshake
@@ -1781,6 +1783,18 @@ async function main() {
     return;
   }
   if (process.argv[2] === "mcp") {
+    if (process.argv[3] === "config") {
+      const { configureTotemMcp } = await import("./mcp-install.mjs");
+      try {
+        process.stdout.write(await configureTotemMcp(process.argv.slice(4)));
+      } catch (error) {
+        process.stderr.write(
+          `${error instanceof Error ? error.message : "Could not export MCP settings."}\n`,
+        );
+        process.exitCode = 1;
+      }
+      return;
+    }
     if (process.argv[3] === "install" || process.argv[3] === "--help" || process.argv[3] === "-h") {
       const { installTotemMcp } = await import("./mcp-install.mjs");
       try {