@khorsheed/dsh-local-agent 0.1.0-rc.6

package/lib/types/index.d.ts

@@ -0,0 +1,1463 @@
+/**
+ * @khorsheed/dsh-local-agent — the local code-agent harness family core.
+ * Each locally-installed coding agent CLI (Kimi Code, Codex, Claude Code, …)
+ * registers itself as one harness: a scoped home under the shared homes root,
+ * the device-code login command, and a session-records adapter. The glue
+ * registers the `/<harness> login|sessions` command family and provisions the
+ * scoped home; every harness's state stays under its own directory and never
+ * touches the user's native installation.
+ *
+ * Delegation deliberately stays OUT of this seam: each harness bundle mounts
+ * its own subagent-provider row into the existing `subagent` capability
+ * (subagent-acp for a harness that speaks ACP over stdio, subagent-codex's
+ * provider for Codex's app-server wire, …), reading the scoped home through
+ * {@link LocalAgentRegistry.homeDir}. This package owns only harness identity
+ * and lifecycle.
+ *
+ * @module @khorsheed/dsh-local-agent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands';
+import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionHeader } from '@deepseek-ai/dsh-session';
+import type { SubagentRun } from '@deepseek-ai/dsh-subagent';
+import type { DelegationCallOptions, LocalAgentDelegationInfo, LocalAgentDelegationIntent, LocalAgentDelegationRecord, LocalAgentEffectiveSettings, LocalAgentMemberRun, LocalAgentModelBroker, LocalAgentMemberBinding, LocalAgentMemberControlState, LocalAgentMemberInbox, LocalAgentMemberConfiguration, LocalAgentControlReceipt, LocalAgentAppliedConfiguration, LocalAgentRosterRow, LocalAgentRunProgress, LocalAgentSessionRecord, LocalAgentStatus, LocalAgentToolCalls } from './types.ts';
+import { MemberInbox } from './member-inbox.ts';
+/** Stable Cordis plugin name. */
+export declare const name = "local-agent";
+/** Services required before the registry and commands can mount. */
+export declare const inject: string[];
+export type { ContainerExecLaunch, } from './container.ts';
+export type { DelegationCallOptions, LocalAgentCredentialState, DelegationExecTarget, LocalAgentDelegationInfo, LocalAgentDelegationIntent, LocalAgentDelegationRecord, LocalAgentDelegationView, LocalAgentEffectiveSettings, LocalAgentMemberRun, LocalAgentPromptResult, LocalAgentRosterRow, LocalAgentRunProgress, LocalAgentSessionRecord, LocalAgentStatus, } from './types.ts';
+export type { LocalAgentMemberMessage, MemberMessageOutcome, RoomMemberMessageGate, RoomMemberMessageReceipt, } from './types.ts';
+export { delegationEnv } from './env.ts';
+export { ModelDirectoryCache, extendModelDirectory, modelDirectoryContextKey } from './model-directory.ts';
+export { MemberConfigurationController } from './member-control.ts';
+export type { MemberConfigurationAdapter, MemberControlStorage, MemberControlRecord } from './member-control.ts';
+export { FileMemberControlStorage } from './member-control-storage.ts';
+export { LiveFlush, LIVE_FLUSH_INTERVAL_MS } from './live-flush.ts';
+import { LocalAgentStreams } from './live-stream.ts';
+export { LocalAgentStreams, LiveStreamPublisher, LIVE_CHECKPOINT_INTERVAL_MS } from './live-stream.ts';
+export { containerExecSpawn, containerScopedHome } from './container.ts';
+export { settingsFace, vol } from './settings-face.ts';
+export type { SettingsFace } from './settings-face.ts';
+export { CLI_VERSION_FAILURE_TTL_MS, CLI_VERSION_PROBE_TIMEOUT_MS, clearCliVersionCache, parseCliVersion, probeCliVersion, } from './cli-version.ts';
+export type { CliVersionProbe } from './cli-version.ts';
+/** Per-harness session listing: reads the harness's own records format. */
+export interface LocalAgentRecordsAdapter {
+    /**
+     * List sessions from the harness's scoped home.
+     * @param homeDir - the harness's scoped home directory.
+     * @returns the sessions in the harness's own order.
+     */
+    listSessions(homeDir: string): Promise<readonly LocalAgentSessionRecord[]>;
+}
+/**
+ * Compose a session-backed subagent's durable label from the harness's
+ * display name and the delegation's own description, so the standard 子代理
+ * surface shows which local agent produced the conversation. Providers
+ * (kimi, future codex/claude-code) call this when appending the child's
+ * `subagent/descriptor` event; the prefix is the durable, model-visible
+ * source marker.
+ * @param displayName - the harness's human display name (e.g. `Kimi Code`).
+ * @param description - the delegation's short description, when the caller
+ *   supplied one.
+ * @returns the composed label, or just the display name without a description.
+ */
+export declare function subagentDelegationLabel(displayName: string, description: string | undefined): string;
+/**
+ * Append the parent-side `subagent/catalog` discovery row for a freshly
+ * established session-backed child. The official SubagentRuntime writes this
+ * row only for IN-PROCESS children (`run.localAgent.session`, harness
+ * `SubagentRuntime.start`); a family provider's run is remote, so the
+ * provider appends the row itself, right where the child's
+ * `subagent/descriptor` lands — exactly once per child session, since resume
+ * rounds never create a session.
+ *
+ * The payload mirrors the upstream `establishCatalogChild` helper
+ * (harness packages/subagent catalog.ts) byte-for-byte. It is inlined
+ * because that helper is unreachable through the package's exports map on
+ * the npm release line: only `./src/*` would resolve it, and published
+ * artifacts ship no `src/`. The `subagent/catalog` event type itself rides
+ * the official package's SessionEventMap augmentation, so this append stays
+ * type-checked against the host's own schema. A throw is the caller's to
+ * degrade (warn and continue) — a missing catalog row never blocks the
+ * delegation itself.
+ * @param parent - the durable direct parent session receiving the row.
+ * @param child - the established child's immutable session header.
+ * @param label - the same composed label the child's descriptor carries.
+ */
+export declare function establishSubagentCatalogChild(parent: Session, child: SessionHeader, label: string | undefined): void;
+/**
+ * Persist a delegated child session's events, the family providers' one entry
+ * point after every mirror pass. Two paths:
+ *
+ * - **live session + a core with {@link LocalAgentRegistry.syncChildSession}**
+ *   (the production wiring): delegate to the registry, which syncs through
+ *   its cached per-child write handle — the same handle the reattach recipe
+ *   holds, so live write routing and the explicit suffix sync share one
+ *   owner and never collide on SessionAlreadyOwnedError. The registry
+ *   downgrades a sync failure to a warn, so this path never throws.
+ * - **anything else** (standalone tests, ad-hoc mirrors, a core predating
+ *   syncChildSession): a one-shot handle flow — claim the write handle
+ *   (creating the stored session on first persist), append only the unstored
+ *   suffix (re-appending the full snapshot violates the contiguous-seq
+ *   contract), flush, close. There is deliberately NO live-session skip:
+ *   reading the stored prefix first makes the suffix append idempotent, so
+ *   on a host line whose write-behind does store live appends the suffix is
+ *   simply empty — while on host 0.1.5, where a mirror session without an
+ *   agent loop never checkpoints, this flow is what lands the events at all.
+ *
+ * @param ctx - host context carrying the sessions/localAgent/sessionPersistence services.
+ * @param childSession - the dsh child session the provider mirrored into.
+ */
+export declare function persistChildSession(ctx: Context, childSession: Session): Promise<void>;
+/**
+ * A harness's login flow. Two variants:
+ *
+ * - **device-code**: spawn the CLI's login command and capture its printed
+ *   prompt (the URL/code) for the reply while the CLI polls in the background.
+ * - **manual handoff**: the CLI's auth is TTY-only, so nothing is spawnable —
+ *   `/login` replies with instructions naming the command for the user's own
+ *   terminal, and the registry watches the scoped home for the credential.
+ */
+export type LocalAgentLogin = {
+    command: string;
+    args: readonly string[];
+    /**
+     * Which stream carries the device-code prompt. Defaults to `stderr`
+     * (kimi's login prints there); harnesses whose CLI prints the prompt to
+     * stdout (codex `login --device-auth`, claude `setup-token`) declare
+     * `stdout` so the reply surfaces the URL instead of timing out.
+     */
+    capture?: 'stderr' | 'stdout';
+} | {
+    manual: {
+        /** The exact command line the user runs in their own terminal. */
+        commandDisplay: string;
+    };
+    /**
+     * Credential probe polled while the handoff is in flight; defaults to the
+     * harness's own `isAuthenticated`.
+     */
+    watch?: (homeDir: string) => Promise<boolean>;
+} | {
+    /**
+     * The CLI's auth needs a TTY but drives the browser itself (claude ≥2.1):
+     * the command is spawned under a pseudo-terminal wrapper so it opens the
+     * user's browser, and its output is watched for an OAuth URL to show as a
+     * fallback. When the CLI prompts for a code, the user pastes it via
+     * `/<name> code <value>`, which the registry writes to the child's stdin.
+     */
+    pty: {
+        command: string;
+        /**
+         * The argv, or a factory that receives the scoped home being logged
+         * in. The factory form exists because one harness pins its scoped home
+         * ON the argv (claude's `env CLAUDE_CONFIG_DIR=… claude auth login`, an
+         * assignment that outranks the spawn env): with a fixed array a
+         * `--scope` login would authorize the DEFAULT directory while claiming
+         * to authorize the scope. The plain array stays the form every other
+         * harness uses.
+         */
+        args: readonly string[] | ((homeDir: string) => readonly string[]);
+    };
+    /**
+     * Credential probe polled while the login is in flight; defaults to the
+     * harness's own `isAuthenticated`.
+     */
+    watch?: (homeDir: string) => Promise<boolean>;
+};
+/**
+ * Per-scope inputs one scope's provisioning may take.
+ *
+ * Provisioning has always been a function of the scoped home alone, which is
+ * right for every knob a harness reads from its own plugin config — one
+ * instance, one answer. `preset` is the first knob that is a property of the
+ * SUBJECT rather than of the deployment: an evaluation whose two conditions
+ * differ in exactly one preset needs two scopes rostering two presets, and a
+ * plugin-level setting cannot say that. So the caller that knows (the
+ * evaluation's `conditions provision`, which reads the condition document)
+ * hands it in here, and the harness persists it into the scope directory so
+ * the next provisioning of that scope reproduces it without being told.
+ *
+ * Only `dsh` reads it. The other three harnesses take the parameter and
+ * ignore it, which is what keeps their provisioning byte-identical.
+ */
+export interface LocalAgentScopeProvisionOptions {
+    /** The agent preset this scope's composition must compose. */
+    preset?: string;
+}
+/**
+ * What one scope's provisioning reports back.
+ *
+ * Every field is optional and every one is a READ-BACK: what the scope now
+ * holds, not what the caller asked for. A caller that wanted to know whether
+ * its request took effect compares the two.
+ */
+export interface LocalAgentScopeProvisionResult {
+    /** The preset the scope's composition now rosters, when it rosters one. */
+    preset?: string;
+    /**
+     * The scope's own copy of that preset directory, when the harness keeps
+     * one. `matchesSource` is the whole content of the claim: the copy is
+     * byte-for-byte the deployment's own preset directory, which is what lets
+     * a fingerprint taken against the deployment's copy describe the scope's.
+     */
+    presetSnapshot?: {
+        matchesSource: boolean;
+    };
+}
+/**
+ * One registered local code-agent harness.
+ */
+export interface LocalAgentPreparation {
+    binding: LocalAgentMemberBinding;
+    childSession: Session;
+    configuration: LocalAgentAppliedConfiguration;
+    signal: AbortSignal;
+}
+export interface LocalAgentHarness {
+    /** Native handshake/configuration only; no prompt, turn, or side-effecting task. */
+    prepareMember?: (request: LocalAgentPreparation) => Promise<void>;
+    /** Command prefix and scoped-home directory name (lowercase, dashed). */
+    name: string;
+    /** Human display name, used in command replies and UI labels. */
+    displayName: string;
+    /** Environment variable naming the scoped home (e.g. `KIMI_CODE_HOME`). */
+    homeEnvVar: string;
+    /**
+     * Subagent provider name this harness delegates through, when it has one.
+     * A harness without delegation is record-and-login only. The core invariant
+     * cross-checks this against the mounted subagent providers, so a record
+     * that names a provider the composition does not mount fails loud.
+     */
+    delegationProvider?: string;
+    /**
+     * Login flow declaration. The device-code variant spawns the CLI and
+     * captures its printed prompt. The manual variant spawns NOTHING: the CLI's
+     * auth is TTY-only (claude ≥2.1 prints no OAuth URL off a TTY and
+     * `setup-token` needs Ink raw mode — scraping broke twice), so `/login`
+     * replies with instructions naming `manual.commandDisplay` for the user's
+     * own terminal, then watches for the credential to land. Absent means the
+     * harness has no login flow — it authenticates through the host instance
+     * (e.g. by resolving a credential from the parent's store), so `/login`
+     * reports that instead of guessing a command.
+     */
+    login?: LocalAgentLogin;
+    /** Session records reader for this harness's format. */
+    records: LocalAgentRecordsAdapter;
+    /**
+     * Bring one scoped home of this harness to the state its CLI needs before a
+     * login or a round can use it (codex's `config.toml` storage pin, kimi's
+     * provider/model config and permission rules, claude's `settings.json`,
+     * dsh's sub-profile). Called by the registry when a NAMED scope's directory
+     * is materialized — the default scope is provisioned by the harness bundle's
+     * own `apply`, exactly as it always was, so nothing about it moves.
+     * Best-effort: a failure is logged and the directory still exists (the
+     * status surface then reports what is actually there).
+     *
+     * `options` carries the per-scope inputs a caller supplies when it
+     * provisions one scope deliberately (see {@link LocalAgentRegistry.provisionScope});
+     * the registry's own materialization passes none, so a harness that reads
+     * nothing from it behaves exactly as it did before the parameter existed.
+     * The return value is a READ-BACK of what the scope now holds, and `void`
+     * is the honest answer for a harness with nothing to report.
+     * @param homeDir - the scoped home to provision.
+     * @param options - per-scope inputs, absent on the registry's own materialization.
+     */
+    provision?: (homeDir: string, options?: LocalAgentScopeProvisionOptions) => LocalAgentScopeProvisionResult | void | Promise<LocalAgentScopeProvisionResult | void>;
+    /**
+     * Whether the scoped home currently holds usable credentials. Absent means
+     * the harness reports "not authenticated" and the status command still
+     * runs; the check is per-harness (a credentials directory, an auth file).
+     */
+    isAuthenticated?: (homeDir: string) => Promise<boolean>;
+    /**
+     * The credential marker's modification stamp (epoch ms), undefined when no
+     * credential exists. Two consumers: the manual-login watch requires a stamp
+     * NEWER than the watch start (a stale marker must not read as a fresh
+     * login), and `statusOf` downgrades a presence-true probe when a delegation
+     * reported an auth failure newer than the stamp (presence cannot see a
+     * server-side revocation; the next real login rewrites the marker and
+     * recovers the status).
+     */
+    credentialStamp?: (homeDir: string) => Promise<number | undefined>;
+    /**
+     * Sign out of the scoped account, clearing the stored credentials so a
+     * later login authorizes another account. Absent means the harness has no
+     * logout path and `/logout` reports it instead of guessing.
+     */
+    logout?: (homeDir: string) => Promise<void>;
+    /**
+     * Optional extra `/<name>` subcommands beyond the family's own. Returning
+     * undefined means the input is not this harness's; the family's unknown-
+     * subcommand error answers instead. A harness owns its extras (config
+     * commands, preset management), keeping the core seam generic.
+     * @param input - the trimmed subcommand input.
+     * @param invocation - the full command invocation.
+     * @returns the command result, or undefined when the subcommand is not this
+     * harness's.
+     */
+    subcommand?: (input: string, invocation: CommandInvocation) => Promise<CommandResult> | CommandResult | undefined;
+    /**
+     * The harness's fairness-relevant effective settings — the read side of an
+     * evaluation condition hash (the web-eval frozen baseline: every factor
+     * must be hashable). The registry's {@link LocalAgentRegistry.effectiveSettings}
+     * resolves it, and both status surfaces (the `/<name> status` reply and the
+     * `LocalAgentStatus` Remote) attach it. The snapshot is a LIVE read — it
+     * reflects what the harness would use right now, including scoped-config
+     * values a person edited. Pure JSON, never credentials; see
+     * {@link LocalAgentEffectiveSettings} for the field vocabulary and the
+     * absence-is-a-knob-absent rule.
+     *
+     * The snapshot is taken of ONE scoped home, named by the parameter: a
+     * harness reads its config out of the directory it is handed, so a named
+     * scope reports the settings that scope's rounds would run with rather than
+     * the default scope's.
+     * @param homeDir - the scoped home to read; the registry passes the
+     *   directory of the scope being asked about.
+     */
+    effectiveSettings?: (homeDir: string) => LocalAgentEffectiveSettings | Promise<LocalAgentEffectiveSettings>;
+    /**
+     * The harness's model knob: the settings card reads the memberless surface
+     * ("what would a round run with"), the member composer reads and switches a
+     * member's session-level override. Absent means the harness exposes no
+     * model surface beyond its free-text settings field — the gateway answers
+     * null and both UIs keep their pre-broker behavior.
+     */
+    modelBroker?: LocalAgentModelBroker;
+}
+/** Plugin config: the shared scoped-homes root and the login prompt wait. */
+export interface Config {
+    /** Root holding one directory per harness; subdirectories are `agent/<name>`. */
+    homesRoot: string;
+    /** How long `/login` waits for the device-code prompt before failing. */
+    loginPromptTimeoutMs?: number;
+}
+/** Grace between SIGTERM and SIGKILL when replacing an abandoned login child. */
+export declare const REPLACE_LOGIN_GRACE_MS = 5000;
+/** Remove terminal escape sequences from scraped CLI text. */
+export declare function stripAnsi(text: string): string;
+/**
+ * The characters a named scope may use. A scope is a NAME, never a path: the
+ * scoped home it selects always lands directly under the shared homes root,
+ * so `..`, a slash, or a leading dash can never walk out of it.
+ */
+export declare const SCOPE_NAME_RE: RegExp;
+/**
+ * The directory NAME of one harness's scoped home under the homes root: the
+ * harness name for the default scope, `<name>@<scope>` for a named one. The
+ * named directory is a SIBLING of the default one, never a child: nesting it
+ * inside would put a second CLI state tree under a directory each harness's
+ * own CLI owns and prunes.
+ * @param name - the harness name.
+ * @param scope - the named scope, or undefined for the default one.
+ * @returns the directory name under the homes root.
+ * @throws when the scope is present but not a `[a-z0-9-]` name.
+ */
+export declare function scopedHomeName(name: string, scope?: string): string;
+/**
+ * Enforce the resume-scope consistency rule, the scoped-home twin of
+ * {@link assertResumeCwdUnchanged}: a CLI session continues in the scoped home
+ * its earlier rounds ran in, so a round naming a different scope — including
+ * naming none when the first round named one, and the reverse — is rejected
+ * instead of resuming the conversation against another account's credentials
+ * and another directory's session records. Records written before the `scope`
+ * field existed carry no scope and are default-scope records; a resume of one
+ * with a scope is exactly the mismatch this refuses.
+ * @param record - the delegation's persisted record, when one exists.
+ * @param scope - the round's scope, or undefined for the default one.
+ * @param provider - the provider name, for the error message.
+ * @throws when the record's scope differs from the round's.
+ */
+export declare function assertResumeScopeUnchanged(record: LocalAgentDelegationRecord | undefined, scope: string | undefined, provider: string): void;
+/**
+ * Refuse a round that names its own model and would be served by a live
+ * driver — the model twin of {@link assertScopeExecOnly}, and refused for the
+ * same reason. A resident runtime (codex's `app-server`, claude's and kimi's
+ * ACP servers, the sub-dsh `serve`) binds its model when the PROCESS starts
+ * and then serves many rounds of one member, so a per-delegation model would
+ * either be ignored or would silently change what every other round of that
+ * runtime runs. Refused rather than quietly downgraded to exec: the caller
+ * named a model, and a fallback would answer a different question than the
+ * one asked. The evaluation pins `drive: exec` anyway (web-eval frozen
+ * decision 2).
+ * @param model - the round's requested model, or undefined for none.
+ * @param provider - the provider name, for the error message.
+ * @throws when a named model meets an active live driver.
+ */
+export declare function assertModelExecOnly(model: string | undefined, provider: string): void;
+/**
+ * The model one round starts its CLI with, resolved in the family's fixed
+ * order: the DELEGATION's own model (the `model` call option on the fresh
+ * round, re-requested by every resume round from the record) first, then the
+ * harness's `model` plugin-config key, then nothing — which leaves the scoped
+ * configuration file and, last, the CLI's own default to decide exactly as
+ * they did before either key existed.
+ *
+ * Blank is not a model: a whitespace-only value at either layer reads as
+ * unset, so an empty settings field cannot produce an empty flag value.
+ * @param requested - the delegation's own model, when it named one.
+ * @param configured - the plugin config's per-round resolver, when the plugin
+ *   passed one.
+ * @returns `{ model }` when either layer names one, `{}` otherwise — the
+ *   fragment a provider spreads into its run spec, so an absent model leaves
+ *   the spawn argv byte-identical to the shape that shipped before.
+ */
+export declare function resolveRoundModel(requested: string | undefined, configured?: () => string | undefined): {
+    model?: string;
+};
+/**
+ * Refuse a scoped round that would be served by a live driver. The resident
+ * runtimes (codex's `app-server`, claude's and kimi's ACP servers, the
+ * sub-dsh `serve`) are started per member against the DEFAULT scoped home and
+ * outlive a single round, so a scoped round taken by one would run under the
+ * wrong credentials and write its records into the wrong directory. Refused
+ * rather than silently downgraded to exec: the caller named a scope, and a
+ * quiet fallback would answer a different question than the one asked. The
+ * evaluation pins `drive: exec` anyway (web-eval frozen decision 2).
+ * @param scope - the round's scope, or undefined for the default one.
+ * @param provider - the provider name, for the error message.
+ * @throws when a named scope meets an active live driver.
+ */
+export declare function assertScopeExecOnly(scope: string | undefined, provider: string): void;
+/** Poll interval for a manual-handoff login watch. */
+export declare const MANUAL_LOGIN_POLL_MS = 2000;
+/** How long a manual-handoff login watches before reporting the timeout. */
+export declare const MANUAL_LOGIN_LIMIT_MS: number;
+/** Heartbeat interval for facade-tracked in-flight runs. */
+export declare const RUN_PROGRESS_HEARTBEAT_MS = 5000;
+/**
+ * How long after a run's result settles the facade still routes progress to
+ * that call's `onProgress`.
+ *
+ * A round's settle OBSERVATION (its observed model, CLI version, and token
+ * usage) is only knowable once the CLI process has exited and its whole
+ * output stream has been parsed — which, on every exec-drive provider, is
+ * strictly after `run.result` resolves (a cancelled run settles at the cancel
+ * moment, before the process is even reaped). Clearing the tracked run at
+ * result-settle therefore dropped exactly the one report the caller asked for:
+ * the `settled` payload reached the cordis event and nothing else. The entry's
+ * cancel lever and heartbeat still stop at result-settle — only the progress
+ * route is held open, and it closes the moment the `settled` report arrives.
+ */
+export declare const RUN_PROGRESS_SETTLE_GRACE_MS = 60000;
+/** Socket filename of the member-bridge listener, under the shared homes root. */
+export declare const MEMBER_BRIDGE_SOCKET_FILENAME = "member-bridge.sock";
+/**
+ * The per-harness append-only delegation-mapping log inside the harness's
+ * scoped home (`<homeDir>/<harness>/delegations.jsonl`): one JSON record per
+ * line, the last line per childSessionId wins — the same replace semantics as
+ * {@link LocalAgentRegistry.recordDelegation}. The file grows without
+ * rotation (accepted; same growth class as session_index/rollout files).
+ */
+export declare const DELEGATIONS_FILENAME = "delegations.jsonl";
+/**
+ * Resolve the working directory one CLI delegation round runs in: the caller's
+ * override when supplied (the {@link DelegationCallOptions.cwd} position —
+ * an orchestrator giving each evaluation cell its own directory), otherwise
+ * the parent session's cwd. Returns `undefined` when neither is present — the
+ * caller fails loud on that, exactly as it did before overrides existed.
+ * Named after the seam the official ACP provider uses for the same override;
+ * the future container-workdir layer (web-eval I3) lands here too.
+ * @param parentCwd - the parent session's cwd, when the session has one.
+ * @param override - the caller-supplied cwd, when one was passed.
+ * @returns the effective cwd, or undefined when neither source has one.
+ */
+export declare function resolveChildCwd(parentCwd: string | undefined, override: string | undefined): string | undefined;
+/**
+ * Enforce the resume-cwd consistency rule: a CLI session continues in the
+ * directory its earlier rounds ran in, so a round whose effective cwd differs
+ * from the recorded first-round cwd is rejected instead of resuming the
+ * conversation somewhere else. Records written before the `cwd` field existed
+ * carry no anchor and opt out — absence is the honest state, never a guess.
+ * @param record - the delegation's persisted record, when one exists.
+ * @param effectiveCwd - the round's resolved working directory.
+ * @param provider - the provider name, for the error message.
+ * @throws when the record anchors a different first-round cwd.
+ */
+export declare function assertResumeCwdUnchanged(record: LocalAgentDelegationRecord | undefined, effectiveCwd: string, provider: string): void;
+export declare const Config: z;
+/** Service name provided by this plugin and injected by patch rows. */
+export declare const LOCAL_AGENT_SERVICE = "localAgent";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        localAgent: LocalAgentRegistry;
+    }
+    interface Events {
+        /**
+         * A harness became resolvable: its scoped home exists and its command
+         * family is registered.
+         * @param harness - the registered harness.
+         * @mode emit
+         */
+        'localAgent/harness-added'(harness: LocalAgentHarness): void;
+        /**
+         * A harness left the registry; its command family is unregistered.
+         * @param name - the harness name that no longer resolves.
+         * @mode emit
+         */
+        'localAgent/harness-removed'(name: string): void;
+        /**
+         * Progress for one delegation run. The facade emits `heartbeat` payloads
+         * while a facade-tracked run is in flight; providers report the
+         * data-bearing kinds through `LocalAgentRegistry.reportRunProgress` and
+         * the registry re-emits them here (reports for sessions with no
+         * facade-tracked run still emit, so a provider-only run stays
+         * observable).
+         * @param childSessionId - the dsh child session id of the run.
+         * @param progress - the progress payload.
+         * @mode emit
+         */
+        'localAgent/run-progress'(childSessionId: string, progress: LocalAgentRunProgress): void;
+    }
+}
+/**
+ * Split one `/<harness>` input into its optional `--scope <name>` flag and the
+ * remaining subcommand. Both spellings a person reaches for are accepted
+ * (`--scope eval-b` and `--scope=eval-b`); everything else is left in place,
+ * so an input without the flag comes back exactly as it went in.
+ * @param input - the trimmed subcommand input.
+ * @returns the remaining input and the scope, or the error naming the rule.
+ */
+export declare function parseScopeFlag(input: string): {
+    input: string;
+    scope?: string;
+    error?: string;
+};
+/**
+ * Registry of local code-agent harnesses and the per-harness command family.
+ * @module @khorsheed/dsh-local-agent
+ */
+export declare class LocalAgentRegistry {
+    private readonly ctx;
+    private readonly homesRoot;
+    private readonly loginPromptTimeoutMs;
+    private readonly preparedMembers;
+    private readonly preparations;
+    readonly memberInbox: MemberInbox;
+    private readonly memberControls;
+    /** All provider starts, including direct tool starts, acquire the same whole-turn lease. */
+    withMemberConfigurationRound(binding: LocalAgentMemberBinding, start: (configuration: LocalAgentAppliedConfiguration) => Promise<SubagentRun>, signal?: AbortSignal, onAdmitted?: () => void | Promise<void>): Promise<SubagentRun>;
+    private requireInboxMember;
+    enqueueMemberInput(childSessionId: string, text: string, requestId: string): string;
+    resumeMemberInbox(childSessionId: string): void;
+    readMemberInbox(childSessionId: string): LocalAgentMemberInbox;
+    queuedMemberRounds(childSessionId: string): number;
+    /** The admitted snapshot belongs to this exact run object, including after settle. */
+    runConfiguration(run: object): LocalAgentAppliedConfiguration | undefined;
+    supportsMemberConfiguration(provider: string): boolean;
+    private memberControl;
+    /** Execution identity is available before the first native transcript exists. */
+    memberBinding(childSessionId: string): LocalAgentMemberBinding | undefined;
+    memberConfiguration(childSessionId: string): LocalAgentMemberControlState;
+    selectMemberConfiguration(childSessionId: string, requestId: string, expectedRevision: number, selection: LocalAgentMemberConfiguration): Promise<LocalAgentControlReceipt>;
+    cancelMemberConfiguration(childSessionId: string, requestId: string, expectedRevision: number): LocalAgentControlReceipt;
+    retryMemberConfiguration(childSessionId: string, expectedRevision: number): Promise<void>;
+    followMemberConfiguration(childSessionId: string, signal: AbortSignal): AsyncIterable<LocalAgentMemberControlState>;
+    /** Compatibility write routes through the durable slot, including while busy. */
+    setMemberModel(childSessionId: string, model: string | undefined): Promise<void>;
+    /** Independent live output transport for mirrored sessions without native Agents. */
+    readonly liveStreams: LocalAgentStreams;
+    private readonly harnesses;
+    /**
+     * Named scopes materialized in this host process, keyed exactly like their
+     * directory (`<name>@<scope>`) — the guard that keeps the mkdir, the
+     * harness provisioning and the per-directory delegation load to once each.
+     */
+    private readonly scopedHomes;
+    /**
+     * The provisioning currently running for each materialized scope.
+     *
+     * Materialization fires the harness's hook and does not wait for it — the
+     * directory is what the caller asked for, and the hook is best-effort. A
+     * caller that then provisions the SAME scope deliberately would otherwise
+     * race it, and both writers regenerate the same files. Recording the
+     * promise lets {@link LocalAgentRegistry.provisionScope} let the first one
+     * finish before it starts.
+     */
+    private readonly scopeProvisioning;
+    private readonly commandDisposers;
+    private readonly logins;
+    /**
+     * One delegation per dsh child session id: the CLI session id a resumed
+     * round continues, plus the ownership proof (parent session) and the
+     * provider that owns the CLI session.
+     */
+    private readonly delegations;
+    /**
+     * Observation recency for {@link latestObservedModel}: a monotonically
+     * increasing stamp per child session, bumped every time a record carrying an
+     * `observedModel` lands in {@link delegations} (recordDelegation,
+     * recordRoundSettled's merge, and the boot-time `delegations.jsonl` load —
+     * file order stamps the load, so the log's own last-line-wins semantics carry
+     * over). In-memory only: the records themselves deliberately carry no
+     * timestamp, and the Map's insertion order cannot serve (a `set` on an
+     * existing key keeps its first position, so an old record re-observed by a
+     * fresh round would sort as old).
+     */
+    private readonly observedModelStamps;
+    /** The stamp counter for {@link observedModelStamps}. */
+    private observedModelClock;
+    /**
+     * A settled round's observation that arrived BEFORE the delegation record
+     * existed ({@link recordRoundSettled} has nothing to merge into yet), held
+     * until {@link recordDelegation} lands and consumed there. A settle and the
+     * first-round record are ordered on every provider path today, but the
+     * record point is the provider's (a live round records at session/new, an
+     * exec round at the settle-time output parse), so the channel tolerates the
+     * inversion instead of dropping the observation. In-memory only and never
+     * persisted on its own: an observation whose record never arrives stays
+     * unrecorded, exactly as before.
+     */
+    private readonly pendingRoundObservations;
+    /**
+     * Per-(parent session, provider) FIFO of delegation intents. The family
+     * resume tool stages exactly one intent per call before awaiting
+     * `ctx.subagents.start()`, and the owning provider consumes exactly one per
+     * start, so fresh and resume rounds stay paired even under parallel
+     * delegations from one parent.
+     */
+    private readonly delegationIntents;
+    /**
+     * Per-child-session resume locks: a dsh child session may have only one
+     * in-flight resume at a time. The provider takes the lock before spawning
+     * the resume CLI and releases it when the run settles, so a second resume
+     * of the same child fails loud instead of racing the first process.
+     */
+    private readonly resumeLocks;
+    /**
+     * Kimi transcript-line mirror offset per child session, tracked
+     * INDEPENDENTLY of the delegation record: the offset must survive even when
+     * the CLI session hint is not parsed from stderr (the record — and therefore
+     * a resume — needs the hint, but the mirror bookkeeping does not). Without
+     * this separation a resume round would fall back to offset 0 and duplicate
+     * the first round's messages.
+     */
+    private readonly kimiMirrorOffsets;
+    /**
+     * Delegation-reported auth failures per harness (epoch ms of the report).
+     * Presence probes cannot see a server-side revocation, so a provider
+     * observing a 401/403 reports it here and `statusOf` downgrades the harness
+     * until its credential marker is rewritten by a real re-login (stamp newer
+     * than the mark).
+     */
+    private readonly authFailures;
+    /**
+     * Delegation-reported auth SUCCESSES per harness (epoch ms of the report):
+     * a round that reached the CLI's endpoint and completed, which is the only
+     * evidence a host has that a present credential is actually live. Cleared
+     * when a login starts or a logout lands, because both change which account
+     * the scoped home holds — a verification of the previous credential says
+     * nothing about the next one. Per host process on purpose: after a restart
+     * a present credential is `present-unverified` until a round exercises it,
+     * which is exactly what is known.
+     */
+    private readonly authSuccesses;
+    /**
+     * In-flight runs registered with the member channel, by per-run token. The
+     * bridge MCP server presents its token (and parent pid) on every callback;
+     * entries are invalidated on the run's settle path.
+     */
+    private readonly memberRuns;
+    /**
+     * The ACTIVE DELEGATION REGISTRY — in-flight local-agent runs by dsh child
+     * session id, the key the `/local-agent stop <childSessionId>` command and
+     * {@link LocalAgentRegistry.cancel} look up. Two registration kinds share
+     * the map:
+     *
+     * - **facade-tracked** ({@link trackRun}): runs started through
+     *   {@link LocalAgentRegistry.start} / {@link LocalAgentRegistry.resume},
+     *   carrying the fused AbortController whose signal reached
+     *   `ctx.subagents.start`; cancel aborts it.
+     * - **tool-registered** ({@link trackDelegationRun}): runs the family tool
+     *   starts directly through `ctx.subagents.start`, carrying an explicit
+     *   cancel lever (its fused controller); cancel calls it.
+     *
+     * Every entry clears itself when the run's result settles (any stop
+     * reason), and facade entries also stop their heartbeat timer then.
+     */
+    private readonly runs;
+    /**
+     * Progress routes held open past their run's result-settle, by child session
+     * id — see {@link RUN_PROGRESS_SETTLE_GRACE_MS}. An entry carries only the
+     * call's `onProgress` (never a cancel lever: a settled run is not
+     * cancellable) and self-destructs on the `settled` report or the grace
+     * timer, whichever comes first.
+     */
+    private readonly settledRuns;
+    /**
+     * Detach disposers for child sessions the facade reattached into the live
+     * store (see {@link LocalAgentRegistry.resume} step 5). Held for the plugin
+     * lifetime — the same lifecycle a provider-created child session has — and
+     * released together on plugin dispose. The reattach's WRITE handle is NOT
+     * here: it lives in {@link childWriteHandles}, shared with
+     * {@link syncChildSession}, and closes with the cache on dispose.
+     */
+    private readonly reattachDisposers;
+    /**
+     * The registry-owned WRITE handle per child session id (a resolved-value
+     * cache: the PROMISE is stored so concurrent acquirers share one open).
+     * Host 0.1.5 routes a live session's `session/event` appends into the
+     * per-id writer only while a write handle is open, so exactly one handle
+     * must exist per child — a second open fails SessionAlreadyOwnedError.
+     * Both owners of a child session's durability share this cache: the
+     * reattach recipe ({@link reattachChildSession}) and the explicit suffix
+     * sync ({@link syncChildSession}). Every handle closes on plugin dispose.
+     */
+    private readonly childWriteHandles;
+    /**
+     * @param ctx - context carrying the command registry.
+     * @param homesRoot - shared scoped-homes root.
+     * @param loginPromptTimeoutMs - device-code prompt wait.
+     */
+    constructor(ctx: Context, homesRoot: string, loginPromptTimeoutMs: number);
+    /**
+     * Absolute scoped home for one harness, in the default scope or in a NAMED
+     * one.
+     *
+     * The default scope (`scope` absent) is `<homesRoot>/<name>` and is a pure
+     * path computation, exactly as it always was. A named scope is the sibling
+     * directory `<homesRoot>/<name>@<scope>` — a name, never a path, so the
+     * directory can only ever be under the homes root — and is MATERIALIZED the
+     * first time it is named here: `mkdir` 0700 plus this harness's own
+     * provisioning, plus the load of that directory's own `delegations.jsonl`,
+     * once per (harness, scope) in this host process. Materializing on the read
+     * is what makes "a scope exists once something names it" true for every
+     * caller at once: `/<name> login --scope`, the status surfaces, a scoped
+     * delegation, and the evaluation's mount source.
+     *
+     * Credentials are never copied between scopes: a new named scope starts
+     * empty, reports `credentialState: absent`, and needs its own login.
+     * @param name - the harness name.
+     * @param scope - the named scope, or undefined for the default one.
+     * @returns `<homesRoot>/<name>`, or `<homesRoot>/<name>@<scope>`.
+     * @throws when the scope is present but not a `[a-z0-9-]` name.
+     */
+    homeDir(name: string, scope?: string): string;
+    /**
+     * Create one named scope's directory the first time it is named, with the
+     * same 0700 the default scope's gets, then run the harness's own
+     * provisioning and load that directory's persisted delegation mappings.
+     * Runs at most once per (harness, scope) per host process; the mkdir itself
+     * is idempotent, so a directory a person created by hand is adopted rather
+     * than refused. An unregistered harness gets the directory and nothing
+     * else — there is no harness to ask for provisioning yet.
+     */
+    private materializeScopedHome;
+    /**
+     * Provision ONE scope deliberately, with per-scope inputs, and report what
+     * the scope now holds.
+     *
+     * The difference from the materialization above is the whole reason this
+     * exists. Materialization runs once per (harness, scope) per host process,
+     * passes no options, and swallows failures — right for "somebody named a
+     * scope". A caller that provisions a scope on purpose is asking a question
+     * (`compose this preset`), needs the answer (`this is what it composes
+     * now`), and needs the failure (a preset that could not be composed must
+     * not read as one that was). So this one awaits, propagates, and returns
+     * the harness's read-back.
+     *
+     * A harness with no `provision` hook is not an error: there is simply
+     * nothing to do, and the caller's own read-back — the file it was going to
+     * check anyway — reports what is actually there.
+     * @param name - the harness name.
+     * @param scope - the named scope, or undefined for the default scoped home.
+     * @param options - per-scope inputs for the harness's provisioning.
+     * @returns the scoped home plus whatever the harness read back.
+     * @throws whatever the harness's provisioning throws.
+     */
+    provisionScope(name: string, scope?: string, options?: LocalAgentScopeProvisionOptions): Promise<LocalAgentScopeProvisionResult & {
+        homeDir: string;
+    }>;
+    /**
+     * Register one harness: provision its scoped home, register the
+     * `/<name> login|sessions` command family, and publish the added event.
+     * @param harness - the harness definition.
+     * @returns the disposer unregistering the command and the harness.
+     */
+    register(harness: LocalAgentHarness): () => void;
+    /**
+     * Resolve one harness by name.
+     * @param name - the harness name.
+     * @returns the harness, or undefined when it is not registered.
+     */
+    get(name: string): LocalAgentHarness | undefined;
+    /**
+     * Resolve the harness that claims one delegation provider — the inverse of
+     * {@link LocalAgentHarness.delegationProvider}, for surfaces handed a
+     * provider name (a delegation record's) that need the owning harness's
+     * knobs (its model broker).
+     * @param provider - the `ctx.subagents` provider name.
+     * @returns the claiming harness, or undefined when none claims it.
+     */
+    harnessForProvider(provider: string): LocalAgentHarness | undefined;
+    /**
+     * Every registered harness name, in registration order.
+     * @returns the harness names.
+     */
+    list(): readonly string[];
+    /**
+     * Every registered harness as a roster row, in registration order.
+     * @returns the roster rows.
+     */
+    roster(): readonly LocalAgentRosterRow[];
+    /**
+     * Record a delegation-observed authentication failure (a 401/403 from the
+     * CLI's endpoint). Presence probes cannot see a server-side revocation, so
+     * this mark downgrades the harness's reported status until a real re-login
+     * rewrites the credential marker (see {@link LocalAgentHarness.credentialStamp}).
+     * @param name - the harness whose credential failed.
+     * @param detail - the endpoint's answer, for the log.
+     * @param scope - the scope whose credential failed; absent means the
+     *   default scope. Each scope holds its own account, so the mark is per
+     *   scope: one scope's revocation says nothing about another's.
+     */
+    reportAuthFailure(name: string, detail: string, scope?: string): void;
+    /**
+     * Record a delegation-observed authentication SUCCESS: a round reached the
+     * harness CLI's endpoint and completed, so the scoped credential is known
+     * live and the status grades it `verified` instead of `present-unverified`.
+     * The counterpart of {@link reportAuthFailure}; providers wire both from the
+     * same settle path. A success newer than a failure mark also clears the
+     * `rejected` grade — a completed round outranks a stale rejection.
+     * @param name - the harness whose credential just worked.
+     * @param scope - the scope whose credential just worked; absent means the
+     *   default scope.
+     */
+    reportAuthSuccess(name: string, scope?: string): void;
+    /**
+     * Forget what delegation rounds observed about one harness's credential.
+     * Called where the account itself can change — a login starting, a logout
+     * landing — because a verdict about the previous credential describes
+     * nothing about the next one.
+     */
+    private forgetCredentialObservations;
+    /**
+     * Query one harness's auth status, in the default scope or in a named one.
+     * @param name - the harness name.
+     * @param scope - the named scope to report on; absent means the default
+     *   scope and the reply is exactly what it always was. A named scope is
+     *   materialized by the read (see {@link homeDir}), so a scope nobody has
+     *   logged into reports `credentialState: absent` against a real, empty
+     *   directory.
+     * @returns the status snapshot.
+     */
+    statusOf(name: string, scope?: string): Promise<LocalAgentStatus>;
+    /**
+     * Grade one harness's credential from the two channels a status read has:
+     * the scoped home's own shape ({@link LocalAgentHarness.isAuthenticated})
+     * and what delegation rounds reported. Presence alone can only ever say
+     * `present-unverified` — an expired, unrefreshable record has exactly the
+     * shape of a working one, and saying so is this grade's whole point.
+     * @param harness - the harness to grade.
+     * @param homeDir - its scoped home.
+     * @param scope - the scope that directory belongs to; the delegation-
+     *   reported observations are per scope, because each scope holds its own
+     *   account.
+     * @returns the credential grade.
+     */
+    private credentialStateOf;
+    /**
+     * One harness's fairness-relevant effective settings — the evaluation
+     * condition hash's read side (web-eval frozen decisions 2 to 4: drive,
+     * approval boundary, reasoning effort, endpoint route). Read-only: the
+     * snapshot reflects the settings in force right now, whatever layer set
+     * them (plugin config, scoped-home config a person edited, process env).
+     * Pure JSON and credential-free by contract; see
+     * {@link LocalAgentEffectiveSettings}.
+     * @param name - the harness name.
+     * @param scope - the scope to snapshot; absent means the default one.
+     * @returns the snapshot, or undefined when the harness declares none.
+     */
+    effectiveSettings(name: string, scope?: string): Promise<LocalAgentEffectiveSettings | undefined>;
+    /**
+     * Query one harness's scoped session records.
+     * @param name - the harness name.
+     * @param scope - the scope to list; absent means the default one. Session
+     *   records belong to the directory the rounds ran in, so a named scope
+     *   lists its own and nothing of the default scope's.
+     * @returns the session records in the harness's own order.
+     */
+    sessionsOf(name: string, scope?: string): Promise<readonly LocalAgentSessionRecord[]>;
+    /**
+     * Record one delegation's CLI-session mapping after its first round
+     * settles, so a later resume round can continue the same CLI session. The
+     * provider learns the CLI session id only from the settled round's output,
+     * so recording happens post-settle. A duplicate child session id replaces
+     * the earlier record: a resumed child keeps one mapping. The record is also
+     * appended to the owning harness's `delegations.jsonl` (last line per child
+     * session wins), so a host restart keeps the mapping resolvable. A settled
+     * round's observation that arrived before this record (the provider's
+     * record point is its own) is merged in from the pending stash — see
+     * {@link recordRoundSettled}.
+     * @param record - the delegation's dsh child session id, provider, owning
+     *   parent session id, and CLI session id.
+     */
+    recordDelegation(record: LocalAgentDelegationRecord): void;
+    /**
+     * Resolve the CLI-session mapping a resume tool call needs to continue a
+     * previous delegation. Ownership is proven by the recorded parent session
+     * id: a caller naming a child session it did not delegate is rejected
+     * instead of resuming someone else's conversation context.
+     * @param childSessionId - the dsh child session id from the first round.
+     * @param claims - the caller's provider and parent session id.
+     * @returns the recorded CLI session id to continue.
+     * @throws when the child session is unknown, owned by another parent, or
+     *   served by a different provider than claimed.
+     */
+    resolveDelegation(childSessionId: string, claims: {
+        readonly provider: string;
+        readonly parentSessionId: string;
+    }): {
+        readonly cliSessionId: string;
+    };
+    /**
+     * Stage one delegation intent for a provider's next `start()`. The family
+     * resume tool stages exactly one intent per call before awaiting
+     * `ctx.subagents.start()`; the provider consumes exactly one per start via
+     * {@link takeDelegationIntent}, so the per-(parent, provider) FIFO pairs
+     * fresh and resume rounds even under parallel delegations from one parent.
+     * @param parentSessionId - the delegating parent session id.
+     * @param provider - the `ctx.subagents` provider name.
+     * @param intent - the fresh or resume intent for the next start.
+     */
+    stageDelegationIntent(parentSessionId: string, provider: string, intent: LocalAgentDelegationIntent): void;
+    /**
+     * Consume the oldest staged intent for one provider start, or `undefined`
+     * when the queue is empty (a provider invoked directly without the family
+     * tool stages nothing and starts a fresh round).
+     * @param parentSessionId - the delegating parent session id.
+     * @param provider - the `ctx.subagents` provider name.
+     * @returns the oldest staged intent, or undefined when none is staged.
+     */
+    takeDelegationIntent(parentSessionId: string, provider: string): LocalAgentDelegationIntent | undefined;
+    /**
+     * Remove one previously staged intent by reference, returning whether it was
+     * still queued. The delegation facade calls this when `ctx.subagents.start()`
+     * throws: an intent the provider never consumed must not linger in the FIFO,
+     * where the NEXT same-(parent, provider) start would misconsume it as its own
+     * (orphan-intent crosstalk). When the provider already consumed the intent
+     * before throwing, the removal is a no-op and the pairing stays intact.
+     * @param parentSessionId - the delegating parent session id.
+     * @param provider - the `ctx.subagents` provider name.
+     * @param intent - the exact intent object passed to
+     *   {@link stageDelegationIntent}.
+     * @returns whether the intent was removed (false when already consumed or
+     *   never staged).
+     */
+    unstageDelegationIntent(parentSessionId: string, provider: string, intent: LocalAgentDelegationIntent): boolean;
+    /**
+     * Every recorded delegation, in recording order. The invariant companion
+     * cross-checks each record's provider against the mounted subagent
+     * providers so a provider rename cannot leave a stale resume mapping.
+     * @returns the recorded delegations.
+     */
+    listDelegations(): readonly LocalAgentDelegationRecord[];
+    /**
+     * Read-only lookup of one delegation by its dsh child session id — the
+     * member channel's membership check. Unlike {@link resolveDelegation} this
+     * never throws and performs no ownership assertion: the gateway composes it
+     * with {@link resume} (whose ownership checks are unchanged) for the
+     * human-opened child session, where the record itself is the authorization
+     * source.
+     * @param childSessionId - the dsh child session id.
+     * @returns the record, or undefined when this child was never delegated
+     *   through the family.
+     */
+    getDelegation(childSessionId: string): LocalAgentDelegationRecord | undefined;
+    /**
+     * Read-only lookup of one delegation's facts by its dsh child session id,
+     * WITHOUT the CLI-session resume handle — the orchestrator-facing read side
+     * (the evaluation reads a cell's recorded `observedModel` and first-round
+     * `cwd` through it). Same never-throws contract as
+     * {@link getDelegation}; the record's optional fields stay absent when the
+     * stream never yielded them.
+     * @param childSessionId - the dsh child session id.
+     * @returns the record without `cliSessionId`, or undefined when this child
+     *   was never delegated through the family.
+     */
+    delegationOf(childSessionId: string): LocalAgentDelegationInfo | undefined;
+    /**
+     * Stamp a record's `observedModel` with the next recency tick, when the
+     * record carries a usable one. Called everywhere a record with an observed
+     * model lands in {@link delegations}; a blank value is no observation.
+     */
+    private noteObservedModel;
+    /**
+     * The most recent model one provider was OBSERVED running across all its
+     * recorded delegations — the display hint behind the cli-builtin layer
+     * (nothing names the CLI's compiled default, but "what ran last" is what a
+     * round with no model layer would run again). Recency is the observation
+     * stamp ({@link observedModelStamps}), not record insertion order: a round
+     * that re-observes an old delegation counts as the freshest. Records whose
+     * stream never yielded a model (absent or blank) are not candidates.
+     * @param provider - the `ctx.subagents` provider name to scan.
+     * @returns the newest observed model identifier, or undefined when this
+     *   provider was never observed running one.
+     */
+    latestObservedModel(provider: string): string | undefined;
+    /**
+     * Record one delegation round's settled observation: merge `observedModel`
+     * into the delegation record when present (in memory and `delegations.jsonl`,
+     * same replace semantics as {@link recordDelegation}) and report the
+     * `settled` run-progress event with the round's observed model and usage.
+     * Providers call it once per settled round, at the point their output
+     * stream has been fully parsed; fields the stream did not yield stay absent
+     * — absence is recorded, never guessed. A record that does not exist yet
+     * (the round's settle beat the provider's record point — e.g. a round whose
+     * CLI session id only parses post-settle) does not lose the observation: it
+     * is stashed and merged by the later {@link recordDelegation}; the event
+     * still reports either way.
+     * @param childSessionId - the dsh child session id of the settled round.
+     * @param round - the round's observed model, version, usage and tool-call
+     *   accounting, each optional.
+     */
+    recordRoundSettled(childSessionId: string, round: {
+        readonly observedEffort?: string;
+        readonly observedModel?: string;
+        readonly cliVersion?: string;
+        readonly usage?: TokenUsage;
+        readonly toolCalls?: LocalAgentToolCalls;
+    }): void;
+    /**
+     * Acquire the resume lock for one child session. A dsh child session may
+     * have only one in-flight resume: the provider takes the lock before
+     * spawning the resume CLI and releases it when the run settles, so a second
+     * resume of the same child fails loud instead of racing the first process.
+     * Fresh delegations never take the lock (they mint a new child session).
+     * @param childSessionId - the dsh child session id to resume.
+     * @returns whether the lock was acquired (false when already held).
+     */
+    acquireResumeLock(childSessionId: string): boolean;
+    /**
+     * Release the resume lock for one child session. The provider releases it
+     * on every settle path (completed, failed, cancelled) so a deadlock never
+     * strands a later resume. Releasing an unheld lock is a no-op.
+     * @param childSessionId - the dsh child session id.
+     */
+    releaseResumeLock(childSessionId: string): void;
+    /**
+     * Read-only probe of the per-child resume lock. The delegation facade uses
+     * it to fail fast BEFORE staging an intent; the authoritative mutual
+     * exclusion stays with the provider's `acquireResumeLock` inside `start()`.
+     * @param childSessionId - the dsh child session id.
+     * @returns whether a resume of this child session is currently in flight.
+     */
+    isResumeLocked(childSessionId: string): boolean;
+    private memberBridgeAvailable;
+    /** Listener lifecycle owns this flag; it is never persisted across host restarts. */
+    setMemberBridgeAvailable(available: boolean): void;
+    /** Transport/readiness capability only; authenticated generation needs separate acceptance. */
+    canCoordinateRoom(childSessionId: string): boolean;
+    /**
+     * Register one CLI run with the member channel and mint its per-run token.
+     * The provider calls this before spawning the CLI (fresh and resume rounds
+     * alike) and injects the token into the bridge MCP server's environment; the
+     * token is how the host resolves which run — and therefore which member — a
+     * bridge callback belongs to, so a member's identity is never self-reported.
+     * @param run - the run's member identity (child session, parent, provider).
+     * @returns the minted token, invalidated by {@link unregisterMemberRun}.
+     */
+    registerMemberRun(run: LocalAgentMemberRun): string;
+    /**
+     * Resolve a member-channel token to its run, or undefined when the token is
+     * unknown or already invalidated (the run settled).
+     * @param token - the token the bridge presented.
+     * @returns the registered run, or undefined.
+     */
+    resolveMemberRun(token: string): LocalAgentMemberRun | undefined;
+    /**
+     * Invalidate a run's member-channel token on its settle path (any stop
+     * reason). A bridge callback arriving after settle is an unknown token.
+     * @param token - the token to invalidate.
+     */
+    unregisterMemberRun(token: string): void;
+    /**
+     * The loopback socket path the member-bridge listener owns. Providers inject
+     * it into the bridge's environment so the stdio MCP server knows where to
+     * call back.
+     * @returns the unix socket path under the shared homes root.
+     */
+    memberBridgeSocketPath(): string;
+    /**
+     * The stdio MCP server entry for the member bridge, for providers to write
+     * into their CLI's scoped MCP config. The bridge script ships inside this
+     * package and runs under the same Node that runs the host.
+     * @returns the command + args declaring the bridge server.
+     */
+    memberBridgeCommand(): {
+        command: string;
+        args: string[];
+    };
+    /** Prepare a roster-owned identity without a paid prompt; repeated calls coalesce. */
+    prepareMember(parentSessionId: string, provider: string, childSessionId: string, options?: DelegationCallOptions): Promise<string>;
+    private prepareMemberNow;
+    isPreparedMember(childSessionId: string): boolean;
+    /**
+     * Start a FRESH delegation on one subagent provider — the programmatic
+     * equivalent of the family tool's fresh call, for plugins acting on the
+     * user's behalf (room, orchestrators). One call performs the provider
+     * pre-check, resolves the live parent agent, stages exactly one
+     * `{ kind: 'fresh' }` intent, and starts the provider in the same
+     * synchronous flow, so the per-(parent, provider) FIFO pairing holds. When
+     * the start throws, the staged intent is rolled back via
+     * {@link unstageDelegationIntent} (a no-op once the provider consumed it).
+     *
+     * The returned run is tracked under its `run.id` (== the new dsh child
+     * session id) until `run.result` settles; {@link cancel} aborts it by that
+     * id. Note on trust: cordis plugins share one process, so the ownership
+     * checks here and in {@link resume} guard against caller MISTAKES, not
+     * against a malicious plugin — their real protection target is untrusted
+     * model text, which never carries the resume handle (first-class parameter
+     * + intent channel only).
+     * @param parentSessionId - the delegating parent session id; must have a
+     *   live agent (`ctx.agents.get`, a harness hard constraint).
+     * @param provider - the `ctx.subagents` provider name.
+     * @param prompt - the child user message content blocks.
+     * @param options - optional label and caller-owned abort signal.
+     * @returns the published subagent run.
+     * @throws when the subagents/agents service is not mounted, the provider is
+     *   not registered, or the parent session has no live agent — in every case
+     *   BEFORE anything is staged.
+     */
+    start(parentSessionId: string, provider: string, prompt: ContentBlock[], options?: DelegationCallOptions): Promise<SubagentRun>;
+    /**
+     * Resume a recorded delegation: continue the SAME CLI session inside the
+     * SAME dsh child session. One call performs, in order:
+     *
+     * 1. provider pre-check (`ctx.subagents.getProvider`) — fails loud WITHOUT
+     *    staging, so an unknown provider never leaves an orphan intent;
+     * 2. `resolveDelegation` ownership check (unchanged semantics): the handle
+     *    must name a delegation THIS parent session recorded through THIS
+     *    provider;
+     * 3. read-only resume-lock probe ({@link isResumeLocked}) — fails fast
+     *    without staging; the provider still takes the authoritative lock inside
+     *    its `start()`;
+     * 4. live parent agent resolution (`ctx.agents.get`) — a harness hard
+     *    constraint, since `ctx.subagents.start` requires a live parent;
+     * 5. child-session REATTACH when `ctx.sessions.get(childSessionId)` is
+     *    undefined (recipe below; `opts.reattach === false` disables this step
+     *    and fails loud on a non-live child instead);
+     * 6. stage `{ kind: 'resume', childSessionId, cliSessionId }` and, in the
+     *    same synchronous flow, `await ctx.subagents.start(provider, …)`;
+     * 7. on start failure, roll the intent back via
+     *    {@link unstageDelegationIntent} (no-op once consumed);
+     * 8. on success, track the run under `childSessionId` for {@link cancel}
+     *    until `run.result` settles.
+     *
+     * **Reattach recipe** (callers replicating this flow — e.g. room — copy
+     * exactly this sequence):
+     *
+     * ```ts
+     * const handle = await ctx.sessionPersistence.open(SessionId(childSessionId), 'write')
+     * try {
+     *   const cold = await handle.read(0)
+     *   const session = ctx.sessions.prepare(SessionId(childSessionId), {
+     *     seed: [...cold.events],
+     *     meta: structuredClone(handle.header),
+     *     inheritedEventCount: handle.inheritedEventCount,
+     *     eventState: cold.eventState,
+     *   })
+     *   // The seeded constructor's session/end-seed marker lands before enter()
+     *   // installs publication hooks — push the unstored suffix through the
+     *   // handle directly, or the writer's contiguous cursor diverges.
+     *   const unstored = session.snapshotEvents().slice(cold.events.length)
+     *   if (unstored.length > 0) await handle.append(unstored)
+     *   const detach = ctx.sessions.enter(session)
+     *   try { ctx.sessions.announce(session) }
+     *   catch (error) { detach(); throw error }
+     *   // Hold BOTH for the reattached lifetime: the backend routes live
+     *   // session/event appends into the per-id writer only while the write
+     *   // handle is open; closing it ends persistence for the session.
+     * } catch (error) {
+     *   await handle.close().catch(() => {})
+     *   throw error
+     * }
+     * ```
+     *
+     * Hold `detach` and `handle` for the plugin lifetime. Announce the restored
+     * live session after entering it, rolling back detach if announcement fails.
+     * History followers need this lifecycle edge to replay the constructor's
+     * end-seed suffix before the provider publishes subsequent events.
+     * @param parentSessionId - the delegating parent session id; must match the
+     *   recorded one and have a live agent.
+     * @param provider - the `ctx.subagents` provider that owns the CLI session.
+     * @param childSessionId - the dsh child session id from the first round (the
+     *   resume handle).
+     * @param prompt - the follow-up user message content blocks.
+     * @param options - optional label and caller-owned abort signal.
+     * @returns the published subagent run.
+     * @throws on unknown provider, unknown/foreign-parent/wrong-provider handle,
+     *   an in-flight resume of the same child, or a missing live parent agent —
+     *   all BEFORE anything is staged.
+     */
+    resume(parentSessionId: string, provider: string, childSessionId: string, prompt: ContentBlock[], options?: DelegationCallOptions): Promise<SubagentRun>;
+    /**
+     * Cancel an in-flight facade-started run by its dsh child session id: aborts
+     * the internal controller whose (fused) signal was passed to
+     * `ctx.subagents.start`, which is the canonical cancellation channel for a
+     * one-shot run. The provider settles the run with an `aborted`-class stop
+     * reason. A caller holding the `SubagentRun` may also `run.dispose()`.
+     * @param childSessionId - the dsh child session id of the run to cancel.
+     * @returns whether an in-flight run was found and signalled (false on a
+     *   miss — never a silent success, never a throw).
+     */
+    cancel(childSessionId: string): boolean;
+    /**
+     * Register a NON-facade in-flight delegation run with the active-delegation
+     * registry, keyed by the dsh child session id, so the `/local-agent stop`
+     * command and {@link cancel} can reach it. This is the family TOOL's entry
+     * point: the tool starts its runs through `ctx.subagents.start` directly
+     * (not the facade), so without this registration its in-flight runs would
+     * be invisible to the stop command. The caller owns the cancel lever — a
+     * controller fused with the run's request signal, aborted exactly like the
+     * facade's tracked controller. The entry clears itself when the run's
+     * result settles (any stop reason); an existing facade entry for the same
+     * child session wins (it already owns cancellation and progress).
+     * @param childSessionId - the dsh child session id (the run id).
+     * @param run - the published subagent run.
+     * @param cancel - the lever that aborts the run's request signal.
+     */
+    trackDelegationRun(childSessionId: string, run: SubagentRun, cancel: () => void): void;
+    /**
+     * Whether the active-delegation registry holds an in-flight run for the
+     * child session — the registry's read side for the `/local-agent stop`
+     * command's miss report (the command cancels through {@link cancel}).
+     * @param childSessionId - the dsh child session id.
+     * @returns whether a run is currently in flight under that id.
+     */
+    isDelegationActive(childSessionId: string): boolean;
+    /**
+     * The child session ids with an in-flight delegation run — the gateway's
+     * `activeDelegations` Remote exposes this to the browser so surfaces can
+     * mark one-shot rows as running.
+     * @returns the in-flight child session ids.
+     */
+    activeDelegations(): readonly string[];
+    /**
+     * Read the kimi transcript lines already mirrored into one child session,
+     * so a resumed round mirrors only its delta instead of duplicating earlier
+     * messages. Absent means the first round has not mirrored yet. Reads the
+     * dedicated offset map (never gated on a delegation record).
+     * @param childSessionId - the dsh child session id.
+     * @returns the mirrored transcript-line count, or undefined.
+     */
+    kimiMirroredLines(childSessionId: string): number | undefined;
+    /**
+     * Advance the kimi transcript-line mirror offset for one child session.
+     * The kimi provider calls this after every mirror (fresh or resumed) with
+     * the new total transcript-line count. Writes the dedicated offset map so
+     * the offset survives even without a delegation record; the record's own
+     * field is mirrored for completeness.
+     * @param childSessionId - the dsh child session id.
+     * @param lines - the total transcript lines mirrored so far.
+     */
+    setKimiMirroredLines(childSessionId: string, lines: number): void;
+    /** Resolve the subagents service or fail loud naming the missing service. */
+    private requireSubagents;
+    /** Fail loud on an unknown provider BEFORE any intent is staged. */
+    private requireProvider;
+    /** Resolve the live parent Agent or fail loud (harness hard constraint). */
+    private requireLiveParent;
+    /**
+     * Ensure a delegated child session is live in this process, reattaching it
+     * from persistence when it is not — a host restart evicts every child from
+     * the live store. This is the public entry of the facade resume's reattach
+     * recipe for callers that start resume rounds WITHOUT the facade (the
+     * family subagent tool starts runs directly through `ctx.subagents.start`;
+     * without this call the provider refuses the resume as "not live").
+     * Idempotent; a child that was never persisted fails through the
+     * persistence layer's own not-found error.
+     * @param childSessionId - the dsh child session id (the resume handle).
+     */
+    ensureChildLive(childSessionId: string): Promise<void>;
+    /**
+     * Restore a persisted child session into the live store when it is absent —
+     * the reattach recipe documented on {@link resume}. Announce the restored
+     * lifecycle so open history followers receive the constructor suffix before
+     * subsequent appends. Hold detach in {@link reattachDisposers} until plugin
+     * dispose; the write handle comes from the shared
+     * {@link childWriteHandles} cache so a later {@link syncChildSession}
+     * reuses it instead of failing SessionAlreadyOwnedError on a second open.
+     */
+    private reattachChildSession;
+    /**
+     * Sync a live delegated child session's events into durable storage through
+     * the registry-cached write handle, creating the stored session on first
+     * sync. The host's live write-behind routes `session/event` appends into
+     * the per-id writer only while a write handle is open AND a checkpoint
+     * drains it — a delegated mirror session has no agent loop, so nothing ever
+     * checkpoints it and production child logs stayed header-only. This explicit
+     * suffix sync is the mirror's durability path: read the stored prefix,
+     * append only what is missing (idempotent under repetition and under a
+     * working write-behind), then flush. A failure downgrades to a warn and the
+     * handle stays cached for the next sync — a persistence hiccup must never
+     * fail the delegation round.
+     * @param session - the live child session to sync.
+     */
+    syncChildSession(session: Session, strict?: boolean): Promise<void>;
+    /**
+     * Get or open the child session's registry-owned WRITE handle (the
+     * {@link childWriteHandles} cache). When the caller carries the session
+     * header (a sync), a missing stored session is created from it; a create
+     * that loses a stat/create race adopts the winner's stored session. A
+     * failed acquisition is evicted so the next call retries from scratch.
+     */
+    private acquireChildWriteHandle;
+    /**
+     * Evict one child session's cached write handle and close it. Used when an
+     * owner gives the session up (a failed reattach); normal lifetimes close
+     * with the cache on plugin dispose.
+     */
+    private releaseChildWriteHandle;
+    /**
+     * Track one facade-started run under its child session id for
+     * {@link cancel} and progress routing; the entry (and its heartbeat timer)
+     * clears itself when the run's result settles (any stop reason, resolved or
+     * rejected). While tracked, the facade emits a `heartbeat` progress every
+     * {@link RUN_PROGRESS_HEARTBEAT_MS}; the timer is unref'd so it never keeps
+     * the process alive.
+     */
+    private trackRun;
+    /** Close one parked progress route, if any. */
+    private dropSettledRun;
+    /**
+     * The provider-facing progress reporting channel: a provider reports a
+     * run's data-bearing progress (mirror counts now, live deltas with M3), and
+     * the registry forwards it — as the `localAgent/run-progress` cordis event,
+     * and to the `onProgress` callback when the child session has a
+     * facade-tracked run. Reports for untracked child sessions still emit the
+     * event (a provider-only run must stay observable) and invoke no callback.
+     * The facade's own heartbeat rides the same path.
+     * @param childSessionId - the dsh child session id of the running delegation.
+     * @param progress - the progress payload.
+     */
+    reportRunProgress(childSessionId: string, progress: LocalAgentRunProgress): void;
+    /**
+     * Resolve one harness or fail loud. */
+    private requireHarness;
+    /**
+     * Append one delegation record to the owning harness's `delegations.jsonl`.
+     * Durability is synchronous (recording happens once per fresh-round settle)
+     * and best-effort: a provider with no claiming harness or a filesystem
+     * failure keeps the in-memory record and warns — recording must never break
+     * a settling run.
+     */
+    private persistDelegation;
+    /**
+     * Load one scoped home's persisted delegation mappings into the in-memory
+     * maps. The default scope runs synchronously inside {@link register} before
+     * `localAgent/harness-added` fires — unchanged; a named scope's file is read
+     * when that scope's directory is materialized ({@link homeDir}). Malformed
+     * or foreign-provider lines skip with a warn; the last line per child
+     * session wins (matching {@link recordDelegation}'s replace semantics), and
+     * a record's `kimiMirroredLines` restores the mirror offset.
+     * @param harness - the harness whose log is read.
+     * @param scope - the scope whose directory holds the log; absent means the
+     *   default scope.
+     */
+    private loadDelegations;
+    /**
+     * Dispatch `/login`, `/status`, `/sessions` and `/logout` for one harness,
+     * in the default scope or — with `--scope <name>` — in a named one. The
+     * flag is parsed off the input before the verb is matched, so every family
+     * verb takes it and an input without it is dispatched exactly as before.
+     * A harness's own extra subcommands receive the RAW input, flag included:
+     * the family does not rewrite a subcommand it does not own.
+     */
+    private handle;
+    /**
+     * Run one login flow. The device-code variant spawns the CLI in the scoped
+     * home and captures its prompt from stderr/stdout; the reply surfaces that
+     * prompt immediately while the child keeps polling in the background. The
+     * manual variant spawns nothing — the reply carries the terminal
+     * instructions and a watch polls the credential probe. A second login while
+     * one is pending replaces it — a stale or abandoned attempt (browser never
+     * opened, user gave up) must not hold the slot forever, and the user's
+     * retry should just get a fresh start. An abandoned device-code login with
+     * no retry self-heals when the CLI's own device code expires and its
+     * polling child exits (kimi/codex do); no idle timer is added because a
+     * too-short one would kill a user who is genuinely authorizing (the manual
+     * watch is bounded instead). A harness without a login flow answers with an
+     * error instead of spawning anything.
+     * Each scope logs in on its own: credentials are never copied between
+     * scopes, so `--scope <name>` authorizes THAT directory's account and the
+     * pending-login slot is per (harness, scope) too — a login in one scope
+     * neither replaces nor observes another's.
+     * @param harness - the harness whose login flow runs.
+     * @param scope - the scope to log in; absent means the default one.
+     * @returns the command result: the device-code prompt, or the manual
+     *   handoff's terminal instructions.
+     */
+    private login;
+    /**
+     * The shared credential watch behind the manual and pty login variants:
+     * polls the probe until the credential lands (presence AND, when the
+     * harness exposes a credential stamp, a stamp rewritten after the watch
+     * started — a leftover marker must not conclude a login), the window
+     * expires, or a new login replaces the watch. Outcomes are logged; the
+     * surfaces' own status polling picks the landed credential up.
+     * @param harness - the harness being logged in.
+     * @param probe - the credential probe.
+     * @param controller - the pending login's controller (done resolves here).
+     * @param scope - the scope being logged in; absent means the default one.
+     */
+    private watchCredential;
+    /**
+     * The manual-handoff login: the reply carries the exact command the user
+     * runs in their own terminal, and a bounded watch polls the credential probe
+     * (default: the harness's `isAuthenticated`) until the credential lands, the
+     * window expires, or a new login replaces the watch. The reply cannot carry
+     * the outcome — the command channel has already returned — so success and
+     * timeout are logged, and the surfaces' own status polling (the settings
+     * section re-probes every few seconds) picks the landed credential up.
+     * @param harness - the harness declaring the manual flow.
+     * @param login - the manual variant declaration.
+     * @param scope - the scope being logged in; absent means the default one.
+     * @returns the instructions as the command success text.
+     */
+    private manualLogin;
+    /**
+     * The pty login: spawn the CLI under a pseudo-terminal wrapper so its
+     * TTY-only auth flow runs — current claude auto-opens the user's browser
+     * itself. The OAuth URL is captured from the merged output as a fallback,
+     * and when the CLI prompts for a code the user pastes it through
+     * `/<name> code <value>` (written to the child's stdin). Completion is the
+     * shared credential watch. Windows has no script(1) wrapper; there the
+     * reply falls back to the manual instruction.
+     * @param harness - the harness declaring the pty flow.
+     * @param login - the pty variant declaration.
+     * @param scope - the scope being logged in; absent means the default one.
+     *   The CLI runs with its scoped-home variable pointed at THAT directory,
+     *   so the grant it writes lands in the scope that asked for it.
+     * @returns the browser/paste instructions as the command success text.
+     */
+    private ptyLogin;
+    /**
+     * Deliver the user's pasted OAuth code to a pending pty login's stdin.
+     * @param harness - the harness whose login is pending.
+     * @param code - the pasted code.
+     * @param scope - the scope whose login is pending; absent means the default
+     *   one. The pending-login slot is per scope, so the code reaches the login
+     *   that asked for it.
+     * @returns the command result.
+     */
+    private submitLoginCode;
+    /**
+     * Spawn the harness login command and capture its device-code prompt. The
+     * scoped-home variable points the CLI at the scope being logged in, so the
+     * grant lands in that directory and nowhere else.
+     */
+    private runLogin;
+}
+/**
+ * Mount the local-agent core: provide the harness registry and the family
+ * command listing the registered harnesses (the client roster channel).
+ * @param ctx - plugin context carrying the command registry.
+ * @param config - shared scoped-homes root and login prompt wait.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map