@mono-agent/agent-runtime 0.4.0 → 0.4.1

package/src/ai/types.js

@@ -1,40 +1,155 @@
 // Runtime contracts. These are JSDoc-only; the codebase is JS
 // (no TypeScript), so the types document the bridge surface that active
 // runtimes implement through src/ai/runtime/registry.js.
+//
+// `tsc -p tsconfig.types.json` (allowJs + declaration + emitDeclarationOnly)
+// compiles these typedefs into packages/agent-runtime/types/ai/types.d.ts;
+// downstream TS consumers (currently the runtime-adapter package) import them
+// via `import('./types.js').X` JSDoc syntax from the other seam files, or
+// transitively through the package root's generated declarations.
+//
+// A few fields below use the `"literal" | (string & {})` shape (a "branded
+// string union"). This keeps the known literal values available for
+// IDE/editor autocomplete while still accepting any plain `string`, since
+// hosts validate the real vocabulary at runtime (parseRuntimeModelReference,
+// resolveRuntimeBridge) rather than at the type level — the type only
+// documents the values active runtimes currently produce.
+
+/**
+ * @typedef {"claude" | "pi" | "codex" | "opencode" | (string & {})} RuntimeSdkId
+ * Canonical active runtime id. See ACTIVE_RUNTIME_KINDS (model-refs.js) for
+ * the enforced-at-runtime vocabulary.
+ */
+
+/**
+ * @typedef {"claude" | "claude-code" | "codex-app" | "opencode-app" | "pi" | (string & {})} RuntimeBridgeId
+ * Registry bridge id (distinct from RuntimeSdkId: a single sdk can be served
+ * by more than one bridge, e.g. sdk "claude" is served by both the "claude"
+ * SDK bridge and the "claude-code" CLI bridge). See
+ * src/ai/runtime/registry.js's builtinBridgeSpecs.
+ */
 
 /**
  * @typedef {Object} RuntimeModelRef
- * @property {"claude" | "pi" | "codex"} sdk Canonical active runtime id.
- * @property {string} model              Provider model id.
- * @property {string} reference          Original canonical model reference.
- * @property {string} [provider]         Pi provider id when sdk === "pi".
+ * @property {RuntimeSdkId} sdk           Canonical active runtime id.
+ * @property {string} model               Provider model id.
+ * @property {string} [reference]         Original canonical model reference; always set by
+ *                                         parseRuntimeModelReference, but router.js's chain
+ *                                         shorthand accepts bare {sdk, model} refs without one.
+ * @property {string} [provider]          Pi/OpenCode provider id when sdk === "pi" | "opencode".
+ */
+
+/**
+ * @typedef {{type: string, [key: string]: *}} RuntimeEvent
+ * Structured runtime/telemetry event. `type` is the only required field;
+ * every event kind (tool_approval_pending, provider_failover_started,
+ * context_compaction_applied, ...) adds its own extra fields.
+ */
+
+/**
+ * @typedef {Object} RuntimeObserver
+ * Per-call or host-level observer merged by createObserverHub (ai/observer.js).
+ * Loose on purpose: observer.js is not a kernel seam file.
+ * @property {(event: RuntimeEvent) => (void|Promise<void>)} [onEvent]
+ * @property {() => (void|Promise<void>)} [flush]
  */
 
 /**
- * @typedef {Object} RuntimeRequest
- * @property {string} systemPrompt
- * @property {Array<Object>} messages
- * @property {RuntimeModelRef} model
+ * @typedef {Object} RuntimeToolLimits
+ * Typed per-run tool-output limits (the supported replacement for the
+ * `agent_tool_*` / `agent_mcp_*` keys of the deprecated `settings` bag). Every
+ * field is optional; an omitted field falls back to the kernel default (see
+ * resolveAgentCompactionPolicy, agent/compaction.js).
+ * @property {number} [toolTextLimitChars]        Max chars of a builtin tool's text result.
+ * @property {number} [bashOutputLimitChars]      Max chars of bash stdout/stderr.
+ * @property {number} [mcpTextLimitChars]         Max chars of an MCP tool's text result.
+ * @property {number} [searchResultLimit]         Max Grep/search hits returned.
+ * @property {number} [imageInlineMaxBytes]       Max bytes of an inlined image result.
+ * @property {number} [toolPayloadMaxBytes]       Hard cap on a single tool_result payload.
+ * @property {number} [mcpCallTimeoutMs]          Per-MCP-call inactivity timeout.
+ * @property {number} [mcpCallMaxTotalTimeoutMs]  Hard wall-clock cap for one MCP call.
+ * @property {number} [bashTimeoutMs]             Documented for forward-compat; NOT wired to
+ *   any tool today (no `agent_bash_*_timeout` mechanism exists — bash reads its per-call
+ *   `timeout` argument), so setting it has no effect until a run-level default is introduced.
+ */
+
+/**
+ * @typedef {Object} RuntimeCompactionPolicy
+ * Typed per-run context-compaction policy (the supported replacement for the
+ * `agent_compaction_*` keys of the deprecated `settings` bag). Every field is
+ * optional; an omitted field falls back to the kernel default.
+ * @property {boolean} [enabled]              Whether auto-compaction runs at all.
+ * @property {number} [triggerRatio]          Fraction of the context window that arms the proactive trigger.
+ * @property {number} [keepRecentTokens]      Recent-token budget preserved across a compaction.
+ * @property {number} [summaryMaxTokens]      Max tokens of the generated summary.
+ * @property {number} [minSavingsTokens]      Minimum token savings required to keep a compaction.
+ * @property {boolean} [fixedOverheadEnabled] Whether the system-prompt + tool-schema overhead correction is folded into the trigger.
+ * @property {number} [contextWindowOverride] Forces the compaction window instead of the live-model-recognized one (applied at resolveLiveCompactionPolicy; has no legacy settings equivalent).
+ */
+
+/**
+ * @typedef {Object} RuntimePromptOverrides
+ * Optional overrides for the kernel's built-in prompt fragments. Precedence is
+ * run over host over the kernel default: an absent field leaves the built-in
+ * string in place. Supplied on both AgentRuntimeHostOptions (host default) and
+ * RuntimeRunOptions (per-run).
+ * @property {(systemPrompt: string) => string} [structuredOutputInstruction]
+ *   Replaces the StructuredOutput system-prompt instruction (receives the raw
+ *   system prompt, returns the augmented one). Only applied when an outputSchema is active.
+ * @property {() => string} [structuredOutputFinalization]
+ *   Replaces the structured-output finalization re-prompt.
+ * @property {(body: string) => string} [liveInputGuidance]
+ *   Replaces the live-input steering wrapper (receives the raw guidance body).
+ */
+
+/**
+ * @typedef {Object} RuntimeRunOptions
+ * The options object a host passes to `createRuntime(host).run(systemPrompt, options)`.
+ * @property {RuntimeModelRef} model                     Resolved model reference; see parseRuntimeModelReference.
+ * @property {string} [executionMode]                     "sdk" (default) or "cli"; selects which bridge variant handles the model.
+ * @property {boolean} [liveInput]                        Whether this run expects a live/streaming input channel.
+ * @property {ReadonlyArray<*>} [observers]               Per-call observers (see RuntimeObserver) merged with host-level (createRuntime) observers.
+ * @property {(event: RuntimeEvent) => void} [onEvent]
+ * @property {ReadonlyArray<Object>} [messages]
  * @property {string} [effort]
  * @property {boolean} [fastMode]
  * @property {string} [cwd]
  * @property {Object<string, Object>} [mcpServers]
- * @property {Array<string>} [allowedTools]
- * @property {Array<string>} [disallowedTools]
+ * @property {ReadonlyArray<string>} [allowedTools]
+ * @property {ReadonlyArray<string>} [disallowedTools]
  * @property {string} [permissionMode]
  * @property {number} [maxTurns]
  * @property {Object} [outputSchema]
  * @property {string} [runArtifactDir]
  * @property {AbortSignal} [abortSignal]
- * @property {Object} [liveInput]
- * @property {Object} [settings]
+ * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy] Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
+ * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine] Per-run concrete sandbox engine handed to the active sandbox implementation.
+ * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox] Per-run sandbox IMPLEMENTATION override; when set it enforces this run's tools instead of the host/ToolContext impl (precedence run > host > passthrough). Policy DATA still merges monotonically (I13); this overrides only the enforcing code.
+ * @property {RuntimeToolLimits} [toolLimits] Typed per-run tool-output limits (supported replacement for the deprecated `settings` tool keys).
+ * @property {RuntimeCompactionPolicy} [compaction] Typed per-run compaction policy (supported replacement for the deprecated `settings` compaction keys).
+ * @property {RuntimePromptOverrides} [prompts] Per-run prompt-fragment overrides (run wins over the host default).
+ * @property {Object} [settings] DEPRECATED. Legacy flat settings bag; consumed only as a per-group FALLBACK when the corresponding typed object (`toolLimits` / `compaction`) is absent. Consuming any key emits one `deprecated_settings_option` runtime_warning per run. Migrate via resolveRuntimePolicies (@mono-agent/runtime-adapter).
  * @property {Object} [nativeSubagents] Same-runtime teammate helpers exposed through native provider subagent surfaces.
- * @property {(event: RuntimeEvent) => void} [onEvent]
+ * @property {Object} [diagnosticsSeed] Set by createRouterRuntime (ai/runtime/router.js) with a `resume_snapshot` when
+ *   failing over mid-chain; a host-level coordinator may relay it forward (see agent/transcript.js), not read by any
+ *   bridge in this package today.
+ * @property {string} [systemPromptPrefix] Set by createRouterRuntime alongside diagnosticsSeed; the router also
+ *   prepends the same text to the systemPrompt argument directly, so bridges that ignore this field still continue
+ *   correctly.
  */
 
 /**
- * @typedef {Object} RuntimeEvent
- * @property {string} type
+ * @typedef {RuntimeRunOptions
+ *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools">
+ *   & {runtimeBrand: import('../runtime-brand.js').RuntimeBrand, toolContext?: import('../agent/tools/shared/tool-context.js').ToolContext, observerHub: {emit: (event: RuntimeEvent) => void, flush: () => Promise<void>}}
+ * } RuntimeRequest
+ * The request shape a bridge's `execute(systemPrompt, req)` receives as its
+ * second (options) argument: the host-supplied RuntimeRunOptions, merged by
+ * createRuntime (runtime.js) with the bound HOST_KEYS host-integration
+ * callbacks, the resolved runtimeBrand, the per-instance toolContext (read by
+ * internal tool helpers; absent when a host drives a bridge directly without
+ * createRuntime), and the per-run observerHub (onEvent is overridden to the
+ * hub's emit). `systemPrompt` is passed positionally, not folded into this object.
  */
 
 /**
@@ -48,22 +163,140 @@
  * @property {number} [numTurns]
  * @property {string} [model]
  * @property {string} [effort]
- * @property {"claude" | "pi" | "codex"} [sdk]
+ * @property {RuntimeSdkId} [sdk]
  * @property {boolean} [cancelled]
  * @property {string|null} [error]
  * @property {Object|null} [errorDetails]
  * @property {string|null} [failureKind]
  * @property {string|null} [providerSessionId]
+ * @property {string|null} [stderrTail] Bounded stderr tail from a CLI-backed bridge; see createStderrTail (ai/failure.js).
  * @property {Array<Object>} [runtimeWarnings]
  * @property {Object} [diagnostics]
+ * @property {Object} [capabilitiesUsed]
+ * @property {Array<{model: RuntimeModelRef, failureKind: (string|null), requestId?: (string|null), retryableSubkind?: (string|null), requirements?: Object}>} [failoverHistory] Set by createRouterRuntime (ai/runtime/router.js) on every attempt after the first.
+ */
+
+/**
+ * @typedef {Object} RuntimeCapabilities
+ * Capability flags a bridge reports for a given model reference. Structural,
+ * not sealed: bridges may report extra provider-specific flags (e.g.
+ * supports_fast_mode) alongside the common ones from COMMON_CAPABILITIES
+ * (ai/runtime/capabilities.js).
+ * @property {string} [kind]
+ * @property {string} [runtime]
+ * @property {boolean} [streaming]
+ * @property {boolean} [structured_output]
+ * @property {boolean} [supports_session_resume]
+ * @property {*} [native_runtime_config]
+ * @property {boolean} [supports_mcp]
+ * @property {boolean} [supports_skills]
+ * @property {boolean} [supports_builtin_tools]
+ * @property {boolean} [supports_live_input]
+ * @property {boolean} [supports_native_subagents]
+ * @property {boolean} [supports_fast_mode]
  */
 
 /**
  * @typedef {Object} RuntimeBridge
- * @property {"claude" | "pi" | "codex"} id
- * @property {(ref: RuntimeModelRef) => boolean} supports
- * @property {(ref?: RuntimeModelRef) => Object} capabilities
+ * A fully loaded bridge (registry.js's resolveRuntimeBridge result): the
+ * executable provider implementation. Unlike RuntimeBridgeDescriptor,
+ * `capabilities` here is the bridge module's own static value (computed once
+ * at module load, e.g. `runtimeCapabilities("pi")`), not a callable.
+ * @property {RuntimeBridgeId} id
+ * @property {(ref: RuntimeModelRef, options?: Object) => boolean} supports
+ * @property {RuntimeCapabilities} capabilities
  * @property {(systemPrompt: string, req: RuntimeRequest) => Promise<RuntimeResult>} execute
  */
 
