@banbolee/dsh-fish-shell 0.5.0 → 0.6.0

package/policy.js

@@ -63,18 +63,43 @@ export const inject = ['tools', 'systemPrompt']
 
 const PLUGIN_TAG = '@banbolee/dsh-fish-shell'
 
+/**
+ * One agent as this policy reads it: the harness `Agent` viewed through the two
+ * members every registration below keys on — its session id (for warnings) and
+ * its agent-scoped context (where the restriction/prompt/tool registrations
+ * land). The full runtime `Agent` face is structurally assignable to this view.
+ * @typedef {{ id?: string, ctx: import('@deepseek-ai/cordis').Context }} PolicyAgent
+ */
+
+/**
+ * One agent's installed policy: which bash form was detected, the preset parent
+ * key it was installed under (the switch/re-entry fast path compares it), and
+ * the disposers that must move with `/preset`.
+ * @typedef {object} PolicyState
+ * @property {'persistent' | 'one-shot'} kind - the bash form this policy swapped out.
+ * @property {import('@deepseek-ai/dsh-scope').ScopeKey | undefined} parentKey - the preset parent scope key this state was installed under (`scopeParentOf(agent)`).
+ * @property {(() => Promise<void> | undefined) | undefined} persistentFish - the persistent fish tool's disposer, when this state installed one.
+ * @property {() => void} restriction - the `deny: ['bash']` restriction disposer.
+ * @property {() => void} prompt - the `tool:bash` prompt-shadow disposer.
+ */
+
 /** Agents currently being reconciled (guards the synchronous tools/change
- * re-entry that restriction/prompt registration and disposal trigger). */
+ * re-entry that restriction/prompt registration and disposal trigger).
+ * @type {WeakSet<PolicyAgent>} */
 const installing = new WeakSet()
-/** Agents already warned about an invisible fish tool (warn once per agent). */
+/** Agents already warned about an invisible fish tool (warn once per agent).
+ * @type {WeakSet<PolicyAgent>} */
 const warned = new WeakSet()
 /** Agents uninstalled via `agent/disposed`: a tools/change fired by the
- * uninstall's own disposals must not re-install a dying agent. */
+ * uninstall's own disposals must not re-install a dying agent.
+ * @type {WeakSet<PolicyAgent>} */
 const removed = new WeakSet()
