Embedding package exports

Workspace registry livenessCopy Anchor Link

@cotal-ai/workspace exports pruneStaleMeshes() for a liveness sweep. It keeps every registration and returns a MeshSweep containing only offline: string[]; catalog entries are not probed. The former always-empty pruned field is removed.

Call pruneMesh(space) only after a credentials, mode, or on-disk space mismatch. It removes an up or pre-origin record and returns whether it was removed. Manual and catalog records stay registered. The reason argument and PruneReason type are removed. Callers that passed "gone" must report the target offline without calling pruneMesh; callers that passed "mismatch" omit the argument.

Node connection signingCopy Anchor Link

Node endpoints and standaloneConnectOpts sign NATS authentication challenges with the existing native Ed25519 signer. Credentials are read on every connection attempt, including reconnects, and the temporary signer is cleared after each callback. JWT, public-key and signature fields use the NATS authenticator contract. Browser connections keep the NATS JavaScript implementation.

User credential authorityCopy Anchor Link

AuthProvider.userCredentials returns the bearer and sentinel credential. A provider may also return authority, containing the owner and the current scope, allowSubscribe, allowPublish and dmHistory grant that its issuer authorized for that mint. The stock provider returns this from the exchange response on local and remote user-auth spaces. It does not decode the bearer to reconstruct access.

The field is optional for provider compatibility. Its absence means the caller has no authoritative grant answer. A status surface must preserve unknown or unavailable instead of inferring broad access from a bearer, successful exchange or broker ping.

Login confirmationCopy Anchor Link

AuthProvider.confirmLogin asks the space's IdP whether this machine's cached login still holds. It mints nothing. It answers confirmed, signed-out when no login is cached, or rejected when the IdP refused the cached one, and throws on any other failure. cotal manager start and restart call it on a user-auth space before they save or launch anything, cotal up before it starts the manager, and a team boot that resumes a stopped stack before any write. Each refuses the manager UNSUPPORTED when the provider does not implement it.

Compiled service contractsCopy Anchor Link

serviceContractTable(rows) returns a frozen contracts table. Each command's input/output pair compiles on first access, is frozen, and is reused on later reads. Listing command names does not compile validators. Callers cannot replace a command or swap its compiled input/output contracts. artifactValues() still returns the schema roots and closure manifests used at registration.

Package entry pointsCopy Anchor Link

Everything below is a real export of a published package, reachable from the package root (each package publishes . via dist/index.{js,d.ts} and ships files: ["dist"]). @cotal-ai/connector-claude-code also publishes ./mcp, which hosts managed Claude Code sessions in one process (Connect Claude). @cotal-ai/core also publishes ./browser-control and ./browser-validators-build (Browser control). Type-only names are marked; import them with import type.

Endpoint presence metadataCopy Anchor Link

CotalEndpoint accepts environment as an explicit presence label. Pass null to omit the label without reading COTAL_ENVIRONMENT. Omitting the option preserves the process environment default.

Shared connector sessions report card.meta.host and card.meta.cwd from the connector process when the session is constructed. They override agent-file values and are advisory display data. The directory is a startup snapshot, not a model harness's later shell directory. Neither field changes routing or access, and the connector reads no command-line arguments or environment dump for these values. A connector whose process can host several sessions passes { withholdProcessCwd: true } as MeshAgent's third argument and reports each session's directory with setCwd (CotalEndpoint.setCardCwd) once the harness supplies it; until then the field is absent. The reported path is kept byte for byte, whitespace included; an empty string leaves it unchanged. Claude Code sessions do this from their SessionStart hook.

Daemon APIsCopy Anchor Link

Daemon runners and lifecycle

Manager APIsCopy Anchor Link

remoteManagerServePrincipal(owner, instanceId) from @cotal-ai/core derives the manager's serve actor and serializes it through principalKey, validating both tokens. Use it when a host derives the serve principal from an instance id. APIs that already receive a serve actor serialize that supplied actor with principalKey(owner, serveActor).key.

Pooled renewal authorityCopy Anchor Link

The remote manager authority parser accepts renewStandingBundle and renewRunDriver only with an assigned account nkey, the current manager process epoch, and a host-authenticated registration proof. A run renewal also names its active holder, takeover, epoch, fencing token, and the two existing nkeys. The host must fresh-check those coordinates against its registration gate and run journal before issuing server-selected profiles. A host without that renewal authorization refuses the request. Until the host issuer wires the operations and validates them on real connections, the presence of these types is not an operational pooled renewal guarantee.

Execution-free controlCopy Anchor Link