+/**
+ * @typedef {Object} RuntimeBridgeDescriptor
+ * The introspection-only projection of a RuntimeBridge (registry.js's
+ * listRuntimeBridges result): id/supports/capabilities without execute, so
+ * hosts can describe backend support without loading provider modules.
+ * @property {RuntimeBridgeId} id
+ * @property {(ref: RuntimeModelRef, options?: Object) => boolean} supports
+ * @property {(ref?: RuntimeModelRef) => RuntimeCapabilities} capabilities
+ */
+
+/**
+ * @typedef {Object} ApprovalRequestPayload
+ * Payload passed to a host's `onToolApprovalRequest` callback (agent/approval.js).
+ * @property {string} requestId
+ * @property {string} toolName
+ * @property {string|null} toolUseId
+ * @property {string} argumentsSummary Secret-redacted, length-capped JSON summary of the tool call arguments.
+ * @property {"low"|"medium"|"high"} riskTier
+ * @property {string|null} model
+ */
+
+/**
+ * @typedef {Object} ApprovalDecision
+ * A host's response to an ApprovalRequestPayload.
+ * @property {"approve"|"deny"|"always"} decision
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {Object} CompactionRecordedPayload
+ * Payload passed to a host's `onCompactionRecorded` callback (ai/providers/pi-native.js)
+ * after a successful context compaction, so the host can persist the row.
+ * @property {string|null} task_run_id
+ * @property {string} trigger
+ * @property {string} provider_kind
+ * @property {string|null} model
+ * @property {number|null} tokens_before
+ * @property {string} summary
+ * @property {string|null} first_kept_entry_id
+ * @property {"succeeded"} status
+ * @property {number} created_at
+ */
+
+/**
+ * @typedef {Object} AgentRuntimeHostOptions
+ * The `host` object passed to `createRuntime(host)` / `createRouterRuntime({host, chain})`.
+ * Combines the tool-runtime keys (forwarded to configureToolRuntime) and the
+ * host-integration callbacks (bound once, applied to every run via hostDefaults).
+ * @property {string} [workspace]
+ * @property {string} [repoRoot]
+ * @property {string} [ripgrepPath]
+ * @property {string} [qaOutputDir]
+ * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy]
+ * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine]
+ * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox] Sandbox seam implementation (see agent/sandbox-seam.js); defaults to the zero-dependency passthroughSandbox. Real hosts inject runtime-adapter's implementation from packages/runtime-adapter/src/sandbox.ts.
+ * @property {RuntimePromptOverrides} [prompts] Host-level prompt-fragment override defaults; a per-run `options.prompts` field wins over these (see resolvePrompts, runtime.js).
+ * @property {ReadonlyArray<*>} [observers] Observer instances (see RuntimeObserver); loose because observer.js is not a kernel seam file.
+ * @property {*} [runtimeBrand] See resolveRuntimeBrand (runtime-brand.js); accepts a partial RuntimeBrand.
+ * @property {(parsed: {sdk: (string|null), provider?: string, model: string}) => (import('./cost.js').NormalizedPricing|null)} [resolveCustomPricing] See resolvePricing (ai/cost.js).
+ * @property {import('../pi-auth.js').PiApiKeyResolver} [resolvePiApiKey] See createPiOAuthApiKeyResolver (pi-auth.js) for a ready-made implementation.
+ * @property {(artifact: {filename: string, buffer: Buffer, toolName: string, toolUseId: (string|null)}) => (string|null)} [persistArtifact]
+ * @property {(record: CompactionRecordedPayload) => void} [onCompactionRecorded]
+ * @property {(payload: ApprovalRequestPayload) => Promise<ApprovalDecision>} [onToolApprovalRequest]
+ * @property {Object<string, ("low"|"medium"|"high")>} [toolRiskTiers]
+ * @property {"low"|"medium"|"high"} [approvalDefaultRiskTier]
+ * @property {number} [approvalTimeoutMs]
+ * @property {ReadonlyArray<string>} [approvalAlwaysAllowTools]
+ */
+
+/**
+ * @typedef {Object} AgentRuntimeToolOptions
+ * The subset of AgentRuntimeHostOptions accepted by `runtime.configureTools(next)`
+ * (createRuntime's TOOL_RUNTIME_KEYS pick).
+ * @property {string} [workspace]
+ * @property {string} [repoRoot]
+ * @property {string} [ripgrepPath]
+ * @property {string} [qaOutputDir]
+ * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy]
+ * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine]
+ * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox]
+ */
+
+/**
+ * @typedef {Object} AgentRuntimeInstance
+ * The object `createRuntime`/`createRouterRuntime` return.
+ * @property {(systemPrompt: string, options: RuntimeRunOptions) => Promise<RuntimeResult>} run
+ * @property {(next?: AgentRuntimeToolOptions) => void} configureTools
+ * @property {(providerSessionId: string) => Promise<boolean|void>} disposeSession
+ * @property {() => Promise<void>} disposeAllSessions
+ */
+
 export const PROVIDER_KIND_VALUES = ["claude", "pi", "codex"];

