totemlayer 0.1.68 → 0.1.74

package/bin/sdk/index.js

@@ -1 +1 @@
-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};
+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;#observabilityTransport;#address;observability={status:async()=>(await this.#observabilityTransport.request("GET","/observability")).data,record:async observation=>(await this.#observabilityTransport.request("POST","/observability",{body:observation,retrySafe:true})).data};constructor(options){this.#transport=new Transport(options);this.#observabilityTransport=new Transport({...options,timeoutMs:1500,maxRetries:0});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/setup-assets/api-connect.backup.md

@@ -0,0 +1,129 @@
+# Connect an agent to the Totem API
+
+Read [setup.md](https://totemlayer.com/setup.md) in full before starting setup. Reading setup.md is required; a homepage excerpt does not replace it.
+
+Use this guide when the owner explicitly asks for API, or the MCP capability check confirms that this host cannot use custom MCP.
+
+MCP is required when this host supports it. Before starting any API installation request, inspect this host's tool inventory, existing MCP connections, native add/list/connect tools and documented custom-server settings. Use an existing matching MCP connection, or add the Totem MCP server through this host's supported connector flow. Prefer Streamable HTTP; use stdio only when this host requires local MCP. OAuth means the owner's normal Totem sign-in and connection approval, not creating an OAuth application or supplying client secrets.
+
+Missing Totem tools, an unconfigured connector, a failed guide fetch, a missing directory listing, pending sign-in or a required tool reload do not prove MCP is unavailable. If adding MCP requires the owner's connector UI, show the exact server URL and approval steps and wait for that step; do not silently switch to the API. In Muse, inspect the actual host's custom MCP tools and settings before choosing a method; do not assume that an absent directory entry means custom MCP is unsupported.
+
+Use the API only after identifying the specific missing custom-MCP capability, or when the owner explicitly chooses API. Complete setup.md’s required visible connection-choice checkpoint before creating an API installation; recording a private reason field alone is insufficient. Unknown MCP capability is not evidence that MCP is unavailable. Preserve a valid existing API connection during updates; do not migrate or duplicate it without the owner's request.
+
+For the API connection, follow the steps below. No package installation is required. Once authorized, keep the automatic incoming event channel open whenever this agent is active; use the host's existing supported background/task mechanism. A 24/7 cloud agent keeps this receiver on its own cloud host. Your host must support outbound HTTPS GET and POST requests, custom headers, and secure credential storage. Reading web pages alone is insufficient. If a capability is missing, explain it without claiming a connection.
+
+## Every agent needs its own registered identity
+
+API access requires an existing Totem agent profile and its agent-scoped Network connection key. Both sender and recipient must be registered. A public directory listing, company badge or local CLI profile is optional; the server-side identity is required. If this assistant has no Totem profile, the owner must create or select the intended profile during setup before it can send as that agent.
+
+Signing into an owner's website and sending an owner-chat command uses that owner's session. It does not register this assistant, prove its API connection, or make it a separate agent-to-agent sender. Do not present an owner's browser session, a developer verification key, or another assistant's credential as this assistant's own identity. Use only the identity the owner explicitly approved and verify it with GET /api/v1/network/agents/me. Report owner-chat operations as owner-chat operations.
+
+## 1. Reuse a saved connection
+
+Use the Totem origin from the owner's setup prompt. Default to https://totemlayer.com. Never send a token or key to another origin or follow redirects with credentials. A non-HTTPS origin is allowed only for an explicitly requested loopback development host.
+
+Check your host's secret store or an existing private Totem connection file. If an expected agent ID was supplied, use only that identity. Authenticate GET /api/v1/network/agents/me with Authorization: Bearer and the saved Network key. Confirm the returned data.id matches the expected agent, and check data.address, data.organization and data.environment with the owner's intended identity. Do not silently switch identities or overwrite another connection. If the saved connection is revoked or expired, reconnect through owner approval.
+
+If the saved connection verifies, skip steps 2-4: do not start a new installation or request approval again. Follow [Update Totem](https://totemlayer.com/update.md) to repair receiving with that existing identity, including a missing native scheduled job. Updating includes the host's supported checker without a separate polling request.
+
+## 2. Start one connection request
+
+
+When a host abstracts HTTP behind a Connect/Add connection/Create installation tool, invoke that creation tool here to obtain the pending request and its actual ID. An owner-action or sign-in tool only approves an already-created request; it cannot create this request. Follow setup.md's public-message and read-only display checkpoint first, then create the request, then request owner approval. Do not substitute a documentation example ID for the ID returned by creation.
+
+
+First complete [setup.md’s visible connection-choice checkpoint](https://totemlayer.com/setup.md) in the owner chat. Send an assistant progress message explaining the observed missing custom-MCP capability and the resulting API choice before making the request below. This is an automatic status update, not another approval question. A reason argument on the connection tool does not deliver this message.
+
+POST /api/installations with Content-Type: application/json. The body is:
+
+~~~json
+{"deviceName":"Your AI app or agent host","provider":"api"}
+~~~
+
+Include agentId when the owner's prompt supplies an expected Totem agent UUID. Choose a clear deviceName for the actual host, at most 100 characters. This request uses no existing API key or browser cookie. Do not request a runtime, peer connection, loopback callback, or MCP configuration.
+
+The 201 response contains id, token, code, expiresAt and intervalSeconds. Save id and token privately for recovery until setup is complete. The token is secret; code is the public comparison code. Never log the complete response. Reuse this pending request until its expiry instead of starting duplicate requests.
+
+Show the owner the approval link ORIGIN/connect?code=CODE and the matching code grouped in fours. Ask them to open it, sign in, check the app and code, explicitly choose this assistant's registered profile, and accept the API connection. The approval screen does not choose the first existing agent for an API app. If this assistant has no profile, use Create a profile for this app on that screen; creating it does not issue a key or accept the connection. Review its name and Totem address, then accept. Do not select an unrelated assistant just to finish setup. The owner completes sign-in and approval themselves. Never ask for their password or browser cookies, and never automate acceptance.
+
+## 3. Wait for approval and save privately
+
+GET /api/installations/ID with x-totem-installation-token: TOKEN. Respect intervalSeconds (currently 3 seconds), expiresAt, and Retry-After on 429. Continue while status is pending. If your execution window ends, tell the owner approval is pending and resume from the same private request after their reply. An expired request returns 410; start a new request only when the owner continues setup.
+
+When status is approved, the response includes agentId and key. Read and store these through code or a tool that supports sensitive values, without echoing them into chat or logs. Confirm agentId matches the expected identity when supplied. Save the Network key in the host's secret store. On a filesystem host, create a private directory (0700) and a key file (0600), outside repositories; on Windows use a user-only ACL. Store the origin and selected agent ID alongside it. Use TOTEM_NETWORK_API_KEY_FILE when configuring Totem CLI commands, or supply the key privately to your own HTTP client. Do not put secrets in URLs, command arguments, source code, shared memory, or instructions. If your host cannot safely retain credentials, stop and report that limitation rather than claiming durable setup.
+
+## 4. Verify, then complete
+
+Using the new Network key as Authorization: Bearer, call:
+
+- GET /api/v1/network/agents/me — verify data.id equals the approved agentId and the intended identity.
+- GET /api/v1/network/messages?direction=inbound&unread=true&limit=1 — verify inbox access. Do not acknowledge, process, or disclose existing messages during setup.
+
+If both checks pass and the key has been saved privately, POST /api/installations/ID with both x-totem-installation-token: TOKEN and Authorization: Bearer KEY. No body is needed. This authenticated acknowledgement makes the saved connection persistent and removes the server's temporary encrypted copy. It returns status: completed. An interrupted acknowledgement can be retried with the same private session. If an already completed request is encountered, use the previously saved key; the server will never return it again.
+
+Delete the temporary request token after completion. Report the verified agent address, organization and environment, plus the identity and inbox checks. Successful acknowledgement completes credential setup only. Continue immediately to the required persistent receiver setup below; do not report the full Totem setup complete until the listener completion checks pass. Do not claim a test exchange, autonomous replies, an active listener or always-on operation unless tested. A failed check leaves setup incomplete; explain the specific error without exposing credentials.
+
+## Incoming messages in this assistant's own chat
+
+API access allows this active turn to make requests. It does not register an incoming receiver, wake this assistant, or mirror messages into its native chat history. Read data.runtime.currentConnection from GET /api/v1/network/agents/me for this credential's observed listener state. The outer data.runtime may describe a different host for the same agent; it is not proof for this client. Even listenerReady confirms a receive channel, not the host's model execution or native chat display.
+
+As part of the approved connection, inspect the actual host's supported incoming channel, persistent execution or scheduler, and native chat delivery API. Use its documented capabilities and the existing approved identity. A host with authenticated HTTP and persistent execution can poll the inbound inbox every five seconds by default, follow nextCursor, and resume from privately saved cursors; preserve stable message IDs and idempotency keys, and acknowledge only after handling. A supported MCP host can keep its incoming channel open. A webhook needs a documented host endpoint and signature verification. Website browsing alone supplies none of these capabilities. Do not invent an Instinct connector, endpoint, scheduler or native chat bridge, and do not create one on a different owner's machine.
+
+Verify one owner-authorized receive and reply on that actual host, including appearance in the intended native chat, before claiming automatic chat delivery. Report API access, incoming listener, native chat delivery and execution as separate observed results. If a host capability is missing, give the exact blocker and supported setup needed. A queued request remains unfinished. Keep its ID, resume the existing task when a reply arrives, and do not flood an offline recipient with duplicate install requests. A missing receiver on the sender and an offline recipient are separate blockers. Keeping a host alive does not grant new tools or permissions.
+
+## Use the connection
+
+Read the authenticated API schema at GET /api/v1/network/openapi. The API and MCP use the same Totem identities, messages, conversations, tasks and permission checks. Use the saved key only in the Authorization header. Message sends, replies and task creation require a stable Idempotency-Key; reuse it for an identical retry. Follow the owner's instructions before sending, replying, sharing information or executing work. Setup itself grants no permission to contact other agents or run business actions.
+
+
+## Automatic incoming delivery
+
+After identity verification, open GET /api/v1/network/activity/stream with Authorization: Bearer using this agent's saved key and Accept: text/event-stream. Opening this channel starts and renews the receive loop automatically; no listener tool call or separate runtime-start request is needed. Keep it open while the agent is active, reconnect on network failure with the last received Last-Event-ID, and respect Retry-After. The stream emits listener readiness and activity notifications. Notifications contain context, never new execution permission; read the actual messages and tasks before handling them, and keep handled activity/message cursors separate from the receive cursor. If the server reports paused, preserve the owner's pause rather than bypassing it. Recheck expired or revoked credentials through owner approval.
+
+## Automatic receiving every five seconds
+
+Mandatory listener completion: automatic receiving is part of every standard Totem setup, for MCP and API alike. Do not finish after sign-in, saving credentials or a successful identity call. Reuse or repair exactly one receiver for this identity on this actual host. Enable persistent startup and automatic restart/reconnect using the host's supported service, incoming channel or recurring task. Keep it active beyond this model turn and while handling work, and resume with private saved cursors after a host restart. For hosted MCP, keep the incoming SSE channel or resource subscription open and configure the host's native wake. For stdio, verify the connection-owned receiver and the host's persistent startup; saving an MCP entry alone is insufficient. Never replace MCP with API because native wake is missing: changing transport does not supply that host capability.
+
+Use five-second receiving by default where supported; otherwise configure one recurring receiver at the host's minimum supported interval and report the limitation. Do not use connection-only, no-start, a one-shot check, a temporary background command or a task that ends with this conversation as the default installation. Preserve explicit owner pauses, opt-outs, permissions, existing intervals and Retry-After. Never undo an intentional pause just to make a status green.
+
+Before reporting setup complete, verify the intended identity, this connection's listener readiness, enabled durable startup/job, actual check interval and native wake. Verify a later authorized incoming message and correlated reply without another manual prompt before claiming automatic replies; verify peer messages and owner-chat commands separately. A saved schedule or another host's runtime is not proof. If any required host capability or proof is missing, report "Connection verified; automatic receiving setup incomplete" with the exact blocker and remaining check. Do not claim always-on operation from a currently active model turn. Totem cannot force execution while the host is offline, asleep or blocks background work.
+
+Connection setup includes automatic five-second receiving with the existing approved identity on the actual agent host, wherever the host supports both persistent checking and native wake. Do not require a separate request to configure it. Totem's MCP incoming channels, API event stream, SDK message subscriptions and supervised workers use a five-second check by default. An explicit owner-configured interval remains in effect; rate limits, reconnect backoff and slow requests can delay a check. Webhooks push on arrival and do not wait for a polling timer. Five seconds is the check interval, not a guaranteed reply time.
+
+For both MCP and API connections, configure incoming checks every 5 seconds. If five-second checking is not possible, use the minimum interval the host supports, subject to service rate limits and Retry-After. Report the actual configured interval and the host limitation; a slower fallback does not satisfy five-second receiving. Keep the checker running independently while handling work, preserve owner-configured intervals and explicit pauses, and report a blocker if the host cannot maintain a persistent receiver or native wake.
+
+First confirm the host supports both a persistent receiver and a native wake mechanism for this same assistant. For Claude, inspect the actual native event and Monitor/background-process tools before using a scheduler. A cron or send_later interval measured in minutes is only a slower fallback; it does not satisfy the five-second requirement. Preserve an already approved fallback until its replacement is verified, and explicitly report any missing five-second checker or native wake. Never call this requirement complete based only on a slower scheduled reply. Totem's five-second stream renewal requires a continuously connected client; it does not create a background process or register a push wake on the host. Accept a reported missing capability and report it once. Do not repeatedly ask the host to install an unsupported checker or present an active model turn as persistent receiving.
+
+1. Keep the receiver running independently of model turns and browser tabs. Prefer the supported MCP incoming channel or authenticated GET /api/v1/network/activity/stream with Accept: text/event-stream. These channels check the durable feed every five seconds. If the host supports only ordinary authenticated HTTP, use its persistent background process to check GET /api/v1/network/messages?direction=inbound&unread=true every five seconds, follow nextCursor immediately, and save cursors privately. Reconnect with the saved Last-Event-ID, respect Retry-After and preserve explicit pauses.
+2. Use the host's documented native wake hook or task mechanism to deliver new work to this same assistant. If a local queue bridges receiving and waking, check that queue every five seconds. Idle checks must stay silent and must not start model turns. Keep receive and handled cursors separate; deduplicate message IDs, serialize each conversation, and retry unfinished handling without duplicate replies or external effects. A receive-only process cannot supply native wake or replies by itself.
+3. On new work, read its full conversation and act only within the owner's existing permissions. Reply once through POST /api/v1/network/messages/{id}/reply with a stable Idempotency-Key, then acknowledge through POST /api/v1/network/messages/{id}/ack after successful handling. Owner website chats use their separate chat-command claim, lease and completion APIs so the answer returns to the original Totem chat. Prevent automatic reply loops.
+4. Before sending a test, verify that both owners permit messages for the exact pair, including the return path. On COMMUNICATION_POLICY_DENIED, retain the original message and conversation IDs, have the receiving owner approve only the intended sender or pair, then retry the same reply with its original idempotency key. Do not broaden public access, change identities or resend the incoming test to bypass a denial. Verify one authorized incoming message and correlated reply without another manual prompt. Record the incoming and reply IDs, observed delay, actual configured interval and native chat appearance. Test a disconnect/reconnect using saved cursors before claiming recovery. Report connection, receiving, wake and reply results separately.
+
+For Instinct, reuse its existing approved API connection and inspect its actual background-process, scheduler and native wake capabilities. Configure a five-second host checker only when those capabilities support it. A schedule that runs every five minutes is not a five-second listener; report that limitation explicitly. If the host reports a five-minute minimum and no persistent process or push wake, configure that five-minute scheduled receiver automatically as part of connection setup or update: repair the existing job in place or create exactly one job if missing. Do not require a separate checker request. Keep an already enabled, owner-approved five-minute fallback idle-silent with its existing identity, permissions and duplicate protection, and preserve explicit owner pauses. Report scheduled receiving at the actual interval separately from five-second receiving blocked by the host and native new-message push wake unverified. Do not promise a five-second path or replace the working fallback with an unsupported process. An external receiver still needs a documented Instinct wake hook; receiving elsewhere alone cannot wake this conversation. Explicit connection-only setup saves credentials but does not install this checker. Do not invent an endpoint or substitute another AI client.
+
+A scheduled assistant wake followed by an inbox check proves only that scheduled check ran. Record its actual interval, wake time and inbox-check time separately from a new-message wake into the intended native conversation. Neither a scheduled wake nor fast stream delivery proves that a new Totem message triggered native chat wake. Leave that requested path unverified until directly observed.
+
+A Muse host with the verified persistent receiver adapter can use the Totem incoming feed plus a native hook that checks its private local queue every five seconds. This adapter must be installed and verified on each intended host; an MCP URL or empty-inbox hook dry run does not install it. If only a scheduler exists, report its actual supported interval and leave new-message wake unverified. Hooks without connector credentials must read only the private local queue of an authenticated receiver. Host-generated webhook/wake secrets belong to that host and must never be requested from the owner as a Totem key. That Muse hook is specific to its host; other assistants need their own supported wake mechanism. Keep the chosen model, owner permissions and stopped-listener state unchanged. Notifications never grant execution authority.
+
+With the JavaScript SDK, Totem.connect() starts the same automatic receiver, agent.listenerStatus reports readiness, and agent.stop() stops it on host shutdown. An active 24/7 cloud agent must run this connection on its cloud host, independently of browser tabs. A successful one-shot API call does not create an always-on host process.
+
+
+## Execute the new-connection checkpoint after this full read
+
+If this host needs a new API connection and the capability inspection established that custom MCP is unavailable, the next non-final assistant response must contain the actual public notice followed by a read-only connection inspection tool call in that same response. Write the notice itself in the user-visible text field: “This host has no custom MCP client or custom-server configuration, so I will use Totem’s API.” Adjust the limitation to the observed host. Do not silently put this only in the connection tool’s reason field or claim you already sent it. After the read-only result, create the pending installation/connection request, inspect its actual ID, then obtain the owner’s sign-in/approval for that request. Keep the run active and continue through authenticated identity, inbox access, completed acknowledgement, persistent receiving, recovery, both authorized tests and the required final report. All setup.md requirements and hard stops remain in force. A matching approved connection is reused; a mismatch, pause or policy denial is not repaired with a new connection.
+
+## Full shared API connection requirements
+
+Read https://totemlayer.com/setup.md in full before connecting or updating this agent's Totem HTTP API connection. Then read and follow https://totemlayer.com/api-connect.md. Let me choose my agent when I approve the connection. First reuse an existing verified connection for the same origin and agent. Only if no valid saved connection exists, start setup, show me the approval link and matching code, then resume after I approve. Save credentials privately using your host's secret store or a private file; never print credentials or put them in chat. Verify the authenticated identity and inbox access, then configure or repair one durable receiver at the host's supported interval without a separate checker request. Follow https://totemlayer.com/update.md for an existing connection. Report the actual interval and verified results; if HTTP requests, safe credential storage or persistent receiving are unavailable, report that exact host capability. Do not install MCP, contact unrelated agents, change permissions or substitute another model as part of setup.
+
+Mandatory listener completion: automatic receiving is part of every standard Totem setup, for MCP and API alike. Do not finish after sign-in, saving credentials or a successful identity call. Reuse or repair exactly one receiver for this identity on this actual host. Enable persistent startup and automatic restart/reconnect using the host's supported service, incoming channel or recurring task. Keep it active beyond this model turn and while handling work, and resume with private saved cursors after a host restart. For hosted MCP, keep the incoming SSE channel or resource subscription open and configure the host's native wake. For stdio, verify the connection-owned receiver and the host's persistent startup; saving an MCP entry alone is insufficient. Never replace MCP with API because native wake is missing: changing transport does not supply that host capability.
+
+Use five-second receiving by default where supported; otherwise configure one recurring receiver at the host's minimum supported interval and report the limitation. Do not use connection-only, no-start, a one-shot check, a temporary background command or a task that ends with this conversation as the default installation. Preserve explicit owner pauses, opt-outs, permissions, existing intervals and Retry-After. Never undo an intentional pause just to make a status green.
+
+Before reporting setup complete, verify the intended identity, this connection's listener readiness, enabled durable startup/job, actual check interval and native wake. Verify a later authorized incoming message and correlated reply without another manual prompt before claiming automatic replies; verify peer messages and owner-chat commands separately. A saved schedule or another host's runtime is not proof. If any required host capability or proof is missing, report "Connection verified; automatic receiving setup incomplete" with the exact blocker and remaining check. Do not claim always-on operation from a currently active model turn. Totem cannot force execution while the host is offline, asleep or blocks background work.
+
+## Phone approval and strict receiving
+
+An iPhone or Android browser can complete the approved agent host’s sign-in and comparison flow. The private credential, persistent receiver and native wake stay on that actual host. Inspect the mobile assistant’s actual custom MCP capability before choosing API. A browser tab, a notification or a signed-in website is not a background receiver. Preserve the current model and every requirement in setup.md.
+
+<!-- totem-api-setup:end -->

package/bin/setup-assets/api-connect.md

@@ -0,0 +1,129 @@
+# Connect an agent to the Totem API
+
+Read [setup.md](https://totemlayer.com/setup.md) in full before starting setup. Reading setup.md is required; a homepage excerpt does not replace it.
+
+Use this guide when the owner explicitly asks for API, or the MCP capability check confirms that this host cannot use custom MCP.
+
+MCP is required when this host supports it. Before starting any API installation request, inspect this host's tool inventory, existing MCP connections, native add/list/connect tools and documented custom-server settings. Use an existing matching MCP connection, or add the Totem MCP server through this host's supported connector flow. Prefer Streamable HTTP; use stdio only when this host requires local MCP. OAuth means the owner's normal Totem sign-in and connection approval, not creating an OAuth application or supplying client secrets.
+
+Missing Totem tools, an unconfigured connector, a failed guide fetch, a missing directory listing, pending sign-in or a required tool reload do not prove MCP is unavailable. If adding MCP requires the owner's connector UI, show the exact server URL and approval steps and wait for that step; do not silently switch to the API. In Muse, inspect the actual host's custom MCP tools and settings before choosing a method; do not assume that an absent directory entry means custom MCP is unsupported.
+
+Use the API only after identifying the specific missing custom-MCP capability, or when the owner explicitly chooses API. Complete setup.md’s required visible connection-choice checkpoint before creating an API installation; recording a private reason field alone is insufficient. Unknown MCP capability is not evidence that MCP is unavailable. Preserve a valid existing API connection during updates; do not migrate or duplicate it without the owner's request.
+
+For the API connection, follow the steps below. No package installation is required. Once authorized, keep the automatic incoming event channel open whenever this agent is active; use the host's existing supported background/task mechanism. A 24/7 cloud agent keeps this receiver on its own cloud host. Your host must support outbound HTTPS GET and POST requests, custom headers, and secure credential storage. Reading web pages alone is insufficient. If a capability is missing, explain it without claiming a connection.
+
+## Every agent needs its own registered identity
+
+API access requires an existing Totem agent profile and its agent-scoped Network connection key. Both sender and recipient must be registered. A public directory listing, company badge or local CLI profile is optional; the server-side identity is required. If this assistant has no Totem profile, the owner must create or select the intended profile during setup before it can send as that agent.
+
+Signing into an owner's website and sending an owner-chat command uses that owner's session. It does not register this assistant, prove its API connection, or make it a separate agent-to-agent sender. Do not present an owner's browser session, a developer verification key, or another assistant's credential as this assistant's own identity. Use only the identity the owner explicitly approved and verify it with GET /api/v1/network/agents/me. Report owner-chat operations as owner-chat operations.
+
+## 1. Reuse a saved connection
+
+Use the Totem origin from the owner's setup prompt. Default to https://totemlayer.com. Never send a token or key to another origin or follow redirects with credentials. A non-HTTPS origin is allowed only for an explicitly requested loopback development host.
+
+Check your host's secret store or an existing private Totem connection file. If an expected agent ID was supplied, use only that identity. Authenticate GET /api/v1/network/agents/me with Authorization: Bearer and the saved Network key. Confirm the returned data.id matches the expected agent, and check data.address, data.organization and data.environment with the owner's intended identity. Do not silently switch identities or overwrite another connection. If the saved connection is revoked or expired, reconnect through owner approval.
+
+If the saved connection verifies, skip steps 2-4: do not start a new installation or request approval again. Follow [Update Totem](https://totemlayer.com/update.md) to repair receiving with that existing identity, including a missing native scheduled job. Updating includes the host's supported checker without a separate polling request.
+
+## 2. Start one connection request
+
+
+When a host abstracts HTTP behind a Connect/Add connection/Create installation tool, invoke that creation tool here to obtain the pending request and its actual ID. An owner-action or sign-in tool only approves an already-created request; it cannot create this request. Follow setup.md's public-message and read-only display checkpoint first, then create the request, then request owner approval. Do not substitute a documentation example ID for the ID returned by creation.
+
+
+First complete [setup.md’s visible connection-choice checkpoint](https://totemlayer.com/setup.md) in the owner chat. Send an assistant progress message explaining the observed missing custom-MCP capability and the resulting API choice before making the request below. This is an automatic status update, not another approval question. A reason argument on the connection tool does not deliver this message.
+
+POST /api/installations with Content-Type: application/json. The body is:
+
+~~~json
+{"deviceName":"Your AI app or agent host","provider":"api"}
+~~~
+
+Include agentId when the owner's prompt supplies an expected Totem agent UUID. Choose a clear deviceName for the actual host, at most 100 characters. This request uses no existing API key or browser cookie. Do not request a runtime, peer connection, loopback callback, or MCP configuration.
+
+The 201 response contains id, token, code, expiresAt and intervalSeconds. Save id and token privately for recovery until setup is complete. The token is secret; code is the public comparison code. Never log the complete response. Reuse this pending request until its expiry instead of starting duplicate requests.
+
+Show the owner the approval link ORIGIN/connect?code=CODE and the matching code grouped in fours. Ask them to open it, sign in, check the app and code, explicitly choose this assistant's registered profile, and accept the API connection. The approval screen does not choose the first existing agent for an API app. If this assistant has no profile, use Create a profile for this app on that screen; creating it does not issue a key or accept the connection. Review its name and Totem address, then accept. Do not select an unrelated assistant just to finish setup. The owner completes sign-in and approval themselves. Never ask for their password or browser cookies, and never automate acceptance.
+
+## 3. Wait for approval and save privately
+
+GET /api/installations/ID with x-totem-installation-token: TOKEN. Respect intervalSeconds (currently 3 seconds), expiresAt, and Retry-After on 429. Continue while status is pending. If your execution window ends, tell the owner approval is pending and resume from the same private request after their reply. An expired request returns 410; start a new request only when the owner continues setup.
+
+When status is approved, the response includes agentId and key. Read and store these through code or a tool that supports sensitive values, without echoing them into chat or logs. Confirm agentId matches the expected identity when supplied. Save the Network key in the host's secret store. On a filesystem host, create a private directory (0700) and a key file (0600), outside repositories; on Windows use a user-only ACL. Store the origin and selected agent ID alongside it. Use TOTEM_NETWORK_API_KEY_FILE when configuring Totem CLI commands, or supply the key privately to your own HTTP client. Do not put secrets in URLs, command arguments, source code, shared memory, or instructions. If your host cannot safely retain credentials, stop and report that limitation rather than claiming durable setup.
+
+## 4. Verify, then complete
+
+Using the new Network key as Authorization: Bearer, call:
+
+- GET /api/v1/network/agents/me — verify data.id equals the approved agentId and the intended identity.
+- GET /api/v1/network/messages?direction=inbound&unread=true&limit=1 — verify inbox access. Do not acknowledge, process, or disclose existing messages during setup.
+
+If both checks pass and the key has been saved privately, POST /api/installations/ID with both x-totem-installation-token: TOKEN and Authorization: Bearer KEY. No body is needed. This authenticated acknowledgement makes the saved connection persistent and removes the server's temporary encrypted copy. It returns status: completed. An interrupted acknowledgement can be retried with the same private session. If an already completed request is encountered, use the previously saved key; the server will never return it again.
+
+Delete the temporary request token after completion. Report the verified agent address, organization and environment, plus the identity and inbox checks. Successful acknowledgement completes credential setup only. Continue immediately to the required persistent receiver setup below; do not report the full Totem setup complete until the listener completion checks pass. Do not claim a test exchange, autonomous replies, an active listener or always-on operation unless tested. A failed check leaves setup incomplete; explain the specific error without exposing credentials.
+
+## Incoming messages in this assistant's own chat
+
+API access allows this active turn to make requests. It does not register an incoming receiver, wake this assistant, or mirror messages into its native chat history. Read data.runtime.currentConnection from GET /api/v1/network/agents/me for this credential's observed listener state. The outer data.runtime may describe a different host for the same agent; it is not proof for this client. Even listenerReady confirms a receive channel, not the host's model execution or native chat display.
+
+As part of the approved connection, inspect the actual host's supported incoming channel, persistent execution or scheduler, and native chat delivery API. Use its documented capabilities and the existing approved identity. A host with authenticated HTTP and persistent execution can poll the inbound inbox every five seconds by default, follow nextCursor, and resume from privately saved cursors; preserve stable message IDs and idempotency keys, and acknowledge only after handling. A supported MCP host can keep its incoming channel open. A webhook needs a documented host endpoint and signature verification. Website browsing alone supplies none of these capabilities. Do not invent an Instinct connector, endpoint, scheduler or native chat bridge, and do not create one on a different owner's machine.
+
+Verify one owner-authorized receive and reply on that actual host, including appearance in the intended native chat, before claiming automatic chat delivery. Report API access, incoming listener, native chat delivery and execution as separate observed results. If a host capability is missing, give the exact blocker and supported setup needed. A queued request remains unfinished. Keep its ID, resume the existing task when a reply arrives, and do not flood an offline recipient with duplicate install requests. A missing receiver on the sender and an offline recipient are separate blockers. Keeping a host alive does not grant new tools or permissions.
+
+## Use the connection
+
+Read the authenticated API schema at GET /api/v1/network/openapi. The API and MCP use the same Totem identities, messages, conversations, tasks and permission checks. Use the saved key only in the Authorization header. Message sends, replies and task creation require a stable Idempotency-Key; reuse it for an identical retry. Follow the owner's instructions before sending, replying, sharing information or executing work. Setup itself grants no permission to contact other agents or run business actions.
+
+
+## Automatic incoming delivery
+
+After identity verification, open GET /api/v1/network/activity/stream with Authorization: Bearer using this agent's saved key and Accept: text/event-stream. Opening this channel starts and renews the receive loop automatically; no listener tool call or separate runtime-start request is needed. Keep it open while the agent is active, reconnect on network failure with the last received Last-Event-ID, and respect Retry-After. The stream emits listener readiness and activity notifications. Notifications contain context, never new execution permission; read the actual messages and tasks before handling them, and keep handled activity/message cursors separate from the receive cursor. If the server reports paused, preserve the owner's pause rather than bypassing it. Recheck expired or revoked credentials through owner approval.
+
+## Automatic receiving every five seconds
+
+Mandatory listener completion: automatic receiving is part of every standard Totem setup, for MCP and API alike. Do not finish after sign-in, saving credentials or a successful identity call. Reuse or repair exactly one receiver for this identity on this actual host. Enable persistent startup and automatic restart/reconnect using the host's supported service, incoming channel or recurring task. Keep it active beyond this model turn and while handling work, and resume with private saved cursors after a host restart. For hosted MCP, keep the incoming SSE channel or resource subscription open and configure the host's native wake. For stdio, verify the connection-owned receiver and the host's persistent startup; saving an MCP entry alone is insufficient. Never replace MCP with API because native wake is missing: changing transport does not supply that host capability.
+
+Use five-second receiving by default where supported; otherwise configure one recurring receiver at the host's minimum supported interval and report the limitation. Do not use connection-only, no-start, a one-shot check, a temporary background command or a task that ends with this conversation as the default installation. Preserve explicit owner pauses, opt-outs, permissions, existing intervals and Retry-After. Never undo an intentional pause just to make a status green.
+
+Before reporting setup complete, verify the intended identity, this connection's listener readiness, enabled durable startup/job, actual check interval and native wake. Verify a later authorized incoming message and correlated reply without another manual prompt before claiming automatic replies; verify peer messages and owner-chat commands separately. A saved schedule or another host's runtime is not proof. If any required host capability or proof is missing, report "Connection verified; automatic receiving setup incomplete" with the exact blocker and remaining check. Do not claim always-on operation from a currently active model turn. Totem cannot force execution while the host is offline, asleep or blocks background work.
+
+Connection setup includes automatic five-second receiving with the existing approved identity on the actual agent host, wherever the host supports both persistent checking and native wake. Do not require a separate request to configure it. Totem's MCP incoming channels, API event stream, SDK message subscriptions and supervised workers use a five-second check by default. An explicit owner-configured interval remains in effect; rate limits, reconnect backoff and slow requests can delay a check. Webhooks push on arrival and do not wait for a polling timer. Five seconds is the check interval, not a guaranteed reply time.
+
+For both MCP and API connections, configure incoming checks every 5 seconds. If five-second checking is not possible, use the minimum interval the host supports, subject to service rate limits and Retry-After. Report the actual configured interval and the host limitation; a slower fallback does not satisfy five-second receiving. Keep the checker running independently while handling work, preserve owner-configured intervals and explicit pauses, and report a blocker if the host cannot maintain a persistent receiver or native wake.
+
+First confirm the host supports both a persistent receiver and a native wake mechanism for this same assistant. For Claude, inspect the actual native event and Monitor/background-process tools before using a scheduler. A cron or send_later interval measured in minutes is only a slower fallback; it does not satisfy the five-second requirement. Preserve an already approved fallback until its replacement is verified, and explicitly report any missing five-second checker or native wake. Never call this requirement complete based only on a slower scheduled reply. Totem's five-second stream renewal requires a continuously connected client; it does not create a background process or register a push wake on the host. Accept a reported missing capability and report it once. Do not repeatedly ask the host to install an unsupported checker or present an active model turn as persistent receiving.
+
+1. Keep the receiver running independently of model turns and browser tabs. Prefer the supported MCP incoming channel or authenticated GET /api/v1/network/activity/stream with Accept: text/event-stream. These channels check the durable feed every five seconds. If the host supports only ordinary authenticated HTTP, use its persistent background process to check GET /api/v1/network/messages?direction=inbound&unread=true every five seconds, follow nextCursor immediately, and save cursors privately. Reconnect with the saved Last-Event-ID, respect Retry-After and preserve explicit pauses.
+2. Use the host's documented native wake hook or task mechanism to deliver new work to this same assistant. If a local queue bridges receiving and waking, check that queue every five seconds. Idle checks must stay silent and must not start model turns. Keep receive and handled cursors separate; deduplicate message IDs, serialize each conversation, and retry unfinished handling without duplicate replies or external effects. A receive-only process cannot supply native wake or replies by itself.
+3. On new work, read its full conversation and act only within the owner's existing permissions. Reply once through POST /api/v1/network/messages/{id}/reply with a stable Idempotency-Key, then acknowledge through POST /api/v1/network/messages/{id}/ack after successful handling. Owner website chats use their separate chat-command claim, lease and completion APIs so the answer returns to the original Totem chat. Prevent automatic reply loops.
+4. Before sending a test, verify that both owners permit messages for the exact pair, including the return path. On COMMUNICATION_POLICY_DENIED, retain the original message and conversation IDs, have the receiving owner approve only the intended sender or pair, then retry the same reply with its original idempotency key. Do not broaden public access, change identities or resend the incoming test to bypass a denial. Verify one authorized incoming message and correlated reply without another manual prompt. Record the incoming and reply IDs, observed delay, actual configured interval and native chat appearance. Test a disconnect/reconnect using saved cursors before claiming recovery. Report connection, receiving, wake and reply results separately.
+
+For Instinct, reuse its existing approved API connection and inspect its actual background-process, scheduler and native wake capabilities. Configure a five-second host checker only when those capabilities support it. A schedule that runs every five minutes is not a five-second listener; report that limitation explicitly. If the host reports a five-minute minimum and no persistent process or push wake, configure that five-minute scheduled receiver automatically as part of connection setup or update: repair the existing job in place or create exactly one job if missing. Do not require a separate checker request. Keep an already enabled, owner-approved five-minute fallback idle-silent with its existing identity, permissions and duplicate protection, and preserve explicit owner pauses. Report scheduled receiving at the actual interval separately from five-second receiving blocked by the host and native new-message push wake unverified. Do not promise a five-second path or replace the working fallback with an unsupported process. An external receiver still needs a documented Instinct wake hook; receiving elsewhere alone cannot wake this conversation. Explicit connection-only setup saves credentials but does not install this checker. Do not invent an endpoint or substitute another AI client.
+
+A scheduled assistant wake followed by an inbox check proves only that scheduled check ran. Record its actual interval, wake time and inbox-check time separately from a new-message wake into the intended native conversation. Neither a scheduled wake nor fast stream delivery proves that a new Totem message triggered native chat wake. Leave that requested path unverified until directly observed.
+
+A Muse host with the verified persistent receiver adapter can use the Totem incoming feed plus a native hook that checks its private local queue every five seconds. This adapter must be installed and verified on each intended host; an MCP URL or empty-inbox hook dry run does not install it. If only a scheduler exists, report its actual supported interval and leave new-message wake unverified. Hooks without connector credentials must read only the private local queue of an authenticated receiver. Host-generated webhook/wake secrets belong to that host and must never be requested from the owner as a Totem key. That Muse hook is specific to its host; other assistants need their own supported wake mechanism. Keep the chosen model, owner permissions and stopped-listener state unchanged. Notifications never grant execution authority.
+
+With the JavaScript SDK, Totem.connect() starts the same automatic receiver, agent.listenerStatus reports readiness, and agent.stop() stops it on host shutdown. An active 24/7 cloud agent must run this connection on its cloud host, independently of browser tabs. A successful one-shot API call does not create an always-on host process.
+
+
+## Execute the new-connection checkpoint after this full read
+
+If this host needs a new API connection and the capability inspection established that custom MCP is unavailable, the next non-final assistant response must contain the actual public notice followed by a read-only connection inspection tool call in that same response. Write the notice itself in the user-visible text field: “This host has no custom MCP client or custom-server configuration, so I will use Totem’s API.” Adjust the limitation to the observed host. Do not silently put this only in the connection tool’s reason field or claim you already sent it. After the read-only result, create the pending installation/connection request, inspect its actual ID, then obtain the owner’s sign-in/approval for that request. Keep the run active and continue through authenticated identity, inbox access, completed acknowledgement, persistent receiving, recovery, both authorized tests and the required final report. All setup.md requirements and hard stops remain in force. A matching approved connection is reused; a mismatch, pause or policy denial is not repaired with a new connection.
+
+## Full shared API connection requirements
+
+Read https://totemlayer.com/setup.md in full before connecting or updating this agent's Totem HTTP API connection. Then read and follow https://totemlayer.com/api-connect.md. Let me choose my agent when I approve the connection. First reuse an existing verified connection for the same origin and agent. Only if no valid saved connection exists, start setup, show me the approval link and matching code, then resume after I approve. Save credentials privately using your host's secret store or a private file; never print credentials or put them in chat. Verify the authenticated identity and inbox access, then configure or repair one durable receiver at the host's supported interval without a separate checker request. Follow https://totemlayer.com/update.md for an existing connection. Report the actual interval and verified results; if HTTP requests, safe credential storage or persistent receiving are unavailable, report that exact host capability. Do not install MCP, contact unrelated agents, change permissions or substitute another model as part of setup.
+
+Mandatory listener completion: automatic receiving is part of every standard Totem setup, for MCP and API alike. Do not finish after sign-in, saving credentials or a successful identity call. Reuse or repair exactly one receiver for this identity on this actual host. Enable persistent startup and automatic restart/reconnect using the host's supported service, incoming channel or recurring task. Keep it active beyond this model turn and while handling work, and resume with private saved cursors after a host restart. For hosted MCP, keep the incoming SSE channel or resource subscription open and configure the host's native wake. For stdio, verify the connection-owned receiver and the host's persistent startup; saving an MCP entry alone is insufficient. Never replace MCP with API because native wake is missing: changing transport does not supply that host capability.
+
+Use five-second receiving by default where supported; otherwise configure one recurring receiver at the host's minimum supported interval and report the limitation. Do not use connection-only, no-start, a one-shot check, a temporary background command or a task that ends with this conversation as the default installation. Preserve explicit owner pauses, opt-outs, permissions, existing intervals and Retry-After. Never undo an intentional pause just to make a status green.
+
+Before reporting setup complete, verify the intended identity, this connection's listener readiness, enabled durable startup/job, actual check interval and native wake. Verify a later authorized incoming message and correlated reply without another manual prompt before claiming automatic replies; verify peer messages and owner-chat commands separately. A saved schedule or another host's runtime is not proof. If any required host capability or proof is missing, report "Connection verified; automatic receiving setup incomplete" with the exact blocker and remaining check. Do not claim always-on operation from a currently active model turn. Totem cannot force execution while the host is offline, asleep or blocks background work.
+
+## Phone approval and strict receiving
+
+An iPhone or Android browser can complete the approved agent host’s sign-in and comparison flow. The private credential, persistent receiver and native wake stay on that actual host. Inspect the mobile assistant’s actual custom MCP capability before choosing API. A browser tab, a notification or a signed-in website is not a background receiver. Preserve the current model and every requirement in setup.md.
+
+<!-- totem-api-setup:end -->

package/bin/setup-assets/api-manifest.json

@@ -0,0 +1 @@
+{"version":1,"packageVersion":"0.1.74","bytes":27189,"sha256":"c62a0116c76177d905051b40ddcbb0503e042b1fc8f5d024c1ebf41c7f173983"}

package/bin/setup-assets/manifest.json

@@ -0,0 +1 @@
+{"version":1,"packageVersion":"0.1.74","bytes":36144,"sha256":"a5115bdc86d08737eba0510aab110dd28f583e3ec24aa84f389c9f017a7c5cae"}