@cotal-ai/pi 0.150.0 → 0.151.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Binary file
Binary file
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ /** @module index */
1
2
  import "./connector.js";
2
3
  export { piConnector } from "./connector.js";
3
4
  export { default as cotalMeshExtension } from "./extension.js";
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,OAAO,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
package/dist/index.js CHANGED
@@ -84,7 +84,7 @@ ${tail}`)}if(history.length){blocks.push(`\u{1F4DA} Cotal \u2014 ${history.lengt
84
84
  ${history.map(format).join("\n")}
85
85
  (This is replayed history, not new work. Do not act on or reply to these old requests unless the person explicitly asks.)`)}return blocks.join("\n\n")}function writeReply(sock,reply,awaitHandoff){return new Promise(resolve=>{let settled=false;const done=ok3=>{if(settled)return;settled=true;resolve(ok3)};sock.once("error",()=>done(false));sock.once("close",()=>done(false));if(!awaitHandoff){const stall=setTimeout(()=>done(false),LEGACY_WRITE_DEADLINE_MS);stall.unref?.();try{sock.end(JSON.stringify(reply)+"\n",(err3=>{clearTimeout(stall);done(!err3)}))}catch{clearTimeout(stall);done(false)}return}const deadline=setTimeout(()=>{sock.destroy();done(false)},HANDOFF_DEADLINE_MS);deadline.unref?.();let receipt2="";sock.on("data",d2=>{receipt2+=d2;if(!receipt2.includes("\n"))return;clearTimeout(deadline);try{sock.end()}catch{}done(true)});try{sock.write(JSON.stringify(reply)+"\n",err3=>{if(!err3)return;clearTimeout(deadline);done(false)})}catch{clearTimeout(deadline);done(false)}})}function startControlServer(agent,endpoint,handle,opts={}){const{path}=endpoint;const digest=createHash6("sha256").update(endpoint.token).digest();const server=createServer(sock=>{let buf="";let handled=false;sock.setEncoding("utf8");const deadline=setTimeout(()=>sock.destroy(),AUTH_DEADLINE_MS);deadline.unref?.();sock.on("close",()=>clearTimeout(deadline));sock.on("data",async d2=>{if(handled)return;buf+=d2;if(buf.length>MAX_FRAME_BYTES){sock.destroy();return}const nl=buf.indexOf("\n");if(nl<0)return;handled=true;clearTimeout(deadline);let frame={};try{frame=JSON.parse(buf.slice(0,nl)||"{}")}catch{}if(!tokenMatches(frame.token,digest)){sock.destroy();return}const op=frame.op;if(op==="shutdown"){try{sock.end(JSON.stringify({ok:true})+"\n")}catch{}opts.onShutdown?.();return}if(op==="session"){const sessionId=opts.onSession?.();try{sock.end(JSON.stringify(sessionId?{ok:true,sessionId}:{ok:false,error:"session not ready"})+"\n")}catch{}return}const ev=frame.event??{};const awaitHandoff=frame.handoff===true;const reply=await handle(agent,ev);const delivered=await writeReply(sock,reply,awaitHandoff);opts.onReply?.(ev,delivered,awaitHandoff)});sock.on("error",()=>{})});let bound=false;let retried=false;const emit=server.emit.bind(server);server.emit=(event,...args)=>{const error51=args[0];if(event!=="error"||bound||retried||process.platform==="win32"||path.startsWith("\0")||error51?.code!=="EADDRINUSE")return emit(event,...args);retried=true;let original;try{original=lstatSync(path);if(!original.isSocket())return emit(event,...args)}catch(e){if(e.code!=="ENOENT")return emit(event,...args)}const probe=connect(path);let settled=false;const finish=stale=>{if(settled)return;settled=true;clearTimeout(deadline);probe.destroy();server.off("close",cancel);if(!stale){emit(event,...args);return}try{const current=lstatSync(path);if(!original||!current.isSocket()||current.dev!==original.dev||current.ino!==original.ino){emit(event,...args);return}unlinkSync(path)}catch(e){if(e.code!=="ENOENT"){emit("error",e);return}}server.listen(path)};const cancel=()=>{settled=true;clearTimeout(deadline);probe.destroy()};const deadline=setTimeout(()=>finish(false),250);server.once("close",cancel);probe.once("connect",()=>finish(false));probe.once("error",e=>finish(e.code==="ECONNREFUSED"||e.code==="ENOENT"));return true};server.on("error",e=>{process.stderr.write(`[cotal-connector] control server error: ${e.message}
86
86
  `);if(opts.fatalBind&&!bound)process.exit(1)});server.listen(path,()=>{bound=true;process.stderr.write(`[cotal-connector] control socket: ${path}
87
- `)});return server}var ok=text=>({text});var err=text=>({text,isError:true});function receipt(status,value){if(status!==202||typeof value!=="object"||value===null||Array.isArray(value))return void 0;const body=value;if(body.ok!==true||typeof body.id!=="string"||body.id.length===0||body.id.length>200)return void 0;if(/[\u0000-\u001f\u007f]/.test(body.id)||body.id.trim()!==body.id)return void 0;if(typeof body.published!=="boolean")return void 0;return{id:body.id,published:body.published}}async function submitFeedback(input,options={}){const url2=options.url??(options.key?FEEDBACK_URL:PUBLIC_FEEDBACK_URL);const headers={"content-type":"application/json"};const body={...input};if(options.key){headers.authorization=`Bearer ${options.key}`}else{if(!options.email)return err("Keyless feedback goes to the public cotal.ai intake, which requires a traceable contact email \u2014 ask the user for one and retry with the email argument (or set COTAL_FEEDBACK_EMAIL).");body.email=options.email}let res;let raw;try{res=await fetch(url2,{method:"POST",headers,body:JSON.stringify(body),redirect:"error"});raw=await res.text()}catch(e){return err(`Couldn't reach the feedback intake at ${url2}: ${e.message} The submission was not retried.`)}let reply=void 0;if(raw)try{reply=JSON.parse(raw)}catch{reply=void 0}const stored=receipt(res.status,reply);if(stored){const note=stored.published===false?" (stored, but the internal feedback channel publish failed)":"";return ok(`Feedback sent (id ${stored.id})${note}. Thanks!`)}const errorText=typeof reply==="object"&&reply!==null&&typeof reply.error==="string"?reply.error:void 0;if(!res.ok)return err(`Feedback rejected (${res.status}${errorText?`: ${errorText}`:""}).`);return err(`Feedback acceptance is unconfirmed (${res.status}). The request may have reached the intake and was not retried.`)}import{execFileSync}from"node:child_process";init_external();init_external();import{isConcreteChannel as isConcreteChannel4,isChannelFamily as isChannelFamily2,assertValidChannel as assertValidChannel3,MAX_CHANNEL_LENGTH,channelInAllow as channelInAllow3,patternInAllow,AmbiguousPeerError,peerLabel as peerLabel4,sharedNameIds,assertLifecycleToken as assertLifecycleToken3,isPermissionDenied as isPermissionDenied2,renderLifecycleBlocked,EpEnvelopeError as EpEnvelopeError3,EP_UNANSWERED as EP_UNANSWERED2,REGISTRY_PAGE_LIMIT,LANG_PROBLEM_DETAIL_KIND,formatAge,parseDuration,presenceAges,presenceText}from"@cotal-ai/core";import{isConcreteChannel as isConcreteChannel3,parsePrincipalKey as parsePrincipalKey2,peerLabel as peerLabel3}from"@cotal-ai/core";import{createHash as createHash7}from"node:crypto";import{readFileSync as readFileSync2}from"node:fs";import{join as join5}from"node:path";import{gunzipSync}from"node:zlib";var DOCS_VERSION="0.150.0";function loadDocsMetadata(){return{"version":"0.150.0","pages":[{"slug":"what-is-cotal","title":"What is Cotal","kind":"Start here (informative)","category":"Start here","summary":"How Cotal lets agents and other software find each other and exchange messages."},{"slug":"getting-started","title":"Quickstart","kind":"Start here (informative)","category":"Start here","summary":"Start a local Cotal mesh, launch an agent, and watch it join."},{"slug":"architecture","title":"Architecture","kind":"Concept (informative)","category":"Concept","summary":"How the wire contract, broker, connectors, and manager fit together."},{"slug":"mcp-tools","title":"MCP tool catalog","kind":"Reference: the `cotal_*` tool surface every connected agent gets.","category":"Reference","summary":"Arguments, availability, and effects of the Cotal tools exposed to agent sessions."},{"slug":"channels-and-permissions","title":"Channel permissions","kind":"Reference (informative task card)","category":"Reference","summary":"Channel read and post permissions, active subscriptions, delivery classes, membership, and replay."},{"slug":"identity-and-auth","title":"Identity","kind":"Concept (informative)","category":"Concept","summary":"How Cotal identifies a peer and limits what that peer can do."},{"slug":"agent-briefing","title":"Agent briefing","kind":"Reference","category":"Reference","summary":"The text every harness hands its agent when the session starts."},{"slug":"agent-files","title":"Agent files","kind":"Reference (the persisted form of an agent's identity + persona, read by every launcher)","category":"Reference","summary":"Fields, lookup rules, and ownership for an agent's persisted identity and persona."},{"slug":"api-reference","title":"Integration interfaces","kind":"Reference (informative)","category":"Reference","summary":"Choose Cotal's CLI, endpoint commands, libraries, agent tools, wire protocol, or HTTP interfaces."},{"slug":"auth-api","title":"Auth HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Auth HTTP interface."},{"slug":"auth-host-api","title":"Auth host HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Auth host HTTP interface."},{"slug":"authoring-a-connector","title":"Authoring a connector","kind":"Guide: describes the TypeScript reference implementation, not the wire contract.","category":"Guide","summary":"Add support for an agent application through Cotal's connector interface and extension loader."},{"slug":"backup-a-mesh","title":"Back up a mesh","kind":"Guide","category":"Guide","summary":"Preserve a supported mesh, create an offline backup, and restore it within the original trust boundary."},{"slug":"build-a-client","title":"Build a Cotal client","kind":"Guide (informative)","category":"Guide","summary":"Implement a client in another language using the wire specification and a NATS client library."},{"slug":"claude-connector-reference","title":"Claude connector reference","kind":"Reference","category":"Reference","summary":"Binding, delivery, presence, event recording, and hosting contracts for the Claude Code connector."},{"slug":"cli-agent-control","title":"Agent terminal control","kind":"Reference","category":"Reference","summary":"Managed seat census, terminal attachment, input receipts, and native agent stops."},{"slug":"cli-agent-views","title":"Agent view reference","kind":"Reference","category":"Reference","summary":"Launch previews, named agent status, and recorded team deployment and removal evidence."},{"slug":"cli-agents","title":"Agent launch reference","kind":"Reference","category":"Reference","summary":"Launch modes, persona definitions, model catalogs, runtimes, and retained PTY seats."},{"slug":"cli-auth","title":"CLI authentication","kind":"Reference","category":"Reference","summary":"Static credentials, endpoint callers, account sessions, actor grants, and credential diagnosis."},{"slug":"cli-backups","title":"CLI backups","kind":"Reference","category":"Reference","summary":"Offline artifacts, integrity checks, restore recovery, and retained seat checkpoints."},{"slug":"cli-endpoints","title":"CLI endpoints","kind":"Reference","category":"Reference","summary":"Presence, local endpoint references, contract authoring, native invocation, and guarded removal."},{"slug":"cli-installation","title":"CLI installation","kind":"Reference","category":"Reference","summary":"Setup, software updates, installed extensions, preferences, completion, and feedback."},{"slug":"cli-integrations","title":"Linear integration","kind":"Reference","category":"Reference","summary":"Linear account configuration, native MCP operations, endpoint serving, and service lifecycle."},{"slug":"cli-maintenance","title":"Manager maintenance","kind":"Reference","category":"Reference","summary":"Guarded issuance-gate repair, retained seat maintenance, and native manager stop impact."},{"slug":"cli-messaging","title":"CLI messaging","kind":"Reference","category":"Reference","summary":"One-shot messages, live chat, channel policy, retained history, and pending direct messages."},{"slug":"cli-observation","title":"CLI observation","kind":"Reference","category":"Reference","summary":"Read-only activity feeds, the operator console, and the dashboard service."},{"slug":"cli-processes","title":"Process supervision","kind":"Reference","category":"Reference","summary":"Manager compatibility entry, owned direct processes, systemd user units, and service logs."},{"slug":"cli-runs","title":"CLI workflow runs","kind":"Reference","category":"Reference","summary":"Hosted and local workflow runs, recorded state, pause answers, offline checks, and seat turns."},{"slug":"cli-selection","title":"CLI spaces","kind":"Reference","category":"Reference","summary":"Space preparation, registration, target selection, discovery, and infrastructure diagnostics."},{"slug":"cli-services","title":"Local service reference","kind":"Reference","category":"Reference","summary":"Saved local services, native adapters, daemon compatibility entries, and service readiness limits."},{"slug":"cli-shutdown","title":"CLI shutdown","kind":"Reference","category":"Reference","summary":"Stack and service stops, process identity checks, preservation, cleanup, and reset."},{"slug":"cli-startup","title":"CLI startup","kind":"Reference","category":"Reference","summary":"Local stack startup, controller recovery, authentication modes, and manifest startup."},{"slug":"cli-usage","title":"CLI usage","kind":"Reference","category":"Reference","summary":"Command discovery, global flags, structured receipts, and exit codes."},{"slug":"cli","title":"CLI reference","kind":"Reference: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract.","category":"Reference","summary":"Find command syntax, flags, receipts, and limits for the Cotal CLI."},{"slug":"codex-connector-reference","title":"Codex connector reference","kind":"Reference","category":"Reference","summary":"Codex launch options, private credentials, delivery behavior, presence, and structured event limits."},{"slug":"config","title":"Configuration","kind":"Reference: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract.","category":"Reference","summary":"Config files, preferences, environment variables, and local storage for the Cotal CLI and connectors."},{"slug":"connect-claude","title":"Connect Claude","kind":"Guide (informative)","category":"Guide","summary":"Connect Claude Code to a mesh, launch an agent, and choose how it receives messages and tools."},{"slug":"connect-codex","title":"Connect Codex","kind":"Guide (informative)","category":"Guide","summary":"Launch Codex on a Cotal mesh, connect your own Codex conversations, choose a model, and set its sandbox permissions."},{"slug":"connect-hermes","title":"Connect Hermes (alpha)","kind":"Guide (informative)","category":"Guide","summary":"Run a Hermes gateway on a Cotal mesh with a managed profile or your own Hermes profile."},{"slug":"connect-jcode","title":"Connect Jcode (beta)","kind":"Guide (informative)","category":"Guide","summary":"Launch a private Jcode session on a Cotal mesh, choose its model, and fork an existing transcript."},{"slug":"connect-opencode","title":"Connect OpenCode","kind":"Guide (informative)","category":"Guide","summary":"Launch OpenCode on a Cotal mesh and choose the model and options for your installed version."},{"slug":"connect-pi","title":"Connect pi (alpha)","kind":"Guide (informative)","category":"Guide","summary":"Launch pi on a Cotal mesh or load the Cotal extension into your own pi host."},{"slug":"connector-runtime-reference","title":"Connector runtime reference","kind":"Reference","category":"Reference","summary":"Shared connection recovery, presence display, send receipts, delivery acknowledgement, reply correlation, and resume records."},{"slug":"connectors","title":"Connectors","kind":"Guide (informative)","category":"Guide","summary":"Choose an agent application and connect its sessions to a Cotal mesh."},{"slug":"console","title":"Use the console","kind":"Guide","category":"Guide","summary":"Inspect a mesh from the terminal and use authorized operator controls."},{"slug":"control-discovery","title":"Endpoint discovery","kind":"Reference","category":"Reference","summary":"Command contracts, manager instance selection, request outcomes, and service registration."},{"slug":"control-lifecycle","title":"Manager lifecycle contracts","kind":"Reference","category":"Reference","summary":"Managed identities, static slots, spawn goals, chat sessions, terminal access, and grants."},{"slug":"control-surface","title":"The control surface","kind":"Concept (informative)","category":"Concept","summary":"How clients discover commands, address service instances, and follow durable actions."},{"slug":"dashboard-api","title":"Dashboard HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Dashboard HTTP interface."},{"slug":"define-a-team","title":"Define a team","kind":"Guide (informative)","category":"Guide","summary":"Describe agents and channels in a manifest, then boot or deploy that team."},{"slug":"delivery-daemon","title":"The delivery daemon","kind":"Concept (informative)","category":"Concept","summary":"Why durable channel delivery needs a trusted service, and what happens without it."},{"slug":"delivery-service-reference","title":"Delivery service contracts","kind":"Reference","category":"Reference","summary":"Fan-out, trusted reads, leases, membership retirement, credential adoption, and daemon lifetime."},{"slug":"deploy","title":"Deploy agent teams","kind":"Guide (informative)","category":"Guide","summary":"Review the container example, its current build limitation, and the credentials it needs."},{"slug":"embedding-daemons","title":"Embedded daemon lifecycle","kind":"Reference","category":"Reference","summary":"Process runners, account-scoped hosted services, and delivery credential renewal."},{"slug":"embedding-delegated-seats","title":"Delegated seat contracts","kind":"Reference","category":"Reference","summary":"Managed lifecycle handoff, provider closure guarantees, and the limits of delegated recovery contracts."},{"slug":"embedding-endpoints","title":"CotalEndpoint reference","kind":"Reference","category":"Reference","summary":"Presence metadata, observer freshness, write diagnosis, liveness probes, and DM-only endpoint readers."},{"slug":"embedding-exports","title":"Embedding package exports","kind":"Reference","category":"Reference","summary":"Public package entry points, endpoint credentials, and Manager execution contracts."},{"slug":"embedding-manager","title":"Manager embedding authority","kind":"Reference","category":"Reference","summary":"Manager startup, signer custody, remote authority callbacks, and delegated user intent contracts."},{"slug":"embedding-provisioning","title":"Embedded space provisioning","kind":"Reference","category":"Reference","summary":"Broker trust, space credentials, durable host state, and current hosting limitations."},{"slug":"embedding-remote-clients","title":"Embedded remote clients","kind":"Reference","category":"Reference","summary":"MCP conversation routing, browser callers, remote Manager clients, and private-result prerequisites."},{"slug":"embedding-schema-inspection","title":"Space schema inspection","kind":"Reference","category":"Reference","summary":"Resource definitions, bounded read-only observations, and the limits of schema and initialization comparisons."},{"slug":"embedding-service-access","title":"Service endpoint access","kind":"Reference","category":"Reference","summary":"Authority proofs, serving credentials, verified grants, and renewal."},{"slug":"embedding-service-authority","title":"Service authority contracts","kind":"Reference","category":"Reference","summary":"Service authority contracts, platform supervisors, revocation prerequisites, and native custody limits."},{"slug":"embedding-service-callers","title":"Service endpoint callers","kind":"Reference","category":"Reference","summary":"Caller policy grants, broker payload prerequisites, revocation, and recovery limits."},{"slug":"embedding-service-custody","title":"Native service custody","kind":"Reference","category":"Reference","summary":"Immutable service reservations, bootstrap, cancellation, and bounded writer guarantees."},{"slug":"embedding-service-host","title":"Service endpoint hosting","kind":"Reference","category":"Reference","summary":"Owner approvals, native host operations, registration, and lifecycle custody."},{"slug":"embedding","title":"Embedding Cotal","kind":"Concept (informative)","category":"Concept","summary":"Choose the published packages and authority boundaries for a service built on Cotal."},{"slug":"examples","title":"Examples","kind":"Start here (informative)","category":"Start here","summary":"Choose a working example of agents collaborating through Cotal."},{"slug":"feedback-intake-api","title":"Feedback intake HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Feedback intake HTTP interface."},{"slug":"glossary","title":"Glossary","kind":"Reference (informative)","category":"Reference","summary":"Definitions of Cotal's identity, messaging, delivery, and operator terms."},{"slug":"hermes-connector-reference","title":"Hermes connector reference","kind":"Reference","category":"Reference","summary":"Hermes gateway ownership, profile state, delivery rules, presence hooks, and session forks."},{"slug":"identity-authority","title":"Credential authority","kind":"Reference","category":"Reference","summary":"Credential minting, profile grants, endpoint generations, and capability limits."},{"slug":"identity-service-auth","title":"Auth service integration","kind":"Reference","category":"Reference","summary":"Auth-service listeners, pinned IdP proofs, bridge hooks, and owner derivation."},{"slug":"identity-user-auth","title":"User-auth lifecycle","kind":"Reference","category":"Reference","summary":"Actor grants, delegation, catalogs, enrollment, sessions, views, and remote managers."},{"slug":"installation","title":"Install Cotal","kind":"Start here","category":"Start here","summary":"Install the cotal command with the shell installer or npm."},{"slug":"jcode-connector-reference","title":"Jcode connector reference","kind":"Reference","category":"Reference","summary":"Private Jcode process ownership, session forks, readiness checks, model selection, and event delivery."},{"slug":"lang-card","title":"The cotal-lang card","kind":"Reference (informative)","category":"Reference","summary":"Effect signatures, result shapes, concurrency rules, and common refusals for cotal-lang programs."},{"slug":"launch-agents","title":"Launch agents","kind":"Guide","category":"Guide","summary":"Launch an agent through a manager, attach to its terminal, and choose its persona and runtime."},{"slug":"manager-console-api","title":"Manager console HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Manager console HTTP interface."},{"slug":"manifest","title":"Mesh manifest (cotal.yaml)","kind":"Reference: every field of the mesh manifest.","category":"Reference","summary":"Manifest fields, persona overrides, channel grants, and access resolution for one team."},{"slug":"mesh-view","title":"MeshView","kind":"Reference: TypeScript observer surfaces (`MeshView`)","category":"Reference","summary":"The TypeScript observer model used by the terminal console and line stream, with dashboard feature coverage."},{"slug":"opencode-connector-reference","title":"OpenCode connector reference","kind":"Reference","category":"Reference","summary":"OpenCode version support, injected configuration, session delivery, and structured event limits."},{"slug":"overview","title":"API reference","kind":"Reference","category":"Reference","summary":"Find Cotal CLI commands, agent tools, configuration fields, and data models."},{"slug":"pi-connector-reference","title":"pi connector reference","kind":"Reference","category":"Reference","summary":"pi host lifecycle, delivery confirmation, continuation attempts, managed recovery, and event persistence."},{"slug":"presence-and-delivery","title":"Message flow","kind":"Concept (informative)","category":"Concept","summary":"How presence, routing, durable delivery, and attention determine what peers can observe and receive."},{"slug":"recover-a-mesh","title":"Recover a mesh","kind":"Guide","category":"Guide","summary":"Use status and logs to diagnose service failures, stuck presence, or a frozen registration gate."},{"slug":"register-a-mesh","title":"Register a mesh","kind":"Guide","category":"Guide","summary":"Choose the mesh a command targets and register remote brokers with verified trust."},{"slug":"release","title":"Publishing a release","kind":"Project (non-normative maintainer notes)","category":"Project","summary":"Cotal releases with pnpm, Changesets, and one GitHub Actions workflow, changesets.yml."},{"slug":"remote-supervision","title":"Supervise a remote mesh","kind":"Guide","category":"Guide","summary":"Separate broker and manager hosts, publish an exchange, and enroll remote agents."},{"slug":"roadmap","title":"Roadmap","kind":"Project (non-normative)","category":"Project","summary":"Cotal is pre-1.0, and the v0.x wire contract can still change under the change process."},{"slug":"run-a-mesh","title":"Run a mesh","kind":"Guide (informative)","category":"Guide","summary":"Start, inspect, and stop the local stack in a prepared project."},{"slug":"security-boundaries","title":"Host boundaries","kind":"Reference","category":"Reference","summary":"Credential lifetimes, metadata exposure, launch authority, and local process risks."},{"slug":"security","title":"Security model","kind":"Concept (informative threat model)","category":"Concept","summary":"Threats, guarantees, and limits for peers sharing a trusted NATS broker."},{"slug":"setup-internals","title":"Setup internals (maintainer notes)","kind":"Project (non-normative maintainer notes)","category":"Project","summary":"How cotal setup works, and the cross-repo couplings it depends on."},{"slug":"setup","title":"Configure a space","kind":"Guide","category":"Guide","summary":"Prepare a project, choose its agent application, and save its space settings."},{"slug":"spaces","title":"Spaces","kind":"Concept (informative)","category":"Concept","summary":"How spaces isolate collaboration, and how channels, permissions, membership, and conversation ids organize work within them."},{"slug":"stability","title":"Interface stability","kind":"Project (informative)","category":"Project","summary":"Cotal's packages are pre-1.0 and publish in lockstep."},{"slug":"supervise-processes","title":"Supervise the stack","kind":"Guide","category":"Guide","summary":"Choose process ownership under systemd and monitor actual component health."},{"slug":"telemetry","title":"Telemetry","kind":"Reference","category":"Reference","summary":"CLI usage telemetry fields, levels, storage, delivery, and opt-outs."},{"slug":"transport","title":"Transport vs protocol","kind":"Concept (informative)","category":"Concept","summary":"How Cotal's wire contract uses NATS and JetStream, and what another transport binding would have to preserve."},{"slug":"upgrade-cotal","title":"Upgrade Cotal","kind":"Guide","category":"Guide","summary":"Choose an exact release, prepare the deployment, and verify the upgraded installation."},{"slug":"upgrading","title":"Upgrading a running deployment","kind":"Guide (informative)","category":"Guide","summary":"Interface stability says what the version numbers promise."},{"slug":"using-cotal","title":"Choose a workflow","kind":"Start here (informative)","category":"Start here","summary":"Choose how to connect sessions, join spaces, launch teams, and run durable work."},{"slug":"watch-a-mesh","title":"Watch a mesh","kind":"Guide (informative)","category":"Guide","summary":"Choose a terminal display, line stream, or read-only browser dashboard for a running mesh."},{"slug":"web-dashboard","title":"Use the web dashboard","kind":"Guide","category":"Guide","summary":"Configure the read-only dashboard and inspect a space through a protected browser session."},{"slug":"workflow-effects","title":"Workflow effect contracts","kind":"Reference","category":"Reference","summary":"Seat ownership, budgets, supervision, decisions, presence, turns, cancellation, and placement."},{"slug":"workflow-operations","title":"Workflow operation contracts","kind":"Reference","category":"Reference","summary":"Hosted and local run commands, agent requests, admission, inventory, and keyed submission."},{"slug":"workflow-runtime","title":"Workflow runtime contracts","kind":"Reference","category":"Reference","summary":"Language replay, recovery, wire authority, durable effects, and engine limits."},{"slug":"workflows","title":"Workflow runs","kind":"Concept (informative)","category":"Concept","summary":"How a program coordinates agents, records progress, and continues after interruption."}],"spec":{"title":"Cotal Wire Specification"},"lang":{"title":"Cotal Lang: the workflow language"},"schema":{"title":"Cotal message schema (JSON Schema)"}}}var corpusPacked;function corpusData(){if(corpusPacked)return corpusPacked;const packed=readFileSync2(join5(import.meta.dirname,"docs-bundle.bin"));if(packed.length!==1154873||createHash7("sha256").update(packed).digest("hex")!=="6dcf838582bc6f75c5792a3569652152e536a1ca593a30574d337d0d6ff5a4d6")throw new Error("docs data file docs-bundle.bin beside this module is not the one built with it");return corpusPacked=packed}var sourceBounds=[[0,2205],[2205,4e3],[4e3,9323],[9323,30004],[30004,34401],[34401,38779],[38779,42301],[42301,48733],[48733,52628],[52628,61616],[61616,65768],[65768,70216],[70216,72287],[72287,76298],[76298,107466],[107466,122954],[122954,138084],[138084,155810],[155810,170674],[170674,185399],[185399,200887],[200887,221220],[221220,226936],[226936,236494],[236494,255410],[255410,259809],[259809,282499],[282499,291605],[291605,321034],[321034,337120],[337120,359902],[359902,389593],[389593,402687],[402687,404634],[404634,413510],[413510,429687],[429687,437324],[437324,440943],[440943,444324],[444324,447627],[447627,449672],[449672,452328],[452328,457053],[457053,458881],[458881,462440],[462440,473909],[473909,481974],[481974,485499],[485499,492772],[492772,497816],[497816,500723],[500723,508682],[508682,511659],[511659,519016],[519016,522006],[522006,526951],[526951,538577],[538577,550492],[550492,555384],[555384,562915],[562915,566264],[566264,568835],[568835,576093],[576093,579513],[579513,581723],[581723,585185],[585185,588602],[588602,589716],[589716,591465],[591465,595128],[595128,599681],[599681,606272],[606272,616782],[616782,630053],[630053,631890],[631890,644875],[644875,650258],[650258,654123],[654123,656632],[656632,661674],[661674,668449],[668449,674659],[674659,675406],[675406,679575],[679575,684880],[684880,688258],[688258,692466],[692466,697288],[697288,702090],[702090,705512],[705512,708911],[708911,713493],[713493,717136],[717136,730362],[730362,733180],[733180,735863],[735863,738530],[738530,741021],[741021,745041],[745041,749741],[749741,751960],[751960,817547],[817547,820618],[820618,821811],[821811,828312],[828312,836320],[836320,846922],[846922,855640],[855640,860697],[860697,1110736],[1110736,1149661],[1149661,1154873]];var sourceLengths=[4844,4048,13310,80803,12190,10700,35598,16675,9375,78405,37758,10864,4656,9872,84938,41661,42535,50397,41170,42638,42202,56449,14375,25041,53944,9884,65192,24959,88758,45388,68054,91273,36249,8216,22172,43312,20768,8796,8035,7790,4835,6062,11949,4349,8347,30545,19884,8745,47165,12743,7133,20461,7140,19027,6860,12405,30020,31428,12022,18311,8355,6090,18823,7536,5100,8160,9930,2248,5412,9845,10853,15950,26828,34058,4227,35397,12366,9420,8201,13306,16844,15126,1464,9444,13555,7818,10170,12034,11921,7511,8528,11024,8527,35301,6519,6405,6095,6007,9711,11730,5283,193807,6927,2473,15538,20475,27423,20876,12299,724977,109957,21676];var decodedBodies=[];function loadDocsSourceLengths(){corpusData();return sourceLengths.slice()}function decodeDocsSource(source){const bounds=sourceBounds[source];if(!Number.isInteger(source)||!bounds)throw new Error("docs source index is out of bounds");const body=JSON.parse(gunzipSync(corpusData().subarray(bounds[0],bounds[1])).toString("utf8"));if(typeof body!=="string"||body.length!==sourceLengths[source])throw new Error("docs source body does not match its generated bounds");return body}function loadDocsSource(source){return decodedBodies[source]??=decodeDocsSource(source)}function loadDocsIndex(){const packed=readFileSync2(join5(import.meta.dirname,"docs-index.bin"));if(packed.length!==598334||createHash7("sha256").update(packed).digest("hex")!=="8f5c36282a158b4fcdd8e0c36622c9711d93c48bdf26a543b21b97ee8e842caf")throw new Error("docs data file docs-index.bin beside this module is not the one built with it");return gunzipSync(packed)}var TOKEN=/[a-z0-9_$.#>*-]+/gi;var EDGE=/^[.>*#-]+|[.>*#-]+$/g;function tokenize(s){const raw=s.toLowerCase().match(TOKEN);if(!raw)return[];const out=[];for(const r of raw){if(r.length>=2)out.push(r);const t=r.replace(EDGE,"");if(t.length>=2&&t!==r)out.push(t);if(t.includes(".")){for(const seg of t.split("."))if(seg.length>=2)out.push(seg)}}return out}var STOP=new Set("a an and are as at be by do for from has how in is it of on or that the this to use using was what when where which who with you your".split(" "));function decodeIndex(bytes,bodyLengths,version2){if(bytes.length<4)throw new Error("docs index is truncated or malformed");const headerLength=bytes.readUInt32LE(0);if(4+headerLength>bytes.length)throw new Error("docs index is truncated or malformed");const header=JSON.parse(bytes.toString("utf8",4,4+headerLength));if(header.version!==version2||header.bodyLengths.length!==bodyLengths.length||header.bodyLengths.some((length2,i)=>length2!==bodyLengths[i]))throw new Error("docs index does not match the docs bundle it is searching");const n=header.sections;const length=4*n+header.terms.length+1+2*header.postings;if(bytes.length-4-headerLength!==4*length)throw new Error("docs index is truncated or malformed");const columns=new Uint32Array(length);for(let i=0;i<length;i++)columns[i]=bytes.readUInt32LE(4+headerLength+4*i);const offsets=4*n;const sectionColumn=offsets+header.terms.length+1;let total=0;for(let i=0;i<n;i++)total+=columns[3*n+i];return{sections:n,terms:header.terms,headings:header.headings,source:columns.subarray(0,n),start:columns.subarray(n,2*n),end:columns.subarray(2*n,3*n),length:columns.subarray(3*n,4*n),offsets:columns.subarray(offsets,sectionColumn),postSection:columns.subarray(sectionColumn,sectionColumn+header.postings),postWeight:columns.subarray(sectionColumn+header.postings),avgdl:total/Math.max(1,n)}}var indexed;function metadata(){return indexed??=loadDocsMetadata()}var pages=new Map;function localPage(source){let page=pages.get(source);if(!page){page={...metadata().pages[source],body:loadDocsSource(source)};pages.set(source,page)}return page}function sourceBody(source){return source<metadata().pages.length?localPage(source).body:loadDocsSource(source)}var REMOTE_BASE="https://docs.cotal.ai";function resolvePage(page){const meta3=metadata();loadDocsSourceLengths();const reference=page.trim().toLowerCase().split(/[?#]/)[0].replace(/^\.\//,"");let key;if(/^(?:\.\.\/)?spec\/cotal-lang\.md$/.test(reference))key="lang";else if(/^(?:\.\.\/)?spec\/cotal\.schema\.json$/.test(reference))key="schema";else if(reference==="../spec.md")key="spec";else{const match=/^(?:(?:\.\.\/)?docs\/)?([a-z0-9-]+)(?:\.mdx?)?$/.exec(reference);if(!match)return void 0;key=match[1]}const count=meta3.pages.length;if(key==="spec")return{slug:"spec",title:meta3.spec.title,kind:"normative",category:"normative",summary:"",body:loadDocsSource(count)};if(key==="lang"||key==="cotal-lang")return{slug:"lang",title:meta3.lang.title,kind:"normative",category:"normative",summary:"",body:loadDocsSource(count+1)};if(key==="schema")return{slug:"schema",title:meta3.schema.title,kind:"reference",category:"reference",summary:"",body:loadDocsSource(count+2)};const source=meta3.pages.findIndex((p,source2)=>(pages.get(source2)??p).slug===key);return source<0?void 0:localPage(source)}function remoteUrl(slug){const base=`${REMOTE_BASE}/v/${DOCS_VERSION}`;if(slug==="schema")return`${base}/cotal.schema.json`;if(slug==="lang")return`${base}/cotal-lang.md`;return`${base}/${slug}.md`}function renderDocsIndex(){const b2=metadata();const rows=b2.pages.map(p=>{const kind=p.kind?`: ${p.kind}`:"";return`- \`${p.slug}\`${kind}
87
+ `)});return server}var ok=text=>({text});var err=text=>({text,isError:true});function receipt(status,value){if(status!==202||typeof value!=="object"||value===null||Array.isArray(value))return void 0;const body=value;if(body.ok!==true||typeof body.id!=="string"||body.id.length===0||body.id.length>200)return void 0;if(/[\u0000-\u001f\u007f]/.test(body.id)||body.id.trim()!==body.id)return void 0;if(typeof body.published!=="boolean")return void 0;return{id:body.id,published:body.published}}async function submitFeedback(input,options={}){const url2=options.url??(options.key?FEEDBACK_URL:PUBLIC_FEEDBACK_URL);const headers={"content-type":"application/json"};const body={...input};if(options.key){headers.authorization=`Bearer ${options.key}`}else{if(!options.email)return err("Keyless feedback goes to the public cotal.ai intake, which requires a traceable contact email \u2014 ask the user for one and retry with the email argument (or set COTAL_FEEDBACK_EMAIL).");body.email=options.email}let res;let raw;try{res=await fetch(url2,{method:"POST",headers,body:JSON.stringify(body),redirect:"error"});raw=await res.text()}catch(e){return err(`Couldn't reach the feedback intake at ${url2}: ${e.message} The submission was not retried.`)}let reply=void 0;if(raw)try{reply=JSON.parse(raw)}catch{reply=void 0}const stored=receipt(res.status,reply);if(stored){const note=stored.published===false?" (stored, but the internal feedback channel publish failed)":"";return ok(`Feedback sent (id ${stored.id})${note}. Thanks!`)}const errorText=typeof reply==="object"&&reply!==null&&typeof reply.error==="string"?reply.error:void 0;if(!res.ok)return err(`Feedback rejected (${res.status}${errorText?`: ${errorText}`:""}).`);return err(`Feedback acceptance is unconfirmed (${res.status}). The request may have reached the intake and was not retried.`)}import{execFileSync}from"node:child_process";init_external();init_external();import{isConcreteChannel as isConcreteChannel4,isChannelFamily as isChannelFamily2,assertValidChannel as assertValidChannel3,MAX_CHANNEL_LENGTH,channelInAllow as channelInAllow3,patternInAllow,AmbiguousPeerError,peerLabel as peerLabel4,sharedNameIds,assertLifecycleToken as assertLifecycleToken3,isPermissionDenied as isPermissionDenied2,renderLifecycleBlocked,EpEnvelopeError as EpEnvelopeError3,EP_UNANSWERED as EP_UNANSWERED2,REGISTRY_PAGE_LIMIT,LANG_PROBLEM_DETAIL_KIND,formatAge,parseDuration,presenceAges,presenceText}from"@cotal-ai/core";import{isConcreteChannel as isConcreteChannel3,parsePrincipalKey as parsePrincipalKey2,peerLabel as peerLabel3}from"@cotal-ai/core";import{createHash as createHash7}from"node:crypto";import{readFileSync as readFileSync2}from"node:fs";import{join as join5}from"node:path";import{gunzipSync}from"node:zlib";var DOCS_VERSION="0.151.1";function loadDocsMetadata(){return{"version":"0.151.1","pages":[{"slug":"what-is-cotal","title":"What is Cotal","kind":"Start here (informative)","category":"Start here","summary":"How Cotal lets agents and other software find each other and exchange messages."},{"slug":"getting-started","title":"Quickstart","kind":"Start here (informative)","category":"Start here","summary":"Start a local Cotal mesh, launch an agent, and watch it join."},{"slug":"architecture","title":"Architecture","kind":"Concept (informative)","category":"Concept","summary":"How the wire contract, broker, connectors, and manager fit together."},{"slug":"mcp-tools","title":"MCP tool catalog","kind":"Reference: the `cotal_*` tool surface every connected agent gets.","category":"Reference","summary":"Arguments, availability, and effects of the Cotal tools exposed to agent sessions."},{"slug":"channels-and-permissions","title":"Channel permissions","kind":"Reference (informative task card)","category":"Reference","summary":"Channel read and post permissions, active subscriptions, delivery classes, membership, and replay."},{"slug":"identity-and-auth","title":"Identity","kind":"Concept (informative)","category":"Concept","summary":"How Cotal identifies a peer and limits what that peer can do."},{"slug":"agent-briefing","title":"Agent briefing","kind":"Reference","category":"Reference","summary":"The text every harness hands its agent when the session starts."},{"slug":"agent-files","title":"Agent files","kind":"Reference (the persisted form of an agent's identity + persona, read by every launcher)","category":"Reference","summary":"Fields, lookup rules, and ownership for an agent's persisted identity and persona."},{"slug":"api-reference","title":"Integration interfaces","kind":"Reference (informative)","category":"Reference","summary":"Choose Cotal's CLI, endpoint commands, libraries, agent tools, wire protocol, or HTTP interfaces."},{"slug":"auth-api","title":"Auth HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Auth HTTP interface."},{"slug":"auth-host-api","title":"Auth host HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Auth host HTTP interface."},{"slug":"authoring-a-connector","title":"Authoring a connector","kind":"Guide: describes the TypeScript reference implementation, not the wire contract.","category":"Guide","summary":"Add support for an agent application through Cotal's connector interface and extension loader."},{"slug":"backup-a-mesh","title":"Back up a mesh","kind":"Guide","category":"Guide","summary":"Preserve a supported mesh, create an offline backup, and restore it within the original trust boundary."},{"slug":"build-a-client","title":"Build a Cotal client","kind":"Guide (informative)","category":"Guide","summary":"Implement a client in another language using the wire specification and a NATS client library."},{"slug":"claude-connector-reference","title":"Claude connector reference","kind":"Reference","category":"Reference","summary":"Binding, delivery, presence, event recording, and hosting contracts for the Claude Code connector."},{"slug":"cli-agent-control","title":"Agent terminal control","kind":"Reference","category":"Reference","summary":"Managed seat census, terminal attachment, input receipts, and native agent stops."},{"slug":"cli-agent-views","title":"Agent view reference","kind":"Reference","category":"Reference","summary":"Launch previews, named agent status, and recorded team deployment and removal evidence."},{"slug":"cli-agents","title":"Agent launch reference","kind":"Reference","category":"Reference","summary":"Launch modes, persona definitions, model catalogs, runtimes, and retained PTY seats."},{"slug":"cli-auth","title":"CLI authentication","kind":"Reference","category":"Reference","summary":"Static credentials, endpoint callers, account sessions, actor grants, and credential diagnosis."},{"slug":"cli-backups","title":"CLI backups","kind":"Reference","category":"Reference","summary":"Offline artifacts, integrity checks, restore recovery, and retained seat checkpoints."},{"slug":"cli-endpoints","title":"CLI endpoints","kind":"Reference","category":"Reference","summary":"Presence, local endpoint references, contract authoring, native invocation, and guarded removal."},{"slug":"cli-installation","title":"CLI installation","kind":"Reference","category":"Reference","summary":"Setup, software updates, installed extensions, preferences, completion, and feedback."},{"slug":"cli-integrations","title":"Linear integration","kind":"Reference","category":"Reference","summary":"Linear account configuration, native MCP operations, endpoint serving, and service lifecycle."},{"slug":"cli-maintenance","title":"Manager maintenance","kind":"Reference","category":"Reference","summary":"Guarded issuance-gate repair, retained seat maintenance, and native manager stop impact."},{"slug":"cli-messaging","title":"CLI messaging","kind":"Reference","category":"Reference","summary":"One-shot messages, live chat, channel policy, retained history, and pending direct messages."},{"slug":"cli-observation","title":"CLI observation","kind":"Reference","category":"Reference","summary":"Read-only activity feeds, the operator console, and the dashboard service."},{"slug":"cli-processes","title":"Process supervision","kind":"Reference","category":"Reference","summary":"Manager compatibility entry, owned direct processes, systemd user units, and service logs."},{"slug":"cli-runs","title":"CLI workflow runs","kind":"Reference","category":"Reference","summary":"Hosted and local workflow runs, recorded state, pause answers, offline checks, and seat turns."},{"slug":"cli-selection","title":"CLI spaces","kind":"Reference","category":"Reference","summary":"Space preparation, registration, target selection, discovery, and infrastructure diagnostics."},{"slug":"cli-services","title":"Local service reference","kind":"Reference","category":"Reference","summary":"Saved local services, native adapters, daemon compatibility entries, and service readiness limits."},{"slug":"cli-shutdown","title":"CLI shutdown","kind":"Reference","category":"Reference","summary":"Stack and service stops, process identity checks, preservation, cleanup, and reset."},{"slug":"cli-startup","title":"CLI startup","kind":"Reference","category":"Reference","summary":"Local stack startup, controller recovery, authentication modes, and manifest startup."},{"slug":"cli-usage","title":"CLI usage","kind":"Reference","category":"Reference","summary":"Command discovery, global flags, structured receipts, and exit codes."},{"slug":"cli","title":"CLI reference","kind":"Reference: describes the TypeScript reference implementation (the `cotal` CLI), not the wire contract.","category":"Reference","summary":"Find command syntax, flags, receipts, and limits for the Cotal CLI."},{"slug":"codex-connector-reference","title":"Codex connector reference","kind":"Reference","category":"Reference","summary":"Codex launch options, private credentials, delivery behavior, presence, and structured event limits."},{"slug":"config","title":"Configuration","kind":"Reference: describes the TypeScript reference implementation (the `cotal` CLI and connectors), not the wire contract.","category":"Reference","summary":"Config files, preferences, environment variables, and local storage for the Cotal CLI and connectors."},{"slug":"connect-claude","title":"Connect Claude","kind":"Guide (informative)","category":"Guide","summary":"Connect Claude Code to a mesh, launch an agent, and choose how it receives messages and tools."},{"slug":"connect-codex","title":"Connect Codex","kind":"Guide (informative)","category":"Guide","summary":"Launch Codex on a Cotal mesh, connect your own Codex conversations, choose a model, and set its sandbox permissions."},{"slug":"connect-hermes","title":"Connect Hermes (alpha)","kind":"Guide (informative)","category":"Guide","summary":"Run a Hermes gateway on a Cotal mesh with a managed profile or your own Hermes profile."},{"slug":"connect-jcode","title":"Connect Jcode (beta)","kind":"Guide (informative)","category":"Guide","summary":"Launch a private Jcode session on a Cotal mesh, choose its model, and fork an existing transcript."},{"slug":"connect-opencode","title":"Connect OpenCode","kind":"Guide (informative)","category":"Guide","summary":"Launch OpenCode on a Cotal mesh and choose the model and options for your installed version."},{"slug":"connect-pi","title":"Connect pi (alpha)","kind":"Guide (informative)","category":"Guide","summary":"Launch pi on a Cotal mesh or load the Cotal extension into your own pi host."},{"slug":"connector-runtime-reference","title":"Connector runtime reference","kind":"Reference","category":"Reference","summary":"Shared connection recovery, presence display, send receipts, delivery acknowledgement, reply correlation, and resume records."},{"slug":"connectors","title":"Connectors","kind":"Guide (informative)","category":"Guide","summary":"Choose an agent application and connect its sessions to a Cotal mesh."},{"slug":"console","title":"Use the console","kind":"Guide","category":"Guide","summary":"Inspect a mesh from the terminal and use authorized operator controls."},{"slug":"control-discovery","title":"Endpoint discovery","kind":"Reference","category":"Reference","summary":"Command contracts, manager instance selection, request outcomes, and service registration."},{"slug":"control-lifecycle","title":"Manager lifecycle contracts","kind":"Reference","category":"Reference","summary":"Managed identities, static slots, spawn goals, chat sessions, terminal access, and grants."},{"slug":"control-surface","title":"The control surface","kind":"Concept (informative)","category":"Concept","summary":"How clients discover commands, address service instances, and follow durable actions."},{"slug":"dashboard-api","title":"Dashboard HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Dashboard HTTP interface."},{"slug":"define-a-team","title":"Define a team","kind":"Guide (informative)","category":"Guide","summary":"Describe agents and channels in a manifest, then boot or deploy that team."},{"slug":"delivery-daemon","title":"The delivery daemon","kind":"Concept (informative)","category":"Concept","summary":"Why durable channel delivery needs a trusted service, and what happens without it."},{"slug":"delivery-service-reference","title":"Delivery service contracts","kind":"Reference","category":"Reference","summary":"Fan-out, trusted reads, leases, membership retirement, credential adoption, and daemon lifetime."},{"slug":"deploy","title":"Deploy agent teams","kind":"Guide (informative)","category":"Guide","summary":"Review the container example, its current build limitation, and the credentials it needs."},{"slug":"embedding-daemons","title":"Embedded daemon lifecycle","kind":"Reference","category":"Reference","summary":"Process runners, account-scoped hosted services, and delivery credential renewal."},{"slug":"embedding-delegated-seats","title":"Delegated seat contracts","kind":"Reference","category":"Reference","summary":"Managed lifecycle handoff, provider closure guarantees, and the limits of delegated recovery contracts."},{"slug":"embedding-endpoints","title":"CotalEndpoint reference","kind":"Reference","category":"Reference","summary":"Presence metadata, observer freshness, write diagnosis, liveness probes, and DM-only endpoint readers."},{"slug":"embedding-exports","title":"Embedding package exports","kind":"Reference","category":"Reference","summary":"Public package entry points, endpoint credentials, and Manager execution contracts."},{"slug":"embedding-manager","title":"Manager embedding authority","kind":"Reference","category":"Reference","summary":"Manager startup, signer custody, remote authority callbacks, and delegated user intent contracts."},{"slug":"embedding-provisioning","title":"Embedded space provisioning","kind":"Reference","category":"Reference","summary":"Broker trust, space credentials, durable host state, and current hosting limitations."},{"slug":"embedding-remote-clients","title":"Embedded remote clients","kind":"Reference","category":"Reference","summary":"MCP conversation routing, browser callers, remote Manager clients, and private-result prerequisites."},{"slug":"embedding-schema-inspection","title":"Space schema inspection","kind":"Reference","category":"Reference","summary":"Resource definitions, bounded read-only observations, and the limits of schema and initialization comparisons."},{"slug":"embedding-service-access","title":"Service endpoint access","kind":"Reference","category":"Reference","summary":"Authority proofs, serving credentials, verified grants, and renewal."},{"slug":"embedding-service-authority","title":"Service authority contracts","kind":"Reference","category":"Reference","summary":"Service authority contracts, platform supervisors, revocation prerequisites, and native custody limits."},{"slug":"embedding-service-callers","title":"Service endpoint callers","kind":"Reference","category":"Reference","summary":"Caller policy grants, broker payload prerequisites, revocation, and recovery limits."},{"slug":"embedding-service-custody","title":"Native service custody","kind":"Reference","category":"Reference","summary":"Immutable service reservations, bootstrap, cancellation, and bounded writer guarantees."},{"slug":"embedding-service-host","title":"Service endpoint hosting","kind":"Reference","category":"Reference","summary":"Owner approvals, native host operations, registration, and lifecycle custody."},{"slug":"embedding","title":"Embedding Cotal","kind":"Concept (informative)","category":"Concept","summary":"Choose the published packages and authority boundaries for a service built on Cotal."},{"slug":"examples","title":"Examples","kind":"Start here (informative)","category":"Start here","summary":"Choose a working example of agents collaborating through Cotal."},{"slug":"feedback-intake-api","title":"Feedback intake HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Feedback intake HTTP interface."},{"slug":"glossary","title":"Glossary","kind":"Reference (informative)","category":"Reference","summary":"Definitions of Cotal's identity, messaging, delivery, and operator terms."},{"slug":"hermes-connector-reference","title":"Hermes connector reference","kind":"Reference","category":"Reference","summary":"Hermes gateway ownership, profile state, delivery rules, presence hooks, and session forks."},{"slug":"identity-authority","title":"Credential authority","kind":"Reference","category":"Reference","summary":"Credential minting, profile grants, endpoint generations, and capability limits."},{"slug":"identity-service-auth","title":"Auth service integration","kind":"Reference","category":"Reference","summary":"Auth-service listeners, pinned IdP proofs, bridge hooks, and owner derivation."},{"slug":"identity-user-auth","title":"User-auth lifecycle","kind":"Reference","category":"Reference","summary":"Actor grants, delegation, catalogs, enrollment, sessions, views, and remote managers."},{"slug":"installation","title":"Install Cotal","kind":"Start here","category":"Start here","summary":"Install the cotal command with the shell installer or npm."},{"slug":"jcode-connector-reference","title":"Jcode connector reference","kind":"Reference","category":"Reference","summary":"Private Jcode process ownership, session forks, readiness checks, model selection, and event delivery."},{"slug":"lang-card","title":"The cotal-lang card","kind":"Reference (informative)","category":"Reference","summary":"Effect signatures, result shapes, concurrency rules, and common refusals for cotal-lang programs."},{"slug":"launch-agents","title":"Launch agents","kind":"Guide","category":"Guide","summary":"Launch an agent through a manager, attach to its terminal, and choose its persona and runtime."},{"slug":"manager-console-api","title":"Manager console HTTP API","kind":"Reference (informative)","category":"Reference","summary":"HTTP operations, parameters, responses, and authentication for the Manager console HTTP interface."},{"slug":"manifest","title":"Mesh manifest (cotal.yaml)","kind":"Reference: every field of the mesh manifest.","category":"Reference","summary":"Manifest fields, persona overrides, channel grants, and access resolution for one team."},{"slug":"mesh-commands","title":"Mesh command catalog","kind":"Reference (informative)","category":"Reference","summary":"Built-in endpoint command declarations, capabilities, targeting modes and JSON schemas."},{"slug":"mesh-view","title":"MeshView","kind":"Reference: TypeScript observer surfaces (`MeshView`)","category":"Reference","summary":"The TypeScript observer model used by the terminal console and line stream, with dashboard feature coverage."},{"slug":"opencode-connector-reference","title":"OpenCode connector reference","kind":"Reference","category":"Reference","summary":"OpenCode version support, injected configuration, session delivery, and structured event limits."},{"slug":"overview","title":"API reference","kind":"Reference","category":"Reference","summary":"Find Cotal CLI commands, agent tools, configuration fields, and data models."},{"slug":"pi-connector-reference","title":"pi connector reference","kind":"Reference","category":"Reference","summary":"pi host lifecycle, delivery confirmation, continuation attempts, managed recovery, and event persistence."},{"slug":"presence-and-delivery","title":"Message flow","kind":"Concept (informative)","category":"Concept","summary":"How presence, routing, durable delivery, and attention determine what peers can observe and receive."},{"slug":"recover-a-mesh","title":"Recover a mesh","kind":"Guide","category":"Guide","summary":"Use status and logs to diagnose service failures, stuck presence, or a frozen registration gate."},{"slug":"register-a-mesh","title":"Register a mesh","kind":"Guide","category":"Guide","summary":"Choose the mesh a command targets and register remote brokers with verified trust."},{"slug":"release","title":"Publishing a release","kind":"Project (non-normative maintainer notes)","category":"Project","summary":"Cotal releases with pnpm, Changesets, and one GitHub Actions workflow, changesets.yml."},{"slug":"remote-supervision","title":"Supervise a remote mesh","kind":"Guide","category":"Guide","summary":"Separate broker and manager hosts, publish an exchange, and enroll remote agents."},{"slug":"roadmap","title":"Roadmap","kind":"Project (non-normative)","category":"Project","summary":"Cotal is pre-1.0, and the v0.x wire contract can still change under the change process."},{"slug":"run-a-mesh","title":"Run a mesh","kind":"Guide (informative)","category":"Guide","summary":"Start, inspect, and stop the local stack in a prepared project."},{"slug":"security-boundaries","title":"Host boundaries","kind":"Reference","category":"Reference","summary":"Credential lifetimes, metadata exposure, launch authority, and local process risks."},{"slug":"security","title":"Security model","kind":"Concept (informative threat model)","category":"Concept","summary":"Threats, guarantees, and limits for peers sharing a trusted NATS broker."},{"slug":"setup-internals","title":"Setup internals (maintainer notes)","kind":"Project (non-normative maintainer notes)","category":"Project","summary":"How cotal setup works, and the cross-repo couplings it depends on."},{"slug":"setup","title":"Configure a space","kind":"Guide","category":"Guide","summary":"Prepare a project, choose its agent application, and save its space settings."},{"slug":"spaces","title":"Spaces","kind":"Concept (informative)","category":"Concept","summary":"How spaces isolate collaboration, and how channels, permissions, membership, and conversation ids organize work within them."},{"slug":"stability","title":"Interface stability","kind":"Project (informative)","category":"Project","summary":"Cotal's packages are pre-1.0 and publish in lockstep."},{"slug":"supervise-processes","title":"Supervise the stack","kind":"Guide","category":"Guide","summary":"Choose process ownership under systemd and monitor actual component health."},{"slug":"telemetry","title":"Telemetry","kind":"Reference","category":"Reference","summary":"CLI usage telemetry fields, levels, storage, delivery, and opt-outs."},{"slug":"transport","title":"Transport vs protocol","kind":"Concept (informative)","category":"Concept","summary":"How Cotal's wire contract uses NATS and JetStream, and what another transport binding would have to preserve."},{"slug":"upgrade-cotal","title":"Upgrade Cotal","kind":"Guide","category":"Guide","summary":"Choose an exact release, prepare the deployment, and verify the upgraded installation."},{"slug":"upgrading","title":"Upgrading a running deployment","kind":"Guide (informative)","category":"Guide","summary":"Interface stability says what the version numbers promise."},{"slug":"using-cotal","title":"Choose a workflow","kind":"Start here (informative)","category":"Start here","summary":"Choose how to connect sessions, join spaces, launch teams, and run durable work."},{"slug":"watch-a-mesh","title":"Watch a mesh","kind":"Guide (informative)","category":"Guide","summary":"Choose a terminal display, line stream, or read-only browser dashboard for a running mesh."},{"slug":"web-dashboard","title":"Use the web dashboard","kind":"Guide","category":"Guide","summary":"Configure the read-only dashboard and inspect a space through a protected browser session."},{"slug":"workflow-effects","title":"Workflow effect contracts","kind":"Reference","category":"Reference","summary":"Seat ownership, budgets, supervision, decisions, presence, turns, cancellation, and placement."},{"slug":"workflow-operations","title":"Workflow operation contracts","kind":"Reference","category":"Reference","summary":"Hosted and local run commands, agent requests, admission, inventory, and keyed submission."},{"slug":"workflow-runtime","title":"Workflow runtime contracts","kind":"Reference","category":"Reference","summary":"Language replay, recovery, wire authority, durable effects, and engine limits."},{"slug":"workflows","title":"Workflow runs","kind":"Concept (informative)","category":"Concept","summary":"How a program coordinates agents, records progress, and continues after interruption."}],"spec":{"title":"Cotal Wire Specification"},"lang":{"title":"Cotal Lang: the workflow language"},"schema":{"title":"Cotal message schema (JSON Schema)"}}}var corpusPacked;function corpusData(){if(corpusPacked)return corpusPacked;const packed=readFileSync2(join5(import.meta.dirname,"docs-bundle.bin"));if(packed.length!==1174763||createHash7("sha256").update(packed).digest("hex")!=="eb950e873d59822f42cca61037f6fccbe58400f8a1b9ae86fb93aacd0a7c7121")throw new Error("docs data file docs-bundle.bin beside this module is not the one built with it");return corpusPacked=packed}var sourceBounds=[[0,2205],[2205,4e3],[4e3,9323],[9323,30004],[30004,34401],[34401,38779],[38779,42301],[42301,48733],[48733,52837],[52837,61825],[61825,65977],[65977,70425],[70425,72496],[72496,76507],[76507,107675],[107675,123163],[123163,138448],[138448,156188],[156188,171145],[171145,185870],[185870,201358],[201358,221756],[221756,227472],[227472,237087],[237087,256005],[256005,260404],[260404,283094],[283094,292306],[292306,321784],[321784,338600],[338600,361382],[361382,391189],[391189,404323],[404323,406270],[406270,415146],[415146,431330],[431330,439102],[439102,442721],[442721,446102],[446102,449405],[449405,451450],[451450,454106],[454106,458831],[458831,460659],[460659,464218],[464218,475687],[475687,483752],[483752,487277],[487277,494550],[494550,499594],[499594,502501],[502501,512095],[512095,515072],[515072,523163],[523163,526153],[526153,531098],[531098,542724],[542724,554639],[554639,559531],[559531,567062],[567062,570411],[570411,572982],[572982,580240],[580240,583660],[583660,585870],[585870,589332],[589332,592749],[592749,593863],[593863,595612],[595612,599275],[599275,603828],[603828,610419],[610419,620929],[620929,634234],[634234,636071],[636071,649056],[649056,654439],[654439,658378],[658378,660887],[660887,665929],[665929,679765],[679765,686540],[686540,692750],[692750,693567],[693567,697736],[697736,703041],[703041,706419],[706419,710627],[710627,715449],[715449,720251],[720251,723673],[723673,727072],[727072,731786],[731786,735429],[735429,748655],[748655,751473],[751473,754156],[754156,756823],[756823,759314],[759314,763334],[763334,768034],[768034,770253],[770253,836906],[836906,839977],[839977,841170],[841170,847671],[847671,855679],[855679,866281],[866281,875092],[875092,880149],[880149,1130626],[1130626,1169551],[1169551,1174763]];var sourceLengths=[4844,4048,13310,80803,12190,10700,35598,16675,9941,78405,37758,10864,4656,9872,84938,41661,42903,50427,41418,42638,42202,56682,14375,25217,53959,9884,65192,25274,88936,47512,68054,91732,36385,8216,22172,43365,21106,8796,8035,7790,4835,6062,11949,4349,8347,30545,19884,8745,47165,12743,7133,24919,7140,21069,6860,12405,30020,31428,12022,18311,8355,6090,18823,7536,5100,8160,9930,2248,5412,9845,10853,15950,26828,34181,4227,35397,12366,9603,8201,13306,95235,16844,15126,1638,9444,13555,7818,10170,12034,11921,7511,8528,11367,8527,35301,6519,6405,6095,6007,9711,11730,5283,196763,6927,2473,15538,20475,27423,21160,12299,726199,109957,21676];var decodedBodies=[];function loadDocsSourceLengths(){corpusData();return sourceLengths.slice()}function decodeDocsSource(source){const bounds=sourceBounds[source];if(!Number.isInteger(source)||!bounds)throw new Error("docs source index is out of bounds");const body=JSON.parse(gunzipSync(corpusData().subarray(bounds[0],bounds[1])).toString("utf8"));if(typeof body!=="string"||body.length!==sourceLengths[source])throw new Error("docs source body does not match its generated bounds");return body}function loadDocsSource(source){return decodedBodies[source]??=decodeDocsSource(source)}function loadDocsIndex(){const packed=readFileSync2(join5(import.meta.dirname,"docs-index.bin"));if(packed.length!==612212||createHash7("sha256").update(packed).digest("hex")!=="d1b09f3e56b810bd3d4ef8f0266c5fd8620dadd2e0081d40730f8f723b008174")throw new Error("docs data file docs-index.bin beside this module is not the one built with it");return gunzipSync(packed)}var TOKEN=/[a-z0-9_$.#>*-]+/gi;var EDGE=/^[.>*#-]+|[.>*#-]+$/g;function tokenize(s){const raw=s.toLowerCase().match(TOKEN);if(!raw)return[];const out=[];for(const r of raw){if(r.length>=2)out.push(r);const t=r.replace(EDGE,"");if(t.length>=2&&t!==r)out.push(t);if(t.includes(".")){for(const seg of t.split("."))if(seg.length>=2)out.push(seg)}}return out}var STOP=new Set("a an and are as at be by do for from has how in is it of on or that the this to use using was what when where which who with you your".split(" "));function decodeIndex(bytes,bodyLengths,version2){if(bytes.length<4)throw new Error("docs index is truncated or malformed");const headerLength=bytes.readUInt32LE(0);if(4+headerLength>bytes.length)throw new Error("docs index is truncated or malformed");const header=JSON.parse(bytes.toString("utf8",4,4+headerLength));if(header.version!==version2||header.bodyLengths.length!==bodyLengths.length||header.bodyLengths.some((length2,i)=>length2!==bodyLengths[i]))throw new Error("docs index does not match the docs bundle it is searching");const n=header.sections;const length=4*n+header.terms.length+1+2*header.postings;if(bytes.length-4-headerLength!==4*length)throw new Error("docs index is truncated or malformed");const columns=new Uint32Array(length);for(let i=0;i<length;i++)columns[i]=bytes.readUInt32LE(4+headerLength+4*i);const offsets=4*n;const sectionColumn=offsets+header.terms.length+1;let total=0;for(let i=0;i<n;i++)total+=columns[3*n+i];return{sections:n,terms:header.terms,headings:header.headings,source:columns.subarray(0,n),start:columns.subarray(n,2*n),end:columns.subarray(2*n,3*n),length:columns.subarray(3*n,4*n),offsets:columns.subarray(offsets,sectionColumn),postSection:columns.subarray(sectionColumn,sectionColumn+header.postings),postWeight:columns.subarray(sectionColumn+header.postings),avgdl:total/Math.max(1,n)}}var indexed;function metadata(){return indexed??=loadDocsMetadata()}var pages=new Map;function localPage(source){let page=pages.get(source);if(!page){page={...metadata().pages[source],body:loadDocsSource(source)};pages.set(source,page)}return page}function sourceBody(source){return source<metadata().pages.length?localPage(source).body:loadDocsSource(source)}var REMOTE_BASE="https://docs.cotal.ai";function resolvePage(page){const meta3=metadata();loadDocsSourceLengths();const reference=page.trim().toLowerCase().split(/[?#]/)[0].replace(/^\.\//,"");let key;if(/^(?:\.\.\/)?spec\/cotal-lang\.md$/.test(reference))key="lang";else if(/^(?:\.\.\/)?spec\/cotal\.schema\.json$/.test(reference))key="schema";else if(reference==="../spec.md")key="spec";else{const match=/^(?:(?:\.\.\/)?docs\/)?([a-z0-9-]+)(?:\.mdx?)?$/.exec(reference);if(!match)return void 0;key=match[1]}const count=meta3.pages.length;if(key==="spec")return{slug:"spec",title:meta3.spec.title,kind:"normative",category:"normative",summary:"",body:loadDocsSource(count)};if(key==="lang"||key==="cotal-lang")return{slug:"lang",title:meta3.lang.title,kind:"normative",category:"normative",summary:"",body:loadDocsSource(count+1)};if(key==="schema")return{slug:"schema",title:meta3.schema.title,kind:"reference",category:"reference",summary:"",body:loadDocsSource(count+2)};const source=meta3.pages.findIndex((p,source2)=>(pages.get(source2)??p).slug===key);return source<0?void 0:localPage(source)}function remoteUrl(slug){const base=`${REMOTE_BASE}/v/${DOCS_VERSION}`;if(slug==="schema")return`${base}/cotal.schema.json`;if(slug==="lang")return`${base}/cotal-lang.md`;return`${base}/${slug}.md`}function renderDocsIndex(){const b2=metadata();const rows=b2.pages.map(p=>{const kind=p.kind?`: ${p.kind}`:"";return`- \`${p.slug}\`${kind}
88
88
  ${p.summary}`});return[`# Cotal v${b2.version} documentation`,"","The authoritative docs bundled with this installed version. This index lists what","exists; it holds no answers itself. Your next call:",'- Know the page? Read it in full: `cotal_docs(page: "<slug>")` (e.g. "spec", "architecture").','- Not sure which page? Search: `cotal_docs(query: "\u2026")` returns the most relevant sections.',"Prefer these docs over training memory, and read the full page before writing code or wire","frames. Docs are bundled and version-exact; add `refresh: true` to also pull any patches","published to docs.cotal.ai for this same version.","","## The normative sources",`- \`spec\`: ${b2.spec.title} (the wire contract; where a page disagrees, the spec wins)`,`- \`lang\`: ${b2.lang.title} (the workflow language a durable run executes; spec \xA714)`,`- \`schema\`: ${b2.schema.title} (authoritative for message shapes)`,"","## Pages",...rows].join("\n")}function renderPage(p,note){return`${note}
