@qqbrowser/qbot-dsh 0.0.5 → 0.0.6

package/node_modules/@qqbrowser/qbot-dsh-tool-cordis/lib/index.js

@@ -16,7 +16,7 @@ Only valid while the agent has produced nothing: swapping tools mid conversation
 
 The swap is a parent re-link, not an unmount: standing mounts are shared and permanent, so the old composition stays for its other agents and the new one is ensured BEFORE the link moves. An unknown or unusable preset therefore throws with the agent exactly as it was — there is no torn-down state to restore. The re-link runs through the binding this roster kept from the agent's mount — dsh-scope's only re-link authority. An agent that never composed one has nothing to re-link: the switch is then the agent's first bind, exactly a mount.`,parameters:[{name:"agentCtx",description:"the agent's scope context."},{name:"id",description:"the preset to compose the agent from instead."}],returns:"the preset now installed.",throws:["when the preset is unknown or its composition is unusable."]},{signature:"async standingKeyFor(id?: string): Promise<ScopeKey>",description:`The standing scope key of one preset, for a host reader with no agent.
 
-A cold transcript read resolves tool presenters against the composition the session recorded, and the standing mount makes that possible without resuming anything: ensuring the mount composes plugins but starts no agent, no session, and no turn.`,parameters:[{name:"id",description:"the preset id, or `undefined` for {@link defaultId}."}],returns:"the standing scope key readers pass as a registry view scope.",throws:["when the preset is unknown or its composition is unusable."]}]},{key:"agents",summary:"Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain.",description:"Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@qqbrowser/qbot-dsh-agent-loop`), registered via setFactory.\n\nInitiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.",methods:[{signature:"currentInitiator(): Agent | undefined",description:"Read the Agent that initiated the inherited asynchronous driver chain. Use this optional form for logging, tracing, metrics, or host attribution that also supports agentless calls. When a parent creates a child, setup reports the causal parent while `agentCtx.agent` identifies the child.",parameters:[],returns:"the inherited Agent, or `undefined` outside an initiator boundary and inside an explicit clearing boundary.",throws:["when this service instance has been disposed."]},{signature:"requireInitiator(): Agent",description:"Read the initiating Agent and fail when no initiator boundary is active. Use this for private helpers contractually below a driver, or for a deployment-owned outbound request whose contract forbids agentless calls. Generic or direct-call paths use optional lookup or explicit request fields.",parameters:[],returns:"the inherited Agent.",throws:["when no initiator is active or this service instance has been disposed."]},{signature:"withInitiator<T>(agent: Agent, operation: () => T): T",description:"Run an operation with one exact Agent as its process-local initiator. The exact synchronous value or Promise returned by the operation is preserved. Custom drivers and test harnesses wrap their complete returned foreground lifetime. A queue or wire receiver may establish this boundary only after validating explicit identity and resolving the exact live Agent; this method does neither. Detached work remains owned by the subsystem that starts it.",parameters:[{name:"agent",description:"initiating Agent to inherit; presence is neither liveness proof nor authorization."},{name:"operation",description:"synchronous or asynchronous operation to invoke."}],returns:"the exact value returned by `operation`.",throws:["when the initiator scope is closing/disposed, or when `operation` throws."]},{signature:"withoutInitiator<T>(operation: () => T): T",description:"Run an operation inside a boundary that hides any inherited initiating Agent. The exact synchronous value or Promise is preserved. Use this while creating lazy shared timers, queue pumps, pool maintenance, watchers, or exporters so they do not inherit the first Agent that happens to initialize them. It clears only initiator attribution, not explicit fields, and does not own or drain detached resources.",parameters:[{name:"operation",description:"synchronous or asynchronous operation to invoke without an initiator."}],returns:"the exact value returned by `operation`.",throws:["when the initiator scope is closing/disposed, or when `operation` throws."]},{signature:"setFactory(factory: AgentFactory): () => void",description:"Register the agent-creation factory (the loop calls this on construction, effect-scoped). A traced Cordis service is canonicalized to its concrete target; each create/resume call is then traced through that caller's context so ownership follows the caller without stacking proxy layers. Throws if a factory is already registered. Returns the disposer; on dispose the factory slot is cleared.",parameters:[{name:"factory",description:"the loop-owned factory {@link create}/{@link resume} delegate to."}],returns:"the disposer that clears the factory slot. The exact Cordis effect disposer (single-shot): composite (generator) effects may yield it directly — exact identity nests the teardown in order."},{signature:"async create(options: CreateAgentOptions): Promise<AgentHandle>",description:"Create and publish a new agent through the registered factory. Distinct from register (which records an already-constructed agent): this constructs the agent and its session. Rejects if no factory is registered or creation/setup fails. The resolved AgentHandle lets the owner tear down exactly this agent.",parameters:[{name:"options",description:"shared identity, session seed/metadata, and agent options."}],returns:"the handle after setup, rollback-covered publication, and loop start complete."},{signature:"async resume(options: ResumeAgentOptions): Promise<AgentHandle>",description:"Load a persisted session and resume an agent on it through the registered factory. Rejects if no factory is registered; the factory rejects if session persistence is not configured or persistence/setup fails.",parameters:[{name:"options",description:"persisted identity, configuration, and optional setup."}],returns:"the handle after setup, rollback-covered publication, and loop start complete."},{signature:"register(agent: Agent): () => void",description:"Register a live agent. Throws if an agent with the same id is already registered. Emits `agent/created` on registration and `agent/disposed` when the calling fiber is disposed — both with the agent's scope carrier (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the emits are scope-filtered regardless of which context invoked `register` (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always requires passing the carrier). Returns the disposer.",parameters:[{name:"agent",description:"the already-constructed agent to record in the store."}],returns:"the EXACT Cordis effect disposer (single-shot; a repeat call returns undefined without awaiting an in-flight teardown). Exact identity is load-bearing: a composite (generator) effect that owns a teardown ORDER — the agent factory's lifecycle chain — must yield THIS function so Cordis nests the unregistration at that yield position; yielding a wrapper would leave it disposing as a concurrent sibling on owner unload, unregistering the agent (and emitting `agent/disposed`) while its final turn is still draining."},{signature:"enter(agent: Agent, owner: Agent | undefined): () => void",description:"Insert an already-constructed agent without announcing it. This is the advanced ordered-lifecycle primitive used by the async agent factory: it first completes setup while the agent is unpublished, then assigns the returned detach closure into its pre-installed composite teardown before calling announce. Ordinary callers use register.",parameters:[{name:"agent",description:"the prepared, unpublished agent."},{name:"owner",description:"live agent whose scoped context created this agent, or undefined for a top-level runtime root. This is runtime ownership, not the resumed session's durable parent lineage."}],returns:"an idempotent closure that removes this exact entry and emits `agent/disposed` with listener failures contained. When called from a synchronous `agent/created` listener, removal and disposal wait until that creation dispatch unwinds."},{signature:"announce(agent: Agent): void",description:"Announce an agent previously inserted with enter.",parameters:[{name:"agent",description:"the live inserted agent to announce."}],throws:["if `agent` is not the exact live registry entry for its id, or its creation announcement already began (including a reentrant call from a creation listener)."]},{signature:"get(id: SessionId): Agent | undefined",description:"Look up a live agent.",parameters:[{name:"id",description:"the shared agent/session id to look up."}],returns:"the agent, or undefined when no live agent has that id."},{signature:"isOwnedBy(id: SessionId, owner: Agent): boolean",description:"Test whether a live agent was created through one exact parent agent's scoped context. Runtime ownership is independent of durable session lineage and remains unambiguous when unrelated providers reuse an id.",parameters:[{name:"id",description:"the candidate child agent's shared agent/session id."},{name:"owner",description:"the expected runtime creator agent."}],returns:"true only while the exact child entry is live under that owner."},{signature:"list(): Agent[]",description:"All live agents, in registration order.",parameters:[],returns:"a fresh array; mutating it does not affect the registry."},{signature:"roots(): Agent[]",description:"All live top-level agents in registration order. A top-level agent was created without an owning agent context; durable session lineage does not affect this runtime relation, so a resumed fork may still be a root.",parameters:[],returns:"a fresh array; mutating it does not affect the registry."}]},{key:"apiProxy",summary:"Root interface of the unified API.",description:"Root interface of the unified API. New client-request domain = one new file pair + one field here + one map row.",methods:[{signature:"downloads: DownloadsApi",description:"Host-only download surfaces (GET, no wire envelope); absent from IApiClient.",parameters:[]},{signature:"respond(message: ClientResponse): Promise<RpcReceipt>",description:"Response entry for server requests; not a domain method.",parameters:[{name:"message",description:"Client response carrying the server request's rpcId."}],returns:"Transport receipt for the response delivery."}]},{key:"approval",summary:"Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session.",description:"Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.",methods:[{signature:"setPolicy(agent: Agent, policy: ApprovalPolicy): void",description:"Switch one live agent's policy and queue the transition for its next model step. Session initialization uses setApprovalPolicy directly because there is no previously visible policy to change.",parameters:[{name:"agent",description:"the live agent whose policy is changing."},{name:"policy",description:"the new effective policy."}]},{signature:"async request(req: ApprovalRequest): Promise<ApprovalOutcome>",description:"Ask the composed answerers to decide one readonly same-process request. The service borrows the request, agent, session, and live signal directly. The request requires an open turn because the audit pair must be enclosed by the durable log's commit/replay boundary; an idle ask rejects before appending anything. The answerer phase always produces an outcome: an aborted signal yields `'cancelled'`, a missing or throwing answerer yields `'unavailable'` (fail closed), and a rogue non-vocabulary return value is normalized to `'unavailable'`. A failure that prevents either audit append from committing still rejects because returning an unlogged decision would violate the pair. Session contains post-commit observer failures, so an authoritative append cannot reject the request or suppress its matching audit event.",parameters:[{name:"req",description:"the pending decision (agent, tool identity, reason, signal)."}],returns:"the closed outcome; `'allowed-once'` is the only grant.",throws:["when no turn is open or either audit event fails before the session append commit point."]},{signature:"overrideOf(session: Session): ApprovalPolicy | undefined",description:"Read the session override without applying the configured default.",parameters:[{name:"session",description:"session whose log supplies the override."}],returns:"the last logged policy, or `undefined` without one."}]},{key:"attachments",summary:"Immutable binary attachment service.",description:"Immutable binary attachment service. Implementations validate bytes before publishing a reference.",methods:[{signature:"abstract readonly imageLimits: ImageAttachmentLimits",description:"Deployment-resolved image policy used by authoritative and fast-path validation.",parameters:[]},{signature:"abstract validateImage(input: SaveImageAttachment): Promise<void>",description:"Validate one image without persisting it. Batch callers validate every member before saving any member.",parameters:[{name:"input",description:"encoded bytes, declared media type, and optional display name."}],returns:"completion after the encoded raster has been fully decoded."},{signature:"abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>",description:"Validate and durably commit one image before its owning session event is appended.",parameters:[{name:"input",description:"encoded bytes, declared media type, and optional display name."}],returns:"a durable content-addressed reference."},{signature:"abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>",description:"Read one image and verify that bytes still match the recorded reference.",parameters:[{name:"ref",description:"durable reference from the session log."},{name:"signal",description:"optional cancellation for backend read and verification work."}],returns:"the verified bytes and canonical reference.",throws:["the signal reason when aborted, or a storage error when verification fails."]}]},{key:"clientModules",summary:"The web plugin table service: incremental `qbot-dsh.client` scan + wire composition + bundle route + index tap.",description:"The web plugin table service: incremental `qbot-dsh.client` scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).",methods:[{signature:"graph(): WebBootGraph",description:"Current composed entry graph (stable object between changes).",parameters:[],returns:"the graph served as `window.__QBOT_DSH_BOOT__`."},{signature:"clientPath(id: string): string | undefined",description:"Absolute path of an entry's client bundle.",parameters:[{name:"id",description:"entry id (package name)."}],returns:"the path, or undefined for an unknown id."},{signature:"rebuilt(id: string): string | undefined",description:"Re-hash one bundle (the HMR watch's registration hook — the only entry point through which bundle content changes reach the graph).",parameters:[{name:"id",description:"entry id (package name)."}],returns:"the new rev, or undefined for an unknown id."},{signature:"onRebuilt(listener: (id: string, rev: string) => void): () => void",description:"Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.",parameters:[{name:"listener",description:"receives the entry id and its new bundle rev."}],returns:"the unsubscriber."},{signature:"onGraphChanged(listener: () => void): () => void",description:"Fires after any flush that recomposed the graph (row added/removed, or a rebuilt rev change). Pull model: listeners re-read graph.",parameters:[{name:"listener",description:"notified with no payload."}],returns:"the unsubscriber."}]},{key:"codeRuntime",summary:"Registers one `ctx.codeRuntime` implementation.",description:"Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.",methods:[{signature:"abstract readonly language: string",description:"The source language run expects `program` to be written in, as a lowercase identifier. Informational, not gating — a consumer that generates language-specific presentation (typed SDK stubs, usage instructions) switches on it and fails loud on a language it cannot present. Well-known values: `'typescript'` and `'python'`, those `dsh-tools` presents; only `'typescript'` has a published backend.",parameters:[]},{signature:"abstract readonly isolation: string",description:"The execution substrate, as a lowercase identifier. Informational, not gating — a descriptor so deployments and diagnostics can tell backends apart, not a security claim. Well-known values: `'worker-thread'`, `'process'`, `'container'`.",parameters:[]},{signature:"abstract run(request: CodeRunRequest): Promise<CodeRunResult>",description:"Execute one program against the request's bindings and capture what it emitted. See the class doc for the resolution contract (error is a result field; rejection means Service Definition contract misuse only).",parameters:[{name:"request",description:"the program, its bindings, and the abort signal; the request carries everything the runtime acts on, with no hidden defaults."}],returns:"the run's outcome: completion value (when transferable), the ordered log capture, and the failure (if any)."}]},{key:"commands",summary:"Human-command registry.",description:"Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.",methods:[{signature:"register(definition: CommandDefinition): () => void",description:"Register a global or calling-agent-scoped command.",parameters:[{name:"definition",description:"discovery metadata and direct UI handler."}],returns:"the exact effect disposer that unregisters this definition."},{signature:"@Remote list(agent: Agent): readonly CommandDescriptor[]",description:"List the effective immutable command descriptors for one agent.",parameters:[{name:"agent",description:"exact receiving agent and scoped-layer key."}],returns:"name-sorted descriptors after scoped shadowing."},{signature:"find(agent: Agent, name: string): CommandDefinition | undefined",description:"Resolve one effective command definition.",parameters:[{name:"agent",description:"exact receiving agent and scoped-layer key."},{name:"name",description:"command name without a slash."}],returns:"the scoped shadow or global definition."},{signature:"@Remote async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>",description:"Parse and execute a known command without sending it to the model.\n\nA resolved command's lifecycle is logged: `command/run` is appended before the handler is invoked and `command/done` after settlement (a thrown or aborted handler settles as `kind: 'error'`). Both are direct log-only appends — no turn wraps them, and persistence drains them at ordinary checkpoints. Admission misses (syntax or unknown name) log nothing — they never entered a handler. A `command/run` append failure fails the execution loud; a `command/done` append failure on the handler-failure path is contained so the handler's own error stays the reported failure.",parameters:[{name:"agent",description:"exact receiving agent."},{name:"line",description:"complete slash-command line."},{name:"signal",description:"cancellation signal owned by the UI request."}],returns:"the settled execution (result + lifecycle pairing id), or `undefined` when syntax or name does not resolve."}]},{key:"compaction",summary:"Abstract compaction service.",description:"Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses compactCheckpointSource with the transaction identity so consumers recognize and correlate it independently of the backend. Load one implementation per context as `ctx.compaction`.",methods:[{signature:"abstract compactIfNeeded( agent: CompactionAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>",description:"Consider automatic compaction for one explicit trigger. Pressure policy uses the latest durable routed request, while context-overflow policy may force a useful balanced reduction even below the normal threshold. Return `null` when no safe range can be compacted. A single oversized retained unit or request envelope cannot be repaired through surface compaction.",parameters:[{name:"agent",description:"agent context owning the session surface and routing options."},{name:"trigger",description:"normal pressure or provider-confirmed context overflow."},{name:"signal",description:"cancellation signal; model-backed implementations must forward it."}],returns:"the compaction result, or `null` if no compaction was needed."},{signature:"abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>",description:"Explicitly compact useful history even below automatic pressure thresholds. Implementations synchronously start an idle task before any asynchronous work, select a useful range without writing on a no-op, then append a standalone `compaction/start` before summarization. That durable marker is the compaction lock until one `compaction/end` attempt. Later waking prompts remain accepted in FIFO order and start only after the optional durability checkpoint and idle-task settlement. Context injected while the summary runs may sit between the marker pair; only the selected span must remain stable.",parameters:[{name:"agent",description:"idle agent whose durable history should be compacted."},{name:"signal",description:"cancellation scoped to this compaction request."},{name:"sourceCommandId",description:"initiating command identity for a manual compaction."}],returns:"the compaction result, or `null` when no safe useful range exists.",throws:["{@link ManualCompactionError} for expected busy, agent-cancellation, changed-span, summarization/shrink, commit-stage, or persistence failures; an aborted request preserves its exact abort reason. Failed attempts remain visible in the log."]},{signature:"abstract compactRegion( start: number, end: number, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>",description:"Forcibly compact a range of surface nodes into a single summary node. `start` and `end` name an inclusive span by surface position, not numeric seq order; replacements can make visible seqs non-monotonic. Both edges must be balanced so assistant tool calls remain paired with their results. A model- backed implementation forwards cancellation and rejects active, missing, reversed, or unbalanced ranges. The target session is `agent.session`. Its replacement user message must use compactCheckpointSource with the transaction's `CompactionId`. Use toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks.",parameters:[{name:"start",description:"first surface seq, inclusive."},{name:"end",description:"last surface seq, inclusive."},{name:"agent",description:"context whose session is mutated and whose routing options guide summarization."},{name:"signal",description:"optional cancellation; model-backed implementations must forward it."}],returns:"the appended event seqs, summary, replaced range, and token accounting.",throws:["when compaction is active or the range is missing, reversed, or unbalanced."]}]},{key:"credentials",summary:"Abstract credential service.",description:"Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.",methods:[{signature:"abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>",description:"Resolve one reference to its current value. Resolution is per call: consumers re-resolve at each operation and must not cache across operations — that per-operation read is what makes a changed credential reach the next operation without a restart.",parameters:[{name:"ref",description:"the reference to resolve."}],returns:"the value and its source, or `undefined` while unconfigured."},{signature:"abstract describe(ref: CredentialRef): Promise<CredentialInfo>",description:"Describe one reference for configuration surfaces without exposing the value.",parameters:[{name:"ref",description:"the reference to describe."}],returns:"configured state, supplying source, and writability."},{signature:"abstract set(ref: CredentialRef, value: string): Promise<void>",description:"Durably store one value in the provider-managed writable source. Rejects while a read-only source shadows the reference — the write would appear to succeed while resolution keeps returning the shadowing value — and rejects an empty value (use unset).",parameters:[{name:"ref",description:"the reference to store."},{name:"value",description:"the non-empty secret value."}]},{signature:"abstract unset(ref: CredentialRef): Promise<void>",description:"Remove one reference from the provider-managed writable source; removing an absent reference is a no-op. Rejects while a read-only source shadows the reference, like set.",parameters:[{name:"ref",description:"the reference to remove."}]}]},{key:"directoryPicker",summary:"Abstract directory-picking service.",description:"Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.",methods:[{signature:"abstract capability(): DirectoryPickerCapability",description:"The backend's interaction capability.",parameters:[],returns:"the discriminated capability consumers switch on."}]},{key:"e2b",summary:"Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal.",description:"Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.",methods:[{signature:"readonly cwd: string",description:"Validated remote working directory shared by provider adapters.",parameters:[]},{signature:"readonly runtimeRoot: string",description:"Remote directory reserved for adapter-owned process and terminal state.",parameters:[]},{signature:"async getSandbox(): Promise<Sandbox>",description:"Return the shared live SDK handle.",parameters:[],returns:"the created sandbox after the configured cwd exists.",throws:["when E2B rejects creation or the service is disposing."]}]},{key:"fs",summary:"Abstract filesystem provider.",description:"Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.",methods:[{signature:"abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>",description:"Resolve a model/plugin-supplied path into a stable FsTarget. May perform I/O (a remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence async even though the local backend only normalizes + realpaths.",parameters:[{name:"path",description:"the path to resolve; relative paths resolve against `opts.cwd`."},{name:"opts",description:"optional cwd override and cancellation signal."}],returns:"the stable target; the same file yields the same `targetKey`."},{signature:"abstract processPath(target: FsTarget): string",description:"Return the canonical absolute path a subprocess in this filesystem's execution world can open. The path is deliberately separate from FsTarget.targetKey: consumers may pass this value to another OS capability, but must continue treating the target key as opaque.",parameters:[{name:"target",description:"the resolved target whose process path is required."}],returns:"an absolute path in the backend's execution world."},{signature:"abstract fileUrl(target: FsTarget): string",description:"Return the canonical `file:` URI for a target in this filesystem's execution world. Backends own URI encoding because the host platform may differ from the execution platform.",parameters:[{name:"target",description:"the resolved target to encode."}],returns:"the target's canonical file URI."},{signature:"abstract contains(parent: FsTarget, child: FsTarget): boolean",description:"Test canonical containment without exposing or parsing backend target keys. Both targets must come from this provider.",parameters:[{name:"parent",description:"canonical directory target."},{name:"child",description:"canonical candidate target."}],returns:"true when `child` is `parent` or a descendant of it."},{signature:"abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>",description:"Return target metadata, or `undefined` when the target does not exist.",parameters:[{name:"target",description:"the resolved target to stat."},{name:"signal",description:"aborts the metadata round-trip."}],returns:"metadata only, never content; undefined for an absent target."},{signature:"abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>",description:"Return path metadata without following the final path component when it is a symbolic link. This is intentionally path-shaped, not target-shaped: resolve follows symlinks to produce the stable identity used by normal reads/writes, while `lstat` lets a consumer reject the path itself before that follow happens.\n\n`opts.cwd` follows resolve's cwd rules. `undefined` means the path is absent.",parameters:[{name:"path",description:"the path to inspect; relative paths resolve against `opts.cwd`."},{name:"opts",description:"`cwd` overrides the backend's default base for relative paths."},{name:"signal",description:"aborts the metadata round-trip."}],returns:"metadata only, never content; undefined for an absent path."},{signature:"abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>",description:"Read the whole regular text file as a single decoded string.",parameters:[{name:"target",description:"the resolved target to read."},{name:"signal",description:"aborts the read."}],returns:"the full decoded UTF-8 content."},{signature:"abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>",description:"Stream the whole regular text file as decoded text chunks (same text semantics as readText, for large files). The backend owns cross-chunk UTF-8 decoding and binary rejection so the policy layer never touches raw bytes.",parameters:[{name:"target",description:"the resolved target to read."},{name:"signal",description:"aborts the stream, including between chunks."}],returns:"the chunk iterable, decoded and validated like {@link readText}."},{signature:"abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>",description:"Read the whole regular file as raw bytes with no decoding or binary rejection. The bound lives at this seam so a backend can never buffer an unbounded file: a target known or discovered to exceed `maxBytes` fails with `FS_TOO_LARGE` instead of returning a truncated result.",parameters:[{name:"target",description:"the resolved target to read."},{name:"signal",description:"aborts the read."},{name:"maxBytes",description:"inclusive byte cap on the complete content."}],returns:"the full raw content, at most `maxBytes` long."},{signature:"abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>",description:"List direct children of a directory in stable name order. Returns resolved child targets plus cheap metadata only; never reads file contents.",parameters:[{name:"target",description:"the resolved directory target."},{name:"signal",description:"aborts the listing."}],returns:"one entry per direct child, in stable name order."},{signature:"abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>",description:"Atomically create or replace UTF-8 text. `expected` guards intent and staleness; omission allows unconditional overwrite.",parameters:[{name:"target",description:"the resolved target to write."},{name:"content",description:"the full new file content."},{name:"expected",description:"the write intent guarding the write; omit for unconditional."},{name:"signal",description:"aborts before atomic publication takes effect."},{name:"sandboxPolicy",description:"the per-call mode and workspace root this write runs under; a sandboxing backend fences the write by it, the bare backend ignores it. Omit to leave the backend its own default."}],returns:"the outcome, including the version the write produced."},{signature:"abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>",description:"Atomically edit literal text. When supplied, the version guard is checked before matching so stale content reports `FS_STALE_VERSION`; omission edits the current content without a freshness precondition.",parameters:[{name:"target",description:"the resolved target to edit."},{name:"edit",description:"the literal search/replace request."},{name:"expected",description:"the version guard; omit for an unconditional edit."},{name:"signal",description:"aborts before atomic publication takes effect."},{name:"sandboxPolicy",description:"the per-call mode and workspace root this edit runs under; a sandboxing backend fences the edit by it, the bare backend ignores it. Omit to leave the backend its own default."}],returns:"the outcome, including the version the edit produced."}]},{key:"goals",summary:"Goal service (`ctx.goals`) backed exclusively by the owning session log.",description:"Goal service (`ctx.goals`) backed exclusively by the owning session log.",methods:[{signature:"get(agent: Agent): GoalView | undefined",description:"Read the current goal for one exact live agent.",parameters:[{name:"agent",description:"owning live agent."}],returns:"a fresh view or `undefined` when no goal is current.",throws:["{@link GoalError} when the agent is not the registry's live instance."]},{signature:"disarm(agent: Agent): GoalView | undefined",description:"Remove process-local continuation authority without changing durable goal phase or revision. Lifecycle owners use this before unloading a driver; a later human-authorized resume records the new activation edge.",parameters:[{name:"agent",description:"owning live agent."}],returns:"a fresh disarmed view, or `undefined` when no goal is current."},{signature:"create(agent: Agent, request: CreateGoalRequest): GoalView",description:"Create and arm a goal. A completed goal may be replaced; every other current phase must be cleared or resumed instead.",parameters:[{name:"agent",description:"owning live agent."},{name:"request",description:"objective and optional round cap."}],returns:"the created live view."},{signature:"@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView",description:"Edit objective and/or round cap without changing phase.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."},{name:"request",description:"at least one replacement field."}],returns:"the edited view."},{signature:"@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView",description:"Pause an active goal and disarm automatic continuation.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the paused view."},{signature:"@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView",description:"Resume and arm a stopped goal, or rearm an active goal after a session-start edge, while its round budget still has capacity.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the active view."},{signature:"@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView",description:"Mark a current non-complete goal complete and disarm it.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the completed view."},{signature:"block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView",description:"Mark an active goal blocked and disarm it.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."},{name:"reason",description:"policy-owned stable code and human-readable explanation."}],returns:"the blocked view with its durable reason."},{signature:"@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef",description:"Clear the current goal while retaining a durable tombstone and history.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the tombstone ref whose revision is one past the cleared snapshot."},{signature:"@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult",description:"Create one Goal through the remote boundary.",parameters:[{name:"agent",description:"exact live Agent resolved from the wire identity."},{name:"request",description:"objective and optional round cap."}],returns:"the created Goal identity."}]},{key:"invariants",summary:"Package-owned invariant registry with global and regex-based selection.",description:"Package-owned invariant registry with global and regex-based selection.",methods:[{signature:"register(packageName: string, installer: InvariantInstaller): () => void",description:"Register one package's invariant installer. The package name is reserved even when filtering disables its checks. Enabled installers run in a child fiber; failure disposes that fiber and releases the reservation.",parameters:[{name:"packageName",description:"full npm package name that owns the contribution."},{name:"installer",description:"listener or startup-check installer for the child context."}],returns:"an effect-scoped disposer for the registration."}]},{key:"jobs",summary:"Abstract background job registry.",description:`Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as \`ctx.jobs\` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+A cold transcript read resolves tool presenters against the composition the session recorded, and the standing mount makes that possible without resuming anything: ensuring the mount composes plugins but starts no agent, no session, and no turn.`,parameters:[{name:"id",description:"the preset id, or `undefined` for {@link defaultId}."}],returns:"the standing scope key readers pass as a registry view scope.",throws:["when the preset is unknown or its composition is unusable."]}]},{key:"agents",summary:"Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain.",description:"Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@qqbrowser/qbot-dsh-agent-loop`), registered via setFactory.\n\nInitiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.",methods:[{signature:"currentInitiator(): Agent | undefined",description:"Read the Agent that initiated the inherited asynchronous driver chain. Use this optional form for logging, tracing, metrics, or host attribution that also supports agentless calls. When a parent creates a child, setup reports the causal parent while `agentCtx.agent` identifies the child.",parameters:[],returns:"the inherited Agent, or `undefined` outside an initiator boundary and inside an explicit clearing boundary.",throws:["when this service instance has been disposed."]},{signature:"requireInitiator(): Agent",description:"Read the initiating Agent and fail when no initiator boundary is active. Use this for private helpers contractually below a driver, or for a deployment-owned outbound request whose contract forbids agentless calls. Generic or direct-call paths use optional lookup or explicit request fields.",parameters:[],returns:"the inherited Agent.",throws:["when no initiator is active or this service instance has been disposed."]},{signature:"withInitiator<T>(agent: Agent, operation: () => T): T",description:"Run an operation with one exact Agent as its process-local initiator. The exact synchronous value or Promise returned by the operation is preserved. Custom drivers and test harnesses wrap their complete returned foreground lifetime. A queue or wire receiver may establish this boundary only after validating explicit identity and resolving the exact live Agent; this method does neither. Detached work remains owned by the subsystem that starts it.",parameters:[{name:"agent",description:"initiating Agent to inherit; presence is neither liveness proof nor authorization."},{name:"operation",description:"synchronous or asynchronous operation to invoke."}],returns:"the exact value returned by `operation`.",throws:["when the initiator scope is closing/disposed, or when `operation` throws."]},{signature:"withoutInitiator<T>(operation: () => T): T",description:"Run an operation inside a boundary that hides any inherited initiating Agent. The exact synchronous value or Promise is preserved. Use this while creating lazy shared timers, queue pumps, pool maintenance, watchers, or exporters so they do not inherit the first Agent that happens to initialize them. It clears only initiator attribution, not explicit fields, and does not own or drain detached resources.",parameters:[{name:"operation",description:"synchronous or asynchronous operation to invoke without an initiator."}],returns:"the exact value returned by `operation`.",throws:["when the initiator scope is closing/disposed, or when `operation` throws."]},{signature:"setFactory(factory: AgentFactory): () => void",description:"Register the agent-creation factory (the loop calls this on construction, effect-scoped). A traced Cordis service is canonicalized to its concrete target; each create/resume call is then traced through that caller's context so ownership follows the caller without stacking proxy layers. Throws if a factory is already registered. Returns the disposer; on dispose the factory slot is cleared.",parameters:[{name:"factory",description:"the loop-owned factory {@link create}/{@link resume} delegate to."}],returns:"the disposer that clears the factory slot. The exact Cordis effect disposer (single-shot): composite (generator) effects may yield it directly — exact identity nests the teardown in order."},{signature:"async create(options: CreateAgentOptions): Promise<AgentHandle>",description:"Create and publish a new agent through the registered factory. Distinct from register (which records an already-constructed agent): this constructs the agent and its session. Rejects if no factory is registered or creation/setup fails. The resolved AgentHandle lets the owner tear down exactly this agent.",parameters:[{name:"options",description:"shared identity, session seed/metadata, and agent options."}],returns:"the handle after setup, rollback-covered publication, and loop start complete."},{signature:"async resume(options: ResumeAgentOptions): Promise<AgentHandle>",description:"Load a persisted session and resume an agent on it through the registered factory. Rejects if no factory is registered; the factory rejects if session persistence is not configured or persistence/setup fails.",parameters:[{name:"options",description:"persisted identity, configuration, and optional setup."}],returns:"the handle after setup, rollback-covered publication, and loop start complete."},{signature:"register(agent: Agent): () => void",description:"Register a live agent. Throws if an agent with the same id is already registered. Emits `agent/created` on registration and `agent/disposed` when the calling fiber is disposed — both with the agent's scope carrier (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the emits are scope-filtered regardless of which context invoked `register` (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always requires passing the carrier). Returns the disposer.",parameters:[{name:"agent",description:"the already-constructed agent to record in the store."}],returns:"the EXACT Cordis effect disposer (single-shot; a repeat call returns undefined without awaiting an in-flight teardown). Exact identity is load-bearing: a composite (generator) effect that owns a teardown ORDER — the agent factory's lifecycle chain — must yield THIS function so Cordis nests the unregistration at that yield position; yielding a wrapper would leave it disposing as a concurrent sibling on owner unload, unregistering the agent (and emitting `agent/disposed`) while its final turn is still draining."},{signature:"enter(agent: Agent, owner: Agent | undefined): () => void",description:"Insert an already-constructed agent without announcing it. This is the advanced ordered-lifecycle primitive used by the async agent factory: it first completes setup while the agent is unpublished, then assigns the returned detach closure into its pre-installed composite teardown before calling announce. Ordinary callers use register.",parameters:[{name:"agent",description:"the prepared, unpublished agent."},{name:"owner",description:"live agent whose scoped context created this agent, or undefined for a top-level runtime root. This is runtime ownership, not the resumed session's durable parent lineage."}],returns:"an idempotent closure that removes this exact entry and emits `agent/disposed` with listener failures contained. When called from a synchronous `agent/created` listener, removal and disposal wait until that creation dispatch unwinds."},{signature:"announce(agent: Agent): void",description:"Announce an agent previously inserted with enter.",parameters:[{name:"agent",description:"the live inserted agent to announce."}],throws:["if `agent` is not the exact live registry entry for its id, or its creation announcement already began (including a reentrant call from a creation listener)."]},{signature:"get(id: SessionId): Agent | undefined",description:"Look up a live agent.",parameters:[{name:"id",description:"the shared agent/session id to look up."}],returns:"the agent, or undefined when no live agent has that id."},{signature:"isOwnedBy(id: SessionId, owner: Agent): boolean",description:"Test whether a live agent was created through one exact parent agent's scoped context. Runtime ownership is independent of durable session lineage and remains unambiguous when unrelated providers reuse an id.",parameters:[{name:"id",description:"the candidate child agent's shared agent/session id."},{name:"owner",description:"the expected runtime creator agent."}],returns:"true only while the exact child entry is live under that owner."},{signature:"list(): Agent[]",description:"All live agents, in registration order.",parameters:[],returns:"a fresh array; mutating it does not affect the registry."},{signature:"roots(): Agent[]",description:"All live top-level agents in registration order. A top-level agent was created without an owning agent context; durable session lineage does not affect this runtime relation, so a resumed fork may still be a root.",parameters:[],returns:"a fresh array; mutating it does not affect the registry."}]},{key:"apiProxy",summary:"Root interface of the unified API.",description:"Root interface of the unified API. New client-request domain = one new file pair + one field here + one map row.",methods:[{signature:"downloads: DownloadsApi",description:"Host-only download surfaces (GET, no wire envelope); absent from IApiClient.",parameters:[]},{signature:"respond(message: ClientResponse): Promise<RpcReceipt>",description:"Response entry for server requests; not a domain method.",parameters:[{name:"message",description:"Client response carrying the server request's rpcId."}],returns:"Transport receipt for the response delivery."}]},{key:"approval",summary:"Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session.",description:"Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session. It exposes deterministic policy changes to the model through the runtime-context snapshot and switch notices.",methods:[{signature:"setPolicy(agent: Agent, policy: ApprovalPolicy): void",description:"Switch one live agent's policy and queue the transition for its next model step. Session initialization uses setApprovalPolicy directly because there is no previously visible policy to change.",parameters:[{name:"agent",description:"the live agent whose policy is changing."},{name:"policy",description:"the new effective policy."}]},{signature:"async request(req: ApprovalRequest): Promise<ApprovalOutcome>",description:"Ask the composed answerers to decide one readonly same-process request. The service borrows the request, agent, session, and live signal directly. The request requires an open turn because the audit pair must be enclosed by the durable log's commit/replay boundary; an idle ask rejects before appending anything. The answerer phase always produces an outcome: an aborted signal yields `'cancelled'`, a missing or throwing answerer yields `'unavailable'` (fail closed), and a rogue non-vocabulary return value is normalized to `'unavailable'`. A failure that prevents either audit append from committing still rejects because returning an unlogged decision would violate the pair. Session contains post-commit observer failures, so an authoritative append cannot reject the request or suppress its matching audit event.",parameters:[{name:"req",description:"the pending decision (agent, tool identity, reason, signal)."}],returns:"the closed outcome; `'allowed-once'` is the only grant.",throws:["when no turn is open or either audit event fails before the session append commit point."]},{signature:"overrideOf(session: Session): ApprovalPolicy | undefined",description:"Read the session override without applying the configured default.",parameters:[{name:"session",description:"session whose log supplies the override."}],returns:"the last logged policy, or `undefined` without one."}]},{key:"attachments",summary:"Immutable binary attachment service.",description:"Immutable binary attachment service. Implementations validate bytes before publishing a reference.",methods:[{signature:"abstract readonly imageLimits: ImageAttachmentLimits",description:"Deployment-resolved image policy used by authoritative and fast-path validation.",parameters:[]},{signature:"abstract validateImage(input: SaveImageAttachment): Promise<void>",description:"Validate one image without persisting it. Batch callers validate every member before saving any member.",parameters:[{name:"input",description:"encoded bytes, declared media type, and optional display name."}],returns:"completion after the encoded raster has been fully decoded."},{signature:"abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>",description:"Validate and durably commit one image before its owning session event is appended.",parameters:[{name:"input",description:"encoded bytes, declared media type, and optional display name."}],returns:"a durable content-addressed reference."},{signature:"abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>",description:"Read one image and verify that bytes still match the recorded reference.",parameters:[{name:"ref",description:"durable reference from the session log."},{name:"signal",description:"optional cancellation for backend read and verification work."}],returns:"the verified bytes and canonical reference.",throws:["the signal reason when aborted, or a storage error when verification fails."]}]},{key:"clientModules",summary:"The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index tap.",description:"The web plugin table service: incremental `dsh.client` scan + wire composition + bundle route + index tap. Construction runs the activation scan synchronously — a malformed declaration or missing bundle among the already-loaded entries aggregates into one loud throw (FAILED fiber; the boot activation audit reports it).",methods:[{signature:"graph(): WebBootGraph",description:"Current composed entry graph (stable object between changes).",parameters:[],returns:"the graph served as `window.__DSH_BOOT__`."},{signature:"clientPath(id: string): string | undefined",description:"Absolute path of an entry's client bundle.",parameters:[{name:"id",description:"entry id (package name)."}],returns:"the path, or undefined for an unknown id."},{signature:"rebuilt(id: string): string | undefined",description:"Re-hash one bundle (the HMR watch's registration hook — the only entry point through which bundle content changes reach the graph).",parameters:[{name:"id",description:"entry id (package name)."}],returns:"the new rev, or undefined for an unknown id."},{signature:"onRebuilt(listener: (id: string, rev: string) => void): () => void",description:"Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.",parameters:[{name:"listener",description:"receives the entry id and its new bundle rev."}],returns:"the unsubscriber."},{signature:"onGraphChanged(listener: () => void): () => void",description:"Fires after any flush that recomposed the graph (row added/removed, or a rebuilt rev change). Pull model: listeners re-read graph.",parameters:[{name:"listener",description:"notified with no payload."}],returns:"the unsubscriber."}]},{key:"codeRuntime",summary:"Registers one `ctx.codeRuntime` implementation.",description:"Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.",methods:[{signature:"abstract readonly language: string",description:"The source language run expects `program` to be written in, as a lowercase identifier. Informational, not gating — a consumer that generates language-specific presentation (typed SDK stubs, usage instructions) switches on it and fails loud on a language it cannot present. Well-known values: `'typescript'` and `'python'`, those `dsh-tools` presents; only `'typescript'` has a published backend.",parameters:[]},{signature:"abstract readonly isolation: string",description:"The execution substrate, as a lowercase identifier. Informational, not gating — a descriptor so deployments and diagnostics can tell backends apart, not a security claim. Well-known values: `'worker-thread'`, `'process'`, `'container'`.",parameters:[]},{signature:"abstract run(request: CodeRunRequest): Promise<CodeRunResult>",description:"Execute one program against the request's bindings and capture what it emitted. See the class doc for the resolution contract (error is a result field; rejection means Service Definition contract misuse only).",parameters:[{name:"request",description:"the program, its bindings, and the abort signal; the request carries everything the runtime acts on, with no hidden defaults."}],returns:"the run's outcome: completion value (when transferable), the ordered log capture, and the failure (if any)."}]},{key:"commands",summary:"Human-command registry.",description:"Human-command registry. Plain-context definitions are global; definitions registered through a command-injected child of an agent context shadow globals for that agent.",methods:[{signature:"register(definition: CommandDefinition): () => void",description:"Register a global or calling-agent-scoped command.",parameters:[{name:"definition",description:"discovery metadata and direct UI handler."}],returns:"the exact effect disposer that unregisters this definition."},{signature:"@Remote list(agent: Agent): readonly CommandDescriptor[]",description:"List the effective immutable command descriptors for one agent.",parameters:[{name:"agent",description:"exact receiving agent and scoped-layer key."}],returns:"name-sorted descriptors after scoped shadowing."},{signature:"find(agent: Agent, name: string): CommandDefinition | undefined",description:"Resolve one effective command definition.",parameters:[{name:"agent",description:"exact receiving agent and scoped-layer key."},{name:"name",description:"command name without a slash."}],returns:"the scoped shadow or global definition."},{signature:"@Remote async execute( agent: Agent, line: string, signal: AbortSignal, ): Promise<CommandExecution | undefined>",description:"Parse and execute a known command without sending it to the model.\n\nA resolved command's lifecycle is logged: `command/run` is appended before the handler is invoked and `command/done` after settlement (a thrown or aborted handler settles as `kind: 'error'`). Both are direct log-only appends — no turn wraps them, and persistence drains them at ordinary checkpoints. Admission misses (syntax or unknown name) log nothing — they never entered a handler. A `command/run` append failure fails the execution loud; a `command/done` append failure on the handler-failure path is contained so the handler's own error stays the reported failure.",parameters:[{name:"agent",description:"exact receiving agent."},{name:"line",description:"complete slash-command line."},{name:"signal",description:"cancellation signal owned by the UI request."}],returns:"the settled execution (result + lifecycle pairing id), or `undefined` when syntax or name does not resolve."}]},{key:"compaction",summary:"Abstract compaction service.",description:"Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. The replacement user message uses compactCheckpointSource with the transaction identity so consumers recognize and correlate it independently of the backend. Load one implementation per context as `ctx.compaction`.",methods:[{signature:"abstract compactIfNeeded( agent: CompactionAgentContext, trigger: CompactionTrigger, signal: AbortSignal, ): Promise<CompactionResult | null>",description:"Consider automatic compaction for one explicit trigger. Pressure policy uses the latest durable routed request, while context-overflow policy may force a useful balanced reduction even below the normal threshold. Return `null` when no safe range can be compacted. A single oversized retained unit or request envelope cannot be repaired through surface compaction.",parameters:[{name:"agent",description:"agent context owning the session surface and routing options."},{name:"trigger",description:"normal pressure or provider-confirmed context overflow."},{name:"signal",description:"cancellation signal; model-backed implementations must forward it."}],returns:"the compaction result, or `null` if no compaction was needed."},{signature:"abstract compactNow( agent: ManualCompactAgentContext, signal: AbortSignal, sourceCommandId?: CommandId, ): Promise<CompactionResult | null>",description:"Explicitly compact useful history even below automatic pressure thresholds. Implementations synchronously start an idle task before any asynchronous work, select a useful range without writing on a no-op, then append a standalone `compaction/start` before summarization. That durable marker is the compaction lock until one `compaction/end` attempt. Later waking prompts remain accepted in FIFO order and start only after the optional durability checkpoint and idle-task settlement. Context injected while the summary runs may sit between the marker pair; only the selected span must remain stable.",parameters:[{name:"agent",description:"idle agent whose durable history should be compacted."},{name:"signal",description:"cancellation scoped to this compaction request."},{name:"sourceCommandId",description:"initiating command identity for a manual compaction."}],returns:"the compaction result, or `null` when no safe useful range exists.",throws:["{@link ManualCompactionError} for expected busy, agent-cancellation, changed-span, summarization/shrink, commit-stage, or persistence failures; an aborted request preserves its exact abort reason. Failed attempts remain visible in the log."]},{signature:"abstract compactRegion( start: number, end: number, agent: CompactionAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>",description:"Forcibly compact a range of surface nodes into a single summary node. `start` and `end` name an inclusive span by surface position, not numeric seq order; replacements can make visible seqs non-monotonic. Both edges must be balanced so assistant tool calls remain paired with their results. A model- backed implementation forwards cancellation and rejects active, missing, reversed, or unbalanced ranges. The target session is `agent.session`. Its replacement user message must use compactCheckpointSource with the transaction's `CompactionId`. Use toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks.",parameters:[{name:"start",description:"first surface seq, inclusive."},{name:"end",description:"last surface seq, inclusive."},{name:"agent",description:"context whose session is mutated and whose routing options guide summarization."},{name:"signal",description:"optional cancellation; model-backed implementations must forward it."}],returns:"the appended event seqs, summary, replaced range, and token accounting.",throws:["when compaction is active or the range is missing, reversed, or unbalanced."]}]},{key:"credentials",summary:"Abstract credential service.",description:"Abstract credential service. Providers implement the four operations over their source layers; one seam-wide rule binds them all: an empty stored value is absent everywhere — `resolve` skips it, `describe` reports it unconfigured — so a blank never masquerades as a configured secret.",methods:[{signature:"abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>",description:"Resolve one reference to its current value. Resolution is per call: consumers re-resolve at each operation and must not cache across operations — that per-operation read is what makes a changed credential reach the next operation without a restart.",parameters:[{name:"ref",description:"the reference to resolve."}],returns:"the value and its source, or `undefined` while unconfigured."},{signature:"abstract describe(ref: CredentialRef): Promise<CredentialInfo>",description:"Describe one reference for configuration surfaces without exposing the value.",parameters:[{name:"ref",description:"the reference to describe."}],returns:"configured state, supplying source, and writability."},{signature:"abstract set(ref: CredentialRef, value: string): Promise<void>",description:"Durably store one value in the provider-managed writable source. Rejects while a read-only source shadows the reference — the write would appear to succeed while resolution keeps returning the shadowing value — and rejects an empty value (use unset).",parameters:[{name:"ref",description:"the reference to store."},{name:"value",description:"the non-empty secret value."}]},{signature:"abstract unset(ref: CredentialRef): Promise<void>",description:"Remove one reference from the provider-managed writable source; removing an absent reference is a no-op. Rejects while a read-only source shadows the reference, like set.",parameters:[{name:"ref",description:"the reference to remove."}]}]},{key:"directoryPicker",summary:"Abstract directory-picking service.",description:"Abstract directory-picking service. Subclass, implement `capability()`, and load the subclass as a plugin — it registers as `ctx.directoryPicker` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior). The capability object must be stable for the service lifetime: consumers may capture it across calls.",methods:[{signature:"abstract capability(): DirectoryPickerCapability",description:"The backend's interaction capability.",parameters:[],returns:"the discriminated capability consumers switch on."}]},{key:"e2b",summary:"Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal.",description:"Creates one lazily consumable E2B SDK handle and deletes the sandbox at timeout or disposal. Creation begins at plugin construction; adapters await getSandbox before their first operation.",methods:[{signature:"readonly cwd: string",description:"Validated remote working directory shared by provider adapters.",parameters:[]},{signature:"readonly runtimeRoot: string",description:"Remote directory reserved for adapter-owned process and terminal state.",parameters:[]},{signature:"async getSandbox(): Promise<Sandbox>",description:"Return the shared live SDK handle.",parameters:[],returns:"the created sandbox after the configured cwd exists.",throws:["when E2B rejects creation or the service is disposing."]}]},{key:"fs",summary:"Abstract filesystem provider.",description:"Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.",methods:[{signature:"abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>",description:"Resolve a model/plugin-supplied path into a stable FsTarget. May perform I/O (a remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence async even though the local backend only normalizes + realpaths.",parameters:[{name:"path",description:"the path to resolve; relative paths resolve against `opts.cwd`."},{name:"opts",description:"optional cwd override and cancellation signal."}],returns:"the stable target; the same file yields the same `targetKey`."},{signature:"abstract processPath(target: FsTarget): string",description:"Return the canonical absolute path a subprocess in this filesystem's execution world can open. The path is deliberately separate from FsTarget.targetKey: consumers may pass this value to another OS capability, but must continue treating the target key as opaque.",parameters:[{name:"target",description:"the resolved target whose process path is required."}],returns:"an absolute path in the backend's execution world."},{signature:"abstract fileUrl(target: FsTarget): string",description:"Return the canonical `file:` URI for a target in this filesystem's execution world. Backends own URI encoding because the host platform may differ from the execution platform.",parameters:[{name:"target",description:"the resolved target to encode."}],returns:"the target's canonical file URI."},{signature:"abstract contains(parent: FsTarget, child: FsTarget): boolean",description:"Test canonical containment without exposing or parsing backend target keys. Both targets must come from this provider.",parameters:[{name:"parent",description:"canonical directory target."},{name:"child",description:"canonical candidate target."}],returns:"true when `child` is `parent` or a descendant of it."},{signature:"abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>",description:"Return target metadata, or `undefined` when the target does not exist.",parameters:[{name:"target",description:"the resolved target to stat."},{name:"signal",description:"aborts the metadata round-trip."}],returns:"metadata only, never content; undefined for an absent target."},{signature:"abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>",description:"Return path metadata without following the final path component when it is a symbolic link. This is intentionally path-shaped, not target-shaped: resolve follows symlinks to produce the stable identity used by normal reads/writes, while `lstat` lets a consumer reject the path itself before that follow happens.\n\n`opts.cwd` follows resolve's cwd rules. `undefined` means the path is absent.",parameters:[{name:"path",description:"the path to inspect; relative paths resolve against `opts.cwd`."},{name:"opts",description:"`cwd` overrides the backend's default base for relative paths."},{name:"signal",description:"aborts the metadata round-trip."}],returns:"metadata only, never content; undefined for an absent path."},{signature:"abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>",description:"Read the whole regular text file as a single decoded string.",parameters:[{name:"target",description:"the resolved target to read."},{name:"signal",description:"aborts the read."}],returns:"the full decoded UTF-8 content."},{signature:"abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>",description:"Stream the whole regular text file as decoded text chunks (same text semantics as readText, for large files). The backend owns cross-chunk UTF-8 decoding and binary rejection so the policy layer never touches raw bytes.",parameters:[{name:"target",description:"the resolved target to read."},{name:"signal",description:"aborts the stream, including between chunks."}],returns:"the chunk iterable, decoded and validated like {@link readText}."},{signature:"abstract readBytes(target: FsTarget, signal: AbortSignal | undefined, maxBytes: number): Promise<Uint8Array>",description:"Read the whole regular file as raw bytes with no decoding or binary rejection. The bound lives at this seam so a backend can never buffer an unbounded file: a target known or discovered to exceed `maxBytes` fails with `FS_TOO_LARGE` instead of returning a truncated result.",parameters:[{name:"target",description:"the resolved target to read."},{name:"signal",description:"aborts the read."},{name:"maxBytes",description:"inclusive byte cap on the complete content."}],returns:"the full raw content, at most `maxBytes` long."},{signature:"abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>",description:"List direct children of a directory in stable name order. Returns resolved child targets plus cheap metadata only; never reads file contents.",parameters:[{name:"target",description:"the resolved directory target."},{name:"signal",description:"aborts the listing."}],returns:"one entry per direct child, in stable name order."},{signature:"abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsWriteOutcome>",description:"Atomically create or replace UTF-8 text. `expected` guards intent and staleness; omission allows unconditional overwrite.",parameters:[{name:"target",description:"the resolved target to write."},{name:"content",description:"the full new file content."},{name:"expected",description:"the write intent guarding the write; omit for unconditional."},{name:"signal",description:"aborts before atomic publication takes effect."},{name:"sandboxPolicy",description:"the per-call mode and workspace root this write runs under; a sandboxing backend fences the write by it, the bare backend ignores it. Omit to leave the backend its own default."}],returns:"the outcome, including the version the write produced."},{signature:"abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxPolicy?: SandboxExecutionPolicy, ): Promise<FsEditOutcome>",description:"Atomically edit literal text. When supplied, the version guard is checked before matching so stale content reports `FS_STALE_VERSION`; omission edits the current content without a freshness precondition.",parameters:[{name:"target",description:"the resolved target to edit."},{name:"edit",description:"the literal search/replace request."},{name:"expected",description:"the version guard; omit for an unconditional edit."},{name:"signal",description:"aborts before atomic publication takes effect."},{name:"sandboxPolicy",description:"the per-call mode and workspace root this edit runs under; a sandboxing backend fences the edit by it, the bare backend ignores it. Omit to leave the backend its own default."}],returns:"the outcome, including the version the edit produced."}]},{key:"goals",summary:"Goal service (`ctx.goals`) backed exclusively by the owning session log.",description:"Goal service (`ctx.goals`) backed exclusively by the owning session log.",methods:[{signature:"get(agent: Agent): GoalView | undefined",description:"Read the current goal for one exact live agent.",parameters:[{name:"agent",description:"owning live agent."}],returns:"a fresh view or `undefined` when no goal is current.",throws:["{@link GoalError} when the agent is not the registry's live instance."]},{signature:"disarm(agent: Agent): GoalView | undefined",description:"Remove process-local continuation authority without changing durable goal phase or revision. Lifecycle owners use this before unloading a driver; a later human-authorized resume records the new activation edge.",parameters:[{name:"agent",description:"owning live agent."}],returns:"a fresh disarmed view, or `undefined` when no goal is current."},{signature:"create(agent: Agent, request: CreateGoalRequest): GoalView",description:"Create and arm a goal. A completed goal may be replaced; every other current phase must be cleared or resumed instead.",parameters:[{name:"agent",description:"owning live agent."},{name:"request",description:"objective and optional round cap."}],returns:"the created live view."},{signature:"@Remote('edit') edit(agent: Agent, ref: GoalRef, request: EditGoalRequest): GoalView",description:"Edit objective and/or round cap without changing phase.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."},{name:"request",description:"at least one replacement field."}],returns:"the edited view."},{signature:"@Remote('pause') pause(agent: Agent, ref: GoalRef): GoalView",description:"Pause an active goal and disarm automatic continuation.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the paused view."},{signature:"@Remote('resume') resume(agent: Agent, ref: GoalRef): GoalView",description:"Resume and arm a stopped goal, or rearm an active goal after a session-start edge, while its round budget still has capacity.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the active view."},{signature:"@Remote('complete') complete(agent: Agent, ref: GoalRef): GoalView",description:"Mark a current non-complete goal complete and disarm it.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the completed view."},{signature:"block(agent: Agent, ref: GoalRef, reason: GoalBlockReason): GoalView",description:"Mark an active goal blocked and disarm it.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."},{name:"reason",description:"policy-owned stable code and human-readable explanation."}],returns:"the blocked view with its durable reason."},{signature:"@Remote('clear') clear(agent: Agent, ref: GoalRef): GoalRef",description:"Clear the current goal while retaining a durable tombstone and history.",parameters:[{name:"agent",description:"owning live agent."},{name:"ref",description:"expected current revision."}],returns:"the tombstone ref whose revision is one past the cleared snapshot."},{signature:"@Remote('create') remoteExportCreate(agent: Agent, request: CreateGoalRequest): CreateGoalResult",description:"Create one Goal through the remote boundary.",parameters:[{name:"agent",description:"exact live Agent resolved from the wire identity."},{name:"request",description:"objective and optional round cap."}],returns:"the created Goal identity."}]},{key:"invariants",summary:"Package-owned invariant registry with global and regex-based selection.",description:"Package-owned invariant registry with global and regex-based selection.",methods:[{signature:"register(packageName: string, installer: InvariantInstaller): () => void",description:"Register one package's invariant installer. The package name is reserved even when filtering disables its checks. Enabled installers run in a child fiber; failure disposes that fiber and releases the reservation.",parameters:[{name:"packageName",description:"full npm package name that owns the contribution."},{name:"installer",description:"listener or startup-check installer for the child context."}],returns:"an effect-scoped disposer for the registration."}]},{key:"jobs",summary:"Abstract background job registry.",description:`Abstract background job registry. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as \`ctx.jobs\` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
 Implementations must honor these semantics:
 
@@ -31,7 +31,7 @@ This is not a superset of onJobDone: that one delivers the terminal record under
 
 Repeated observations of an unchanged log return the same revision. A successful mutating load repair changes the next listed revision. Revisions also distinguish independently backed stores so backend-local counters cannot compare equal across different persistence sources.`,parameters:[{name:"signal",description:"optional cancellation for backend snapshot-listing work."}],returns:"one header and opaque revision per materialized session without loading full logs."}]},{key:"sessionProjectionCache",summary:"The persisted projection cache service.",description:"The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.",methods:[{signature:"cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined",description:"The zero-I/O listing read: whole values viewed straight from the stored rows (version-matching keys only), each cut carried with its watermark so a client value store can seed under its higher-seq-wins rule — as stale as the last durable checkpoint but never wrong, and never from an unrelated log (the caller's header is the identity witness). Fresher paths (the history tail baseline, coldSnapshot) supersede these values whenever a session is actually opened.",parameters:[{name:"meta",description:"the listed session's header (identity witness; no log read)."}],returns:"the cut (`asOfSeq` = lowest served-row watermark), or `undefined` when no usable row exists for this lifecycle."},{signature:"async write(session: Session): Promise<void>",description:"Durably checkpoint one live session NOW (both mandatory points call this; tests and carriers may too). The registry cut is snapshotted at this boundary (states are live references), then the whole record is replaced. NOT fail-soft — callers on the fail-soft paths contain it.",parameters:[{name:"session",description:"the live session to checkpoint."}],returns:"resolution after durability and event emission."},{signature:"async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>",description:"Cold-read one persisted session's projections with zero full-log load: cached rows + a persistence `readFrom` tail from the registry's restore floor, refolded by the registry and written back (fail-soft) so the next cold read starts closer. A cache row invalidated by a shrunk log (crash-repair truncation) triggers one full re-read from seq 0 — the ladder's slow rung, still no crash. Rejects when the session has no persisted log (`not found` from the persistence seam).",parameters:[{name:"id",description:"the persisted session to read."},{name:"signal",description:"optional cancellation for the persistence reads."}],returns:"the snapshot cut at the stored log end."}]},{key:"sessionProjections",summary:"`ctx.sessionProjections`: the projection unit table and its drive.",description:"`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected. Registrants sharing a key share one unit and are counted: the same tool package mounted in N agent presets registers N times, and the key survives until the last one unloads.",methods:[{signature:"register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void",description:"Register one domain's unit. The registration is an effect on the calling context's fiber: disposing the fiber (or calling the returned disposer) removes the key — and the unit's cached cells — from subsequent drives and snapshots.",parameters:[{name:"definition",description:"key, state schema, pure unit functions, and stateVersion."}],returns:"the exact disposer that unregisters this unit."},{signature:"onChanged(listener: ProjectionChangeListener): () => void",description:"Subscribe to the change feed. The registration is an effect on the calling context's fiber.",parameters:[{name:"listener",description:"called once per unit whose state reference changed, per committed event."}],returns:"the exact disposer that unsubscribes."},{signature:"snapshot(session: Session): ProjectionSnapshot",description:"One consistent cut over every registered unit for one session, read from the watermark cache (missing cells fold lazily over the in-memory log). Fully synchronous — every value and `asOfSeq` reflect the same log position. Each value passes its unit's schema before leaving.",parameters:[{name:"session",description:"the session whose projection values are read."}],returns:"the snapshot; `values` is empty when no unit is registered."},{signature:"checkpoint(session: Session): ProjectionCheckpoint",description:"State-level checkpoint of every registered unit for one session, read from the watermark cache (missing cells fold lazily over the in-memory log). This is the write side of the persisted projection cache: the returned rows are the `(key → {ver, seq, val})` part of the durable `(sessionId, key, ver, seq, val)` rows. Every `val` is a DETACHED structured clone — never the live cell reference: the watermark cache is this registry's authoritative mutable state, and a caller reaching the live reference could corrupt every subsequent snapshot and frame through it (plain JSON by the unit contract, so the clone is total).",parameters:[{name:"session",description:"the session whose unit states are checkpointed."}],returns:"one row per registered key; empty when no unit is registered."},{signature:"restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined",description:"The stored seq a restore tail read over `checkpoint` must start at: one event BELOW the lowest usable watermark (a row is usable when its `ver` matches the live unit's `stateVersion`; an absent or mismatched row pulls the floor to `0` — that key must refold the full log). The one-below anchor is load-bearing: the tail then proves how far the stored log still extends, so restore can detect a log that shrank below a row's watermark (crash-repair truncation) instead of serving the stale row as current — an empty tail read from the anchor yields an end below every watermark and the restore rejects for a full re-read.",parameters:[{name:"checkpoint",description:"persisted rows for one session (possibly stale or empty)."}],returns:"the seq to hand the persistence `readFrom`, or `undefined` when no unit is registered (no read needed — {@link restore} would serve empty values regardless)."},{signature:"viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>",description:"View a checkpoint's rows without any log read: for every registered unit whose row's `ver` matches, serve the schema-validated `view` of the stored state; mismatched or absent rows leave their key absent (a cold or listing consumer treats it as not-yet-available and a fuller read path refolds it). The zero-I/O rung of the read ladder — values are as stale as their rows, never wrong.",parameters:[{name:"checkpoint",description:"persisted rows for one session (possibly stale or empty)."}],returns:"whole values per key with a usable row; empty when none."},{signature:"restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }",description:"Cold read: fold every registered unit over a stored log suffix, seeding each from its checkpoint row when usable — the one read recipe (cached state + forward tail replay + `view`) applied without a live `Session`. Call with the events returned by a persistence `readFrom(id, restoreFloor(checkpoint))` and that same floor as `baseSeq`; the floor's one-below anchor makes the supplied end honest, so a shrunk log is detected here. A row is usable iff its `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq` (`seq >= baseSeq - 1`), and it does not claim events past the supplied end (`seq <= endSeq`); an unusable row is discarded and its key refolds from `init` — which is only sound over the full log, so a discarded row with `baseSeq > 0` throws (the caller re-reads from seq 0, e.g. after a crash-repair truncation shrank the log below a row's watermark).",parameters:[{name:"checkpoint",description:"persisted rows for one session (possibly stale or empty)."},{name:"events",description:"the stored events with `seq >= baseSeq`, in seq order."},{name:"baseSeq",description:"the seq `events` starts at (its first event's seq when non-empty)."}],returns:"the snapshot cut at the supplied log end (`asOfSeq` is the last supplied event's seq, `baseSeq - 1` for an empty tail) plus the refreshed checkpoint rows at that cut, ready for a durable write-back."}]},{key:"sessionQuery",summary:"Unified live-preferred session query service.",description:"Unified live-preferred session query service.\n\nExact reads, filters, and traces are backend-independent concrete behavior. A backend implements full-text observation, reconciliation, ranking, cursor generations, and query execution on the same `ctx.sessionQuery` service.",methods:[{signature:"abstract searchSessions( request: SessionSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionSearchPage<SessionSearchHit>>",description:"Search the live-preferred logical corpus and group by session.",parameters:[{name:"request",description:"query text, metadata filters, page size, and cursor."},{name:"exec",description:"optional cancellation control."}],returns:"session hits ranked by their strongest matching event."},{signature:"abstract searchEvents( request: SessionEventSearchRequest, exec?: SessionSearchExecContext, ): Promise<SessionEventSearchPage>",description:"Search events within one live-preferred logical session.",parameters:[{name:"request",description:"target session, query text, filters, page size, and cursor."},{name:"exec",description:"optional cancellation control."}],returns:"matching event hits and their target header from one indexed generation."},{signature:"listSessions(signal?: AbortSignal): Promise<SessionRecord[]>",description:"List the complete logical corpus using live-preferred records.",parameters:[{name:"signal",description:"optional cancellation for persistence listing."}],returns:"deterministic newest-first cloned session records."},{signature:"async readSession(sessionId: SessionId): Promise<SessionLogSnapshot>",description:"Read and replay-validate one complete logical session log without making it live.",parameters:[{name:"sessionId",description:"live or persisted session id to read."}],returns:"cloned header and complete raw event log from one observation.",throws:["when persistence, header compatibility, or replay validation fails."]},{signature:"async filterSessions( filters: readonly SessionResultFilter[], signal?: AbortSignal, ): Promise<SessionRecord[]>",description:"Filter the complete logical corpus with provider-independent predicates.",parameters:[{name:"filters",description:"ANDed session metadata and availability clauses."},{name:"signal",description:"optional cancellation for persistence listing."}],returns:"matching cloned records in deterministic newest-first order."},{signature:"async readTitle( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleSnapshot | undefined>",description:"Fold the latest log-backed title from one live-preferred logical session.",parameters:[{name:"sessionId",description:"live or persisted session id to read."},{name:"signal",description:"optional cancellation for source resolution and title folding."}],returns:"latest title snapshot, or `undefined` when the log has no title event."},{signature:"async readTitleSnapshot( sessionId: SessionId, signal?: AbortSignal, ): Promise<SessionTitleObservation>",description:"Fold the latest title and return its source header from one corpus observation.",parameters:[{name:"sessionId",description:"live or persisted session id to read."},{name:"signal",description:"optional cancellation for source resolution and title folding."}],returns:"cloned source header and optional latest title snapshot."},{signature:"async readTitleSnapshots( sessionIds: readonly SessionId[], signal?: AbortSignal, ): Promise<SessionTitleObservationResult[]>",description:`Fold titles for unique sessions from one cancellable corpus observation.
 
-Results preserve first-occurrence input order. Operational failures stay isolated per session, while cancellation rejects the complete operation.`,parameters:[{name:"sessionIds",description:"live or persisted session ids to observe."},{name:"signal",description:"optional cancellation shared by all source reads."}],returns:"one fulfilled or rejected result per unique requested id."},{signature:"async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>",description:"List lightweight raw-log event records for one logical session.",parameters:[{name:"sessionId",description:"live-preferred session id to read."}],returns:"event records in ascending seq order."},{signature:"async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>",description:"Scan first-party semantic event documents with provider-independent filters.",parameters:[{name:"sessionId",description:"live-preferred session id to scan."},{name:"filters",description:"ANDed metadata and literal-text predicates."}],returns:"matching semantic documents in ascending seq order."},{signature:"async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>",description:"Read one session's complete current model surface from one corpus observation.",parameters:[{name:"sessionId",description:"live-preferred session id to read."}],returns:"cloned header, current surface, and the last sequence number included in the raw-log capture.",throws:["when source resolution fails or the session surface is invalid."]},{signature:"async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>",description:"Trace known ancestry and descendants from one corpus observation.",parameters:[{name:"sessionId",description:"logical session id to trace."},{name:"signal",description:"optional cancellation for persistence listing."}],returns:"a complete lineage or the first parent that could not be resolved.",throws:["when corpus resolution fails, the target is absent, or its known ancestry cycles."]},{signature:"async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>",description:"Trace one event's direct positional replacements and cited source events.",parameters:[{name:"request",description:"target session id and event seq."},{name:"signal",description:"optional cancellation for persisted source resolution."}],returns:"source header, direct links, and the target's positional replacement chain.",throws:["when source resolution fails, the target is absent, or surface/source-event validation fails."]},{signature:"async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>",description:"Read one full event plus a bounded raw-log context window.",parameters:[{name:"request",description:"target session/seq and context sizes."},{name:"signal",description:"optional cancellation for persisted source resolution."}],returns:"cloned target and neighboring events."}]},{key:"sessionReferenceResolver",summary:"Exact-read consumer that prepares immutable cross-session message context.",description:"Exact-read consumer that prepares immutable cross-session message context.",methods:[{signature:"async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>",description:"List reference candidates, ranked by working-directory affinity.",parameters:[{name:"agent",description:"target agent; self is excluded and its cwd drives ranking."},{name:"query",description:"optional case-insensitive session-id/cwd/title substring."},{name:"limit",description:"optional positive result cap."},{name:"signal",description:"optional cancellation boundary for host autocomplete teardown."}],returns:"candidates labeled by latest title or, when absent, session id."},{signature:"async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>",description:"Snapshot all references before enqueue and return one aggregated durable context.",parameters:[{name:"agent",description:"target agent; references to it are rejected."},{name:"content",description:"already host-normalized readable message content."},{name:"references",description:"structured source sessions in mention order."},{name:"signal",description:"optional cancellation boundary for host request teardown."}],returns:"detached content and optional referenced-session context."}]},{key:"sessions",summary:"In-memory session store (`ctx.sessions`).",description:"In-memory session store (`ctx.sessions`).\n\nPersistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.",methods:[{signature:"create(id?: SessionId, options?: CreateSessionOptions): Session",description:"Create a session owned by the calling fiber: disposing that fiber stops event notification and removes the session from the store. `options.seed` populates the session with a copy of those events (replay/fork); `options.meta` attaches creation metadata (validated absolute `cwd`, seed and parent lineage, and delegation depth) as the immutable SessionHeader (the store fills `version`/`id`/`createdAt`).\n\nFor an agent whose session must be torn down IN ORDER with its loop (so the loop's final events are published before the store attachment ends), do NOT use this — fold the session lifecycle into the agent's own effect via prepare + enter + announce (see `dsh-agent-loop`'s creation transaction).",parameters:[{name:"id",description:"the session id; omitted, the store mints `session-<n>`."},{name:"options",description:"seed events and/or creation metadata for the header."}],returns:"the live session, already entered and announced.",throws:["if a session with `id` already exists, metadata is not a plain lossless-JSON record with valid scalar fields, or `meta.cwd` is a non-absolute path (storage backends key directories off it)."]},{signature:"prepare(id?: SessionId, options?: PrepareSessionOptions): Session",description:"Build a session WITHOUT entering it into the store — validate the id/cwd and construct the Session (with its immutable SessionHeader). Pairs with enter + announce: a caller that owns a composite `ctx.effect` (the agent factory) folds the session lifecycle into that ONE effect so a fiber unload tears the session + agent down as a single ORDERED chain rather than as racing sibling effects — which would remove the publication hooks before the driver's closing events commit, dropping them.",parameters:[{name:"id",description:"the session id; omitted, the store mints `session-<n>`."},{name:"options",description:"seed events and/or creation metadata for the header. With `seedSource: 'persistence'`, metadata and events must be fresh detached graphs whose ownership transfers to this call: they are validated and frozen in place through {@link Session.fromRestore}, so the caller must retain no mutable aliases."}],returns:"the constructed session, NOT yet in the store.",throws:["if a session with `id` already exists, metadata is not a plain lossless-JSON record with valid scalar fields, or `meta.cwd` is a non-absolute path."]},{signature:"enter(session: Session): () => void",description:"Enter a prepared session into the store: install the module-private append publication hooks and add it to the store. Returns the DETACH disposer (hooks + store removal). Does NOT emit `session/created` — the caller yields this disposer inside its effect and THEN calls announce, so a throwing `session/created` listener rolls the attach back instead of leaking it.\n\nRe-checks the id for a duplicate: `prepare` and `enter` are public cross-package primitives and a caller may interleave arbitrary work (or another create) between them, so a stale prepared session must NOT overwrite a live store entry of the same id — its detach disposer would later delete the REAL session. The create convenience and the agent factory call the two back-to-back so they never trip this, but the public API cannot assume that.",parameters:[{name:"session",description:"a {@link prepare}d session not yet in the store."}],returns:"the detach disposer (publication hooks + store removal). When called from a synchronous `session/created` listener, removal and disposal wait until that creation dispatch unwinds.",throws:["if a session with this id is already in the store."]},{signature:"announce(session: Session): void",description:"Emit `session/created` exactly once for an entered session (with the carrier enter captured). Separate from enter so the caller can yield the detach disposer first (rollback safety — see enter).",parameters:[{name:"session",description:"the entered session to announce to listeners."}],throws:["if the session is not live or its announcement already began, including a reentrant call from a creation listener."]},{signature:"async flush(session: Session): Promise<boolean>",description:"Dispatch the awaited `session/flush` durability checkpoint for `session`, with the carrier captured at enter. THE flush entry point: the store owns the carrier, so callers (the checkpoint policy's per-request barrier, goal-round-driver's idle checkpoint, teardown drains, and consumers that flush themselves before reading storage) must come through here rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner, one spelling, and the scoped-dispatch invariant can pin it.",parameters:[{name:"session",description:"the session whose buffered events must reach durable storage."}],returns:"whether at least one durability listener participated, after every listener has settled successfully.",throws:["the first registered listener failure after every listener settles."]},{signature:"get(id: SessionId): Session | undefined",description:"Look up a live session.",parameters:[{name:"id",description:"the session id to look up."}],returns:"the session, or undefined when no live session has that id."},{signature:"list(): Session[]",description:"All live sessions, in creation order.",parameters:[],returns:"a fresh array; mutating it does not affect the store."},{signature:"fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session",description:"Create a live child session from a stable prefix of a live source. `boundary` is an inclusive source event seq; omitted means the source's current last event. The selected slice may end with a between-turn event but must not end inside an open turn.",parameters:[{name:"source",description:"Live source session object or id."},{name:"boundary",description:"Inclusive source event seq to fork through; omitted means the source's current last event, and omitted on an empty source forks an empty child."},{name:"childSessionId",description:"Optional child session id; omitted delegates to `SessionStore`'s id policy."}],returns:"The created live child session."}]},{key:"sessionTelemetry",summary:"Loadable form of the backend contract: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior.",description:"Loadable form of the backend contract: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a SessionTelemetryCoordinator in its constructor to install the capture side.",methods:[{signature:"abstract readonly sharing: SessionTelemetrySharingStatus",description:'Deployment-selected session-sharing policy, disclosed for acknowledgement surfaces that report whether recorded feedback leaves the process. Every backend must disclose its policy; a consumer renders "not configured" only when no telemetry service is mounted. The seam owns this vocabulary so the disclosure is backend-independent.',parameters:[]},{signature:"abstract emit(record: SessionTelemetryRecord): void",description:"See SessionTelemetrySink.emit — that declaration is the contract's one home.",parameters:[{name:"record",description:"the logical record to report; owned by the backend after the call."}]},{signature:"flush?(): void",description:"See SessionTelemetrySink.flush.",parameters:[]},{signature:"abstract shutdown(): Promise<void>",description:"See SessionTelemetrySink.shutdown.",parameters:[],returns:"resolves when the backend's pipeline has quiesced."}]},{key:"sessionTitle",summary:"Log-backed title fold plus asynchronous fallback generation.",description:"Log-backed title fold plus asynchronous fallback generation.",methods:[{signature:"get(session: Session): SessionTitleSnapshot | undefined",description:"Read the latest folded title from one live or replayed session.",parameters:[{name:"session",description:"session whose log is the title source of truth."}],returns:"latest title snapshot, or `undefined` before eligible input."},{signature:"rename(session: Session, title: string): SessionTitleSnapshot",description:"Accept an explicit user title. Appends a `session/title` event with the `user` source, which pins the title: in-flight automatic generation is superseded and later user messages schedule none (an explicit SessionTitleService.refresh remains the deliberate unpin).",parameters:[{name:"session",description:"exact live session to rename."},{name:"title",description:"raw user input; normalized before acceptance."}],returns:"the accepted title snapshot.",throws:["{SessionTitleInvalidError} when the title normalizes to empty.","{Error} when the session is not live or the service is disposed."]},{signature:"async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>",description:"Explicitly retry the registered provider, or materialize the built-in fallback when no provider is registered.",parameters:[{name:"session",description:"exact live session to refresh."},{name:"signal",description:"optional caller cancellation."}],returns:"latest accepted title, or `undefined` when no eligible text exists."},{signature:"register(provider: SessionTitleProvider): () => Promise<void>",description:"Register the sole optional title provider. Disposal aborts its pending and active work before another provider may register.",parameters:[{name:"provider",description:"provider identity, cadence, and generation function."}],returns:"exact Cordis effect disposer, which settles after active calls quiesce."}]},{key:"settings",summary:"Abstract settings service.",description:"Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.",methods:[{signature:"abstract readonly writable: boolean",description:"Whether update may persist through this provider.",parameters:[]},{signature:"prepareDocument(): Promise<string | undefined>",description:"Prepare the provider's user-editable document for a native editor. File providers may materialize an absent document before returning its path; non-file providers return undefined.",parameters:[],returns:"the absolute local document path, or undefined for non-file storage."},{signature:"register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>",description:"Register a namespace schema and receive its owner scope. The registration is an effect on the calling plugin's fiber: disposing that fiber removes the namespace and its observers. An invalid stored section fails the registration itself — the earliest point where the schema can judge it.",parameters:[{name:"ns",description:"unique namespace; duplicate registration fails loud."},{name:"schema",description:"schemastery schema resolving this namespace's value."},{name:"options",description:"composition `base` layer and effect timing."}],returns:"the owner scope for reads, observation, and updates."},{signature:"describe(options?: SettingsDescribeOptions): SettingsDescriptor[]",description:"Describe every registered namespace for configuration surfaces, including the composition `base` and raw user layers so a form can mark which fields the user overrode (presence in `user`) and what a reset returns to.",parameters:[{name:"options",description:"redaction switch; wire surfaces must redact."}],returns:"one descriptor per registered namespace, in registration order."},{signature:"get(ns: SettingsNamespace): unknown",description:"Read one registered namespace's resolved value.",parameters:[{name:"ns",description:"the namespace to read."}],returns:"the resolved value, or `undefined` while unregistered."},{signature:"async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>",description:"Merge a patch into one registered namespace's user layer, validate the resolved candidate, persist through the provider, then commit and emit. A validation failure rejects before anything is persisted. Writes to one namespace are serialized: concurrent updates apply in call order, each merging over the previous write's committed section.",parameters:[{name:"ns",description:"the registered namespace to update."},{name:"patch",description:"plain-object patch over the user section."},{name:"expectedRevision",description:"the descriptor `revision` the caller read; a namespace that moved past it rejects with {@link SettingsConflictError}."}]},{signature:"async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>",description:"Replace one registered namespace's user section wholesale, validate, persist, then commit and emit. Keys absent from `section` fall back to the composition `base` and schema defaults — this is the removal/reset path a merge-only patch cannot express (`replace({})` re-inherits everything).",parameters:[{name:"ns",description:"the registered namespace to replace."},{name:"section",description:"the complete next user section."},{name:"expectedRevision",description:"the descriptor `revision` the caller read; a namespace that moved past it rejects with {@link SettingsConflictError}."}]},{signature:"async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>",description:"Apply path-addressed edits to one registered namespace's user section, validate, persist, then commit and emit. The ops are applied to the section as it stands when the write reaches the front of the queue, so a caller never has to restate fields it did not touch — and, crucially, cannot delete fields it never saw. This is the write path for any caller holding a redacted view; `replace` remains the wholesale reset.",parameters:[{name:"ns",description:"the registered namespace to edit."},{name:"ops",description:"ordered path edits; later ops observe earlier ones."},{name:"expectedRevision",description:"the descriptor `revision` the caller read; a namespace that moved past it rejects with {@link SettingsConflictError}."}]}]},{key:"shell",summary:"Abstract bash execution service.",description:"Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.shell` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a ShellRunResult.\n- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.\n- ShellProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.\n- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.",methods:[{signature:"abstract resolve(request: ShellExecRequest): ShellExecSpec",description:"Apply implementation-owned defaults and caps to a request before execution.",parameters:[{name:"request",description:"the caller's request; omitted fields get this implementation's defaults, capped fields are clamped."}],returns:"the fully-specified spec to hand to {@link run}/{@link start}."},{signature:"abstract run(spec: ShellExecSpec): Promise<ShellRunResult>",description:"Run a command in the foreground; resolves when it finishes.",parameters:[{name:"spec",description:"a resolved spec from {@link resolve}, never a raw request."}],returns:"the outcome; nonzero exits, timeout kills, and abort kills resolve with a descriptive result rather than reject."},{signature:"abstract start(spec: ShellExecSpec): ShellProcess",description:"Start a background process and return its handle immediately.",parameters:[{name:"spec",description:"a resolved spec from {@link resolve}, never a raw request."}],returns:"the live process handle (reads, kill, quiescence promise)."}]},{key:"shellEnv",summary:"Registry (`ctx.shellEnv`) for trusted, per-execution `QBOT_DSH_*` variables.",description:"Registry (`ctx.shellEnv`) for trusted, per-execution `QBOT_DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `QBOT_DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.",methods:[{signature:"register(contributor: BashEnvContributor): () => void",description:"Register one environment contributor. Names and keys are unique; built-in keys are reserved. Registration is disposed with the calling plugin fiber.",parameters:[{name:"contributor",description:"declared key ownership and per-execution resolver."}],returns:"the disposer that unregisters the contribution."},{signature:"collect(execution: ToolExecution): DshEnvironment",description:"Build the trusted `QBOT_DSH_*` snapshot for one shell tool execution.",parameters:[{name:"execution",description:"the current tool execution."}],returns:"an immutable environment overlay containing built-ins and current contributions."},{signature:"list(): BashEnvVariableInfo[]",description:"Enumerate plugin-contributed variables without executing their resolvers.",parameters:[],returns:"declarations sorted by environment variable name."}]},{key:"skills",summary:"Layered registry of skill providers, the host+per-scope shape the tools registry established.",description:"Layered registry of skill providers, the host+per-scope shape the tools registry established. A registration files into the layer of its calling context's scope (scopeOf): host rows and repository plugins land in the global layer, while a plugin mounted by an agent preset's standing composition lands in that preset's layer. A read merges the global layer with the viewing scope's chain — the nearest layer's entry wins a duplicate name outright, and the rank order decides duplicates only within one layer. It exposes sorted invocation-neutral summaries and loads full skill bodies on demand.",methods:[{signature:"registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void",description:"Register a borrowed same-process provider synchronously during plugin apply, into the calling context's layer: a scoped context (an agent preset's standing mount) registers for that scope alone, an unscoped context registers globally. Duplicate names within one layer and reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters the provider and invalidates catalog caches.",parameters:[{name:"create",description:"synchronous factory receiving this registration's lifecycle and invalidation control."}],returns:"the exact Cordis effect disposer that unregisters this provider; composite effects may yield it directly to preserve teardown ordering."},{signature:"register(skill: SkillRegistration): () => void",description:"Register a borrowed readonly runtime skill into the calling context's layer. Project entries outrank runtime entries, which outrank user entries, within one layer. Same-name runtime entries in one layer are first-wins; a duplicate logs a warning and receives a no-op disposer so it cannot remove the winner.",parameters:[{name:"skill",description:"the skill definition input; omitted invocation and provider fields receive defaults."}],returns:"the exact Cordis effect disposer, preserving composite teardown order and invalidating caches."},{signature:"async list(options: SkillViewOptions = {}): Promise<SkillSummary[]>",description:"List invocation-neutral skill summaries for a workspace. Consumers apply model or user invocation policy at their operational boundary. Lookup options and provider candidates are readonly same-process values borrowed throughout discovery.",parameters:[{name:"options",description:"view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery."}],returns:"all sorted winning summaries."},{signature:"async snapshot(options: SkillViewOptions = {}): Promise<SkillCatalogSnapshot>",description:"Observe the current invocation-neutral catalog and whether discovery completed within a stable revision. Incomplete observations are never cached, allowing consumers to retain last-good state and retry on their next request boundary.",parameters:[{name:"options",description:"view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery."}],returns:"sorted summaries plus discovery-completeness state."},{signature:"async get(name: string, options: SkillViewOptions = {}): Promise<SkillDefinition | undefined>",description:"Load and validate the winning candidate, passing its opaque discovery locator back to the provider. Cancellation is rechecked after selection, including cache hits, and raced against loading so an uncooperative provider cannot hang the caller.",parameters:[{name:"name",description:"kebab-case skill name."},{name:"options",description:"view options; `scope` selects the viewing agent's layers, `cwd` selects workspace-sensitive skills, and `signal` cancels work."}],returns:"the full skill, including body content, or `undefined`."}]},{key:"spillStore",summary:"Abstract spill storage service.",description:"Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).\n\nSemantics every implementation must honor:\n\n- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.\n- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.\n- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).",methods:[{signature:"abstract saveText(input: SaveTextSpill): Promise<SpillRef>",description:"Persist `input.content` to a session-scoped spill artifact.",parameters:[{name:"input",description:"the owner, caller-supplied source fields, suggested name, and full text to save."}],returns:"the saved artifact's {@link SpillRef}; rejects on a storage failure."}]},{key:"storage",summary:"The storage hub service.",description:"The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.",methods:[{signature:"readonly backend: BackendRegistry = new BackendRegistry()",description:"Named backend table; multiple backends stay mounted side by side.",parameters:[]},{signature:"mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void",description:"Mount a data-form facility on the hub. Mounting is an effect: the returned disposer unmounts the form.",parameters:[{name:"form",description:"Form key declared in {@link StorageForms}."},{name:"facility",description:"The facility instance to expose."}],returns:"the disposer that unmounts the form."},{signature:"form<K extends keyof StorageForms>(form: K): StorageForms[K]",description:"Resolve a mounted data form.",parameters:[{name:"form",description:"Form key declared in {@link StorageForms}."}],returns:"the mounted facility."}]},{key:"storageDomain",summary:"The mounted domain facility.",description:"The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.",methods:[{signature:"async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>",description:"Open one declared domain. Steps, each failing the whole call: reject a name that is already open (`already-open`); resolve the backend route (`backend-not-found` passes through from the hub); require its `kv` facet (`facet-unsupported`); open the unit projected from the spec (backend `version-mismatch`/`malformed-medium` pass through); load and validate every stored record against the spec's zod schemas (`invalid-record` with the offending table and key); construct the domain.\n\nLifecycle: the CALLER owns the returned handle and closes it via `Domain.close()` (typically as its own `ctx.effect` disposer) — the facility does not tie the domain to any consumer fiber. Domains still open when the facility unmounts are closed by the plugin disposer.",parameters:[{name:"spec",description:"The domain declaration, typically from `defineDomain`."}],returns:"the opened domain handle, typed by the spec."},{signature:"get(name: string): DomainImpl | undefined",description:"Look up an open domain by name, untyped. Diagnostic surface (the package invariant cross-checks change events against live domain state); typed consumers hold the handle returned by open.",parameters:[{name:"name",description:"Domain name."}],returns:"the open domain runtime, or `undefined` when not open."},{signature:"async closeAll(): Promise<void>",description:"Close every domain still open on this facility. The unmount path for consumers that never called `Domain.close()` themselves; closing is idempotent, so double-closing an already-closed domain is harmless.",parameters:[],returns:"resolution after every unit is released."}]},{key:"subagents",summary:"Named provider registry with one-shot runs, durable discovery, and continuable-child operations.",description:"Named provider registry with one-shot runs, durable discovery, and continuable-child operations.",methods:[{signature:"async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>",description:"Establish one durable continuable child and deliver its initial prompt. Resolves when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls back the child entirely.",parameters:[{name:"spec",description:"provider, delegation request, and caller cancellation."}],returns:"the durable child id and the accepted prompt's message id.",throws:["when continuation services are unavailable or materialization fails."]},{signature:"async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>",description:"Deliver one later message to a continuable child as its next FIFO turn. A resident child's Agent inbox accepts it directly (waking a `waiting` Activation), while an absent one is cold-resumed from its persisted Session. The Agent inbox is the only queue, so every accepted message has one observable order.",parameters:[{name:"parent",description:"the exact live direct parent authorizing this delivery."},{name:"childId",description:"durable child session id."},{name:"content",description:"user-role content to deliver."},{name:"options",description:"the message source fields and caller cancellation, which stops the operation only before inbox acceptance."}],returns:"the accepted message's inbox id.",throws:["when continuation services are unavailable, parent authority is rejected, or the message was not admitted."]},{signature:"interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void",description:"Interrupt one live continuable child's current turn under a human parent address or an exact live ancestor Agent. Fire-and-return: the cancel signal is issued before this returns, but the target may keep running until it observes the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; claimed work is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — including a one-shot or unknown id — is an accepted no-op, as is a manager-less composition, which cannot own a live Activation.",parameters:[{name:"targetSessionId",description:"the durable child session id to interrupt."},{name:"authority",description:"the human parent address or exact live ancestor Agent."}],throws:["{SubagentError} `UNAUTHORIZED` when the authority does not own the live target."]},{signature:"async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>",description:"Deliver selected content from one live continuable child to its durable direct parent. The child is the authority credential; callers cannot name a recipient. Reporting does not conclude the child's turn or Activation.",parameters:[{name:"child",description:"exact live reporting child."},{name:"content",description:"selected model-facing content."},{name:"options",description:"parent scheduling and pre-acceptance cancellation."}],returns:"the stable identity of the parent-accepted message.",throws:["when continuation services are unavailable, sender authorization fails, or the direct parent is not live."]},{signature:"registerContinuableSetup(contribution: ContinuableSetupContribution): () => void",description:"Compose one deployment capability into every continuable child's unpublished creation context on fresh creation and cold resume. Grants wait for the next Activation; removing the contribution revokes every resident installation immediately.",parameters:[{name:"contribution",description:"synchronous child-scope installer."}],returns:"the exact Cordis effect disposer."},{signature:"async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>",description:"Close continuable admission below exact live parent Agents, stop only their visible descendant Activations synchronously, then await admitted scoped materializations and release those forests child-first. The scoped cutoff lasts until each exact parent leaves the registry; unrelated parent trees remain live.",parameters:[{name:"parents",description:"exact host-owned parent Agents entering teardown."}],returns:"once every retained descendant Activation released its `AgentHandle`.",throws:["an aggregate error after all branches settle when any failed."]},{signature:"listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>",description:"Enumerate the parent's direct session-backed subagents without loading or resuming an Agent and without any query service: the listing merges the live session store with optional session persistence (live-preferred) and serves each child's durable mode/label from the registered `subagent` projection unit down a three-rung ladder — the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when the optional cache serves an own-suffix identity (its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended), else one persistence inspection folded through the registry. The projection fold is the single classification authority; per-child diagnostics relay a fold that served no identity or a failed inspection, never a list-time descriptor parse. Absent persistence, enumeration is live-only (a cold child cannot be resumed then either, so its absence is capability absence, not an error). This service consults no Agent registrations, Activations, or providers.\n\nEvery persistence read receives `signal`, and the listing rechecks cancellation around each of those awaits. Read rejections that settle after an abort become a stable `SubagentError` with code `CANCELLED`.",parameters:[{name:"parentSessionId",description:"parent session whose direct children are listed."},{name:"signal",description:"caller-owned cancellation forwarded to persistence reads and observed around every read await."}],returns:"children and per-child diagnostics ordered by `createdAt`, then id.",throws:["{@link SubagentError} when the projection registry or the session store is not mounted, or the caller cancels the listing."]},{signature:"listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>",description:"Enumerate the root's complete session-backed subagent tree in stable pre-order from one live-preferred corpus, without loading or resuming an Agent. Ordinary sessions and one-shot children remain traversal nodes so continuable descendants below them are discovered; each returned entry adds its durable `parentId` and root-relative `depth`. Identity resolution, diagnostics, optional persistence, and cancellation follow the same projection-backed contract as listChildren.",parameters:[{name:"rootSessionId",description:"session whose complete descendant tree is listed."},{name:"signal",description:"caller-owned cancellation forwarded to persistence reads and observed around every read await."}],returns:"children and per-candidate diagnostics with tree position, in stable pre-order.",throws:["{@link SubagentError} under the same conditions as {@link listChildren}."]},{signature:"registerProvider(provider: SubagentProvider): () => void",description:"Register a provider under its name. Registration is effect-scoped and HMR safe; removing a provider blocks new starts but does not revoke runs that were already returned to their holders.",parameters:[{name:"provider",description:"the trusted provider implementation."}],returns:"the exact Cordis effect disposer."},{signature:"getProvider(name: string): SubagentProvider | undefined",description:"Look up a provider by name.",parameters:[{name:"name",description:"the provider name."}],returns:"the provider, or undefined when absent."},{signature:"list(): string[]",description:"List registered provider names in insertion order.",parameters:[],returns:"the registered names."},{signature:"async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>",description:"Establish a published child on the named provider. Capability and semantic checks run before delegation. Provider ownership lasts until its promise fulfills; a rejection therefore has no run for the caller to dispose and emits no run lifecycle events. Post-publication turn and infrastructure failures settle through the returned run.",parameters:[{name:"name",description:"the provider to use."},{name:"request",description:"child label, prompt, parent, signal, and optional capabilities."}],returns:"the published holder-owned run."}]},{key:"subprocess",summary:"Abstract subprocess service.",description:`Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as \`ctx.subprocess\` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
+Results preserve first-occurrence input order. Operational failures stay isolated per session, while cancellation rejects the complete operation.`,parameters:[{name:"sessionIds",description:"live or persisted session ids to observe."},{name:"signal",description:"optional cancellation shared by all source reads."}],returns:"one fulfilled or rejected result per unique requested id."},{signature:"async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>",description:"List lightweight raw-log event records for one logical session.",parameters:[{name:"sessionId",description:"live-preferred session id to read."}],returns:"event records in ascending seq order."},{signature:"async filterEvents( sessionId: SessionId, filters: readonly SessionEventResultFilter[], ): Promise<SessionEventSearchDocument[]>",description:"Scan first-party semantic event documents with provider-independent filters.",parameters:[{name:"sessionId",description:"live-preferred session id to scan."},{name:"filters",description:"ANDed metadata and literal-text predicates."}],returns:"matching semantic documents in ascending seq order."},{signature:"async readSurface(sessionId: SessionId): Promise<SessionSurfaceSnapshot>",description:"Read one session's complete current model surface from one corpus observation.",parameters:[{name:"sessionId",description:"live-preferred session id to read."}],returns:"cloned header, current surface, and the last sequence number included in the raw-log capture.",throws:["when source resolution fails or the session surface is invalid."]},{signature:"async traceSession(sessionId: SessionId, signal?: AbortSignal): Promise<SessionLineageTrace>",description:"Trace known ancestry and descendants from one corpus observation.",parameters:[{name:"sessionId",description:"logical session id to trace."},{name:"signal",description:"optional cancellation for persistence listing."}],returns:"a complete lineage or the first parent that could not be resolved.",throws:["when corpus resolution fails, the target is absent, or its known ancestry cycles."]},{signature:"async traceEvent(request: SessionEventTraceRequest, signal?: AbortSignal): Promise<SessionEventTraceObservation>",description:"Trace one event's direct positional replacements and cited source events.",parameters:[{name:"request",description:"target session id and event seq."},{name:"signal",description:"optional cancellation for persisted source resolution."}],returns:"source header, direct links, and the target's positional replacement chain.",throws:["when source resolution fails, the target is absent, or surface/source-event validation fails."]},{signature:"async readEvent(request: SessionEventReadRequest, signal?: AbortSignal): Promise<SessionEventWindow>",description:"Read one full event plus a bounded raw-log context window.",parameters:[{name:"request",description:"target session/seq and context sizes."},{name:"signal",description:"optional cancellation for persisted source resolution."}],returns:"cloned target and neighboring events."}]},{key:"sessionReferenceResolver",summary:"Exact-read consumer that prepares immutable cross-session message context.",description:"Exact-read consumer that prepares immutable cross-session message context.",methods:[{signature:"async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>",description:"List reference candidates, ranked by working-directory affinity.",parameters:[{name:"agent",description:"target agent; self is excluded and its cwd drives ranking."},{name:"query",description:"optional case-insensitive session-id/cwd/title substring."},{name:"limit",description:"optional positive result cap."},{name:"signal",description:"optional cancellation boundary for host autocomplete teardown."}],returns:"candidates labeled by latest title or, when absent, session id."},{signature:"async prepare( agent: Agent, content: ContentBlock[], references: SessionReferenceInput[], signal?: AbortSignal, ): Promise<PreparedReferencedMessage>",description:"Snapshot all references before enqueue and return one aggregated durable context.",parameters:[{name:"agent",description:"target agent; references to it are rejected."},{name:"content",description:"already host-normalized readable message content."},{name:"references",description:"structured source sessions in mention order."},{name:"signal",description:"optional cancellation boundary for host request teardown."}],returns:"detached content and optional referenced-session context."}]},{key:"sessions",summary:"In-memory session store (`ctx.sessions`).",description:"In-memory session store (`ctx.sessions`).\n\nPersistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose.",methods:[{signature:"create(id?: SessionId, options?: CreateSessionOptions): Session",description:"Create a session owned by the calling fiber: disposing that fiber stops event notification and removes the session from the store. `options.seed` populates the session with a copy of those events (replay/fork); `options.meta` attaches creation metadata (validated absolute `cwd`, seed and parent lineage, and delegation depth) as the immutable SessionHeader (the store fills `version`/`id`/`createdAt`).\n\nFor an agent whose session must be torn down IN ORDER with its loop (so the loop's final events are published before the store attachment ends), do NOT use this — fold the session lifecycle into the agent's own effect via prepare + enter + announce (see `dsh-agent-loop`'s creation transaction).",parameters:[{name:"id",description:"the session id; omitted, the store mints `session-<n>`."},{name:"options",description:"seed events and/or creation metadata for the header."}],returns:"the live session, already entered and announced.",throws:["if a session with `id` already exists, metadata is not a plain lossless-JSON record with valid scalar fields, or `meta.cwd` is a non-absolute path (storage backends key directories off it)."]},{signature:"prepare(id?: SessionId, options?: PrepareSessionOptions): Session",description:"Build a session WITHOUT entering it into the store — validate the id/cwd and construct the Session (with its immutable SessionHeader). Pairs with enter + announce: a caller that owns a composite `ctx.effect` (the agent factory) folds the session lifecycle into that ONE effect so a fiber unload tears the session + agent down as a single ORDERED chain rather than as racing sibling effects — which would remove the publication hooks before the driver's closing events commit, dropping them.",parameters:[{name:"id",description:"the session id; omitted, the store mints `session-<n>`."},{name:"options",description:"seed events and/or creation metadata for the header. With `seedSource: 'persistence'`, metadata and events must be fresh detached graphs whose ownership transfers to this call: they are validated and frozen in place through {@link Session.fromRestore}, so the caller must retain no mutable aliases."}],returns:"the constructed session, NOT yet in the store.",throws:["if a session with `id` already exists, metadata is not a plain lossless-JSON record with valid scalar fields, or `meta.cwd` is a non-absolute path."]},{signature:"enter(session: Session): () => void",description:"Enter a prepared session into the store: install the module-private append publication hooks and add it to the store. Returns the DETACH disposer (hooks + store removal). Does NOT emit `session/created` — the caller yields this disposer inside its effect and THEN calls announce, so a throwing `session/created` listener rolls the attach back instead of leaking it.\n\nRe-checks the id for a duplicate: `prepare` and `enter` are public cross-package primitives and a caller may interleave arbitrary work (or another create) between them, so a stale prepared session must NOT overwrite a live store entry of the same id — its detach disposer would later delete the REAL session. The create convenience and the agent factory call the two back-to-back so they never trip this, but the public API cannot assume that.",parameters:[{name:"session",description:"a {@link prepare}d session not yet in the store."}],returns:"the detach disposer (publication hooks + store removal). When called from a synchronous `session/created` listener, removal and disposal wait until that creation dispatch unwinds.",throws:["if a session with this id is already in the store."]},{signature:"announce(session: Session): void",description:"Emit `session/created` exactly once for an entered session (with the carrier enter captured). Separate from enter so the caller can yield the detach disposer first (rollback safety — see enter).",parameters:[{name:"session",description:"the entered session to announce to listeners."}],throws:["if the session is not live or its announcement already began, including a reentrant call from a creation listener."]},{signature:"async flush(session: Session): Promise<boolean>",description:"Dispatch the awaited `session/flush` durability checkpoint for `session`, with the carrier captured at enter. THE flush entry point: the store owns the carrier, so callers (the checkpoint policy's per-request barrier, goal-round-driver's idle checkpoint, teardown drains, and consumers that flush themselves before reading storage) must come through here rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner, one spelling, and the scoped-dispatch invariant can pin it.",parameters:[{name:"session",description:"the session whose buffered events must reach durable storage."}],returns:"whether at least one durability listener participated, after every listener has settled successfully.",throws:["the first registered listener failure after every listener settles."]},{signature:"get(id: SessionId): Session | undefined",description:"Look up a live session.",parameters:[{name:"id",description:"the session id to look up."}],returns:"the session, or undefined when no live session has that id."},{signature:"list(): Session[]",description:"All live sessions, in creation order.",parameters:[],returns:"a fresh array; mutating it does not affect the store."},{signature:"fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session",description:"Create a live child session from a stable prefix of a live source. `boundary` is an inclusive source event seq; omitted means the source's current last event. The selected slice may end with a between-turn event but must not end inside an open turn.",parameters:[{name:"source",description:"Live source session object or id."},{name:"boundary",description:"Inclusive source event seq to fork through; omitted means the source's current last event, and omitted on an empty source forks an empty child."},{name:"childSessionId",description:"Optional child session id; omitted delegates to `SessionStore`'s id policy."}],returns:"The created live child session."}]},{key:"sessionTelemetry",summary:"Loadable form of the backend contract: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior.",description:"Loadable form of the backend contract: one implementation per context — the cordis `Service` registration under the `telemetry` key throws on a duplicate, cordis' standard behavior. A backend composes a SessionTelemetryCoordinator in its constructor to install the capture side.",methods:[{signature:"abstract readonly sharing: SessionTelemetrySharingStatus",description:'Deployment-selected session-sharing policy, disclosed for acknowledgement surfaces that report whether recorded feedback leaves the process. Every backend must disclose its policy; a consumer renders "not configured" only when no telemetry service is mounted. The seam owns this vocabulary so the disclosure is backend-independent.',parameters:[]},{signature:"abstract emit(record: SessionTelemetryRecord): void",description:"See SessionTelemetrySink.emit — that declaration is the contract's one home.",parameters:[{name:"record",description:"the logical record to report; owned by the backend after the call."}]},{signature:"flush?(): void",description:"See SessionTelemetrySink.flush.",parameters:[]},{signature:"abstract shutdown(): Promise<void>",description:"See SessionTelemetrySink.shutdown.",parameters:[],returns:"resolves when the backend's pipeline has quiesced."}]},{key:"sessionTitle",summary:"Log-backed title fold plus asynchronous fallback generation.",description:"Log-backed title fold plus asynchronous fallback generation.",methods:[{signature:"get(session: Session): SessionTitleSnapshot | undefined",description:"Read the latest folded title from one live or replayed session.",parameters:[{name:"session",description:"session whose log is the title source of truth."}],returns:"latest title snapshot, or `undefined` before eligible input."},{signature:"rename(session: Session, title: string): SessionTitleSnapshot",description:"Accept an explicit user title. Appends a `session/title` event with the `user` source, which pins the title: in-flight automatic generation is superseded and later user messages schedule none (an explicit SessionTitleService.refresh remains the deliberate unpin).",parameters:[{name:"session",description:"exact live session to rename."},{name:"title",description:"raw user input; normalized before acceptance."}],returns:"the accepted title snapshot.",throws:["{SessionTitleInvalidError} when the title normalizes to empty.","{Error} when the session is not live or the service is disposed."]},{signature:"async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>",description:"Explicitly retry the registered provider, or materialize the built-in fallback when no provider is registered.",parameters:[{name:"session",description:"exact live session to refresh."},{name:"signal",description:"optional caller cancellation."}],returns:"latest accepted title, or `undefined` when no eligible text exists."},{signature:"register(provider: SessionTitleProvider): () => Promise<void>",description:"Register the sole optional title provider. Disposal aborts its pending and active work before another provider may register.",parameters:[{name:"provider",description:"provider identity, cadence, and generation function."}],returns:"exact Cordis effect disposer, which settles after active calls quiesce."}]},{key:"settings",summary:"Abstract settings service.",description:"Abstract settings service. Providers implement raw-document storage (`load`/`persist`) and push external changes through Settings.publish; the base class owns namespace registration, resolution, validation, change detection, and the `settings/updated` commit event.",methods:[{signature:"abstract readonly writable: boolean",description:"Whether update may persist through this provider.",parameters:[]},{signature:"prepareDocument(): Promise<string | undefined>",description:"Prepare the provider's user-editable document for a native editor. File providers may materialize an absent document before returning its path; non-file providers return undefined.",parameters:[],returns:"the absolute local document path, or undefined for non-file storage."},{signature:"register<T>(ns: SettingsNamespace, schema: z<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>",description:"Register a namespace schema and receive its owner scope. The registration is an effect on the calling plugin's fiber: disposing that fiber removes the namespace and its observers. An invalid stored section fails the registration itself — the earliest point where the schema can judge it.",parameters:[{name:"ns",description:"unique namespace; duplicate registration fails loud."},{name:"schema",description:"schemastery schema resolving this namespace's value."},{name:"options",description:"composition `base` layer and effect timing."}],returns:"the owner scope for reads, observation, and updates."},{signature:"describe(options?: SettingsDescribeOptions): SettingsDescriptor[]",description:"Describe every registered namespace for configuration surfaces, including the composition `base` and raw user layers so a form can mark which fields the user overrode (presence in `user`) and what a reset returns to.",parameters:[{name:"options",description:"redaction switch; wire surfaces must redact."}],returns:"one descriptor per registered namespace, in registration order."},{signature:"get(ns: SettingsNamespace): unknown",description:"Read one registered namespace's resolved value.",parameters:[{name:"ns",description:"the namespace to read."}],returns:"the resolved value, or `undefined` while unregistered."},{signature:"async update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>",description:"Merge a patch into one registered namespace's user layer, validate the resolved candidate, persist through the provider, then commit and emit. A validation failure rejects before anything is persisted. Writes to one namespace are serialized: concurrent updates apply in call order, each merging over the previous write's committed section.",parameters:[{name:"ns",description:"the registered namespace to update."},{name:"patch",description:"plain-object patch over the user section."},{name:"expectedRevision",description:"the descriptor `revision` the caller read; a namespace that moved past it rejects with {@link SettingsConflictError}."}]},{signature:"async replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>",description:"Replace one registered namespace's user section wholesale, validate, persist, then commit and emit. Keys absent from `section` fall back to the composition `base` and schema defaults — this is the removal/reset path a merge-only patch cannot express (`replace({})` re-inherits everything).",parameters:[{name:"ns",description:"the registered namespace to replace."},{name:"section",description:"the complete next user section."},{name:"expectedRevision",description:"the descriptor `revision` the caller read; a namespace that moved past it rejects with {@link SettingsConflictError}."}]},{signature:"async mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>",description:"Apply path-addressed edits to one registered namespace's user section, validate, persist, then commit and emit. The ops are applied to the section as it stands when the write reaches the front of the queue, so a caller never has to restate fields it did not touch — and, crucially, cannot delete fields it never saw. This is the write path for any caller holding a redacted view; `replace` remains the wholesale reset.",parameters:[{name:"ns",description:"the registered namespace to edit."},{name:"ops",description:"ordered path edits; later ops observe earlier ones."},{name:"expectedRevision",description:"the descriptor `revision` the caller read; a namespace that moved past it rejects with {@link SettingsConflictError}."}]}]},{key:"shell",summary:"Abstract bash execution service.",description:"Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.shell` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).\n\nImplementations must honor these semantics:\n\n- run rejects only for infrastructure failures. Nonzero exits, timeout kills, and abort kills resolve with a ShellRunResult.\n- start returns immediately; no timeout applies to background processes. `done` settles at process close and never rejects; spawn failures settle as `killed` with the error on stderr.\n- ShellProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.\n- A still-running background process is stopped and awaited when its owning composition tears down. With the subprocess seam that boundary is `ctx.subprocess` disposal, so a background process survives an executor-only reload.",methods:[{signature:"abstract resolve(request: ShellExecRequest): ShellExecSpec",description:"Apply implementation-owned defaults and caps to a request before execution.",parameters:[{name:"request",description:"the caller's request; omitted fields get this implementation's defaults, capped fields are clamped."}],returns:"the fully-specified spec to hand to {@link run}/{@link start}."},{signature:"abstract run(spec: ShellExecSpec): Promise<ShellRunResult>",description:"Run a command in the foreground; resolves when it finishes.",parameters:[{name:"spec",description:"a resolved spec from {@link resolve}, never a raw request."}],returns:"the outcome; nonzero exits, timeout kills, and abort kills resolve with a descriptive result rather than reject."},{signature:"abstract start(spec: ShellExecSpec): ShellProcess",description:"Start a background process and return its handle immediately.",parameters:[{name:"spec",description:"a resolved spec from {@link resolve}, never a raw request."}],returns:"the live process handle (reads, kill, quiescence promise)."}]},{key:"shellEnv",summary:"Registry (`ctx.shellEnv`) for trusted, per-execution `DSH_*` variables.",description:"Registry (`ctx.shellEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model shell call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.",methods:[{signature:"register(contributor: BashEnvContributor): () => void",description:"Register one environment contributor. Names and keys are unique; built-in keys are reserved. Registration is disposed with the calling plugin fiber.",parameters:[{name:"contributor",description:"declared key ownership and per-execution resolver."}],returns:"the disposer that unregisters the contribution."},{signature:"collect(execution: ToolExecution): DshEnvironment",description:"Build the trusted `DSH_*` snapshot for one shell tool execution.",parameters:[{name:"execution",description:"the current tool execution."}],returns:"an immutable environment overlay containing built-ins and current contributions."},{signature:"list(): BashEnvVariableInfo[]",description:"Enumerate plugin-contributed variables without executing their resolvers.",parameters:[],returns:"declarations sorted by environment variable name."}]},{key:"skills",summary:"Layered registry of skill providers, the host+per-scope shape the tools registry established.",description:"Layered registry of skill providers, the host+per-scope shape the tools registry established. A registration files into the layer of its calling context's scope (scopeOf): host rows and repository plugins land in the global layer, while a plugin mounted by an agent preset's standing composition lands in that preset's layer. A read merges the global layer with the viewing scope's chain — the nearest layer's entry wins a duplicate name outright, and the rank order decides duplicates only within one layer. It exposes sorted invocation-neutral summaries and loads full skill bodies on demand.",methods:[{signature:"registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void",description:"Register a borrowed same-process provider synchronously during plugin apply, into the calling context's layer: a scoped context (an agent preset's standing mount) registers for that scope alone, an unscoped context registers globally. Duplicate names within one layer and reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters the provider and invalidates catalog caches.",parameters:[{name:"create",description:"synchronous factory receiving this registration's lifecycle and invalidation control."}],returns:"the exact Cordis effect disposer that unregisters this provider; composite effects may yield it directly to preserve teardown ordering."},{signature:"register(skill: SkillRegistration): () => void",description:"Register a borrowed readonly runtime skill into the calling context's layer. Project entries outrank runtime entries, which outrank user entries, within one layer. Same-name runtime entries in one layer are first-wins; a duplicate logs a warning and receives a no-op disposer so it cannot remove the winner.",parameters:[{name:"skill",description:"the skill definition input; omitted invocation and provider fields receive defaults."}],returns:"the exact Cordis effect disposer, preserving composite teardown order and invalidating caches."},{signature:"async list(options: SkillViewOptions = {}): Promise<SkillSummary[]>",description:"List invocation-neutral skill summaries for a workspace. Consumers apply model or user invocation policy at their operational boundary. Lookup options and provider candidates are readonly same-process values borrowed throughout discovery.",parameters:[{name:"options",description:"view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery."}],returns:"all sorted winning summaries."},{signature:"async snapshot(options: SkillViewOptions = {}): Promise<SkillCatalogSnapshot>",description:"Observe the current invocation-neutral catalog and whether discovery completed within a stable revision. Incomplete observations are never cached, allowing consumers to retain last-good state and retry on their next request boundary.",parameters:[{name:"options",description:"view options; `scope` selects the viewing agent's layers, `cwd` selects project roots, and `signal` cancels discovery."}],returns:"sorted summaries plus discovery-completeness state."},{signature:"async get(name: string, options: SkillViewOptions = {}): Promise<SkillDefinition | undefined>",description:"Load and validate the winning candidate, passing its opaque discovery locator back to the provider. Cancellation is rechecked after selection, including cache hits, and raced against loading so an uncooperative provider cannot hang the caller.",parameters:[{name:"name",description:"kebab-case skill name."},{name:"options",description:"view options; `scope` selects the viewing agent's layers, `cwd` selects workspace-sensitive skills, and `signal` cancels work."}],returns:"the full skill, including body content, or `undefined`."}]},{key:"spillStore",summary:"Abstract spill storage service.",description:"Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).\n\nSemantics every implementation must honor:\n\n- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.\n- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.\n- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).",methods:[{signature:"abstract saveText(input: SaveTextSpill): Promise<SpillRef>",description:"Persist `input.content` to a session-scoped spill artifact.",parameters:[{name:"input",description:"the owner, caller-supplied source fields, suggested name, and full text to save."}],returns:"the saved artifact's {@link SpillRef}; rejects on a storage failure."}]},{key:"storage",summary:"The storage hub service.",description:"The storage hub service. Backends register under `backend`; data forms mount under their `StorageForms` key and are reached as `ctx.storage.<form>`.",methods:[{signature:"readonly backend: BackendRegistry = new BackendRegistry()",description:"Named backend table; multiple backends stay mounted side by side.",parameters:[]},{signature:"mount<K extends keyof StorageForms>(form: K, facility: StorageForms[K]): () => void",description:"Mount a data-form facility on the hub. Mounting is an effect: the returned disposer unmounts the form.",parameters:[{name:"form",description:"Form key declared in {@link StorageForms}."},{name:"facility",description:"The facility instance to expose."}],returns:"the disposer that unmounts the form."},{signature:"form<K extends keyof StorageForms>(form: K): StorageForms[K]",description:"Resolve a mounted data form.",parameters:[{name:"form",description:"Form key declared in {@link StorageForms}."}],returns:"the mounted facility."}]},{key:"storageDomain",summary:"The mounted domain facility.",description:"The mounted domain facility. Opens declared domains over routed backends; one facility instance owns the open-domain table and enforces single-open per domain name.",methods:[{signature:"async open<S extends DomainSpec>(spec: S): Promise<Domain<S>>",description:"Open one declared domain. Steps, each failing the whole call: reject a name that is already open (`already-open`); resolve the backend route (`backend-not-found` passes through from the hub); require its `kv` facet (`facet-unsupported`); open the unit projected from the spec (backend `version-mismatch`/`malformed-medium` pass through); load and validate every stored record against the spec's zod schemas (`invalid-record` with the offending table and key); construct the domain.\n\nLifecycle: the CALLER owns the returned handle and closes it via `Domain.close()` (typically as its own `ctx.effect` disposer) — the facility does not tie the domain to any consumer fiber. Domains still open when the facility unmounts are closed by the plugin disposer.",parameters:[{name:"spec",description:"The domain declaration, typically from `defineDomain`."}],returns:"the opened domain handle, typed by the spec."},{signature:"get(name: string): DomainImpl | undefined",description:"Look up an open domain by name, untyped. Diagnostic surface (the package invariant cross-checks change events against live domain state); typed consumers hold the handle returned by open.",parameters:[{name:"name",description:"Domain name."}],returns:"the open domain runtime, or `undefined` when not open."},{signature:"async closeAll(): Promise<void>",description:"Close every domain still open on this facility. The unmount path for consumers that never called `Domain.close()` themselves; closing is idempotent, so double-closing an already-closed domain is harmless.",parameters:[],returns:"resolution after every unit is released."}]},{key:"subagents",summary:"Named provider registry with one-shot runs, durable discovery, and continuable-child operations.",description:"Named provider registry with one-shot runs, durable discovery, and continuable-child operations.",methods:[{signature:"async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart>",description:"Establish one durable continuable child and deliver its initial prompt. Resolves when the child's inbox accepts that prompt, without waiting for the turn to start or for the message to reach the Session log; any earlier failure rejects with no ids and rolls back the child entirely.",parameters:[{name:"spec",description:"provider, delegation request, and caller cancellation."}],returns:"the durable child id and the accepted prompt's message id.",throws:["when continuation services are unavailable or materialization fails."]},{signature:"async followup( parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions, ): Promise<MessageId>",description:"Deliver one later message to a continuable child as its next FIFO turn. A resident child's Agent inbox accepts it directly (waking a `waiting` Activation), while an absent one is cold-resumed from its persisted Session. The Agent inbox is the only queue, so every accepted message has one observable order.",parameters:[{name:"parent",description:"the exact live direct parent authorizing this delivery."},{name:"childId",description:"durable child session id."},{name:"content",description:"user-role content to deliver."},{name:"options",description:"the message source fields and caller cancellation, which stops the operation only before inbox acceptance."}],returns:"the accepted message's inbox id.",throws:["when continuation services are unavailable, parent authority is rejected, or the message was not admitted."]},{signature:"interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void",description:"Interrupt one live continuable child's current turn under a human parent address or an exact live ancestor Agent. Fire-and-return: the cancel signal is issued before this returns, but the target may keep running until it observes the signal. Unclaimed pending inbox work, the Activation, and published descendants are preserved; claimed work is not requeued. Once the interrupted driver is idle, a waking send resumes the parked FIFO queue. An absent target — including a one-shot or unknown id — is an accepted no-op, as is a manager-less composition, which cannot own a live Activation.",parameters:[{name:"targetSessionId",description:"the durable child session id to interrupt."},{name:"authority",description:"the human parent address or exact live ancestor Agent."}],throws:["{SubagentError} `UNAUTHORIZED` when the authority does not own the live target."]},{signature:"async reportFrom( child: Agent, content: ContentBlock[], options: SubagentReportOptions, ): Promise<MessageId>",description:"Deliver selected content from one live continuable child to its durable direct parent. The child is the authority credential; callers cannot name a recipient. Reporting does not conclude the child's turn or Activation.",parameters:[{name:"child",description:"exact live reporting child."},{name:"content",description:"selected model-facing content."},{name:"options",description:"parent scheduling and pre-acceptance cancellation."}],returns:"the stable identity of the parent-accepted message.",throws:["when continuation services are unavailable, sender authorization fails, or the direct parent is not live."]},{signature:"registerContinuableSetup(contribution: ContinuableSetupContribution): () => void",description:"Compose one deployment capability into every continuable child's unpublished creation context on fresh creation and cold resume. Grants wait for the next Activation; removing the contribution revokes every resident installation immediately.",parameters:[{name:"contribution",description:"synchronous child-scope installer."}],returns:"the exact Cordis effect disposer."},{signature:"async drainContinuableDescendants(parents: readonly Agent[]): Promise<void>",description:"Close continuable admission below exact live parent Agents, stop only their visible descendant Activations synchronously, then await admitted scoped materializations and release those forests child-first. The scoped cutoff lasts until each exact parent leaves the registry; unrelated parent trees remain live.",parameters:[{name:"parents",description:"exact host-owned parent Agents entering teardown."}],returns:"once every retained descendant Activation released its `AgentHandle`.",throws:["an aggregate error after all branches settle when any failed."]},{signature:"listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]>",description:"Enumerate the parent's direct session-backed subagents without loading or resuming an Agent and without any query service: the listing merges the live session store with optional session persistence (live-preferred) and serves each child's durable mode/label from the registered `subagent` projection unit down a three-rung ladder — the registry's watermark snapshot for a live child; for a cold one, a durable projection-cache row when the optional cache serves an own-suffix identity (its `seq` gate proves the value postdates the fork seed, where a child's own descriptor is immutable once appended), else one persistence inspection folded through the registry. The projection fold is the single classification authority; per-child diagnostics relay a fold that served no identity or a failed inspection, never a list-time descriptor parse. Absent persistence, enumeration is live-only (a cold child cannot be resumed then either, so its absence is capability absence, not an error). This service consults no Agent registrations, Activations, or providers.\n\nEvery persistence read receives `signal`, and the listing rechecks cancellation around each of those awaits. Read rejections that settle after an abort become a stable `SubagentError` with code `CANCELLED`.",parameters:[{name:"parentSessionId",description:"parent session whose direct children are listed."},{name:"signal",description:"caller-owned cancellation forwarded to persistence reads and observed around every read await."}],returns:"children and per-child diagnostics ordered by `createdAt`, then id.",throws:["{@link SubagentError} when the projection registry or the session store is not mounted, or the caller cancels the listing."]},{signature:"listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>",description:"Enumerate the root's complete session-backed subagent tree in stable pre-order from one live-preferred corpus, without loading or resuming an Agent. Ordinary sessions and one-shot children remain traversal nodes so continuable descendants below them are discovered; each returned entry adds its durable `parentId` and root-relative `depth`. Identity resolution, diagnostics, optional persistence, and cancellation follow the same projection-backed contract as listChildren.",parameters:[{name:"rootSessionId",description:"session whose complete descendant tree is listed."},{name:"signal",description:"caller-owned cancellation forwarded to persistence reads and observed around every read await."}],returns:"children and per-candidate diagnostics with tree position, in stable pre-order.",throws:["{@link SubagentError} under the same conditions as {@link listChildren}."]},{signature:"registerProvider(provider: SubagentProvider): () => void",description:"Register a provider under its name. Registration is effect-scoped and HMR safe; removing a provider blocks new starts but does not revoke runs that were already returned to their holders.",parameters:[{name:"provider",description:"the trusted provider implementation."}],returns:"the exact Cordis effect disposer."},{signature:"getProvider(name: string): SubagentProvider | undefined",description:"Look up a provider by name.",parameters:[{name:"name",description:"the provider name."}],returns:"the provider, or undefined when absent."},{signature:"list(): string[]",description:"List registered provider names in insertion order.",parameters:[],returns:"the registered names."},{signature:"async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>",description:"Establish a published child on the named provider. Capability and semantic checks run before delegation. Provider ownership lasts until its promise fulfills; a rejection therefore has no run for the caller to dispose and emits no run lifecycle events. Post-publication turn and infrastructure failures settle through the returned run.",parameters:[{name:"name",description:"the provider to use."},{name:"request",description:"child label, prompt, parent, signal, and optional capabilities."}],returns:"the published holder-owned run."}]},{key:"subprocess",summary:"Abstract subprocess service.",description:`Abstract subprocess service. Subclass, implement spawn, and load the subclass as a plugin — it registers as \`ctx.subprocess\` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
 
 Implementations must honor these semantics:
 
@@ -395,7 +395,9 @@ When a caller supplies an agent, human interaction is valid only for the exact l
         sessionId: SessionId;
         includeDescendants?: boolean;
     }, signal: AbortSignal): Promise<Response>;
-}`},{name:"DshEnvironment",declaration:"export type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>;"},{name:"DshEnvironmentKey",declaration:"export type DshEnvironmentKey = `${typeof QBOT_DSH_ENV_PREFIX}${string}`;"},{name:"DynamicCordisPackage",declaration:`export interface DynamicCordisPackage {
+}`},{name:"DshEnvironment",declaration:`export type DshEnvironment = Readonly<Record<DshEnvironmentKey, string> & {
+    QBOT_DSH_HOME?: string;
+}>;`},{name:"DshEnvironmentKey",declaration:"export type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`;"},{name:"DynamicCordisPackage",declaration:`export interface DynamicCordisPackage {
     pluginId: CordisDynamicPluginId;
     packageId: CordisDynamicPackageId;
     pluginRunId: CordisDynamicPluginRunId;
@@ -2126,7 +2128,7 @@ When a caller supplies an agent, human interaction is valid only for the exact l
     maxTotalAgents?: number;
     parent: Agent;
     signal?: AbortSignal;
-}`},{name:"WorkflowStopReason",declaration:"export type WorkflowStopReason = 'completed' | 'cancelled' | 'error';"}];function k(e){const n=new Set;let t=[...e];for(;t.length>0;){const r=[];for(const s of x){if(n.has(s.name))continue;const i=new RegExp(`\b${s.name}\b`);t.some(o=>i.test(o))&&(n.add(s.name),r.push(s.declaration))}t=r}return x.filter(r=>n.has(r.name))}a(k,"referencedTypeClosure");function B(e){return/^[A-Za-z_$][\w$]*$/.test(e)?`ctx.${e}`:`ctx[${JSON.stringify(e)}]`}a(B,"contextProperty");function N(e,n=j){if(e===void 0)return{mode:"catalog",services:n.map(r=>({key:r.key,description:r.summary,methods:r.methods.map(s=>({signature:s.signature}))}))};const t=n.find(r=>r.key===e);if(t===void 0)throw new Error(`no catalogued Service named "${e}"`);return{mode:"service",service:{key:t.key,description:t.description,access:{optional:{expression:`ctx.get(${JSON.stringify(t.key)})`,requiresUndefinedCheck:!0},hardDependency:{inject:[t.key],expression:B(t.key)}},methods:t.methods},referencedTypes:k(t.methods.map(r=>r.signature))}}a(N,"queryServiceApi");function W(e,n=S){if(e===void 0)return{mode:"catalog",events:n.map(r=>({name:r.name,description:r.summary,mode:r.mode,signature:r.signature}))};const t=n.find(r=>r.name===e);if(t===void 0)throw new Error(`no catalogued Event named "${e}"`);return{mode:"event",event:{name:t.name,description:t.description,mode:t.mode,signature:t.signature,parameters:t.parameters},referencedTypes:k([t.signature])}}a(W,"queryEventApi");const m={PENDING:0,LOADING:1,ACTIVE:2,FAILED:3,DISPOSED:4,UNLOADING:5};m.PENDING,m.LOADING,m.ACTIVE,m.FAILED,m.DISPOSED,m.UNLOADING;function U(e){const n=e.reflect.store;return Object.getOwnPropertySymbols(n).map(t=>n[t]).filter(t=>t!==void 0)}a(U,"liveImpls");function V(e,n){let t=e;for(;;){if(t===n)return!0;const r=t.parent.fiber;if(r===t)return!1;t=r}}a(V,"withinFiber");function R(e,n){return U(e).filter(t=>V(t.fiber,n)).map(t=>t.name).sort()}a(R,"providedServices");function f(e,n){return Object.keys(n.inject).filter(t=>e.get(t)===void 0)}a(f,"missingServices");function _(){return{card:"generic",kind:"read",title:"List Cordis Inspect Providers"}}a(_,"presentInspectListCall");function H(e){return{card:"generic",kind:"read",title:`Query Cordis ${e.platform} ${e.provider}.${e.method}`}}a(H,"presentInspectQueryCall");function G(e){return{card:"generic",kind:"read",title:`Inspect ${e.pluginId===void 0?"dynamic Cordis Plugins":e.packageId===void 0?e.pluginId:`${e.pluginId}/${e.packageId}`}`}}a(G,"presentInspectSelfCall");function J(e){const n=e.plugin.kind==="new"?`new ${e.plugin.idPrefix}-*`:e.plugin.pluginId;return{card:"generic",kind:"execute",title:`Register Cordis Plugin "${e.name}" for ${n}: ${e.purpose}`,rawInput:e.code}}a(J,"presentDefineCall");function z(e){return{card:"generic",kind:"delete",title:`Remove Cordis Plugin ${e.pluginId}`}}a(z,"presentUndefineCall");function K(e){return{card:"generic",kind:"execute",title:`${e.mode==="update"?"Update":"Run"} Cordis Plugin ${e.pluginId} · ${e.packageId}`}}a(K,"presentRunCall");function Q(e){return{card:"generic",kind:"execute",title:`Stop Cordis Plugin ${e.pluginId}`}}a(Q,"presentStopCall");const $=`# Dynamic Cordis Plugins
+}`},{name:"WorkflowStopReason",declaration:"export type WorkflowStopReason = 'completed' | 'cancelled' | 'error';"}];function k(e){const n=new Set;let t=[...e];for(;t.length>0;){const r=[];for(const s of x){if(n.has(s.name))continue;const i=new RegExp(`\b${s.name}\b`);t.some(o=>i.test(o))&&(n.add(s.name),r.push(s.declaration))}t=r}return x.filter(r=>n.has(r.name))}a(k,"referencedTypeClosure");function B(e){return/^[A-Za-z_$][\w$]*$/.test(e)?`ctx.${e}`:`ctx[${JSON.stringify(e)}]`}a(B,"contextProperty");function N(e,n=j){if(e===void 0)return{mode:"catalog",services:n.map(r=>({key:r.key,description:r.summary,methods:r.methods.map(s=>({signature:s.signature}))}))};const t=n.find(r=>r.key===e);if(t===void 0)throw new Error(`no catalogued Service named "${e}"`);return{mode:"service",service:{key:t.key,description:t.description,access:{optional:{expression:`ctx.get(${JSON.stringify(t.key)})`,requiresUndefinedCheck:!0},hardDependency:{inject:[t.key],expression:B(t.key)}},methods:t.methods},referencedTypes:k(t.methods.map(r=>r.signature))}}a(N,"queryServiceApi");function W(e,n=S){if(e===void 0)return{mode:"catalog",events:n.map(r=>({name:r.name,description:r.summary,mode:r.mode,signature:r.signature}))};const t=n.find(r=>r.name===e);if(t===void 0)throw new Error(`no catalogued Event named "${e}"`);return{mode:"event",event:{name:t.name,description:t.description,mode:t.mode,signature:t.signature,parameters:t.parameters},referencedTypes:k([t.signature])}}a(W,"queryEventApi");const m={PENDING:0,LOADING:1,ACTIVE:2,FAILED:3,DISPOSED:4,UNLOADING:5};m.PENDING,m.LOADING,m.ACTIVE,m.FAILED,m.DISPOSED,m.UNLOADING;function U(e){const n=e.reflect.store;return Object.getOwnPropertySymbols(n).map(t=>n[t]).filter(t=>t!==void 0)}a(U,"liveImpls");function V(e,n){let t=e;for(;;){if(t===n)return!0;const r=t.parent.fiber;if(r===t)return!1;t=r}}a(V,"withinFiber");function R(e,n){return U(e).filter(t=>V(t.fiber,n)).map(t=>t.name).sort()}a(R,"providedServices");function f(e,n){return Object.keys(n.inject).filter(t=>e.get(t)===void 0)}a(f,"missingServices");function H(){return{card:"generic",kind:"read",title:"List Cordis Inspect Providers"}}a(H,"presentInspectListCall");function _(e){return{card:"generic",kind:"read",title:`Query Cordis ${e.platform} ${e.provider}.${e.method}`}}a(_,"presentInspectQueryCall");function G(e){return{card:"generic",kind:"read",title:`Inspect ${e.pluginId===void 0?"dynamic Cordis Plugins":e.packageId===void 0?e.pluginId:`${e.pluginId}/${e.packageId}`}`}}a(G,"presentInspectSelfCall");function J(e){const n=e.plugin.kind==="new"?`new ${e.plugin.idPrefix}-*`:e.plugin.pluginId;return{card:"generic",kind:"execute",title:`Register Cordis Plugin "${e.name}" for ${n}: ${e.purpose}`,rawInput:e.code}}a(J,"presentDefineCall");function z(e){return{card:"generic",kind:"delete",title:`Remove Cordis Plugin ${e.pluginId}`}}a(z,"presentUndefineCall");function K(e){return{card:"generic",kind:"execute",title:`${e.mode==="update"?"Update":"Run"} Cordis Plugin ${e.pluginId} · ${e.packageId}`}}a(K,"presentRunCall");function Q(e){return{card:"generic",kind:"execute",title:`Stop Cordis Plugin ${e.pluginId}`}}a(Q,"presentStopCall");const $=`# Dynamic Cordis Plugins
 
 Dynamic Cordis plugins temporarily extend the current DSH process. A Plugin uses apply(ctx) to consume Services, listen to Events, provide Services, register model Tools, or register browser UI in Slots.
 
@@ -2230,7 +2232,7 @@ return {
 - Do not wait inside a Tool for approval or browser work that can happen only after the current turn ends.
 - Asynchronous success, rejection, and runtime errors update Run state and notify you through steering context.
 - After a technical failure, use cordis_inspect_self to read the exact Package source and its message/stack. Define a corrected Package under the same Plugin and retry autonomously.
-- Use the cordis-plugin-development Skill for other failure causes, repair procedures, and complete extension patterns.`,I={type:"object",properties:{},additionalProperties:!1},P={description:"JSON data owned by this inspect provider."},Y=T("service","Exact Service key. Omit it for the compact Service and method-signature directory."),Z=T("event","Exact Event name. Omit it for the compact Event and listener-signature directory."),X={description:"Compact Service directory, or one exact Service contract with only its referenced type declarations."},ee={description:"Compact Event directory, or one exact Event contract with only its referenced type declarations."},ne=S.filter(e=>!e.name.startsWith("cordis/"));function te(e){return[b("Service","Progressive Host Service discovery: compact capability/signature directory, then one exact coding contract.","listService",n=>N(C(n,"service")),Y,X),b("Event","Progressive Host Event discovery: compact listener directory, then one exact event contract.","listEvents",n=>W(C(n,"event"),ne),Z,ee),b("Builtin","Plain-JavaScript symbols available to a dynamic Host half.","listBuiltins",()=>({builtins:F,referencedTypes:[]})),{manifest:{id:"Tool",description:"Tools visible to the requesting Agent, including scoped and dynamic registrations.",methods:[{name:"listTools",description:"Return every Tool schema currently callable by this Agent.",inputSchema:I,outputSchema:P}]},query(n,t,r){if(n!=="listTools")throw new Error(`unknown Tool inspect method "${n}"`);return Promise.resolve({tools:e.tools.schemas(r.agent)})}}]}a(te,"hostInspectProviders");function b(e,n,t,r,s=I,i=P){return{manifest:{id:e,description:n,methods:[{name:t,description:n,inputSchema:s,outputSchema:i}]},async query(o,l){if(o!==t)throw new Error(`unknown ${e} inspect method "${o}"`);return await r(l)}}}a(b,"registration");function T(e,n){return{type:"object",properties:{[e]:{type:"string",description:n}},additionalProperties:!1}}a(T,"exactInput");function C(e,n){if(e==null||Array.isArray(e)||typeof e!="object")return;const t=e[n];return typeof t=="string"?t:void 0}a(C,"readExact");const A="tool-cordis",re=["tools","systemPrompt","dynamicCordisRunner","cordisInspect"];function g(e){if(e.agent===void 0)throw new Error("Cordis dynamic tools require an Agent-backed session");return e.agent}a(g,"requireAgent");function ae(e){e.systemPrompt.section({name:"tool:cordis",order:115,text:$});for(const n of te(e))e.effect(()=>e.cordisInspect.register(n),`tool-cordis: inspect ${n.manifest.id}`);e.tools.register(p({name:"cordis_inspect_list",description:"List every Cordis Inspect Provider currently known to the Host, including local Host Providers and the latest manifests synchronized from the Client. Each entry includes its platform, purpose, read-only methods, and input/output schemas. Call this Tool before creating or modifying a Package, then select the provider and method for cordis_inspect_query from its result. Do not guess names or treat an Inspect method as a business Service that Plugin code can call.",parameters:{},output:{schema:{type:"json"},render:a((n,t)=>[{type:"text",text:JSON.stringify(t,null,2)}],"render")},execute(n,t){return Promise.resolve({providers:e.cordisInspect.list()})},presentCall:_})),e.tools.register(p({name:"cordis_inspect_query",description:"Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before cordis_define to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query the exact root for its complete registration contract and props.",parameters:{platform:{type:"string",required:!0,enum:["host","client"],description:"Runtime platform that owns the Provider."},provider:{type:"string",required:!0,description:"Exact Provider ID returned by cordis_inspect_list."},method:{type:"string",required:!0,description:"Exact method name declared by the Provider manifest."},input:{type:"json",description:"Optional query input; it must satisfy the method input schema."}},output:{schema:{type:"json"},render:a((n,t)=>[{type:"text",text:JSON.stringify(t,null,2)}],"render")},async execute(n,t){const r=await e.cordisInspect.query(n.platform,n.provider,n.method,n.input,g(t),t.signal);return{platform:n.platform,provider:n.provider,method:n.method,data:r}},presentCall:H})),e.tools.register(p({name:"cordis_inspect_self",description:"Inspect dynamic Cordis objects owned by the current Session at increasing levels of detail. With no IDs, list only Plugin summaries. With pluginId alone, return version pointers, the latest Run, and every Package summary. Only pluginId plus packageId returns that immutable Package's Host/Client source and runtime diagnostics. packageId cannot be supplied alone. Query an exact Package before handling @pluginId, repairing an asynchronous failure, or defining an updated version. This Tool is read-only: it neither executes code nor changes version pointers.",parameters:{pluginId:{type:"string",description:"Stable Plugin ID returned by cordis_define or injected by @pluginId; omit it to list every current Plugin."},packageId:{type:"string",description:"Exact immutable Package ID owned by pluginId; when specified, source and diagnostics are returned."}},output:{schema:{type:"json"},render:a((n,t)=>[{type:"text",text:JSON.stringify(t,null,2)}],"render")},execute(n,t){const r=g(t);if(n.packageId!==void 0&&n.pluginId===void 0)throw new Error("cordis_inspect_self packageId requires pluginId");if(n.pluginId===void 0)return Promise.resolve({mode:"plugins",plugins:e.dynamicCordisRunner.listPlugins(r).map(i=>v(i))});const s=u(n.pluginId);if(n.packageId===void 0){const i=e.dynamicCordisRunner.inspectPlugin(r,s);return Promise.resolve({mode:"plugin",...v(i),packages:i.packages.map(o=>({...o,packageId:String(o.packageId),isCurrent:o.packageId===i.currentPackageId,isNext:o.packageId===i.nextPackageId}))})}return Promise.resolve(oe(e,r,s,w(n.packageId)))},presentCall:G})),e.tools.register(p({name:"cordis_define",description:'Define an immutable Cordis Package. For a new Plugin, use kind:"new" and provide only a semantic prefix of 3–6 lowercase English letters; the Host returns the final pluginId and packageId. To modify an existing Plugin, use kind:"existing" with its exact pluginId to append a Package without overwriting older versions. Provide at least one of code.host and code.client. Each value is a plain JavaScript function body that returns a Cordis Plugin; no TypeScript, JSX, or import transformation occurs. Query Inspect before depending on a Service, Event, Builtin, Slot, or token. Define only validates parameters and syntax and records source: it does not request approval, execute apply, or change currentPackageId. On success, call cordis_run with the returned IDs.',parameters:{plugin:{required:!0,oneOf:[{type:"object",additionalProperties:!1,properties:{kind:{type:"string",const:"new",required:!0},idPrefix:{type:"string",required:!0,description:"Suggested semantic prefix of 3–6 lowercase English letters; the Host adds a unique numeric suffix."}}},{type:"object",additionalProperties:!1,properties:{kind:{type:"string",const:"existing",required:!0},pluginId:{type:"string",required:!0,description:"Exact ID of an existing Plugin; the new Package is appended to that instance."}}}]},name:{type:"string",required:!0,description:"Short, readable Package name."},purpose:{type:"string",required:!0,description:"One-sentence, user-facing description of the Package purpose."},code:{type:"object",additionalProperties:!1,required:!0,properties:{host:{type:"string",description:"Plain JavaScript function body that returns the Host-half Cordis Plugin."},client:{type:"string",description:"Plain JavaScript function body that returns the browser Client-half Cordis Plugin."}}}},output:{schema:{type:"object",additionalProperties:!1,properties:{pluginId:{type:"string",required:!0},packageId:{type:"string",required:!0},name:{type:"string",required:!0},purpose:{type:"string",required:!0},hasHostHalf:{type:"boolean",required:!0},hasClientHalf:{type:"boolean",required:!0}}},render:a((n,t)=>[{type:"text",text:`Defined ${t.pluginId}/${t.packageId} (${t.name}); it is not running yet. Use cordis_run to activate this Package.`}],"render"),presentationMeta:a((n,t)=>({pluginId:t.pluginId,packageId:t.packageId}),"presentationMeta")},execute(n,t){const r=n.plugin.kind==="new"?{kind:"new",idPrefix:n.plugin.idPrefix}:{kind:"existing",pluginId:u(n.plugin.pluginId)},s=e.dynamicCordisRunner.define({sessionId:g(t).id,plugin:r,name:n.name,purpose:n.purpose,code:{...n.code.host===void 0?{}:{host:n.code.host},...n.code.client===void 0?{}:{client:n.code.client}}});return Promise.resolve({...s,pluginId:String(s.pluginId),packageId:String(s.packageId)})},presentCall:J})),e.tools.register(p({name:"cordis_run",description:'Activate one exact Package of a dynamic Plugin. Use mode:"run" for the first activation, restarting currentPackageId, or rollback. When current exists, use mode:"update" to switch to a different Package, even if the Plugin is currently stopped. An unauthorized Client Package creates an approval request and returns awaiting-approval; an authorized Package returns starting and continues asynchronously in the browser. Neither result waits for the final outcome inside the Tool. currentPackageId changes only after complete success; on failure, the old current and target next remain. Asynchronous success, rejection, or technical failure is reported through state and steering. After a technical failure, read diagnostics with cordis_inspect_self, correct the same Plugin, and retry autonomously. Do not request approval again after the user rejects it.',parameters:{pluginId:{type:"string",required:!0,description:"Stable Plugin ID returned by cordis_define."},packageId:{type:"string",required:!0,description:"Exact immutable Package ID to activate under that Plugin."},mode:{type:"string",required:!0,enum:["run","update"],description:"Use run for the first activation, restarting current, or rollback; use update to switch from current to a different Package."}},output:{schema:{type:"json"},render:a((n,t)=>{const r=q(t),s=h(r,"pluginId"),i=h(r,"packageId"),o=h(r,"pluginRunId");return[{type:"text",text:r.status==="awaiting-approval"?`${s}/${i} is awaiting user approval (${o}).`:r.status==="starting"?`${s}/${i} is starting asynchronously (${o}).`:`${s}/${i} is running (${o}).`}]},"render"),presentationMeta:a((n,t)=>{const r=q(t);return{pluginId:h(r,"pluginId"),packageId:h(r,"packageId"),pluginRunId:h(r,"pluginRunId")}},"presentationMeta")},async execute(n,t){const r=g(t),s=u(n.pluginId),i=w(n.packageId),o=await e.dynamicCordisRunner.run(r,s,i,n.mode,t.signal);if(!o.ok)throw new Error(o.message);if(o.status!=="running")return{status:o.status,pluginId:n.pluginId,packageId:n.packageId,pluginRunId:String(o.pluginRunId),mode:o.mode,...o.currentPackageId===void 0?{}:{currentPackageId:String(o.currentPackageId)},nextPackageId:String(o.nextPackageId)};const l=e.dynamicCordisRunner.snapshot(r).find(c=>c.pluginId===s),d=l?.activeRun?.pluginRunId===o.pluginRunId?l.activeRun.fiber:void 0;return{status:"running",pluginId:n.pluginId,packageId:n.packageId,pluginRunId:String(o.pluginRunId),currentPackageId:String(o.currentPackageId),...o.nextPackageId===void 0?{}:{nextPackageId:String(o.nextPackageId)},host:{status:d===void 0?"absent":f(e,d).length===0?"running":"waiting",provides:d===void 0?[]:R(e,d),waitingFor:d===void 0?[]:f(e,d)},client:{status:o.clientWaitingFor===void 0?"absent":o.clientWaitingFor.length===0?"running":"waiting",waitingFor:[...o.clientWaitingFor??[]]}}},presentCall:K})),e.tools.register(p({name:"cordis_stop",description:"Stop the current Run of a dynamic Plugin and cancel unfinished approval or activation requests. Retain the Plugin, every immutable Package, grants, currentPackageId, and nextPackageId so it can later run or update directly. Stopping an already stopped Plugin succeeds idempotently. Use this Tool to disable effects temporarily; use cordis_undefine for permanent removal.",parameters:{pluginId:{type:"string",required:!0,description:"Stable dynamic Plugin ID to stop."}},output:{schema:{type:"object",additionalProperties:!1,properties:{pluginId:{type:"string",required:!0}}},render:a((n,t)=>[{type:"text",text:`Dynamic Plugin ${t.pluginId} is stopped; its definition and versions remain.`}],"render")},async execute(n,t){const r=await e.dynamicCordisRunner.stop(g(t),u(n.pluginId));if(!r.ok&&r.reason!=="not-running")throw new Error(r.message);return{pluginId:n.pluginId}},presentCall:Q})),e.tools.register(p({name:"cordis_undefine",description:'Permanently remove a dynamic Plugin owned by the current Session. If it is running or awaiting approval, first stop it and cancel the request, then delete every Package, grant, and version pointer. After this returns, its pluginId, packageIds, @ reference, and Package business views are invalid; historical cards retain only a "Plugin removed" record. Do not call this Tool when versions must remain available for restart or rollback; use cordis_stop instead.',parameters:{pluginId:{type:"string",required:!0,description:"Stable dynamic Plugin ID to remove permanently."}},output:{schema:{type:"object",additionalProperties:!1,properties:{pluginId:{type:"string",required:!0},wasRunning:{type:"boolean",required:!0}}},render:a((n,t)=>[{type:"text",text:`Removed dynamic Plugin ${t.pluginId} and all of its Packages.`}],"render")},async execute(n,t){const r=await e.dynamicCordisRunner.undefine(g(t),u(n.pluginId));if(!r.ok)throw new Error(r.message);return{pluginId:n.pluginId,wasRunning:r.wasRunning}},presentCall:z})),e.on("agent/pre-step",async({agent:n,messages:t,signal:r},s)=>{const i=await s();if(i.kind==="reject")return i;const o=se(t);if(o.length===0)return i;r.throwIfAborted();const l=o.map(d=>{const c=e.dynamicCordisRunner.reference(n,u(d));return L({content:[{type:"text",text:c===void 0?de(d):ie(c)}],source:{kind:"plugin",plugin:A,form:"instructions"}})});return{kind:"enter",messages:[...i.messages,...l]}})}a(ae,"apply");function q(e){if(typeof e!="object"||e===null||Array.isArray(e))throw new Error("expected a JSON object");return e}a(q,"requireJsonObject");function h(e,n){const t=e[n];if(typeof t!="string")throw new Error(`expected JSON string field "${n}"`);return t}a(h,"requireJsonString");function v(e){const n=e.latestRun,t=E(e);return{pluginId:String(e.pluginId),name:e.name,packageCount:e.packages?.length??1,state:t,...e.currentPackageId===void 0?{}:{currentPackageId:String(e.currentPackageId)},...e.nextPackageId===void 0?{}:{nextPackageId:String(e.nextPackageId)},...e.activeRun===void 0?{}:{activeRun:{pluginRunId:String(e.activeRun.pluginRunId),packageId:String(e.activeRun.packageId)}},...n?.status!=="awaiting-approval"?{}:{pendingApproval:{pluginRunId:String(n.pluginRunId),packageId:String(n.packageId),mode:n.mode}}}}a(v,"selfSummary");function E(e){const n=e.latestRun?.status;return n==="awaiting-approval"?"awaiting-approval":n==="client-pending"||n==="starting-host"?"client-pending":n==="failed"||n==="rejected"||n==="cancelled"?"failed":n==="waiting"?"waiting":n==="running"||e.activeRun!==void 0?"running":e.currentPackageId===void 0?"defined":"stopped"}a(E,"selfState");function oe(e,n,t,r){const s=e.dynamicCordisRunner.inspectPackage(n,t,r),i=e.dynamicCordisRunner.snapshot(n).find(y=>y.pluginId===t),o=i?.packages.find(y=>y.packageId===r),l=i?.activeRun?.packageId===r?i.activeRun:void 0,d=s.latestRun?.packageId===r?s.latestRun:void 0,c=l?.fiber===void 0?[...d?.host.waitingFor??[]]:f(e,l.fiber),D=o?.hasHostHalf!==!0?"absent":d?.host.status??(l===void 0?"stopped":c.length===0?"running":"waiting"),M=o?.hasClientHalf!==!0?"absent":d?.client.status??"stopped";return{mode:"package",plugin:v(s),packageId:String(r),name:s.name,purpose:s.purpose,code:s.code,runtime:{state:E(s),host:{status:D,provides:l?.fiber===void 0?[]:R(e,l.fiber),waitingFor:c,handlers:l?.handlers??[],...d?.host.error===void 0?{}:{error:d.host.error}},client:{status:M,waitingFor:[...d?.client.waitingFor??[]],...d?.client.error===void 0?{}:{error:d.client.error},...l?.renderFailure===void 0?{}:{renderFailure:l.renderFailure}}}}}a(oe,"inspectSelfPackage");function se(e){const n=new Set,t=/(?:^|\s)@([a-z]{3,6}-\d+)(?=\s|$)/g;for(const r of e){if(r.source.kind!=="user")continue;const s=r.content.flatMap(i=>i.type==="text"?[i.text]:[]).join(`
+- Use the cordis-plugin-development Skill for other failure causes, repair procedures, and complete extension patterns.`,I={type:"object",properties:{},additionalProperties:!1},P={description:"JSON data owned by this inspect provider."},Y=T("service","Exact Service key. Omit it for the compact Service and method-signature directory."),Z=T("event","Exact Event name. Omit it for the compact Event and listener-signature directory."),X={description:"Compact Service directory, or one exact Service contract with only its referenced type declarations."},ee={description:"Compact Event directory, or one exact Event contract with only its referenced type declarations."},ne=S.filter(e=>!e.name.startsWith("cordis/"));function te(e){return[b("Service","Progressive Host Service discovery: compact capability/signature directory, then one exact coding contract.","listService",n=>N(C(n,"service")),Y,X),b("Event","Progressive Host Event discovery: compact listener directory, then one exact event contract.","listEvents",n=>W(C(n,"event"),ne),Z,ee),b("Builtin","Plain-JavaScript symbols available to a dynamic Host half.","listBuiltins",()=>({builtins:F,referencedTypes:[]})),{manifest:{id:"Tool",description:"Tools visible to the requesting Agent, including scoped and dynamic registrations.",methods:[{name:"listTools",description:"Return every Tool schema currently callable by this Agent.",inputSchema:I,outputSchema:P}]},query(n,t,r){if(n!=="listTools")throw new Error(`unknown Tool inspect method "${n}"`);return Promise.resolve({tools:e.tools.schemas(r.agent)})}}]}a(te,"hostInspectProviders");function b(e,n,t,r,s=I,i=P){return{manifest:{id:e,description:n,methods:[{name:t,description:n,inputSchema:s,outputSchema:i}]},async query(o,l){if(o!==t)throw new Error(`unknown ${e} inspect method "${o}"`);return await r(l)}}}a(b,"registration");function T(e,n){return{type:"object",properties:{[e]:{type:"string",description:n}},additionalProperties:!1}}a(T,"exactInput");function C(e,n){if(e==null||Array.isArray(e)||typeof e!="object")return;const t=e[n];return typeof t=="string"?t:void 0}a(C,"readExact");const A="tool-cordis",re=["tools","systemPrompt","dynamicCordisRunner","cordisInspect"];function g(e){if(e.agent===void 0)throw new Error("Cordis dynamic tools require an Agent-backed session");return e.agent}a(g,"requireAgent");function ae(e){e.systemPrompt.section({name:"tool:cordis",order:115,text:$});for(const n of te(e))e.effect(()=>e.cordisInspect.register(n),`tool-cordis: inspect ${n.manifest.id}`);e.tools.register(p({name:"cordis_inspect_list",description:"List every Cordis Inspect Provider currently known to the Host, including local Host Providers and the latest manifests synchronized from the Client. Each entry includes its platform, purpose, read-only methods, and input/output schemas. Call this Tool before creating or modifying a Package, then select the provider and method for cordis_inspect_query from its result. Do not guess names or treat an Inspect method as a business Service that Plugin code can call.",parameters:{},output:{schema:{type:"json"},render:a((n,t)=>[{type:"text",text:JSON.stringify(t,null,2)}],"render")},execute(n,t){return Promise.resolve({providers:e.cordisInspect.list()})},presentCall:H})),e.tools.register(p({name:"cordis_inspect_query",description:"Run a read-only query explicitly declared by an Inspect Provider. platform, provider, and method must come from cordis_inspect_list, and input must satisfy that method's schema. Use this Tool before cordis_define to read exact Service methods, Event modes, Builtin signatures, Tool schemas, theme tokens, or live Slot trees and props. Host queries run locally. A Client query waits for the first valid page response and remains pending until a page answers or the Tool is cancelled. This Tool cannot invoke business Service methods or modify the runtime. For Service.listService and Event.listEvents, query without input to navigate the compact signature directory, then query the exact service or event for its structured contract and referenced types. For Slots.listSubTree, query without root to navigate the compact tree, then query the exact root for its complete registration contract and props.",parameters:{platform:{type:"string",required:!0,enum:["host","client"],description:"Runtime platform that owns the Provider."},provider:{type:"string",required:!0,description:"Exact Provider ID returned by cordis_inspect_list."},method:{type:"string",required:!0,description:"Exact method name declared by the Provider manifest."},input:{type:"json",description:"Optional query input; it must satisfy the method input schema."}},output:{schema:{type:"json"},render:a((n,t)=>[{type:"text",text:JSON.stringify(t,null,2)}],"render")},async execute(n,t){const r=await e.cordisInspect.query(n.platform,n.provider,n.method,n.input,g(t),t.signal);return{platform:n.platform,provider:n.provider,method:n.method,data:r}},presentCall:_})),e.tools.register(p({name:"cordis_inspect_self",description:"Inspect dynamic Cordis objects owned by the current Session at increasing levels of detail. With no IDs, list only Plugin summaries. With pluginId alone, return version pointers, the latest Run, and every Package summary. Only pluginId plus packageId returns that immutable Package's Host/Client source and runtime diagnostics. packageId cannot be supplied alone. Query an exact Package before handling @pluginId, repairing an asynchronous failure, or defining an updated version. This Tool is read-only: it neither executes code nor changes version pointers.",parameters:{pluginId:{type:"string",description:"Stable Plugin ID returned by cordis_define or injected by @pluginId; omit it to list every current Plugin."},packageId:{type:"string",description:"Exact immutable Package ID owned by pluginId; when specified, source and diagnostics are returned."}},output:{schema:{type:"json"},render:a((n,t)=>[{type:"text",text:JSON.stringify(t,null,2)}],"render")},execute(n,t){const r=g(t);if(n.packageId!==void 0&&n.pluginId===void 0)throw new Error("cordis_inspect_self packageId requires pluginId");if(n.pluginId===void 0)return Promise.resolve({mode:"plugins",plugins:e.dynamicCordisRunner.listPlugins(r).map(i=>v(i))});const s=u(n.pluginId);if(n.packageId===void 0){const i=e.dynamicCordisRunner.inspectPlugin(r,s);return Promise.resolve({mode:"plugin",...v(i),packages:i.packages.map(o=>({...o,packageId:String(o.packageId),isCurrent:o.packageId===i.currentPackageId,isNext:o.packageId===i.nextPackageId}))})}return Promise.resolve(oe(e,r,s,w(n.packageId)))},presentCall:G})),e.tools.register(p({name:"cordis_define",description:'Define an immutable Cordis Package. For a new Plugin, use kind:"new" and provide only a semantic prefix of 3–6 lowercase English letters; the Host returns the final pluginId and packageId. To modify an existing Plugin, use kind:"existing" with its exact pluginId to append a Package without overwriting older versions. Provide at least one of code.host and code.client. Each value is a plain JavaScript function body that returns a Cordis Plugin; no TypeScript, JSX, or import transformation occurs. Query Inspect before depending on a Service, Event, Builtin, Slot, or token. Define only validates parameters and syntax and records source: it does not request approval, execute apply, or change currentPackageId. On success, call cordis_run with the returned IDs.',parameters:{plugin:{required:!0,oneOf:[{type:"object",additionalProperties:!1,properties:{kind:{type:"string",const:"new",required:!0},idPrefix:{type:"string",required:!0,description:"Suggested semantic prefix of 3–6 lowercase English letters; the Host adds a unique numeric suffix."}}},{type:"object",additionalProperties:!1,properties:{kind:{type:"string",const:"existing",required:!0},pluginId:{type:"string",required:!0,description:"Exact ID of an existing Plugin; the new Package is appended to that instance."}}}]},name:{type:"string",required:!0,description:"Short, readable Package name."},purpose:{type:"string",required:!0,description:"One-sentence, user-facing description of the Package purpose."},code:{type:"object",additionalProperties:!1,required:!0,properties:{host:{type:"string",description:"Plain JavaScript function body that returns the Host-half Cordis Plugin."},client:{type:"string",description:"Plain JavaScript function body that returns the browser Client-half Cordis Plugin."}}}},output:{schema:{type:"object",additionalProperties:!1,properties:{pluginId:{type:"string",required:!0},packageId:{type:"string",required:!0},name:{type:"string",required:!0},purpose:{type:"string",required:!0},hasHostHalf:{type:"boolean",required:!0},hasClientHalf:{type:"boolean",required:!0}}},render:a((n,t)=>[{type:"text",text:`Defined ${t.pluginId}/${t.packageId} (${t.name}); it is not running yet. Use cordis_run to activate this Package.`}],"render"),presentationMeta:a((n,t)=>({pluginId:t.pluginId,packageId:t.packageId}),"presentationMeta")},execute(n,t){const r=n.plugin.kind==="new"?{kind:"new",idPrefix:n.plugin.idPrefix}:{kind:"existing",pluginId:u(n.plugin.pluginId)},s=e.dynamicCordisRunner.define({sessionId:g(t).id,plugin:r,name:n.name,purpose:n.purpose,code:{...n.code.host===void 0?{}:{host:n.code.host},...n.code.client===void 0?{}:{client:n.code.client}}});return Promise.resolve({...s,pluginId:String(s.pluginId),packageId:String(s.packageId)})},presentCall:J})),e.tools.register(p({name:"cordis_run",description:'Activate one exact Package of a dynamic Plugin. Use mode:"run" for the first activation, restarting currentPackageId, or rollback. When current exists, use mode:"update" to switch to a different Package, even if the Plugin is currently stopped. An unauthorized Client Package creates an approval request and returns awaiting-approval; an authorized Package returns starting and continues asynchronously in the browser. Neither result waits for the final outcome inside the Tool. currentPackageId changes only after complete success; on failure, the old current and target next remain. Asynchronous success, rejection, or technical failure is reported through state and steering. After a technical failure, read diagnostics with cordis_inspect_self, correct the same Plugin, and retry autonomously. Do not request approval again after the user rejects it.',parameters:{pluginId:{type:"string",required:!0,description:"Stable Plugin ID returned by cordis_define."},packageId:{type:"string",required:!0,description:"Exact immutable Package ID to activate under that Plugin."},mode:{type:"string",required:!0,enum:["run","update"],description:"Use run for the first activation, restarting current, or rollback; use update to switch from current to a different Package."}},output:{schema:{type:"json"},render:a((n,t)=>{const r=q(t),s=h(r,"pluginId"),i=h(r,"packageId"),o=h(r,"pluginRunId");return[{type:"text",text:r.status==="awaiting-approval"?`${s}/${i} is awaiting user approval (${o}).`:r.status==="starting"?`${s}/${i} is starting asynchronously (${o}).`:`${s}/${i} is running (${o}).`}]},"render"),presentationMeta:a((n,t)=>{const r=q(t);return{pluginId:h(r,"pluginId"),packageId:h(r,"packageId"),pluginRunId:h(r,"pluginRunId")}},"presentationMeta")},async execute(n,t){const r=g(t),s=u(n.pluginId),i=w(n.packageId),o=await e.dynamicCordisRunner.run(r,s,i,n.mode,t.signal);if(!o.ok)throw new Error(o.message);if(o.status!=="running")return{status:o.status,pluginId:n.pluginId,packageId:n.packageId,pluginRunId:String(o.pluginRunId),mode:o.mode,...o.currentPackageId===void 0?{}:{currentPackageId:String(o.currentPackageId)},nextPackageId:String(o.nextPackageId)};const l=e.dynamicCordisRunner.snapshot(r).find(c=>c.pluginId===s),d=l?.activeRun?.pluginRunId===o.pluginRunId?l.activeRun.fiber:void 0;return{status:"running",pluginId:n.pluginId,packageId:n.packageId,pluginRunId:String(o.pluginRunId),currentPackageId:String(o.currentPackageId),...o.nextPackageId===void 0?{}:{nextPackageId:String(o.nextPackageId)},host:{status:d===void 0?"absent":f(e,d).length===0?"running":"waiting",provides:d===void 0?[]:R(e,d),waitingFor:d===void 0?[]:f(e,d)},client:{status:o.clientWaitingFor===void 0?"absent":o.clientWaitingFor.length===0?"running":"waiting",waitingFor:[...o.clientWaitingFor??[]]}}},presentCall:K})),e.tools.register(p({name:"cordis_stop",description:"Stop the current Run of a dynamic Plugin and cancel unfinished approval or activation requests. Retain the Plugin, every immutable Package, grants, currentPackageId, and nextPackageId so it can later run or update directly. Stopping an already stopped Plugin succeeds idempotently. Use this Tool to disable effects temporarily; use cordis_undefine for permanent removal.",parameters:{pluginId:{type:"string",required:!0,description:"Stable dynamic Plugin ID to stop."}},output:{schema:{type:"object",additionalProperties:!1,properties:{pluginId:{type:"string",required:!0}}},render:a((n,t)=>[{type:"text",text:`Dynamic Plugin ${t.pluginId} is stopped; its definition and versions remain.`}],"render")},async execute(n,t){const r=await e.dynamicCordisRunner.stop(g(t),u(n.pluginId));if(!r.ok&&r.reason!=="not-running")throw new Error(r.message);return{pluginId:n.pluginId}},presentCall:Q})),e.tools.register(p({name:"cordis_undefine",description:'Permanently remove a dynamic Plugin owned by the current Session. If it is running or awaiting approval, first stop it and cancel the request, then delete every Package, grant, and version pointer. After this returns, its pluginId, packageIds, @ reference, and Package business views are invalid; historical cards retain only a "Plugin removed" record. Do not call this Tool when versions must remain available for restart or rollback; use cordis_stop instead.',parameters:{pluginId:{type:"string",required:!0,description:"Stable dynamic Plugin ID to remove permanently."}},output:{schema:{type:"object",additionalProperties:!1,properties:{pluginId:{type:"string",required:!0},wasRunning:{type:"boolean",required:!0}}},render:a((n,t)=>[{type:"text",text:`Removed dynamic Plugin ${t.pluginId} and all of its Packages.`}],"render")},async execute(n,t){const r=await e.dynamicCordisRunner.undefine(g(t),u(n.pluginId));if(!r.ok)throw new Error(r.message);return{pluginId:n.pluginId,wasRunning:r.wasRunning}},presentCall:z})),e.on("agent/pre-step",async({agent:n,messages:t,signal:r},s)=>{const i=await s();if(i.kind==="reject")return i;const o=se(t);if(o.length===0)return i;r.throwIfAborted();const l=o.map(d=>{const c=e.dynamicCordisRunner.reference(n,u(d));return L({content:[{type:"text",text:c===void 0?de(d):ie(c)}],source:{kind:"plugin",plugin:A,form:"instructions"}})});return{kind:"enter",messages:[...i.messages,...l]}})}a(ae,"apply");function q(e){if(typeof e!="object"||e===null||Array.isArray(e))throw new Error("expected a JSON object");return e}a(q,"requireJsonObject");function h(e,n){const t=e[n];if(typeof t!="string")throw new Error(`expected JSON string field "${n}"`);return t}a(h,"requireJsonString");function v(e){const n=e.latestRun,t=E(e);return{pluginId:String(e.pluginId),name:e.name,packageCount:e.packages?.length??1,state:t,...e.currentPackageId===void 0?{}:{currentPackageId:String(e.currentPackageId)},...e.nextPackageId===void 0?{}:{nextPackageId:String(e.nextPackageId)},...e.activeRun===void 0?{}:{activeRun:{pluginRunId:String(e.activeRun.pluginRunId),packageId:String(e.activeRun.packageId)}},...n?.status!=="awaiting-approval"?{}:{pendingApproval:{pluginRunId:String(n.pluginRunId),packageId:String(n.packageId),mode:n.mode}}}}a(v,"selfSummary");function E(e){const n=e.latestRun?.status;return n==="awaiting-approval"?"awaiting-approval":n==="client-pending"||n==="starting-host"?"client-pending":n==="failed"||n==="rejected"||n==="cancelled"?"failed":n==="waiting"?"waiting":n==="running"||e.activeRun!==void 0?"running":e.currentPackageId===void 0?"defined":"stopped"}a(E,"selfState");function oe(e,n,t,r){const s=e.dynamicCordisRunner.inspectPackage(n,t,r),i=e.dynamicCordisRunner.snapshot(n).find(y=>y.pluginId===t),o=i?.packages.find(y=>y.packageId===r),l=i?.activeRun?.packageId===r?i.activeRun:void 0,d=s.latestRun?.packageId===r?s.latestRun:void 0,c=l?.fiber===void 0?[...d?.host.waitingFor??[]]:f(e,l.fiber),D=o?.hasHostHalf!==!0?"absent":d?.host.status??(l===void 0?"stopped":c.length===0?"running":"waiting"),M=o?.hasClientHalf!==!0?"absent":d?.client.status??"stopped";return{mode:"package",plugin:v(s),packageId:String(r),name:s.name,purpose:s.purpose,code:s.code,runtime:{state:E(s),host:{status:D,provides:l?.fiber===void 0?[]:R(e,l.fiber),waitingFor:c,handlers:l?.handlers??[],...d?.host.error===void 0?{}:{error:d.host.error}},client:{status:M,waitingFor:[...d?.client.waitingFor??[]],...d?.client.error===void 0?{}:{error:d.client.error},...l?.renderFailure===void 0?{}:{renderFailure:l.renderFailure}}}}}a(oe,"inspectSelfPackage");function se(e){const n=new Set,t=/(?:^|\s)@([a-z]{3,6}-\d+)(?=\s|$)/g;for(const r of e){if(r.source.kind!=="user")continue;const s=r.content.flatMap(i=>i.type==="text"?[i.text]:[]).join(`
 `);for(const i of s.matchAll(t))i[1]!==void 0&&n.add(i[1])}return[...n]}a(se,"referencedPluginIds");function ie(e){const n=e.currentPackageId===void 0?"run":"update";return["<cordis_dynamic_plugin_context>",JSON.stringify(e,null,2),"",`The user explicitly referenced @${e.pluginId}. Use Package ${e.packageId} as the base for this modification.`,`Before modifying it, call cordis_inspect_self with pluginId="${e.pluginId}" and packageId="${e.packageId}" to read the exact metadata and source.`,`Use cordis_define with plugin.kind="existing" and the original pluginId="${e.pluginId}" to append an immutable Package.`,`Do not create a new Plugin for this request. After cordis_define succeeds, call cordis_run mode="${n}" with the returned packageId.`,"</cordis_dynamic_plugin_context>"].join(`
 `)}a(ie,"renderReference");function de(e){return["<cordis_dynamic_plugin_context>",`The user explicitly referenced @${e}, but this Plugin is unavailable in the current Session.`,"It may have been removed, belong to another Session, or have been lost when the DSH process restarted.","Do not claim that it was updated or silently create a replacement Plugin. Tell the user that the reference is currently unavailable.","</cordis_dynamic_plugin_context>"].join(`
 `)}a(de,"renderUnavailableReference");export{ae as apply,re as inject,A as name};