-/** Per-agent policy state, including disposers that must move with /preset. */
+/** Per-agent policy state, including disposers that must move with /preset.
+ * @type {WeakMap<PolicyAgent, PolicyState>} */
 const states = new WeakMap()
 /** Live agents with policy installed; traversable so plugin teardown can
- * strip every registration (a WeakMap would be unreachable on teardown). */
+ * strip every registration (a WeakMap would be unreachable on teardown).
+ * @type {Set<PolicyAgent>} */
 const liveAgents = new Set()
 /** Global reconcile re-entrancy guard: a tools/change arriving while a
  * reconcile round is in flight marks `reconcilePending` instead of starting a
@@ -83,17 +108,32 @@ const liveAgents = new Set()
 let reconciling = false
 let reconcilePending = false
 
+/**
+ * Narrow one unchecked value to a non-null, non-array object: the shape this
+ * policy reads duck-typed tool definitions and disposer results through.
+ * @param {unknown} value - the value to inspect.
+ * @returns {value is Record<string, unknown>} whether it is a plain object record.
+ */
 function isPlainObject(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+/**
+ * Dispose one registration quietly: `undefined` means nothing was installed,
+ * a synchronous throw and a rejected async disposer are both warned instead of
+ * breaking the policy round that runs the disposal.
+ * @param {(() => unknown) | undefined} disposer - the registration's disposer, when there is one.
+ * @param {string} label - the registration's name in the warning.
+ * @param {PolicyAgent} agent - the agent the registration belongs to.
+ */
 function disposeQuietly(disposer, label, agent) {
   if (disposer === undefined) return
   try {
     const result = disposer()
     // Async disposers (persistent fish cleanup) are awaited out-of-band so a
-    // failing teardown is recorded instead of unhandled.
-    if (result !== undefined && typeof result.then === 'function') {
+    // failing teardown is recorded instead of unhandled; a plain `void`
+    // disposer returns a non-thenable and needs no wait.
+    if (isPlainObject(result) && typeof result.then === 'function') {
       void Promise.resolve(result).catch((error) => {
         console.warn(`${PLUGIN_TAG}: could not dispose ${label} for agent ${agent.id ?? '(unnamed)'}:`, String(error))
       })
@@ -103,12 +143,23 @@ function disposeQuietly(disposer, label, agent) {
   }
 }
 
+/**
+ * Drop every registration one policy state owns.
+ * @param {PolicyAgent} agent - the agent the state belongs to.
+ * @param {PolicyState} state - the installed state to tear down.
+ */
 function disposeState(agent, state) {
   disposeQuietly(state.prompt, 'tool:bash prompt shadow', agent)
   disposeQuietly(state.restriction, 'bash restriction', agent)
   disposeQuietly(state.persistentFish, 'persistent fish tool', agent)
 }
 
+/**
+ * Drop the registrations a preset switch must lift before it probes the target
+ * preset's surface (the prompt shadow and the bash restriction only).
+ * @param {PolicyAgent} agent - the agent whose transient policy is removed.
+ * @param {PolicyState | undefined} state - the previous state, when there is one.
+ */
 function removeTransientPolicy(agent, state) {
   disposeQuietly(state?.prompt, 'tool:bash prompt shadow', agent)
   disposeQuietly(state?.restriction, 'bash restriction', agent)
@@ -120,8 +171,8 @@ function removeTransientPolicy(agent, state) {
  * output schema is a plain string. The one-shot bash tool (command +
  * description + workdir + timeoutMs + run_in_background +
  * sandbox_permissions…) and every other tool shape fall through.
- * @param definition - the tool definition an agent resolves for `bash`.
- * @returns true when the agent's bash is the persistent PTY form.
+ * @param {import('@deepseek-ai/dsh-tools').ToolDefinition} definition - the tool definition an agent resolves for `bash`.
+ * @returns {boolean} true when the agent's bash is the persistent PTY form.
  */
 export function isPersistentBashForm(definition) {
   if (!isPlainObject(definition)) return false
@@ -139,7 +190,10 @@ export function isPersistentBashForm(definition) {
   return isPlainObject(properties) && Object.keys(properties).length === 1 && Object.hasOwn(properties, 'command')
 }
 
-/** Remove every policy-owned registration for an agent. */
+/**
+ * Remove every policy-owned registration for an agent.
+ * @param {PolicyAgent} agent - the agent whose policy is uninstalled.
+ */
 export function uninstallFishPolicy(agent) {
   liveAgents.delete(agent)
   removed.add(agent)
@@ -160,7 +214,7 @@ export function uninstallFishPolicy(agent) {
  * disposers THIS call created.
  *
  * @param {import('@deepseek-ai/cordis').Context} ctx - the policy plugin's context.
- * @param {object} agent - the live agent (its `ctx` is the agent's scoped context).
+ * @param {PolicyAgent} agent - the live agent (its `ctx` is the agent's scoped context).
  */
 export function installFishPolicy(ctx, agent) {
   if (installing.has(agent)) return
@@ -222,6 +276,7 @@ export function installFishPolicy(ctx, agent) {
       // bash is hidden, so minimal sessions keep persistent semantics.
       persistentFish = registerPersistentFish(ctx, agent.ctx)
     }
+    /** @type {Array<() => void>} */
     const created = []
     try {
       const restriction = agent.ctx.tools.restrict({ deny: ['bash'] })
@@ -244,7 +299,7 @@ export function installFishPolicy(ctx, agent) {
       // persistent fish. The previous state's entries were already removed
       // above, so `states` ends up consistent: no restriction, no shadow, no
       // persistent fish — bash stays visible and the failure is surfaced.
-      for (let index = created.length - 1; index >= 0; index -= 1) created[index]()
+      for (let index = created.length - 1; index >= 0; index -= 1) created[index]?.()
       disposeQuietly(persistentFish, 'persistent fish tool', agent)
       throw error
     }
@@ -256,11 +311,15 @@ export function installFishPolicy(ctx, agent) {
   }
 }
 
-/** Apply the policy to every live agent (no-op when the agents service is
+/**
+ * Apply the policy to every live agent (no-op when the agents service is
  * absent). Re-entrant calls (a registration/disposal mid-round fires
  * `tools/change` synchronously) are absorbed into at most ONE coalesced
  * catch-up round, so an external change dispatches a small constant number
- * of times regardless of how many agents are live. */
+ * of times regardless of how many agents are live.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the policy plugin's context (the `agents` service is resolved from it).
+ * @param {boolean} [catchUp] - whether this round is the coalesced catch-up (never re-triggers one).
+ */
 function reconcile(ctx, catchUp = false) {
   if (reconciling) {
     reconcilePending = true

package/terminal-fish.js

@@ -76,6 +76,56 @@ const DEFAULT_PTY_CONFIG = {
   disposeGraceMs: 3e3,
 }
 
+/**
+ * The terminal handle surface this backend reads: the cleanup verb a failed
+ * session factory must call (the real handle is `SubprocessTerminalHandle`).
+ * @typedef {{ terminate(): void | Promise<void> }} TerminalHandleLike
+ */
+
+/**
+ * The fully resolved backend configuration: the public `Config` surface with
+ * every default materialized, matching `@deepseek-ai/dsh-terminal-bash`'s
+ * `ResolvedConfig` (which that package does not export from its root).
+ * @typedef {object} ResolvedBackendConfig
+ * @property {string} backendType - backend registry type (`fish` by default).
+ * @property {'bash'} shellDialect - the readiness/prompt contract the fish prompt implements.
+ * @property {string} shellPath - the fish executable to spawn.
+ * @property {string[]} shellArgs - the resolved fish arguments.
+ * @property {number} rows - initial terminal rows.
+ * @property {number} cols - initial terminal columns.
+ * @property {number} scrollbackLines - retained logical lines.
+ * @property {number} scrollbackMaxBytes - retained UTF-8 bytes.
+ * @property {number} maxReadBytes - one read's byte cap.
+ * @property {number} pollIntervalMs - readiness polling interval.
+ * @property {number} exactProbeAfterMs - delay before exact syscall probes.
+ * @property {number} idleSilenceMs - silence that yields `inferred_idle`.
+ * @property {number} handoffGraceMs - extra wait for foreground handoff.
+ * @property {number} timeoutMs - readiness deadline for one startup sequence.
+ * @property {number} disposeGraceMs - SIGTERM→SIGKILL grace for the PTY session.
+ */
+
+/**
+ * The backend session surface this module drives: `TerminalBackendSession`
+ * with the backend's own mutable `motd`. The interface declares that field
+ * read-only, while the concrete `LocalPtySession` (and the test doubles) assign
+ * the startup banner once readiness settles.
+ * @typedef {Omit<import('@deepseek-ai/dsh-terminal').TerminalBackendSession, 'motd'> & { motd: string }} PersistentPtySession
+ */
+
+/**
+ * The `BashTerminalBackend` internals this subclass must reach to override
+ * `spawn()`. The upstream declarations mark `ctx`, `config`, `spawnTerminal`,
+ * and `createSession` private — and are byte-identical in 0.1.5-rc.1 and
+ * 0.1.7-rc.2 — while the JS prototype keeps them as ordinary fields, so the
+ * subclass reads them through this one structural view instead of a
+ * suppression per access.
+ * @typedef {object} BashBackendInternals
+ * @property {import('@deepseek-ai/cordis').Context} ctx - the backend's plugin context.
+ * @property {ResolvedBackendConfig} config - the resolved backend configuration the base class stores.
+ * @property {(spec: object) => Promise<TerminalHandleLike>} spawnTerminal - the subprocess terminal primitive (`ctx.subprocess.spawnTerminal` by default).
+ * @property {(terminal: unknown, config: unknown) => any} createSession - the session factory (`new LocalPtySession(...)` by default).
+ */
+
 /**
  * One-line fish prompt setup submitted before readiness: suppresses the
  * greeting and right prompt, and defines a prompt that emits the shared OSC
@@ -89,24 +139,32 @@ export const FISH_PROMPT_SETUP = 'function fish_greeting; end; function fish_pro
  * Resolve the effective fish shell specification: an unset or empty
  * `shellPath`/`shellArgs` selects the defaults, a non-empty explicit value
  * wins. Mirrors the official `resolveConfig` (minus dialect selection).
- * @param config - the plugin configuration.
- * @returns the fully resolved configuration.
+ * @param {import('@deepseek-ai/dsh-terminal-bash').TerminalLocalConfig} config - the plugin configuration.
+ * @returns {ResolvedBackendConfig} the fully resolved configuration.
  */
 export function resolveConfig(config) {
   return {
-    backendType: config.backendType?.length > 0 ? config.backendType : 'fish',
+    // `config.backendType?.length > 0` compared an optional property with `>`
+    // (a coercion, not a narrowing); the explicit guard is the same decision
+    // and lets the compiler see a `string` in the true branch.
+    backendType: config.backendType !== undefined && config.backendType.length > 0 ? config.backendType : 'fish',
+    // Inherited `ResolvedConfig` shape, not a dialect choice: this backend
+    // overrides `spawn()` with its own child environment and fish prompt, so
+    // the field is inert — `bash` names the readiness/prompt contract the
+    // fish prompt implements (`dsh-terminal-bash`'s bash branch).
+    shellDialect: /** @type {const} */ ('bash'),
     shellPath: config.shellPath !== undefined && config.shellPath.length > 0 ? config.shellPath : DEFAULT_FISH_SHELL,
     shellArgs: config.shellArgs !== undefined && config.shellArgs.length > 0 ? config.shellArgs : DEFAULT_FISH_ARGS,
     ...DEFAULT_PTY_CONFIG,
-    ...Object.fromEntries(Object.entries(config).filter(([key]) => key in DEFAULT_PTY_CONFIG && config[key] !== undefined)),
+    ...Object.fromEntries(Object.entries(config).filter(([key, value]) => key in DEFAULT_PTY_CONFIG && value !== undefined)),
   }
 }
 
 /**
  * Validate the effective configuration (mirrors the official
  * `validateConfig`).
- * @param config - the fully resolved configuration.
- * @returns the narrowed configuration.
+ * @param {ResolvedBackendConfig} config - the fully resolved configuration.
+ * @returns {void} throws on a value the backend cannot run with.
  */
 export function validateConfig(config) {
   const resolved = config
@@ -125,8 +183,8 @@ export function validateConfig(config) {
  * Fish child environment: the official bash `childEnvironment` common set
  * (TERM=dumb so the reader emits no cursor/redraw sequences, PAGER=cat,
  * harness identity facts) minus the bash-only PS1/PROMPT_COMMAND.
- * @param spec - the spawn specification.
- * @returns the child environment.
+ * @param {import('@deepseek-ai/dsh-terminal').TerminalBackendSpawnSpec} spec - the spawn specification.
+ * @returns {Record<string, string>} the child environment.
  */
 export function childEnvironment(spec) {
   return {
@@ -157,7 +215,17 @@ export function childEnvironment(spec) {
 // ever contributed the fence falls back to the terminals registry probe
 // (`ctx.terminals` may be absent — missing services resolve to `undefined`
 // on a Cordis context, never a throw).
+/** Per-owner fence state: the context whose dispatch is watched plus every
+ * manager's aggregated activity probe. @type {WeakMap<import('@deepseek-ai/dsh-agent').Agent, { ctx: import('@deepseek-ai/cordis').Context, checkers: Set<() => boolean> }>} */
 const sandboxModeFences = new WeakMap()
+
+/**
+ * Install (or refresh) the per-owner sandbox-mode fence and register this
+ * manager's owner-activity probe with it.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the context whose `internal/dispatch` the fence listens to.
+ * @param {import('@deepseek-ai/dsh-agent').Agent} owner - the live owner whose activity keeps the fence closed.
+ * @param {() => boolean} [hasActivity] - this manager's owner-activity probe, when it has one.
+ */
 export function ensureSandboxModeFence(ctx, owner, hasActivity) {
   let state = sandboxModeFences.get(owner)
   if (state === undefined) {
@@ -185,21 +253,25 @@ export function ensureSandboxModeFence(ctx, owner, hasActivity) {
 /**
  * Confine the fish argv through the shared sandbox policy, exactly like the
  * official `spawnArgv` (which is private to `@deepseek-ai/dsh-terminal-bash`
- * and therefore copied here).
- * @param ctx - the plugin context carrying the sandbox provider.
- * @param config - the resolved backend configuration.
- * @param policy - the resolved execution policy for this session.
- * @returns the (possibly confined) argv.
+ * and therefore copied here). `SandboxProvider.confine` is ASYNC in
+ * 0.1.7-rc.2, so the confined branch MUST be awaited: reading `.argv` off the
+ * returned promise yields `undefined`, which made every confined persistent
+ * spawn fail (previously masked by a synchronous test double).
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the plugin context carrying the sandbox provider.
+ * @param {ResolvedBackendConfig} config - the resolved backend configuration the base class stores.
+ * @param {import('@deepseek-ai/dsh-sandbox').SandboxExecutionPolicy} policy - the resolved execution policy for this session; the `danger-full-access` early return narrows `mode` to a confined mode for `confine()`.
+ * @param {AbortSignal} [signal] - cancellation of confinement preparation.
+ * @returns {Promise<string[]>} the (possibly confined) argv.
  */
-export function spawnArgv(ctx, config, policy) {
+export async function spawnArgv(ctx, config, policy, signal) {
   const argv = [config.shellPath, ...config.shellArgs]
   if (policy.mode === 'danger-full-access') return argv
   const sandbox = ctx.get('sandbox')
   if (sandbox === undefined) throw new Error(`terminal-fish: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`)
-  return sandbox.confine(argv, {
+  return (await sandbox.confine(argv, {
     ...policy,
     mode: policy.mode,
-  }).argv
+  }, signal)).argv
 }
 
 /**
@@ -207,11 +279,12 @@ export function spawnArgv(ctx, config, policy) {
  * poll with empty sends until the fish prompt satisfies the shared
  * readiness contract (OSC `133;D;` + `dsh> ` tail). Mirrors the official
  * `startupSession` pwsh branch, with a startup deadline race.
- * @param session - the backend session.
- * @param timeoutMs - readiness deadline.
- * @param signal - optional cancellation.
+ * @param {PersistentPtySession} session - the backend session to bring up.
+ * @param {number} timeoutMs - readiness deadline.
+ * @param {AbortSignal} [signal] - optional cancellation.
  */
 export async function startupSession(session, timeoutMs, signal) {
+  /** @type {import('@deepseek-ai/dsh-terminal').TerminalSendOperation | undefined} */
   let startupOperation
   const start = async () => {
     let viewport = ''
@@ -255,6 +328,25 @@ export async function startupSession(session, timeoutMs, signal) {
   }
 }
 
+/**
+ * Reject a failed startup only after its unpublished resources reach
+ * quiescence (copied from the official `@deepseek-ai/dsh-terminal-bash`,
+ * which does not export it): a cleanup failure is reported as
+ * `TerminalBackendCleanupError` so a leaked PTY is distinguishable from the
+ * startup failure that caused it.
+ * @param {unknown} error - the startup or session-factory failure.
+ * @param {() => unknown} cleanup - releases the resource the failure left behind.
+ * @returns {Promise<never>} never resolves; always rejects.
+ */
+async function rejectAfterStartupCleanup(error, cleanup) {
+  try {
+    await cleanup()
+  } catch (cleanupError) {
+    throw new TerminalBackendCleanupError(error, cleanupError)
+  }
+  throw error
+}
+
 /**
  * Local fish PTY backend registered under the configured type (`fish`):
  * spawns `fish --no-config -i` (config-overridable) with the fish child
@@ -264,37 +356,55 @@ export async function startupSession(session, timeoutMs, signal) {
  * `BashTerminalBackend`/`LocalPtySession`.
  */
 export class FishTerminalBackend extends BashTerminalBackend {
+  /**
+   * Spawn and bring up one fish PTY session for a spec the registry (or the
+   * self-managed persistent tool) resolved. Resolves with the ready session
+   * the configured session factory built (the base class declares the concrete
+   * `LocalPtySession` return, which this package cannot name).
+   * @param {import('@deepseek-ai/dsh-terminal').TerminalBackendSpawnSpec} spec - the identified spawn request.
+   */
   async spawn(spec) {
     spec.signal?.throwIfAborted()
-    ensureSandboxModeFence(this.ctx, spec.owner)
+    // The inherited fields (`ctx`, `config`, `spawnTerminal`, `createSession`)
+    // are TS-private upstream, so they are read through the one structural
+    // view declared above instead of repeating the same suppression per use.
+    const backend = /** @type {BashBackendInternals} */ (/** @type {unknown} */ (this))
+    ensureSandboxModeFence(backend.ctx, spec.owner)
     // Resolve services through `ctx.get` (never property access): the
     // backend may be constructed with a plugin context whose inject list
     // does not declare these services (the policy plugin's ctx), and Cordis
     // property access would throw "cannot get property … without inject".
     // `ctx.get` resolves any registered service regardless of inject.
-    const policy = this.ctx.get('sandboxPolicy').resolve({ session: spec.owner.session })
-    const argv = spawnArgv(this.ctx, this.config, policy)
+    const policy = backend.ctx.get('sandboxPolicy').resolve({ session: spec.owner.session })
+    const argv = await spawnArgv(backend.ctx, backend.config, policy, spec.signal)
+    // Confinement is async, so the caller may have cancelled while it ran.
+    spec.signal?.throwIfAborted()
     if (argv[0] === undefined) throw new Error('terminal-fish: sandbox returned empty argv')
-    const terminal = await this.spawnTerminal({
+    const terminal = await backend.spawnTerminal({
       argv,
       cwd: spec.cwd ?? policy.workspaceRoot,
       env: childEnvironment(spec),
-      rows: this.config.rows,
-      cols: this.config.cols,
-      graceMs: this.config.disposeGraceMs,
+      rows: backend.config.rows,
+      cols: backend.config.cols,
+      // The provider advertises this as the child's `TERM` (it overwrites
+      // whatever `env` carried with it), so it must be the same `dumb` the
+      // fish prompt readiness contract is verified against.
+      terminalType: 'dumb',
+      graceMs: backend.config.disposeGraceMs,
       signal: spec.signal,
     })
-    const session = this.createSession(terminal, this.config)
+    let session
+    try {
+      session = backend.createSession(terminal, backend.config)
+    } catch (error) {
+      // A failed session factory must not leak the freshly allocated terminal.
+      return rejectAfterStartupCleanup(error, () => terminal.terminate())
+    }
     try {
-      await startupSession(session, this.config.timeoutMs, spec.signal)
+      await startupSession(session, backend.config.timeoutMs, spec.signal)
       return session
     } catch (error) {
-      try {
-        await session.close('PTY startup failed')
-      } catch (closeError) {
-        throw new TerminalBackendCleanupError(error, closeError)
-      }
-      throw error
+      return rejectAfterStartupCleanup(error, () => session.close('PTY startup failed'))
     }
   }
 }
@@ -307,8 +417,8 @@ export class FishTerminalBackend extends BashTerminalBackend {
  * backend up explicitly. Plugin configuration mirrors the official
  * `@deepseek-ai/dsh-terminal-bash` Config surface (sans dialect), with fish
  * defaults: backend type `fish`, `fish --no-config -i` argv.
- * @param ctx - the harness context.
- * @param config - optional backend configuration.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the harness context.
+ * @param {import('@deepseek-ai/dsh-terminal-bash').TerminalLocalConfig} [config] - optional backend configuration.
  */
 export function apply(ctx, config = {}) {
   const resolved = resolveConfig(config)