An execution-free control Manager retains native registration, goal recovery, session-ledger, renewal and maintenance duties. Its status reports execution: "none", runtime: "none", custody: "none", no children or connectors, and false classSpawn, runHosting and terminalSessions. Local NONE uses this existing status schema without a new wire field. Execution is recorded per instance. An incompatible record, retained seat/turn inventory or an older unclassified instance refuses boot before recovery. NONE refuses caller-driven writes, including persona definition, purge, transcript transfer, preservation and resume, and resolves no model adapter. It starts no transcript receiver or sweep. Autonomous registration, lease, renewal, session-ledger and goal maintenance still write their native control state.

Select the genuine participant Manager with a host-issued, instance-pinned manager-caller view for workflow and terminal operations. That Manager retains the children, workflow journal and terminal sessions. The control instance neither adopts roster peers nor proxies user runs. Missing participant selection or authority refuses. This capability adds no application routing.

Local control admissionCopy Anchor Link

For a genuine local control instance, pass execution: "none" without pooled, remoteAuthority or runtime. Startup requires that space's local signing trust, provider pin and user-mode mesh record. It keeps the native persisted local instance and serve identity; local-primary selection uses the existing gate. An existing unclassified identity, including a preclaimed identity with no execution record, is refused. A NONE record cannot restart as runtime. Retained seat or turn inventory refuses before recovery. Do not remove identity or capability files to change modes.

The public cotal supervise --execution none --space <space> composition supports the same local mode. It validates arguments before connector seeding, resolves no Runtime, and rejects startup workload flags and participant registrations. Omitted execution keeps the ordinary PTY behavior. This does not opt an auth service into local-primary, change scopes or broaden native ps.

Manager execution modesCopy Anchor Link

Runtime remains the default, but local startup now claims its native identity and execution record during admission, before later authentication and registration checks. A failed start can leave those files classified as runtime. Malformed identity or capability files also refuse earlier. These lifecycle timing changes do not change the instance's identity format or authority.

With renewStandingBundle configured, the manager renews all five standing credentials together. It checks every returned credential for the held nkey and assigned account, test-connects each one, and adopts them only if the serve epoch has not moved. A refused or failed candidate leaves the current credentials in place and records the refusal as cleanup debt until a later renewal succeeds. On shutdown, after the standing context is drained, an expired maintenance executor is renewed through the existing scoped host operation so deregistration can finish without restarting duties.

Issued-authority references, source coordinates and stores accept nonempty space tokens in [A-Za-z0-9_-], including underscores. These boundaries reject input that would be rewritten by the subject-token sanitizer. Endpoint names still use the separate DNS-label grammar.

Provisioning APIsCopy Anchor Link

Provisioning and minting (all @cotal-ai/core)

Authentication APIsCopy Anchor Link

Auth building blocks (all @cotal-ai/auth)

startAuthCallout processes up to 32 connections concurrently. Its hooks must support overlapping calls for different connections. A slow authority check or recorder occupies one slot; other connections can still authenticate. Each response waits for that connection's authority checks, durable issuance and final expiry check. Work beyond the bound waits and can still reach the broker's authorization deadline. The returned done waits for admitted hooks when the subscription ends and rejects an unexpected worker failure after those hooks settle.

Composition APIsCopy Anchor Link

Seams and the wire (all @cotal-ai/core unless noted)

For a Linux Unix-socket adapter, peerCredentials(socket) from @cotal-ai/seat returns kernel-observed peer pid, uid and gid. Compare these against the host's authorization policy; request-supplied identity and process liveness do not replace that policy or a lifecycle fence. The helper starts no custodian and refuses unsupported platforms or a missing native helper.

The runners take a CLI-shaped ParsedArgs, not a typed options object, so a host fabricates one:

const args: ParsedArgs = { values: { space, server, port: "0" }, positionals: [], raw: [] };

Long-lived endpoint credentialsCopy Anchor Link

EndpointOptions.bearer accepts either a string or a function, and the difference is not stylistic. A string is minted once, so when it expires (which it will: callout bearers live minutes) the endpoint has nothing to renew with. It will not present the dead token to the broker, since that is a guaranteed denial that still costs a full auth-callout round trip. It refuses to reconnect, emits warning saying which case it is in, and retries on a widening backoff until the process re-authenticates and rebuilds it. Retry notices use warning rather than error because Node rethrows an unhandled error event and would kill a host the endpoint is still trying to recover.