89
89
 
90
90
  ${p.body}`.trimStart()}var K1=1.2;var B=.75;function sources(){const b2=metadata();return[...b2.pages.map((page,source)=>pages.get(source)??page),{slug:"spec",...b2.spec},{slug:"lang",...b2.lang},{slug:"schema",...b2.schema}]}var index;function searchIndex(){if(index)return index;const lengths=loadDocsSourceLengths();for(const[source,page]of pages)lengths[source]=page.body.length;return index=decodeIndex(loadDocsIndex(),lengths,DOCS_VERSION)}function termId(terms,term){let low=0;let high=terms.length-1;while(low<=high){const mid=low+high>>>1;const candidate=terms[mid];if(candidate===term)return mid;if(candidate<term)low=mid+1;else high=mid-1}return-1}function searchDocs(query,limit=5){if(limit<=0)return[];let terms=tokenize(query).filter(t=>!STOP.has(t));if(!terms.length)terms=tokenize(query);const termSet=new Set(terms);if(!termSet.size)return[];const idx=searchIndex();const N2=idx.sections;const scores=new Float64Array(N2);for(const t of termSet){const id=termId(idx.terms,t);if(id<0)continue;const from=idx.offsets[id];const to=idx.offsets[id+1];const n=to-from;const idf=Math.log(1+(N2-n+.5)/(n+.5));for(let p=from;p<to;p++){const s=idx.postSection[p];const f=idx.postWeight[p];scores[s]+=idf*(f*(K1+1)/(f+K1*(1-B+B*idx.length[s]/idx.avgdl)))}}const scored=[];for(let s=0;s<N2;s++)if(scores[s]>0)scored.push({s,score:scores[s]});scored.sort((a,b2)=>b2.score-a.score);const all=sources();const perPage=new Map;const hits=[];for(const{s,score}of scored){const source=all[idx.source[s]];const seen=perPage.get(source.slug)??0;if(seen>=2)continue;perPage.set(source.slug,seen+1);hits.push({slug:source.slug,pageTitle:source.title,heading:idx.headings[s],text:sourceBody(idx.source[s]).slice(idx.start[s],idx.end[s]),score});if(hits.length>=limit)break}return hits}function capSection(text,maxLines=48){const lines=text.split("\n");if(lines.length<=maxLines)return text.trim();return lines.slice(0,maxLines).join("\n").trimEnd()+"\n\n\u2026 (section continues; read the full page)"}function renderSearch(query,hits){loadDocsSourceLengths();if(!hits.length){return`No matches for "${query}" in the Cotal v${DOCS_VERSION} docs. Call cotal_docs() for the page index, or search an exact identifier (a subject, a cotal_* tool, a field name).`}const blocks=hits.map(h2=>`## ${h2.heading}