package/src/index.js

@@ -1,4 +1,4 @@
-// Public entry for @mono-agent/agent-runtime.
+// Public entry for the agent-runtime package.
 //
 // Most consumers should reach for `createRuntime` (see runtime.js) — it
 // binds the host integration callbacks once and returns a `.run()` method.

package/src/pi-auth.js

@@ -1,48 +1,174 @@
+// @ts-check
+
+import { realpathSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 
 import { getOAuthApiKey } from "@earendil-works/pi-ai/oauth";
 
+/**
+ * @typedef {{type: "api_key", key?: string, env?: Object<string, *>}} PiApiKeyCredential
+ * @typedef {{type: "oauth", access?: string, refresh?: string, expires: number, [key: string]: *}} PiOAuthCredential
+ * @typedef {PiApiKeyCredential|PiOAuthCredential} PiCredential
+ * @typedef {((provider: string) => Promise<string|undefined>) & {
+ *   readCredential?: (provider: string) => Promise<PiCredential|undefined>,
+ *   modifyCredential?: (provider: string, fn: (current: PiCredential|undefined) => Promise<PiCredential|undefined>) => Promise<PiCredential|undefined>,
+ *   deleteCredential?: (provider: string) => Promise<void>
+ * }} PiApiKeyResolver
+ */
+
+const authFileChains = new Map();
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.path] Path to the pi auth.json credentials file.
+ * @returns {PiApiKeyResolver}
+ */
 export function createPiOAuthApiKeyResolver(options = {}) {
-  const authPath = typeof options.path === "string" && options.path.trim().length > 0
+  const configuredAuthPath = typeof options.path === "string" && options.path.trim().length > 0
     ? options.path
     : undefined;
+  const authPath = configuredAuthPath ? canonicalizeAuthPath(configuredAuthPath) : undefined;
 
-  return async function resolvePiOAuthApiKey(provider) {
+  async function resolvePiOAuthApiKey(provider) {
     if (!authPath || typeof provider !== "string" || provider.trim().length === 0) {
       return undefined;
     }
 
-    const auth = await readAuthFile(authPath);
-    if (auth === undefined || auth[provider] === undefined) {
+    return enqueueAuthFile(authPath, async () => {
+      const auth = await readAuthFile(authPath);
+      if (auth === undefined || auth[provider] === undefined) {
+        return undefined;
+      }
+
+      const result = await getOAuthApiKey(provider, cloneAuth(auth));
+      if (result === null || result === undefined || typeof result.apiKey !== "string" || result.apiKey.length === 0) {
+        return undefined;
+      }
+
+      auth[provider] = {
+        type: "oauth",
+        ...result.newCredentials,
+      };
+      await writeAuthFile(authPath, auth);
+      return result.apiKey;
+    });
+  }
+
+  resolvePiOAuthApiKey.readCredential = async function readCredential(provider) {
+    if (!authPath || typeof provider !== "string" || provider.trim().length === 0) {
       return undefined;
     }
+    const auth = await readAuthFile(authPath);
+    return cloneCredential(auth?.[provider]);
+  };
 
-    const result = await getOAuthApiKey(provider, cloneAuth(auth));
-    if (result === null || result === undefined || typeof result.apiKey !== "string" || result.apiKey.length === 0) {
+  resolvePiOAuthApiKey.modifyCredential = async function modifyCredential(provider, fn) {
+    if (!authPath || typeof provider !== "string" || provider.trim().length === 0) {
       return undefined;
     }
+    if (typeof fn !== "function") {
+      throw new TypeError("modifyCredential requires a function");
+    }
+    return enqueueAuthFile(authPath, async () => {
+      const auth = (await readAuthFile(authPath)) || {};
+      const current = cloneCredential(auth[provider]);
+      const next = await fn(current);
+      if (next !== undefined) {
+        auth[provider] = cloneCredential(next) || next;
+        await writeAuthFile(authPath, auth);
+        return cloneCredential(auth[provider]);
+      }
+      return current;
+    });
+  };
 
-    auth[provider] = {
-      type: "oauth",
-      ...result.newCredentials,
-    };
-    await writeAuthFile(authPath, auth);
-    return result.apiKey;
+  resolvePiOAuthApiKey.deleteCredential = async function deleteCredential(provider) {
+    if (!authPath || typeof provider !== "string" || provider.trim().length === 0) {
+      return;
+    }
+    await enqueueAuthFile(authPath, async () => {
+      const auth = await readAuthFile(authPath);
+      if (!auth || !Object.hasOwn(auth, provider)) return;
+      delete auth[provider];
+      await writeAuthFile(authPath, auth);
+    });
   };
+
+  return resolvePiOAuthApiKey;
+}
+
+/**
+ * @param {string} path
+ * @param {() => Promise<*>} task
+ * @returns {Promise<*>}
+ */
+function enqueueAuthFile(path, task) {
+  const previous = authFileChains.get(path) ?? Promise.resolve();
+  const next = (async () => {
+    await previous.catch(() => {});
+    return task();
+  })();
+  authFileChains.set(path, next.catch(() => {}));
+  return next;
+}
+
+/**
+ * @param {string} path
+ * @returns {string}
+ */
+function canonicalizeAuthPath(path) {
+  const resolved = resolve(path);
+  try {
+    return realpathSync.native(resolved);
+  } catch (error) {
+    if (!isMissingPathError(error)) {
+      return resolved;
+    }
+  }
+
+  try {
+    return join(realpathSync.native(dirname(resolved)), basename(resolved));
+  } catch {
+    return resolved;
+  }
 }
 
+/**
+ * @param {*} error
+ * @returns {boolean}
+ */
+function isMissingPathError(error) {
+  return error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
+
+/**
+ * @param {Object<string, *>} auth
+ * @returns {Object<string, *>}
+ */
 function cloneAuth(auth) {
   return Object.fromEntries(
     Object.entries(auth).map(([provider, credentials]) => [
       provider,
-      credentials && typeof credentials === "object" && !Array.isArray(credentials)
-        ? { ...credentials }
-        : credentials,
+      cloneCredential(credentials),
     ]),
   );
 }
 
+/**
+ * @param {*} credential
+ * @returns {*}
+ */
+function cloneCredential(credential) {
+  return credential && typeof credential === "object" && !Array.isArray(credential)
+    ? { ...credential }
+    : credential;
+}
+
+/**
+ * @param {string} path
+ * @returns {Promise<Object<string, *>|undefined>}
+ */
 async function readAuthFile(path) {
   let raw;
   try {
@@ -69,6 +195,11 @@ async function readAuthFile(path) {
 // writers in the same millisecond never collide on the temp path.
 let atomicWriteSequence = 0;
 
+/**
+ * @param {string} path
+ * @param {Object<string, *>} auth
+ * @returns {Promise<void>}
+ */
 async function writeAuthFile(path, auth) {
   const dir = dirname(path);
   await mkdir(dir, { recursive: true, mode: 0o700 });

package/src/runtime-brand.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 // Host-customisable identity strings used by the runtime when it has to
 // stamp a name onto something that leaves the process: MCP client name,
 // transcript-snapshot schema id, temp-directory prefix, the doctor command
@@ -7,6 +9,20 @@
 // to `createRuntime` to make the package look like theirs without forking
 // string-by-string.
 
+/**
+ * @typedef {Object} RuntimeBrand
+ * @property {string} schemaPrefix
+ * @property {string} mcpClientName
+ * @property {string} mcpClientVersion
+ * @property {string} tempdirPrefix
+ * @property {string} providerModelPrefix
+ * @property {string} doctorCommand
+ * @property {string} serviceName
+ * @property {string} clientInfoName
+ * @property {string} clientInfoTitle
+ */
+
+/** @type {RuntimeBrand} */
 export const DEFAULT_RUNTIME_BRAND = Object.freeze({
   schemaPrefix: "agent_runtime",
   mcpClientName: "agent-runtime",
@@ -21,10 +37,14 @@ export const DEFAULT_RUNTIME_BRAND = Object.freeze({
   clientInfoTitle: "Agent Runtime",
 });
 
+/**
+ * @param {Partial<RuntimeBrand>} [input]
+ * @returns {RuntimeBrand}
+ */
 export function resolveRuntimeBrand(input) {
   if (!input || typeof input !== "object") return { ...DEFAULT_RUNTIME_BRAND };
   const out = { ...DEFAULT_RUNTIME_BRAND };
-  for (const key of Object.keys(DEFAULT_RUNTIME_BRAND)) {
+  for (const key of /** @type {Array<keyof RuntimeBrand>} */ (Object.keys(DEFAULT_RUNTIME_BRAND))) {
     const value = input[key];
     if (typeof value === "string" && value.trim()) out[key] = value.trim();
   }