When the broker refuses a bearer at connect, the warning says the broker refused this endpoint's bearer and that the auth service logs why, because nats-server passes the client no reason. The endpoint then retries on its capped backoff. Each wait is a random point in the upper half of its step, so endpoints refused together, after a broker restart or by an auth limit, do not retry together. A bearer source that throws an error with a numeric retryAfterSeconds is called again when those seconds have passed, not before, and a reconnect inside that wait dials on the bearer it holds. The auth provider's rate-limited exchange throws that way, and agentBearerCommand prints retry-after <seconds> for it.

Pass a function for anything that outlives one bearer. That is a renewal source: it is called ahead of each expiry and again whenever a reconnect finds the cached bearer dead, and it requires explicit card.owner and card.actor. The first-party surfaces already do this (UserViewAuth.source, the connector's agentBearerCommand). A string bearer is for a short one-shot connection.

A MeshAgent a host runs in its own process takes the same kind of source. Pass userAuth.bearer, a function returning a fresh bearer, instead of userAuth.bearerCmd, the argv a launched seat execs. Such an agent has no manager-call bearer, so its spawn, despawn, persona and run calls return a refusal without reaching a manager.

Endpoint event handlingCopy Anchor Link

Long-lived hosts must also subscribe to the endpoint's warning event. It carries conditions the endpoint is surviving, including failed credential renewal, reconnect retries, its own DM inbox missing from the broker while the connection is up, a durable leave it keeps retrying after the broker refuses a durable channel's live subscription, and a channel registry entry that does not decode to a valid config, such as a raw put of an unknown delivery class or of null on the defaults key. The endpoint drops that entry from its cache and applies the default policy until a valid entry is written. The DM inbox warning comes once, after the broker has reported the inbox missing twice. The endpoint does not recreate the inbox. It keeps checking and receives again if its provisioner creates the inbox again. A host may choose to ignore warnings for a one-shot endpoint whose awaited operation owns the verdict, but that choice should be explicit. An unhandled warning is nonfatal and silent.

The error event carries a fault the endpoint cannot return from a call, such as a refused subscription or a refused publish that no request was waiting on. Attach a listener before start(), since Node throws on an unhandled error. A denial the broker returns to a request, such as an observer's read of the DM stream, reaches only that call, which decides what it means, and is not emitted again as an error.

Native transport livenessCopy Anchor Link

CotalEndpoint accepts transportPingIntervalMs and transportMaxPingOut together as positive safe integers. Omission uses a 10-second interval and two outstanding pings. Connector seats and CLI endpoints use these defaults, including loopback proxy connections. A silent link normally disconnects within about 30 seconds, subject to scheduling. The delivery daemon retains its 2.5-second override. Native PING/PONG uses the resident socket without another authenticated probe connection. A stale connection emits a transport disconnect before reconnect attempts. The delivery daemon's connection handling explains how that event affects the service. The option validation and NATS mapping are in endpoint.ts.

transportConnectTimeoutMs is a positive integer bounding the first connection attempt. Omission keeps the transport's 20-second default. Transport liveness does not prove endpoint readiness, presence health, or a send outcome.

Finite KV scansCopy Anchor Link

liveKvEntries(kv, options?) and liveKvEntries(kv, filter, options?) read one finite scan of live entries. A { signal } argument can appear second or after a key filter. The filter may be a string, an array of strings, or undefined. liveKvValues(kv, decode, options?) and liveKvValues(kv, decode, filter, options?) provide the same forms with decoded results. Passing options in both slots is a TypeScript error and rejects with TypeError at runtime before scanning. Combine the signal and callbacks into one options object. An interrupted scan throws IncompleteKvScan. Cancellation throws the signal's reason, including during a bind to an empty bucket. The ordered consumer's pending count distinguishes an empty completed scan from an interrupted read. Completion requires a zero pending count at bind or a delivered message reporting zero pending. Successful empty and nonempty results await cleanup before returning. Cancellation still wins while cleanup is pending, before a result returns.

Cleanup deletes only the scan's owned consumers, including consumers nats.js rebuilt from them. It waits for broker replies to every create sent by those rebuilds. A confirmed not-found delete counts as gone. A refused delete leaves the consumer to broker inactivity expiry, which also covers a crash. Other delete failures are thrown. A not-found delete also fails when the broker never answered that consumer's create before a timeout or closed connection.

A cleanup error replaces only an otherwise successful result. The scan's own error, cancellation reason, or IncompleteKvScan takes precedence.

Related contractsCopy Anchor Link

Runtime executionCopy Anchor Link

Manager execution mode determines whether a host can launch agents and workflows. See the detailed contract.