@@ -114,7 +114,7 @@ ${who}`)}return err2(`Couldn't DM: ${e.message}`)}}},{name:"cotal_anycast",title
114
114
  ${lines.join("\n")}`:`No channels in "${config2.space}" to list${want?` matching ${JSON.stringify(filter)}`:""}${after===void 0?"":` after #${after}`}.`;return ok2(notes.length?`${head}
115
115
  ${notes.join("\n")}`:head)}},{name:"cotal_channel_mode",title:"Cotal: silence or mute a channel",description:"Set how a single channel interrupts you: your per-channel attention, more specific than cotal_status. quiet = ambient stays buffered and pull-only (read it with cotal_inbox); it never enters another turn, while an @mention still wakes and injects. muted = you stop receiving this channel entirely, including @mentions (DMs still reach you). normal = clear the override; the channel follows your global attention. Runtime + per-instance: resets when your session restarts. An operator can set a lasting default in your agent file. See your current settings with cotal_channels.",schema:{channel:external_exports.string().describe("The channel to set (a concrete channel you can read, e.g. random)."),mode:external_exports.enum(["normal","quiet","muted"]).describe("quiet = receive silently, @mentions still wake; muted = stop receiving it (incl. @mentions); normal = follow global attention.")},async run(agent,_config,{channel,mode}){if(!agent.connected)return ok2(`Not connected to the mesh yet (${config2.servers}).`);try{await agent.setChannelMode(channel,mode);const desc=mode==="quiet"?"delivered but won't wake you; @mentions still wake you":mode==="muted"?"no longer received (incl. @mentions); DMs still reach you":"back to following your global attention";return ok2(`#${channel} is now ${mode} \u2014 ${desc}.`)}catch(e){return err2(`Couldn't set #${channel} to ${mode}: ${e.message}`)}}},{name:"cotal_join",title:"Cotal: join a channel",description:"Join a channel to see its posts. If the channel replays history, you also get its recent posts as catch-up. Join the channel of every task you are part of. You can join only channels your read permission covers. A pattern follows a whole family of channels: review.> covers every channel under review, including ones opened later, but not review itself, and review.* covers one level. Follow a family only if that is your job, because every post in it reaches you. Under a family such as review.>, posts on its durable channels are kept for you while you are offline, from the join on, and its live channels reach you only while you are connected. A pattern with * or the root > is followed live only: posts sent while you are offline are not kept for you. Join a channel by its full name when you must not miss a post.",schema:{channel:external_exports.string().describe("The channel to join (e.g. incident), or a family such as team.>.")},async run(agent,_config,{channel}){const notName=notAChannelName(channel,"Nothing was joined.");if(notName!==void 0)return err2(`Couldn't join: ${notName}`);if(!(isConcreteChannel4(channel)?channelInAllow3:patternInAllow)(config2.allowSubscribe,channel))return err2(`Can't join #${channel}: it's outside your read ACL (allowSubscribe: ${config2.allowSubscribe.map(c=>`#${c}`).join(", ")}).`);try{const r=await agent.joinChannel(channel);if(!r.joined)return ok2(`Already on #${channel}.`);const info=renderChannelInfo(channel,agent.channelInfo(channel));const caught=r.backfilled>0?`
116
116
  Backfilled ${r.backfilled} earlier message${r.backfilled===1?"":"s"} into your inbox (marked "history" \u2014 they pre-date your join; read with cotal_inbox).`:"";const headline=r.durable?isChannelFamily2(channel)?`Joined #${channel} (stored copies on: posts on its durable channels are kept for you while you're offline, from now on; its live channels reach you only while you're connected).`:`Joined #${channel} (durable backstop active \u2014 messages sent while you're offline replay on your next turn).`:r.reason?isConcreteChannel4(channel)||isChannelFamily2(channel)?`Joined #${channel} (LIVE only \u2014 ${r.reason}; messages sent while you're offline won't be replayed).`:`Joined #${channel} (live only: ${r.reason}).`:`Joined #${channel} (live).`;return ok2(`${headline}
117
- ${info}${caught}`)}catch(e){return err2(`Couldn't join #${channel}: ${e.message}`)}}},{name:"cotal_leave",title:"Cotal: leave a channel",description:"Leave a channel when you are done with its task. You stay reachable by DM and anycast.",schema:{channel:external_exports.string().describe("The channel or family to leave.")},async run(agent,_config,{channel}){try{const r=await agent.leaveChannel(channel);return ok2(r.left?`Left #${channel}.`:`You weren't on #${channel}.`)}catch(e){return err2(`Couldn't leave #${channel}: ${e.message}`)}}},{name:"cotal_spawn",title:"Cotal: spawn a new teammate",description:`Start another agent on the mesh to do a job. It runs as its own process: it shows up on the roster, the user can watch it work, and any agent can message it. A subagent that your own harness starts, such as Claude Code's Task tool, runs inside your session, where nobody else can see or reach it. Prefer cotal_spawn. Use a subagent only for a self-contained job nobody else needs to follow, where it keeps the work contained and can be more efficient, depending on the harness. Usually you write the new agent's persona here: pass persona, whose prompt says who it is, and a name. The top-level prompt is the first message it works on, so say there what to do. If others could use its work, put it on the task's channel with join and say in the prompt where the brief is. To start a saved persona instead, pass its name and no persona; cotal_personas lists them. Pass persona.save: true, or use cotal_persona, only for a persona worth reusing. Example: \`{name: "reviewer", join: ["review.login-page"], persona: {prompt: "You review the login page change and report each finding with its file and line.", allowSubscribe: ["review.login-page"], allowPublish: ["review.login-page"]}, prompt: "Read the brief on #review.login-page, post your findings there, then despawn yourself."}\` The new agent can read and post wherever its persona allows. A persona you pass here, or an operator's persona, that names no channels gets your read and post grants and no more; one you save with cotal_persona gets only the channels it lists. Give a helper only what its job needs, so list just the channels it needs. You can give it only channels and capabilities you hold. On a mesh that checks grants, a spawn that asks for more is refused, and the refusal names each part you do not hold. It can spawn agents or run workflows only if its persona lists spawn or run. Endpoint access comes from the operator, so ask the user if the job needs it. cotal_orientation shows what you hold. For a single job on a Claude Code, jcode, OpenCode or pi helper, pass once: true with the prompt, and the helper is stopped when it ends that turn; or tell it in the prompt to despawn itself when done, as in the example. A standing teammate keeps running until it despawns itself or you call cotal_despawn. For work with several steps, a wait on a person, or a need to survive restarts, use cotal_run.`,schema:{name:external_exports.string().describe("With `persona`, the new helper's name (auto-numbered with an underscore, e.g. reviewer_2, if that's taken). Without it, which catalog persona to spawn: the persona FILENAME in .cotal/agents (e.g. `review-critic`), without the .md; the peer joins under the persona's own `name:`, and an unknown name fails."),persona:external_exports.object({prompt:external_exports.string().min(1).describe("Who the helper is: its persona body, as a persona file's body would be. Its first message is the top-level `prompt`."),role:external_exports.string().min(1).optional().describe("The helper's role (e.g. reviewer). The top-level `role` wins."),model:external_exports.string().min(1).optional().describe("The helper's model. The top-level `model` wins. The spawn fails if the manager does not record this pin."),variant:external_exports.string().min(1).optional().describe("The helper's model variant. The top-level `variant` wins."),description:external_exports.string().min(1).optional().describe("A one-line description, shown in the catalog when the persona is saved."),subscribe:external_exports.array(external_exports.string()).optional().describe("Channels the helper reads at start. Omit every channel field to take your own read and post grants; pass [] for none."),allowSubscribe:external_exports.array(external_exports.string()).optional().describe("Channels the helper may read. Each must be one you may read."),allowPublish:external_exports.array(external_exports.string()).optional().describe("Channels the helper may post to. Each must be one you may post to."),capabilities:external_exports.array(external_exports.string()).optional().describe("Capabilities to hand on, such as spawn or run. Each must be one you hold."),save:external_exports.boolean().optional().describe("Also save this persona to the catalog under `name`, for a broad persona worth reusing. A name already in the catalog is refused before anything starts.")}).strict().optional().describe("Define the helper on this spawn instead of from a catalog file: `prompt` (who it is), with optional `role`, `model`, `variant`, `description`, `subscribe`, `allowSubscribe`, `allowPublish`, `capabilities` and `save`. Not saved unless `save` is true."),join:external_exports.array(external_exports.string()).optional().describe("Channels the new peer joins at start, on top of what its persona file lists (e.g. ['general']). Concrete names only, each within YOUR read ACL (a spawn hands on only what you may read yourself; anything else is refused before launch). Omitted, a persona that lists no channel starts on none and its cotal_send with no channel is refused."),instance:external_exports.string().refine(value=>{try{assertLifecycleToken3(value,"instance");return true}catch{return false}},"instance must be a lifecycle token ([a-z0-9]{26,32})").optional().describe("Optional manager instance id for a multi-manager space. An open managed seat defaults to its launching manager; an unbound open or static caller uses class anycast. User-auth selection remains issuer-bound. A pin that cannot be resolved is refused without falling back to another manager."),role:external_exports.string().optional().describe("Optional role for the new peer (e.g. worker, reviewer); overrides the persona's role. A role of `manager` requires the helper to hold `spawn`, from `persona.capabilities` or its catalog file: a seat that presents as a manager but cannot spawn is refused at spawn time. You can hand on `spawn` only if you hold it."),agent:external_exports.string().optional().describe("Optional harness the new peer runs on: the agent/connector type (claude, jcode, opencode, hermes), NOT the persona to spawn (that's `name`). Resolution order: this explicit agent > the persona's agent: pin > the caller's COTAL_DEFAULT_AGENT > the manager's COTAL_DEFAULT_AGENT > the product default (Claude)."),model:external_exports.string().min(1).optional().describe("Optional model override (e.g. opus, sonnet); it wins over the persona file's model:. The spawn fails if the manager does not record this pin. The result names the recorded model; do not treat a spawn as cross-vendor unless that name matches what you requested. If the pin cannot be read back, the result is partial and the seat still runs."),variant:external_exports.string().optional().describe("Optional model variant override (connector-defined; for OpenCode, a model variant such as high/max/low)."),launchOptions:external_exports.record(external_exports.string(),external_exports.unknown()).optional().describe("Optional connector-specific launch options: an opaque key\u2192value map the chosen connector forwards raw to its own host form (claude CLI flags, OpenCode agent config); a connector with no option surface (Hermes) rejects any, and malformed keys are refused."),cwd:external_exports.string().optional().describe("Optional working directory to root the new peer at (e.g. a different repo). A relative path resolves against the manager's workspace; omitted \u2192 it shares the manager's workspace. A directory that does not exist on the serving manager's host is refused before launch, with the host named; in a multi-manager space pin the manager with instance."),prompt:external_exports.string().min(1).optional().describe("Optional kickoff message auto-submitted as the new peer's first turn. Pass it when the peer should begin work immediately; omitted means no first model turn is submitted."),events:external_exports.boolean().optional().describe("Event planes are on by default for connectors that publish one. Pass false to opt out; true only restates the default."),once:external_exports.boolean().optional().describe("Run `prompt` as the new peer's one task, then stop the peer. The task reaches the peer as a relayed turn rather than a kickoff, and the peer is stopped when it ends that turn or when the deadline passes. Needs `prompt`. A Claude Code peer takes the task only when its startup shows channels on; otherwise the spawn fails at startup and says why."),deadline:external_exports.string().optional().describe("With once: how long the task may run, as a duration such as 30m, 2h or 1d, counted from when the manager accepts the spawn. Omitted, it is 1h. Pass -1 for no deadline: the peer then keeps its name and its seat slot until it ends its turn or is despawned."),runtime:external_exports.string().trim().min(1).optional().describe("Optional terminal runtime for this one seat (pty, or an installed extension such as tmux). Omitted, the serving manager uses its own. An unknown or unreachable runtime, and auto, refuse the launch and start nothing.")},async run(agent,_config,{name,persona,instance,role,agent:agentType,model,variant,launchOptions,cwd,prompt,events,once,deadline,runtime,join:join8}){let onceArg;if(deadline!==void 0&&once!==true)return err2("`deadline` applies only to a once spawn; pass once: true with it.");if(once===true){if(deadline===void 0)onceArg={};else if(deadline.trim()==="-1")onceArg={deadlineMs:-1};else{let ms;try{ms=parseDuration(deadline)}catch(e){return err2(`deadline: ${e.message}, or -1 for no deadline`)}if(!Number.isSafeInteger(ms)||ms<1)return err2(`deadline: "${deadline}" is not a positive duration; pass one such as 30m, or -1 for no deadline`);onceArg={deadlineMs:ms}}}try{const reply=await agent.spawn(name,role,{agent:agentType,model,variant,launchOptions,cwd,prompt,events,runtime,instance,join:join8,persona,...onceArg!==void 0?{once:onceArg}:{}});const pending=reply.code==="uncertain";const submission=reply.data;if(!reply.ok&&submission?.submissionUnknown&&submission.goalId){const goalId=submission.goalId;const next=`cotal_invoke(endpoint="manager", command="goal-result", args={"goalId":${JSON.stringify(goalId)}})`;const message=`Spawn submission for ${name} has an unknown outcome for goal "${goalId}". Acceptance has not been confirmed; the seat may appear later. Do NOT retry: another submission could create a second lifecycle. ${reply.error??"The submission wait ended."} Next: ${next} as this same caller, or inspect 'ps'/'inspect'. A missing result does not prove the submission failed.`;return{text:message,structured:{status:"unknown",name,goalId,next,message}}}if(!reply.ok&&!pending)return err2(`Couldn't spawn ${name}: ${renderLifecycleBlocked(reply.error??"manager refused",reply)}`);const d2=reply.data;const actual=d2?.name??name;const mode=d2?.mode;const who=peerLabel4({name:actual,role});const lead=actual!==name?`"${name}" was taken \u2014 spawning ${who} instead`:`Spawning ${who}`;const pin=d2?.model?` recorded model ${JSON.stringify(d2.model)}`:"";if(d2?.pinAudit){const{requested,error:error51,unreported}=d2.pinAudit;const id=d2.id??d2.actor;const manager=d2.executor?.lifecycleUid??reply.instanceId;const next=`cotal ps --on ${manager}`;const state=pending?"it has not joined the mesh within its readiness window and may still be booting":"it joined the mesh";const audit=unreported?"was not reported by this manager":"could not be audited";const message=`${lead} (id ${id}, manager ${manager}${mode?`, runtime ${mode}`:""}): ${state}, but its model pin ${JSON.stringify(requested)} ${audit} (${error51}). Do not spawn it again: a retry starts a second agent. Next: \`${next}\` shows the seat and the model its manager recorded.`;return{text:message,structured:{status:"partial",name:actual,id,manager,...mode?{runtime:mode}:{},joined:!pending,model:{requested,audited:false,reported:!unreported,error:error51},next,message}}}if(pending)return ok2(`${lead}${pin} (id ${d2?.actor}, manager ${d2?.executor?.lifecycleUid}), but it did not join the mesh within its readiness window. It may still be booting, so do not spawn it again: a retry starts a second agent. Watch cotal_roster for ${actual}, and cotal_despawn it if it never joins.`);const task=d2?.once?` Its task is goal ${JSON.stringify(d2.once.goalId)}, ${d2.once.deadlineAt!==void 0?`with a deadline of ${new Date(d2.once.deadlineAt).toISOString()}`:"with no deadline"}; it is stopped when the task ends. Read the outcome with cotal_invoke(endpoint="manager", command="goal-result", args={"goalId":${JSON.stringify(d2.once.goalId)}}).`:"";return ok2(spawnResult({requested:name,started:who,renamed:actual!==name,mode,model:d2?.model,join:join8,waitingFor:d2?.waitingFor,once:d2?.once!==void 0})+task)}catch(e){return controlFailure(`Couldn't spawn ${name}`,e)}}},{name:"cotal_feedback",title:"Cotal: send beta feedback",description:"Send feedback about Cotal to its developers. With a configured feedback key it goes to the keyed beta intake; without one it goes to the public cotal.ai intake, which requires a contact email.",schema:{origin:external_exports.enum(["human","agent"]).describe(`"human" when relaying the user's feedback, "agent" when reporting an issue you hit yourself.`),type:external_exports.enum(["bug","idea","friction","praise","other"]).describe("What kind of feedback this is."),summary:external_exports.string().max(300).describe("Required one-line summary, max 300 characters."),details:external_exports.string().max(1e4).optional().describe("Longer free-form details. Do not include secrets."),severity:external_exports.enum(["low","medium","high"]).optional().describe("How badly this hurts (bugs/friction)."),area:external_exports.string().max(120).optional().describe("The part of Cotal this concerns (e.g. presence, channels, CLI)."),repro:external_exports.string().max(1e4).optional().describe("Steps to reproduce."),expected:external_exports.string().max(5e3).optional().describe("What you expected to happen."),actual:external_exports.string().max(5e3).optional().describe("What actually happened."),diagnostics:external_exports.string().max(1e4).optional().describe("Relevant diagnostics as text (logs, errors). Never include secrets."),email:external_exports.string().optional().describe("Contact email, required on the keyless public path when none is configured in the environment.")},async run(_agent,_config,args){const{email:email3,...payload}=args;const contact=config2.feedbackKey?void 0:resolveFeedbackEmail(email3,env);return submitFeedback({...payload,source},{key:config2.feedbackKey,url:config2.feedbackUrl,email:contact})}},{name:"cotal_despawn",title:"Cotal: stop a teammate",description:"Stop a helper when its job is done, or stop yourself by leaving out name. The manager that started you then ends your process. This works only for an agent a manager started; a session someone connected by hand is refused. Graceful by default; pass graceful: false only for a hung agent.",schema:{name:external_exports.string().optional().describe("Name of the peer to stop. Omit to stop yourself (self-despawn)."),instance:external_exports.string().refine(value=>{try{assertLifecycleToken3(value,"instance");return true}catch{return false}},"instance must be a lifecycle token ([a-z0-9]{26,32})").optional().describe("Optional manager instance id for the named peer. Requires `name`. Omitted keeps this session's existing manager selection. A managed user-auth seat must use its own manager. An unresolved pin is refused without fallback."),graceful:external_exports.boolean().optional().describe("Default true: let the session exit cleanly. false = hard kill.")},async run(agent,_config,{name,instance,graceful}){try{const reply=await agent.despawn(name,{graceful,instance});if(!reply.ok){return err2(`Couldn't despawn ${name??"self"}: ${reply.error??"manager refused"}`)}const who=name??"self";return ok2(`Stopping ${who}${graceful===false?" (hard)":""} \u2014 it will leave the roster shortly.`)}catch(e){return controlFailure(`Couldn't despawn ${name??"self"}`,e)}}},{name:"cotal_yield",title:"Cotal: yield a run turn",description:'Report the outcome of a workflow turn assigned to you. Use this only when your context contains a pending run turn; it does not start a workflow or resolve a checkpoint/ask.\n\nUsually finish your session turn normally: that yields `done` automatically. If you cannot progress, call `{"status":"blocked","note":"<what prevents progress>"}`. To hand the assigned turn to another agent, call `{"status":"handoff","to":"<agent-name>","note":"<handoff context>"}`.\n\nWhen you hold several assigned turns, pass `turn` with the exact goal id from the relevant run-turn context block. Without `turn`, the oldest turn already shown to your session is selected. A turn that has not been shown cannot be yielded, and neither can one the run already settled, such as a turn whose deadline elapsed: that refusal names the turn and its deadline. A successful reply confirms the turn was yielded, not that the whole workflow completed; the run\'s coordinator can inspect progress with `cotal_run` status.',schema:{status:external_exports.enum(["done","blocked","handoff"]).describe("done = finished (usually implicit: just end your turn instead); blocked = can't proceed; handoff = another agent should take it."),to:external_exports.string().optional().describe("Required for handoff: the agent name the assigned turn should pass to."),note:external_exports.string().max(4096).optional().describe("Short free-text for the run: what blocked you, or what the next agent should know."),turn:external_exports.string().optional().describe("The turn's goal id, from the \u{1F3AF} block. Omit when you hold only one.")},async run(agent,_config,{status,to,note,turn}){try{const reply=await agent.yieldTurn(status,{to,note,turn});if(!reply.ok)return err2(`Couldn't yield: ${reply.error??"manager refused"}`);return ok2(`Turn yielded (${status}${to?` \u2192 ${to}`:""}) \u2014 the run continues.`)}catch(e){return err2(`Couldn't yield: ${e.message}`)}}},{name:"cotal_run",title:"Cotal: run a workflow program",description:'Use for coordination with several steps, waits on a person, or work that must survive restarts. For one job done by one helper, use cotal_spawn. Use Cotal Lang to program multi-step coordination between agents: sequence work, run tasks in parallel, branch on results, wait for events, and request human decisions. Agents own their reasoning and conversations; the workflow specifies when they act and which outcomes determine the next step.\n\nBefore writing a program, read cotal_docs pages `workflows` and `lang-card`. Hosted execution requires a running execution-capable manager, the `run` capability, and issued caller authority. A managed agent on a user-auth mesh uses its own bearer command and selected participant manager; both its current grant and its direct parent\'s current grant must allow `run`. Open meshes, unsupported local user-mode hosts and execution-free control managers refuse hosted runs. `@cotal-ai/lang` provides validation and simulation separately; those are not verbs of this tool.\n\nSTART: pass `verb: "start"` and the program text in `source`. Example: `{"verb":"start","source":"await sleep(\\"1s\\", { name: \\"first-run\\" });"}`. Optional `file` labels diagnostics only; it reads nothing from disk. The manager validates before recording the run and returns a runId. Acceptance is not completion.\n\nINSPECT: use `verb: "status"` with that `runId` for state and step journal, or `verb: "ps"` to list runs. Both are read-only. Report completion only after observing state `completed`; surface failures or unresolved steps.\n\nANSWER: first inspect status, then pass `verb: "answer"`, `runId`, the exact open `stepKey`, and, when requested, `value` matching the answer shape. An ask requires its requested record; a checkpoint can resolve without a value. `artifact` may name the evidence reviewed. Answer only with authority to make that decision; never invent an approval.\n\nRESUME: pass `verb: "resume"` and `runId` to continue a run from its recorded source. A held run appears as `released` in status. Do not start a duplicate run to continue it or resume one the manager is already driving.\n\nRuns continue independently of your session and can recover after a manager restart. Their channel effects are bounded by the starting credential\'s issued channel scope. To report that your assigned agent turn is blocked or handed off, use `cotal_yield` instead. Pass `instance` for the exact manager when an unbound user-auth caller has several managers; a failed pin does not fall back.',schema:{verb:external_exports.enum(["start","status","ps","answer","resume"]).describe("start = validate and drive a new program; status = one run's record + journal; ps = list runs; answer = resolve an open checkpoint/ask; resume = take a released or held run over."),source:external_exports.string().min(1).optional().describe("start only: the cotal-lang program source, inline. Required for start."),file:external_exports.string().min(1).optional().describe("start only: a file name to attribute the source to in error messages. Diagnostic only; nothing is read from disk."),timeout:external_exports.string().min(1).optional().describe("start/resume: the default checkpoint timeout for the drive, as a duration (e.g. `1h`, `30m`). Default 1h."),runId:external_exports.string().min(1).optional().describe("Required for status, answer and resume: the run id (`run-<32 hex>`) returned by start or ps."),stepKey:external_exports.string().min(1).optional().describe("Required for answer: copy the exact open step key from status, e.g. `/checkpoint:approve#0`."),value:external_exports.unknown().optional().describe("answer only: supply the value requested by the open checkpoint or ask and match its answer shape. A checkpoint may resolve without a value; an ask must receive its requested record. Use null only when that is the intended answer."),artifact:external_exports.string().min(1).optional().describe("answer only: a reference to what you reviewed before answering, recorded beside the answer."),endpoint:external_exports.string().min(1).optional().describe("status/ps/answer: the endpoint the run record lives under. Omit for runs the manager hosts."),page:external_exports.strictObject({limit:external_exports.number().int().min(1).max(16).optional(),cursor:external_exports.string().min(1).max(3072).regex(/^[A-Za-z0-9_-]+$/).optional()}).optional().describe("ps only: one bounded diagnostic JSON page, default 8 rows. Pin the manager with instance unless this session is already bound. Continuation is not snapshot, absence or ownership proof. A manager from release 0.88.0 or earlier refuses `page`."),instance:managerInstanceArg},async run(agent,config3,a){const need=(field,verb)=>a[field]===void 0?err2(`cotal_run ${verb}: \`${String(field)}\` is required`):void 0;try{if(a.page!==void 0&&a.verb!=="ps")return err2("cotal_run: page is supported only for ps");if(a.page!==void 0&&a.instance===void 0&&config3.managerInstanceId===void 0)return err2("cotal_run ps: diagnostic pages require an explicit instance or a bound manager");if(a.verb==="start"){const missing2=need("source","start");if(missing2)return missing2;const reply2=await agent.run("start",{source:a.source,file:a.file,timeout:a.timeout},a.instance);if(!reply2.ok)return err2(renderRunRefusal("start",reply2));const{runId}=reply2.data;return ok2(`Started run ${runId} on the manager. It runs there until it completes or is held; cotal_run(verb="status", runId="${runId}"${a.instance?`, instance="${a.instance}"`:""}) follows its steps, and an open checkpoint is answered with verb="answer"${a.instance?` on instance="${a.instance}"`:""}.`)}if(a.verb==="resume"){const missing2=need("runId","resume");if(missing2)return missing2;const reply2=await agent.run("resume",{runId:a.runId,timeout:a.timeout},a.instance);if(!reply2.ok)return err2(renderRunRefusal("resume",reply2));return ok2(`Resumed run ${a.runId} on the manager from its recorded program.${a.instance?` Use instance="${a.instance}" for subsequent status and answer calls to this manager.`:""}`)}if(a.verb==="ps"){const reply2=await agent.run("ps",{endpoint:a.endpoint,...a.page!==void 0?{page:a.page}:{}},a.instance);if(!reply2.ok)return err2(renderRunRefusal("ps",reply2));if(a.page!==void 0){const page=reply2.data;if(page===null||typeof page!=="object"||Array.isArray(page)||page.semantics!=="diagnostic")return err2("the manager did not return a diagnostic inventory page");const text=JSON.stringify(page);if(a.page.cursor!==void 0&&page.nextCursor===a.page.cursor)return err2(`Diagnostic inventory made no progress; retain this incomplete observation, do not retry in a loop: ${text}`);return ok2(text)}const rows=reply2.data;if(rows.length===0)return ok2("No workflow runs are recorded in this space.");return ok2(rows.map(r=>`${r.runId} ${r.endpoint} ${r.state??"(no status)"} holder=${r.holder??"-"} journal=${r.journalHigh??"-"}${r.forkedFrom?` forked-from=${r.forkedFrom.run}@${r.forkedFrom.step}`:""}`).join("\n"))}if(a.verb==="status"){const missing2=need("runId","status");if(missing2)return missing2;const reply2=await agent.run("status",{runId:a.runId,endpoint:a.endpoint},a.instance);if(!reply2.ok)return err2(renderRunRefusal("status",reply2));const v2=reply2.data;const head=`run ${v2.runId} on ${v2.endpoint}: ${v2.status?`${v2.status.state}, holder ${v2.status.holder}, epoch ${v2.status.epoch}`:"(no status)"}`;const lines=v2.journal.map(r=>r.kind==="activation"?`#${r.n} activation holder=${r.holder} epoch=${r.epoch} replayedTo=${r.replayedTo}`:`#${r.n} step ${r.step} ${r.outcome}${r.asks!==void 0?`
117
+ ${info}${caught}`)}catch(e){return err2(`Couldn't join #${channel}: ${e.message}`)}}},{name:"cotal_leave",title:"Cotal: leave a channel",description:"Leave a channel when you are done with its task. You stay reachable by DM and anycast.",schema:{channel:external_exports.string().describe("The channel or family to leave.")},async run(agent,_config,{channel}){try{const r=await agent.leaveChannel(channel);return ok2(r.left?`Left #${channel}.`:`You weren't on #${channel}.`)}catch(e){return err2(`Couldn't leave #${channel}: ${e.message}`)}}},{name:"cotal_spawn",title:"Cotal: spawn a new teammate",description:`Start another agent on the mesh to do a job. It runs as its own process: it shows up on the roster, the user can watch it work, and any agent can message it. A subagent that your own harness starts, such as Claude Code's Task tool, runs inside your session, where nobody else can see or reach it. Prefer cotal_spawn. Use a subagent only for a self-contained job nobody else needs to follow, where it keeps the work contained and can be more efficient, depending on the harness. Usually you write the new agent's persona here: pass persona, whose prompt says who it is, and a name. The top-level prompt is the first message it works on, so say there what to do. If others could use its work, put it on the task's channel with join and say in the prompt where the brief is. To start a saved persona instead, pass its name and no persona; cotal_personas lists them. Pass persona.save: true, or use cotal_persona, only for a persona worth reusing. Example: \`{name: "reviewer", join: ["review.login-page"], persona: {prompt: "You review the login page change and report each finding with its file and line.", allowSubscribe: ["review.login-page"], allowPublish: ["review.login-page"]}, prompt: "Read the brief on #review.login-page, post your findings there, then despawn yourself."}\` The new agent can read and post wherever its persona allows. A persona you pass here, or an operator's persona, that names no channels gets your read and post grants and no more; one you save with cotal_persona gets only the channels it lists. Give a helper only what its job needs, so list just the channels it needs. You can give it only channels and capabilities you hold. On a mesh that checks grants, a spawn that asks for more is refused, and the refusal names each part you do not hold. It can spawn agents or run workflows only if its persona lists spawn or run. Endpoint access comes from the operator, so ask the user if the job needs it. cotal_orientation shows what you hold. For a single job on a Claude Code, jcode, OpenCode or pi helper, pass once: true with the prompt, and the helper is stopped when it ends that turn; or tell it in the prompt to despawn itself when done, as in the example. A standing teammate keeps running until it despawns itself or you call cotal_despawn. For work with several steps, a wait on a person, or a need to survive restarts, use cotal_run.`,schema:{name:external_exports.string().describe("With `persona`, the new helper's name (auto-numbered with an underscore, e.g. reviewer_2, if that's taken). Without it, which catalog persona to spawn: the persona FILENAME in .cotal/agents (e.g. `review-critic`), without the .md; the peer joins under the persona's own `name:`, and an unknown name fails."),persona:external_exports.object({prompt:external_exports.string().min(1).describe("Who the helper is: its persona body, as a persona file's body would be. Its first message is the top-level `prompt`."),role:external_exports.string().min(1).optional().describe("The helper's role (e.g. reviewer). The top-level `role` wins."),model:external_exports.string().min(1).optional().describe("The helper's model. The top-level `model` wins. The spawn fails if the manager does not record this pin."),variant:external_exports.string().min(1).optional().describe("The helper's model variant. The top-level `variant` wins."),description:external_exports.string().min(1).optional().describe("A one-line description, shown in the catalog when the persona is saved."),subscribe:external_exports.array(external_exports.string()).optional().describe("Channels the helper reads at start. Omit every channel field to take your own read and post grants; pass [] for none."),allowSubscribe:external_exports.array(external_exports.string()).optional().describe("Channels the helper may read. Each must be one you may read."),allowPublish:external_exports.array(external_exports.string()).optional().describe("Channels the helper may post to. Each must be one you may post to."),capabilities:external_exports.array(external_exports.string()).optional().describe("Capabilities to hand on, such as spawn or run. Each must be one you hold."),save:external_exports.boolean().optional().describe("Also save this persona to the catalog under `name`, for a broad persona worth reusing. A name already in the catalog is refused before anything starts.")}).strict().optional().describe("Define the helper on this spawn instead of from a catalog file: `prompt` (who it is), with optional `role`, `model`, `variant`, `description`, `subscribe`, `allowSubscribe`, `allowPublish`, `capabilities` and `save`. Not saved unless `save` is true."),join:external_exports.array(external_exports.string()).optional().describe("Channels the new peer joins at start, on top of what its persona file lists (e.g. ['general']). Concrete names only, each within YOUR read ACL (a spawn hands on only what you may read yourself; anything else is refused before launch). Omitted, a persona that lists no channel starts on none and its cotal_send with no channel is refused."),instance:external_exports.string().refine(value=>{try{assertLifecycleToken3(value,"instance");return true}catch{return false}},"instance must be a lifecycle token ([a-z0-9]{26,32})").optional().describe("Optional manager instance id for a multi-manager space. An open managed seat defaults to its launching manager; an unbound open or static caller uses class anycast. User-auth selection remains issuer-bound. A pin that cannot be resolved is refused without falling back to another manager."),role:external_exports.string().optional().describe("Optional role for the new peer (e.g. worker, reviewer); overrides the persona's role. A role of `manager` requires the helper to hold `spawn`, from `persona.capabilities` or its catalog file: a seat that presents as a manager but cannot spawn is refused at spawn time. You can hand on `spawn` only if you hold it."),agent:external_exports.string().optional().describe("Optional harness the new peer runs on: the agent/connector type (claude, jcode, opencode, hermes), NOT the persona to spawn (that's `name`). Resolution order: this explicit agent > the persona's agent: pin > the caller's COTAL_DEFAULT_AGENT > the manager's COTAL_DEFAULT_AGENT > the product default (Claude)."),model:external_exports.string().min(1).optional().describe("Optional model override (e.g. opus, sonnet); it wins over the persona file's model:. The spawn fails if the manager does not record this pin. The result names the recorded model; do not treat a spawn as cross-vendor unless that name matches what you requested. If the pin cannot be read back, the result is partial and the seat still runs."),variant:external_exports.string().optional().describe("Optional model variant override (connector-defined; for OpenCode, a model variant such as high/max/low)."),launchOptions:external_exports.record(external_exports.string(),external_exports.unknown()).optional().describe("Optional connector-specific launch options: an opaque key\u2192value map the chosen connector forwards raw to its own host form (claude CLI flags, OpenCode agent config); a connector with no option surface (Hermes) rejects any, and malformed keys are refused."),cwd:external_exports.string().optional().describe("Optional working directory to root the new peer at (e.g. a different repo). A relative path resolves against the manager's workspace; omitted \u2192 it shares the manager's workspace. A directory that does not exist on the serving manager's host is refused before launch, with the host named; in a multi-manager space pin the manager with instance."),prompt:external_exports.string().min(1).optional().describe("Optional kickoff message auto-submitted as the new peer's first turn. Pass it when the peer should begin work immediately; omitted means no first model turn is submitted."),events:external_exports.boolean().optional().describe("Event planes are on by default for connectors that publish one. Pass false to opt out; true only restates the default."),once:external_exports.boolean().optional().describe("Run `prompt` as the new peer's one task, then stop the peer. The task reaches the peer as a relayed turn rather than a kickoff, and the peer is stopped when it ends that turn or when the deadline passes. Needs `prompt`. A Claude Code peer takes the task only when its startup shows channels on; otherwise the spawn fails at startup and says why."),deadline:external_exports.string().optional().describe("With once: how long the task may run, as a duration such as 30m, 2h or 1d, counted from when the manager accepts the spawn. Omitted, it is 1h. Pass -1 for no deadline: the peer then keeps its name and its seat slot until it ends its turn or is despawned."),runtime:external_exports.string().trim().min(1).optional().describe("Optional terminal runtime for this one seat (pty, or an installed extension such as tmux). Omitted, the serving manager uses its own. An unknown or unreachable runtime, and auto, refuse the launch and start nothing.")},async run(agent,_config,{name,persona,instance,role,agent:agentType,model,variant,launchOptions,cwd,prompt,events,once,deadline,runtime,join:join8}){let onceArg;if(deadline!==void 0&&once!==true)return err2("`deadline` applies only to a once spawn; pass once: true with it.");if(once===true){if(deadline===void 0)onceArg={};else if(deadline.trim()==="-1")onceArg={deadlineMs:-1};else{let ms;try{ms=parseDuration(deadline)}catch(e){return err2(`deadline: ${e.message}, or -1 for no deadline`)}if(!Number.isSafeInteger(ms)||ms<1)return err2(`deadline: "${deadline}" is not a positive duration; pass one such as 30m, or -1 for no deadline`);onceArg={deadlineMs:ms}}}try{const reply=await agent.spawn(name,role,{agent:agentType,model,variant,launchOptions,cwd,prompt,events,runtime,instance,join:join8,persona,...onceArg!==void 0?{once:onceArg}:{}});const pending=reply.code==="uncertain";const submission=reply.data;if(!reply.ok&&submission?.submissionUnknown&&submission.goalId){const goalId=submission.goalId;const next=`cotal_invoke(endpoint="manager", command="goal-result", args={"goalId":${JSON.stringify(goalId)}})`;const message=`Spawn submission for ${name} has an unknown outcome for goal "${goalId}". Acceptance has not been confirmed; the seat may appear later. Do NOT retry: another submission could create a second lifecycle. ${reply.error??"The submission wait ended."} Next: ${next} as this same caller, or inspect 'ps'/'inspect'. A missing result does not prove the submission failed.`;return{text:message,structured:{status:"unknown",name,goalId,next,message}}}if(!reply.ok&&!pending)return err2(`Couldn't spawn ${name}: ${renderLifecycleBlocked(reply.error??"manager refused",reply)}`);const d2=reply.data;const actual=d2?.name??name;const mode=d2?.mode;const who=peerLabel4({name:actual,role});const lead=actual!==name?`"${name}" was taken \u2014 spawning ${who} instead`:`Spawning ${who}`;const pin=d2?.model?` recorded model ${JSON.stringify(d2.model)}`:"";if(d2?.pinAudit){const{requested,error:error51,unreported}=d2.pinAudit;const id=d2.id??d2.actor;const manager=d2.executor?.lifecycleUid??reply.instanceId;const next=`cotal ps --on ${manager}`;const state=pending?"it has not joined the mesh within its readiness window and may still be booting":"it joined the mesh";const audit=unreported?"was not reported by this manager":"could not be audited";const message=`${lead} (id ${id}, manager ${manager}${mode?`, runtime ${mode}`:""}): ${state}, but its model pin ${JSON.stringify(requested)} ${audit} (${error51}). Do not spawn it again: a retry starts a second agent. Next: \`${next}\` shows the seat and the model its manager recorded.`;return{text:message,structured:{status:"partial",name:actual,id,manager,...mode?{runtime:mode}:{},joined:!pending,model:{requested,audited:false,reported:!unreported,error:error51},next,message}}}if(pending)return ok2(`${lead}${pin} (id ${d2?.actor}, manager ${d2?.executor?.lifecycleUid}), but it did not join the mesh within its readiness window. It may still be booting, so do not spawn it again: a retry starts a second agent. Watch cotal_roster for ${actual}, and cotal_despawn it if it never joins.`);const task=d2?.once?` Its task is goal ${JSON.stringify(d2.once.goalId)}, ${d2.once.deadlineAt!==void 0?`with a deadline of ${new Date(d2.once.deadlineAt).toISOString()}`:"with no deadline"}; it is stopped when the task ends. Read the outcome with cotal_invoke(endpoint="manager", command="goal-result", args={"goalId":${JSON.stringify(d2.once.goalId)}}).`:"";const wake=d2?.startupNotice?` It joined, but ${d2.startupNotice}. A message to it waits until someone starts its next turn.`:"";return ok2(spawnResult({requested:name,started:who,renamed:actual!==name,mode,model:d2?.model,join:join8,waitingFor:d2?.waitingFor,once:d2?.once!==void 0})+task+wake)}catch(e){return controlFailure(`Couldn't spawn ${name}`,e)}}},{name:"cotal_feedback",title:"Cotal: send beta feedback",description:"Send feedback about Cotal to its developers. With a configured feedback key it goes to the keyed beta intake; without one it goes to the public cotal.ai intake, which requires a contact email.",schema:{origin:external_exports.enum(["human","agent"]).describe(`"human" when relaying the user's feedback, "agent" when reporting an issue you hit yourself.`),type:external_exports.enum(["bug","idea","friction","praise","other"]).describe("What kind of feedback this is."),summary:external_exports.string().max(300).describe("Required one-line summary, max 300 characters."),details:external_exports.string().max(1e4).optional().describe("Longer free-form details. Do not include secrets."),severity:external_exports.enum(["low","medium","high"]).optional().describe("How badly this hurts (bugs/friction)."),area:external_exports.string().max(120).optional().describe("The part of Cotal this concerns (e.g. presence, channels, CLI)."),repro:external_exports.string().max(1e4).optional().describe("Steps to reproduce."),expected:external_exports.string().max(5e3).optional().describe("What you expected to happen."),actual:external_exports.string().max(5e3).optional().describe("What actually happened."),diagnostics:external_exports.string().max(1e4).optional().describe("Relevant diagnostics as text (logs, errors). Never include secrets."),email:external_exports.string().optional().describe("Contact email, required on the keyless public path when none is configured in the environment.")},async run(_agent,_config,args){const{email:email3,...payload}=args;const contact=config2.feedbackKey?void 0:resolveFeedbackEmail(email3,env);return submitFeedback({...payload,source},{key:config2.feedbackKey,url:config2.feedbackUrl,email:contact})}},{name:"cotal_despawn",title:"Cotal: stop a teammate",description:"Stop a helper when its job is done, or stop yourself by leaving out name. The manager that started you then ends your process. This works only for an agent a manager started; a session someone connected by hand is refused. Graceful by default; pass graceful: false only for a hung agent.",schema:{name:external_exports.string().optional().describe("Name of the peer to stop. Omit to stop yourself (self-despawn)."),instance:external_exports.string().refine(value=>{try{assertLifecycleToken3(value,"instance");return true}catch{return false}},"instance must be a lifecycle token ([a-z0-9]{26,32})").optional().describe("Optional manager instance id for the named peer. Requires `name`. Omitted keeps this session's existing manager selection. A managed user-auth seat must use its own manager. An unresolved pin is refused without fallback."),graceful:external_exports.boolean().optional().describe("Default true: let the session exit cleanly. false = hard kill.")},async run(agent,_config,{name,instance,graceful}){try{const reply=await agent.despawn(name,{graceful,instance});if(!reply.ok){return err2(`Couldn't despawn ${name??"self"}: ${reply.error??"manager refused"}`)}const who=name??"self";return ok2(`Stopping ${who}${graceful===false?" (hard)":""} \u2014 it will leave the roster shortly.`)}catch(e){return controlFailure(`Couldn't despawn ${name??"self"}`,e)}}},{name:"cotal_yield",title:"Cotal: yield a run turn",description:'Report the outcome of a workflow turn assigned to you. Use this only when your context contains a pending run turn; it does not start a workflow or resolve a checkpoint/ask.\n\nUsually finish your session turn normally: that yields `done` automatically. If you cannot progress, call `{"status":"blocked","note":"<what prevents progress>"}`. To hand the assigned turn to another agent, call `{"status":"handoff","to":"<agent-name>","note":"<handoff context>"}`.\n\nWhen you hold several assigned turns, pass `turn` with the exact goal id from the relevant run-turn context block. Without `turn`, the oldest turn already shown to your session is selected. A turn that has not been shown cannot be yielded, and neither can one the run already settled, such as a turn whose deadline elapsed: that refusal names the turn and its deadline. A successful reply confirms the turn was yielded, not that the whole workflow completed; the run\'s coordinator can inspect progress with `cotal_run` status.',schema:{status:external_exports.enum(["done","blocked","handoff"]).describe("done = finished (usually implicit: just end your turn instead); blocked = can't proceed; handoff = another agent should take it."),to:external_exports.string().optional().describe("Required for handoff: the agent name the assigned turn should pass to."),note:external_exports.string().max(4096).optional().describe("Short free-text for the run: what blocked you, or what the next agent should know."),turn:external_exports.string().optional().describe("The turn's goal id, from the \u{1F3AF} block. Omit when you hold only one.")},async run(agent,_config,{status,to,note,turn}){try{const reply=await agent.yieldTurn(status,{to,note,turn});if(!reply.ok)return err2(`Couldn't yield: ${reply.error??"manager refused"}`);return ok2(`Turn yielded (${status}${to?` \u2192 ${to}`:""}) \u2014 the run continues.`)}catch(e){return err2(`Couldn't yield: ${e.message}`)}}},{name:"cotal_run",title:"Cotal: run a workflow program",description:'Use for coordination with several steps, waits on a person, or work that must survive restarts. For one job done by one helper, use cotal_spawn. Use Cotal Lang to program multi-step coordination between agents: sequence work, run tasks in parallel, branch on results, wait for events, and request human decisions. Agents own their reasoning and conversations; the workflow specifies when they act and which outcomes determine the next step.\n\nBefore writing a program, read cotal_docs pages `workflows` and `lang-card`. Hosted execution requires a running execution-capable manager, the `run` capability, and issued caller authority. A managed agent on a user-auth mesh uses its own bearer command and selected participant manager; both its current grant and its direct parent\'s current grant must allow `run`. Open meshes, unsupported local user-mode hosts and execution-free control managers refuse hosted runs. `@cotal-ai/lang` provides validation and simulation separately; those are not verbs of this tool.\n\nSTART: pass `verb: "start"` and the program text in `source`. Example: `{"verb":"start","source":"await sleep(\\"1s\\", { name: \\"first-run\\" });"}`. Optional `file` labels diagnostics only; it reads nothing from disk. The manager validates before recording the run and returns a runId. Acceptance is not completion.\n\nINSPECT: use `verb: "status"` with that `runId` for state and step journal, or `verb: "ps"` to list runs. Both are read-only. Report completion only after observing state `completed`; surface failures or unresolved steps.\n\nANSWER: first inspect status, then pass `verb: "answer"`, `runId`, the exact open `stepKey`, and, when requested, `value` matching the answer shape. An ask requires its requested record; a checkpoint can resolve without a value. `artifact` may name the evidence reviewed. Answer only with authority to make that decision; never invent an approval.\n\nRESUME: pass `verb: "resume"` and `runId` to continue a run from its recorded source. A held run appears as `released` in status. Do not start a duplicate run to continue it or resume one the manager is already driving.\n\nRuns continue independently of your session and can recover after a manager restart. Their channel effects are bounded by the starting credential\'s issued channel scope. To report that your assigned agent turn is blocked or handed off, use `cotal_yield` instead. Pass `instance` for the exact manager when an unbound user-auth caller has several managers; a failed pin does not fall back.',schema:{verb:external_exports.enum(["start","status","ps","answer","resume"]).describe("start = validate and drive a new program; status = one run's record + journal; ps = list runs; answer = resolve an open checkpoint/ask; resume = take a released or held run over."),source:external_exports.string().min(1).optional().describe("start only: the cotal-lang program source, inline. Required for start."),file:external_exports.string().min(1).optional().describe("start only: a file name to attribute the source to in error messages. Diagnostic only; nothing is read from disk."),timeout:external_exports.string().min(1).optional().describe("start/resume: the default checkpoint timeout for the drive, as a duration (e.g. `1h`, `30m`). Default 1h."),runId:external_exports.string().min(1).optional().describe("Required for status, answer and resume: the run id (`run-<32 hex>`) returned by start or ps."),stepKey:external_exports.string().min(1).optional().describe("Required for answer: copy the exact open step key from status, e.g. `/checkpoint:approve#0`."),value:external_exports.unknown().optional().describe("answer only: supply the value requested by the open checkpoint or ask and match its answer shape. A checkpoint may resolve without a value; an ask must receive its requested record. Use null only when that is the intended answer."),artifact:external_exports.string().min(1).optional().describe("answer only: a reference to what you reviewed before answering, recorded beside the answer."),endpoint:external_exports.string().min(1).optional().describe("status/ps/answer: the endpoint the run record lives under. Omit for runs the manager hosts."),page:external_exports.strictObject({limit:external_exports.number().int().min(1).max(16).optional(),cursor:external_exports.string().min(1).max(3072).regex(/^[A-Za-z0-9_-]+$/).optional()}).optional().describe("ps only: one bounded diagnostic JSON page, default 8 rows. Pin the manager with instance unless this session is already bound. Continuation is not snapshot, absence or ownership proof. A manager from release 0.88.0 or earlier refuses `page`."),instance:managerInstanceArg},async run(agent,config3,a){const need=(field,verb)=>a[field]===void 0?err2(`cotal_run ${verb}: \`${String(field)}\` is required`):void 0;try{if(a.page!==void 0&&a.verb!=="ps")return err2("cotal_run: page is supported only for ps");if(a.page!==void 0&&a.instance===void 0&&config3.managerInstanceId===void 0)return err2("cotal_run ps: diagnostic pages require an explicit instance or a bound manager");if(a.verb==="start"){const missing2=need("source","start");if(missing2)return missing2;const reply2=await agent.run("start",{source:a.source,file:a.file,timeout:a.timeout},a.instance);if(!reply2.ok)return err2(renderRunRefusal("start",reply2));const{runId}=reply2.data;return ok2(`Started run ${runId} on the manager. It runs there until it completes or is held; cotal_run(verb="status", runId="${runId}"${a.instance?`, instance="${a.instance}"`:""}) follows its steps, and an open checkpoint is answered with verb="answer"${a.instance?` on instance="${a.instance}"`:""}.`)}if(a.verb==="resume"){const missing2=need("runId","resume");if(missing2)return missing2;const reply2=await agent.run("resume",{runId:a.runId,timeout:a.timeout},a.instance);if(!reply2.ok)return err2(renderRunRefusal("resume",reply2));return ok2(`Resumed run ${a.runId} on the manager from its recorded program.${a.instance?` Use instance="${a.instance}" for subsequent status and answer calls to this manager.`:""}`)}if(a.verb==="ps"){const reply2=await agent.run("ps",{endpoint:a.endpoint,...a.page!==void 0?{page:a.page}:{}},a.instance);if(!reply2.ok)return err2(renderRunRefusal("ps",reply2));if(a.page!==void 0){const page=reply2.data;if(page===null||typeof page!=="object"||Array.isArray(page)||page.semantics!=="diagnostic")return err2("the manager did not return a diagnostic inventory page");const text=JSON.stringify(page);if(a.page.cursor!==void 0&&page.nextCursor===a.page.cursor)return err2(`Diagnostic inventory made no progress; retain this incomplete observation, do not retry in a loop: ${text}`);return ok2(text)}const rows=reply2.data;if(rows.length===0)return ok2("No workflow runs are recorded in this space.");return ok2(rows.map(r=>`${r.runId} ${r.endpoint} ${r.state??"(no status)"} holder=${r.holder??"-"} journal=${r.journalHigh??"-"}${r.forkedFrom?` forked-from=${r.forkedFrom.run}@${r.forkedFrom.step}`:""}`).join("\n"))}if(a.verb==="status"){const missing2=need("runId","status");if(missing2)return missing2;const reply2=await agent.run("status",{runId:a.runId,endpoint:a.endpoint},a.instance);if(!reply2.ok)return err2(renderRunRefusal("status",reply2));const v2=reply2.data;const head=`run ${v2.runId} on ${v2.endpoint}: ${v2.status?`${v2.status.state}, holder ${v2.status.holder}, epoch ${v2.status.epoch}`:"(no status)"}`;const lines=v2.journal.map(r=>r.kind==="activation"?`#${r.n} activation holder=${r.holder} epoch=${r.epoch} replayedTo=${r.replayedTo}`:`#${r.n} step ${r.step} ${r.outcome}${r.asks!==void 0?`
118
118
  asks: ${r.asks}${r.addressee!==void 0?` (escalates to ${r.addressee})`:""}`:""}`);return ok2([head,...lines.length?lines:["(no journal records: never started, or retired)"]].join("\n"))}const missing=need("runId","answer")??need("stepKey","answer");if(missing)return missing;const reply=await agent.run("answer",{runId:a.runId,stepKey:a.stepKey,value:a.value,artifact:a.artifact,endpoint:a.endpoint},a.instance);if(!reply.ok)return err2(renderRunRefusal("answer",reply));return ok2(`Answered ${a.stepKey} on run ${a.runId} as ${config3.name}: ${JSON.stringify(reply.data)}`)}catch(e){return runFailure(`cotal_run ${a.verb}`,e)}}},{name:"cotal_persona",title:"Cotal: define a persona",description:'Save a persona that cotal_spawn can start by name. Most jobs need a persona written for them. For one job, pass persona to cotal_spawn instead, and save one here only when it is worth reusing. Reuse one from cotal_personas only when it really fits, such as a general reviewer. Every persona you save stays in the user\'s workspace after the helper stops. No cotal_* tool removes one: remove one you own with cotal_invoke, endpoint `manager`, command `remove-persona`, args `{ name }`; the operator removes any with `cotal persona remove <name>`. Name it after what it does, such as review-login-page. Write the prompt about the job: what to do, where the brief is, how to report, and when to stop. Point to sources for facts rather than stating them. Set role when others should reach it through a role. List its channels and give it only what the job needs: subscribe for where it starts, allowSubscribe for what it may read, and allowPublish for what it may post to. If you list subscribe alone, it may read just those channels and can\'t post anywhere. Leave all three out and it can read and post nowhere, so list the channels it needs. A persona you pass to cotal_spawn differs here: with no channel field it takes your own read and post grants. To let its agent spawn others or run workflows, list spawn or run in capabilities. You can give only capabilities you hold, and each later spawn of the persona is checked again against its spawner. Only you or an operator can change a persona you saved.\n\nBefore you write one, check what you can give. cotal_orientation shows your own channels and capabilities, and cotal_channels lists the channels in the space. cotal_endpoints lists the endpoints you can call, and cotal_describe shows what one lets a caller do. The agent-files page in cotal_docs lists every persona field.\n\nExample:\n\n```\n{\n name: "review-login-page",\n role: "reviewer",\n subscribe: ["review.login-page"],\n allowPublish: ["review.login-page"],\n prompt: "You review the login page change in PR 812. The brief is on #review.login-page. Check the session timeout and the error messages against docs/auth.md. Post each finding there with its file and line. When you are done, post a one-line verdict and despawn yourself."\n}\n```',schema:{name:external_exports.string().regex(/^[A-Za-z0-9_-]+$/,"letters, digits, _ or - only").describe("Unique name for the persona (also the spawn name): letters, digits, _ or -."),instance:managerInstanceArg,prompt:external_exports.string().max(1e4).describe("The persona: an appended system prompt describing who this agent is. A complete agent file (leading --- frontmatter with subscribe / allowSubscribe / allowPublish) is merged, not wrapped."),model:external_exports.string().max(120).optional().describe("Optional model override (e.g. opus, sonnet). Wins over a model: in the prompt's frontmatter."),role:external_exports.string().max(120).optional().describe("Optional role written into the persona file (e.g. reviewer). Wins over a role: in the prompt's frontmatter."),agent:external_exports.string().max(120).optional().describe("Optional harness pin written into the persona file (e.g. jcode). Wins over an agent: in the prompt's frontmatter."),subscribe:external_exports.array(external_exports.string()).optional().describe("Optional active read set written into the persona file. Wins over subscribe: in the prompt's frontmatter."),allowSubscribe:external_exports.array(external_exports.string()).optional().describe("Optional read ACL written into the persona file. Wins over allowSubscribe: in the prompt's frontmatter."),allowPublish:external_exports.array(external_exports.string()).optional().describe("Optional post ACL written into the persona file. Wins over allowPublish: in the prompt's frontmatter."),capabilities:external_exports.array(external_exports.string()).optional().describe("Optional capabilities written into the persona file, such as spawn or run. Each must be one you hold; the manager refuses anything more and writes nothing. A redefine that omits it keeps the saved list, which is checked the same way; pass [] to clear it. Capabilities in the prompt's frontmatter are dropped."),announce:external_exports.string().optional().describe("Optional channel to post a one-line note on once the persona is saved. Omit it to keep the definition private to the manager's persona catalog. Name the channel your team is actually working on, not `general`: a peer that did not ask for this persona has no way to judge whether spawning it is wanted, and a broadcast soliciting spawns from an unfamiliar principal gives peers no reason to trust the request. Your post ACL applies as it does to any other message.")},async run(agent,_config,{name,prompt,instance,model,role,agent:agentType,subscribe,allowSubscribe,allowPublish,capabilities,announce}){try{const reply=await agent.definePersona({name,prompt,instance,model,role,agent:agentType,subscribe,allowSubscribe,allowPublish,capabilities,announce});if(reply.definitionOutcome==="unknown"){const readback=`cotal_personas(name="${name}"${instance===void 0?"":`, instance="${instance}"`})`;const message=`The definition outcome for persona \`${name}\` is unknown: ${reply.error??"the manager reply was not observed"}. The file may already have been written or may still be written. Do not re-run this definition or spawn it on this result. Read back with ${readback} on the same manager before acting. A missing readback alone does not prove the write will not land.`;return{text:message,structured:{status:"unknown",name,...instance===void 0?{}:{instance},next:readback,message}}}if(!reply.ok)return err2(`Couldn't define ${name}: ${reply.error??"manager refused"}`);const spawnHint=`spawn it with cotal_spawn(name="${name}"${instance===void 0?"":`, instance="${instance}"`}) to bring it online`;if(reply.announceError&&reply.announceOutcome==="denied")return ok2(`Persona \`${name}\` saved \u2014 but the announcement to #${announce} was REFUSED and did not go out: ${reply.announceError}. The persona is on disk; do not re-run this call. Check your \`allowPublish\` for #${announce}, then post it yourself if you still want to. You can ${spawnHint}.`);if(reply.announceError)return ok2(`Persona \`${name}\` saved \u2014 but I could NOT CONFIRM the announcement to #${announce}: ${reply.announceError}. It may or may not have been delivered. The persona is on disk; do not re-run this call, and READ #${announce} before posting anything yourself \u2014 posting blind is how the channel gets it twice. You can ${spawnHint}.`);return ok2(`Persona \`${name}\` saved${announce?` and announced on #${announce}`:""} \u2014 ${spawnHint}.`)}catch(e){const detail=e?.message??String(e);if(detail.startsWith("announce:"))return err2(`Couldn't define ${name}: ${detail}. Nothing was written.`);return controlFailure(`Couldn't define ${name}`,e)}}},{name:"cotal_personas",title:"Cotal: list or show personas",description:"Read the workspace persona catalog the manager owns (.cotal/agents). Omit `name` to list spawnable persona names (role, model, and a one-line description when you own the file). Pass `name` to show one card you own, including the persona body. Same ownership as cotal_persona: a file you do not own lists as a name only, while unauthorized, unknown, and unparseable shows are all not-found. Use this to see whether a name is taken before cotal_persona, or what a teammate's persona says, without shelling out. Pass `instance` to read one manager's catalog when the owner has several managers.",schema:{name:external_exports.string().regex(/^[A-Za-z0-9_-]+$/,"letters, digits, _ or - only").optional().describe("Persona to show. Omit to list the catalog."),instance:managerInstanceArg},async run(agent,_config,{name,instance}){try{if(name){const reply2=await agent.showPersona(name,instance);if(!reply2.ok)return err2(`Couldn't show ${name}: ${reply2.error??"manager refused"}`);const row=reply2.data??{};if(row.error)return err2(`Persona \`${name}\` is unparseable: ${row.error}`);const meta3=[row.role&&`role=${row.role}`,row.model&&`model=${row.model}`,row.owner&&`owner=${row.owner}`].filter(Boolean).join(" ");const lines2=[`Persona \`${row.name??name}\`${meta3?` ${meta3}`:""}`];if(row.description)lines2.push(row.description);if(row.persona)lines2.push("",row.persona);return ok2(lines2.join("\n"))}const reply=await agent.listPersonas(instance);if(!reply.ok)return err2(`Couldn't list personas: ${reply.error??"manager refused"}`);const personas=reply.data?.personas??[];if(!personas.length)return ok2("No personas in the manager catalog.");const lines=personas.map(p=>{if(p.error)return`${p.name} \u2A2F unparseable`;const meta3=[p.role,p.model&&`model=${p.model}`,p.owner&&`owner=${p.owner}`].filter(Boolean).join(" ");const head=meta3?`${p.name} ${meta3}`:p.name;return p.description?`${head}
119
119
  ${p.description}`:head});return ok2(`Personas in the manager catalog (${personas.length}):
120
120
  ${lines.join("\n")}`)}catch(e){return controlFailure(name?`Couldn't show ${name}`:"Couldn't list personas",e)}}},{name:"cotal_endpoints",title:"Cotal: list the endpoints you can call",description:"List the endpoints registered in this space that this session can call, and for each one the commands its grants cover and the request forms they allow. The space's registry answers from the grants recorded when this session's credential was issued, so the broker or the endpoint can still refuse a listed command. Endpoints where this session holds no command are left out, and so are endpoints whose command declarations cannot be read. A command whose grants are too many to list form by form is named under `unprojected`. On a user-auth mesh manager commands ride a separate manager-call credential; pass view=\"manager\" to list what that credential can call. Call cotal_describe for a command's input schema. A page holds up to 100 endpoints; pass the previous page's `next` as `after` for the next one.",schema:{after:external_exports.string().min(1).max(128).optional().describe("The `next` value from the previous page."),limit:external_exports.number().int().min(1).max(REGISTRY_PAGE_LIMIT).optional().describe(`Endpoints per page (default ${REGISTRY_PAGE_LIMIT}).`),view:external_exports.enum(["session","manager"]).optional().describe("`session` (default): this session's own credential. `manager`: its manager-call credential."),instance:external_exports.string().min(1).max(64).optional().describe("Manager view only: the manager instance whose call credential to use.")},async run(agent,_config,{after,limit,view,instance}){if(instance!==void 0&&view!=="manager")return err2('`instance` selects the manager for view="manager" only.');const label=view==="manager"?"the manager-call credential":"this session";try{const input={...after!==void 0?{after}:{},...limit!==void 0?{limit}:{}};const r=view==="manager"?await agent.listManagerEndpoints(input,instance):await agent.ep.listEndpoints(input);if("none"in r)return err2(`There is no manager view: ${r.none}.`);if(r.unbound)return err2(`The credential of ${label} has no listing binding, so the registry cannot list what it may call. A credential issued before the listing existed, or one with no expiry, has none; a new credential does.`);if(r.reply.reply.ok!==true){const e=r.reply.reply.error;return err2(`The registry refused the listing: ${e?.code??"error"}: ${e?.message??"no message"}`)}const page=r.page;const more=page.next!==void 0?` More endpoints follow; pass after="${page.next}".`:"";return endpointData(`${page.rows.length} endpoints ${label} can call (source: ${page.source}).${more}`,page)}catch(e){if(e instanceof EpEnvelopeError3&&e.details?.some(d2=>d2.kind===EP_UNANSWERED2))return err2("The registry did not answer, so nothing is listed. The space may run no registry, or it is down; other tools are unaffected.");return endpointFailure("Couldn't list endpoints",e)}}},{name:"cotal_describe",title:"Cotal: describe an endpoint",description:"List the commands a registered endpoint serves, as this session's credential sees them: each command's capability, whether it is targeted, and its input schema. The surface comes from the endpoint's describe reply and the content-addressed contract store, digest-verified, never from the endpoint's own claims. Read it before cotal_invoke.",schema:{endpoint:external_exports.string().min(1).max(200).describe("The endpoint name, e.g. com.example.orders."),refresh:external_exports.boolean().optional().describe("Resolve again instead of using this session's cached surface.")},async run(agent,config3,{endpoint,refresh}){try{const instanceId=endpoint==="manager"&&!isAuthed(config3)?config3.managerInstanceId:void 0;const svc=await agent.ep.describeService(endpoint,{refresh,...instanceId!==void 0?{instanceId}:{}});const commands=[...svc.commands.values()].sort((a,b2)=>a.command.localeCompare(b2.command)).map(c=>({command:c.command,capability:c.capability,class:c.class,targeted:c.targeted,...c.targeted?{modes:c.modes}:{},input:c.contract.input.validate.schema,inputDigest:c.contract.input.closureDigest}));return endpointData(`${svc.endpoint}: owner ${svc.owner}, instance ${svc.responder.instanceId}, epoch ${svc.responder.epoch}, ${commands.length} commands.`,commands)}catch(e){return endpointFailure(`Couldn't describe ${endpoint}`,e)}}},{name:"cotal_invoke",title:"Cotal: invoke an endpoint command",description:"Call one command on a registered endpoint with JSON arguments, over this session's own connection and grants. The arguments are checked against the command's digest-verified input schema before anything is sent, and the reply against its output schema. A failure reports its code and outcome: `not-executed` means the command did not run; `unknown` means it may have. Do not repeat a call whose outcome is unknown without checking first.",schema:{endpoint:external_exports.string().min(1).max(200).describe("The endpoint name, e.g. com.example.orders."),command:external_exports.string().min(1).max(128).describe("The command name from cotal_describe."),args:external_exports.record(external_exports.string(),external_exports.unknown()).optional().describe("The command's arguments as a JSON object."),self:external_exports.boolean().optional().describe("Targeted commands only: act on this session itself."),timeoutMs:external_exports.number().int().min(1).max(12e4).optional().describe("Reply deadline in milliseconds (default 30000).")},async run(agent,config3,{endpoint,command,args,self,timeoutMs}){try{const instanceId=endpoint==="manager"&&self&&!isAuthed(config3)?config3.managerInstanceId:void 0;const r=await agent.ep.invokeService(endpoint,command,args,{deadlineMs:timeoutMs??3e4,...self?{target:{mode:"self"}}:{},...instanceId!==void 0?{instanceId}:{}});if(r.reply.ok!==true){const e=r.reply.error;const details=e?.details?.length?JSON.stringify(e.details):"";const message=e?.message??"no message";const head=`${endpoint}.${command} failed: ${e?.code??"error"}${e?.outcome?` (outcome ${e.outcome})`:""}: `;if(head.length+message.length>ENDPOINT_RESULT_MAX_CHARS)return err2(`${head}the error message is ${message.length} characters, over this tool's ${ENDPOINT_RESULT_MAX_CHARS}-character limit, and was withheld.`);if(head.length+message.length+details.length+40>ENDPOINT_RESULT_MAX_CHARS)return err2(`${head}${message}