@banbolee/dsh-fish-shell 0.4.0 → 0.5.0

package/README.md

@@ -3,7 +3,8 @@
 Fish shell executors and tool for DeepSeek Harness: run commands with
 **fish** instead of bash. Distribution-ready and surface-agnostic: works in
 any profile that mounts it — preset-roster based (dsh-tui, web) or
-host-tool based (headless).
+host-tool based (headless) — and under **any agent preset** (standard, ptc,
+cordis, minimal, or a third-party preset).
 
 ## What this bundle does
 
@@ -20,36 +21,104 @@ host-tool based (headless).
   without a sandbox. For custom compositions that deliberately run without a
   sandbox; composing it with `dsh-permission-presets` fails loud at load.
 - **Tool** (`tool.js`, exported as `@banbolee/dsh-fish-shell/tool`): a model-facing
-  `fish` tool mounted host-globally, executing through `ctx.shell`. It passes
-  the calling session's resolved sandbox policy (so `/permission` switches
-  and the session workspace root are honored), collects the managed `DSH_*`
-  environment from `ctx.shellEnv`, and renders the harness marker contract
-  (`[exit code: N]`, `[stderr]`, `[sandbox: file access denied under <mode>
-  mode]`, `[output truncated; full output: <path>]`). Its description teaches
-  the model fish syntax.
-- **Agent preset** (bundled at `presets/fish/`): a copy of the shipped
-  `standard` preset with the shell section removed (the `fish` tool is
-  host-global, so the preset needs no shell row). The bundle patch adds the
-  package's `presets/` directory as a system preset root and switches the
-  preset-roster default to `fish` for both roster row ids (`agent-presets`
-  used by web, `dsh-tui-agent-presets` used by dsh-tui). The tool plugin also
-  installs the preset under `$DSH_HOME/.agent-presets/fish` create-only
-  (never overwrites an existing file, including a user-authored one; a failed
-  write is a warning) as a fallback for rosters whose row this bundle does
-  not patch.
+  `fish` tool mounted host-globally, executing through `ctx.shell`. Its
+  functional surface is aligned with the official `@deepseek-ai/dsh-tool-bash`
+  (with shell wording swapped to fish):
+  - **Background execution**: `run_in_background: true` registers the command
+    with `ctx.jobs` (`kind: fish`) and returns `{kind: 'background', jobId}`;
+    output reads carry the lossy-read and sandbox runner-failure/denial
+    notices, and the job controller's `job_output`/`job_kill` handle the rest.
+  - **Sandbox escalation**: when the mounted executor confines, the schema
+    advertises `sandbox_permissions` + `justification`; an escalation is
+    resolved through `ctx.approval` BEFORE anything executes (strictly wider
+    modes only, fail-closed), and a denial result carries the same-turn
+    escalation hint. Headless compositions (no sandboxing executor) expose
+    neither field.
+  - **Result facts**: foreground results carry the complete canonical facts,
+    including the sandbox `enforcement`/`runnerFailed` fields.
+  - **UI presentation**: `presentCall`/`presentResult` render foreground calls
+    as terminal cards (with an exit-status pill) and background/error
+    outcomes as generic fenced console output.
+  - **Exit-code prompt section**: registers the `tool:fish` section
+    ("Check the [exit code: N] marker on every fish result…") at the
+    `TOOL_BASH` position.
+  - On top of all that it passes the calling session's resolved sandbox policy
+    (so `/permission` switches and the session workspace root are honored),
+    collects the managed `DSH_*` environment from `ctx.shellEnv`, renders the
+    harness marker contract (`[exit code: N]`, `[stderr]`, `[sandbox: file
+    access denied under <mode> mode]`, `[output truncated; full output:
+    <path>]`), and its description teaches the model fish syntax with
+    per-result `[fish syntax]` hints.
+- **Per-agent fish policy** (`policy.js`, exported as
+  `@banbolee/dsh-fish-shell/policy`): a host-mounted Cordis plugin that makes
+  every agent see fish instead of bash **regardless of which agent preset it
+  runs under**. The bundle patch disables the base bash executor
+  (`bash-sandbox`) and the host bash tool (`tool-bash`), mounts the fish
+  executor and the host-global `fish` tool, and leaves presets untouched —
+  it no longer changes the roster default, injects preset roots, or writes
+  copies under `$DSH_HOME/.agent-presets/`. Presets still register their own
+  `bash`-named tool (standard/minimal do), and on `agent/created` (and again
+  on every `tools/change`, i.e. after `/preset` recomposes) the policy hides
+  that inherited bash tool per agent via
+  `agent.ctx.tools.restrict({ deny: ['bash'] })` and shadows the preset's
+  static `tool:bash` prompt guidance with an empty agent-scoped section. The
+  agent is left with exactly one shell tool: `fish`. Under `minimal` — whose
+  standing bash is the persistent PTY form (parameters carry only `command`,
+  output schema is a plain string) — the policy first registers a persistent
+  `fish` tool at the agent scope (shadowing the one-shot fish) and then
+  hides bash, so minimal sessions keep their persistent semantics in fish.
+- **Persistent fish terminal backend** (`terminal-fish.js`, exported as
+  `@banbolee/dsh-fish-shell/terminal-fish`): a library — NOT mounted by the
+  bundle patch — providing the `fish` PTY backend used by the persistent
+  tool. It subclasses the official `BashTerminalBackend`, spawning
+  `fish --no-config -i` (config-overridable) with a controlled prompt that
+  speaks the harness readiness contract (OSC `133;D;<status>` + `dsh> `),
+  confined through the same sandbox policy, with the official
+  sandbox-mode fence copied in (the official module does not export it;
+  the copy takes an injectable owner-activity check for self-managed use).
+  The patch deliberately has no `fish-terminal` host row: the `terminals`
+  service is entry-local to the `minimal` preset's isolate realm and
+  invisible at the host plane (headless / dsh-tui / composition test
+  profiles), so such a row would stay pending forever. `apply` is exported
+  for direct assembly and tests (or a composition that explicitly mounts the
+  registry).
+- **Persistent fish tool** (`persistent.js`, exported as
+  `@banbolee/dsh-fish-shell/persistent`): a fish translation of the official
+  `dsh-tool-bash-persistent` pattern — a per-agent cached PTY shell whose
+  cwd, variables, and functions survive across calls, with marker-wrapped
+  commands, serialized execution, deadline/timeout reset, and scrollback
+  reads. It deliberately exports no Cordis `apply`: `policy.js` calls
+  `registerPersistentFish(ctx, agentCtx)` at the agent boundary for the
+  persistent-bash preset. The PTY is **self-managed**: the tool owns one
+  `FishTerminalBackend` instance and drives its sessions directly
+  (`backend.spawn(...)`, `session.startSend/read/status/close`) instead of
+  going through the `terminals` registry, which agent-scope tools cannot
+  resolve (the registry lives only inside the minimal preset's entry-local
+  realm). Command quoting uses fish single-quote escaping and `eval` with
+  one string argument (fish 4 has no `$'...'` ANSI-C quoting and no
+  `eval --`), verified against real fish 4.0.0.
 
 ## Install
 
+**From npm (recommended)** — no clone needed:
+
 ```sh
-# from this checkout, per profile:
-dsh plugin --profile <name> add ./plugins/fish-shell
+dsh plugin --profile <name> add @banbolee/dsh-fish-shell
 ```
 
-For a published npm package: `dsh plugin --profile <name> add @banbolee/dsh-fish-shell`.
+From this checkout, per profile:
+
+```sh
+dsh plugin --profile <name> add ./plugins/fish-shell
+```
 
-Add it to every profile that should default to fish (dsh-tui, web, headless,
-…). The bundle patch is a no-op (with a warning) for a roster row id that the
-profile does not have, so one patch file is safe across surfaces.
+Add it to every profile that should run fish (dsh-tui, web, headless, …).
+The bundle patch (`cordis.patch.yml`) is one safe patch across surfaces: it
+disables the host bash executor and `tool-bash` rows, mounts the fish
+executor and the host-global `fish` tool, and inserts the
+`fish-preset-policy` row, which hides the preset-inherited `bash` tool per
+agent (restriction + empty `tool:bash` prompt shadow, persistent-fish swap
+under `minimal`). The patch no longer touches the preset roster.
 
 ### Deployed copy and the symlink chain
 
@@ -59,32 +128,57 @@ runtime instance the harness uses — the launcher-maintained
 `profiles/node_modules/@deepseek-ai/*` symlink chain. A plain `link:` to this
 checkout (outside the profile tree) would resolve no `@deepseek-ai` package,
 so the deployed copy lives at `profiles/node_modules/@banbolee/dsh-fish-shell` (inside
-the tree). `scripts/sync-to-profile.sh` copies the plugin there after edits
-and checks the bundled fish preset for drift against the shipped `standard`
-preset; a pnpm `file:` dependency points each profile at the deployed copy. A
+the tree). `scripts/sync-to-profile.sh` copies the plugin there after edits.
+A pnpm `file:` dependency points each profile at the deployed copy. A
 package published to npm installs normally (its realpath already lies inside
 the profile tree).
 
 ## Per-surface behavior
 
-- **Preset-roster surfaces** (dsh-tui, web): agents compose tools from the
-  `fish` preset (default) — `standard` minus the shell rows — and see exactly
-  one shell tool, `fish`. **Upstream presets (`standard`, `code`) are not
-  fish-safe**: they register a `bash`-named tool that still executes through
-  the fish executor, so the name/description lie about the shell. Only the
-  bundled `fish` preset is fish-only. (`minimal` has no one-shot shell tool.)
+- **Preset-roster surfaces** (dsh-tui, web): the roster default is untouched
+  (`standard`). The `fish-preset-policy` plugin applies per agent, so an
+  agent under **any** preset — `standard`, `ptc`, `cordis`, `minimal`, or a
+  plain third-party preset — has its preset-inherited `bash` tool hidden and
+  sees exactly one shell tool: `fish`. The preset's static
+  `tool:bash` prompt guidance is shadowed (empty agent-scoped section), so
+  the model is not told to "check the bash result". Under `minimal` the
+  policy detects the preset's persistent bash and swaps in the persistent
+  `fish` tool instead, so minimal sessions keep their persistent semantics.
+  The persistent PTY is self-managed by the policy (one `FishTerminalBackend`
+  driven directly, no `terminals` registry), so it works in every surface —
+  the registry is only visible inside the minimal preset's entry-local
+  realm, which is exactly why the bundle mounts no `fish-terminal` row.
 - **Host-tool surfaces** (headless): the agent uses host-plane tools; the
   disabled host `tool-bash` and the host-global `fish` tool make fish the
   agent's only shell tool.
 
 ## Behavior
 
-- Every shell call spawns a fresh non-login shell (under the configured
+- **One-shot** (standard, ptc, cordis, third-party presets, and headless):
+  every shell call spawns a fresh non-login shell (under the configured
   sandbox backend for `FishSandboxExecutor`); no state (cwd, variables,
   functions, history) persists between calls.
+- **Persistent** (`minimal` preset, which mounts the persistent PTY bash
+  machinery): the agent's `fish` tool keeps one live fish session per agent.
+  The current directory, exported variables, and defined functions survive
+  across calls; commands run through the tool are serialized; a command that
+  exceeds the tool's deadline is interrupted and the shell is reset (the
+  next call starts from the workspace with a fresh shell). The persistent
+  fish PTY is spawned and driven by the tool itself through a
+  `FishTerminalBackend` (no `terminals` registry involved).
 - Output is bounded per stream by the executor's configured caps; timeouts
   are clamped to the executor's cap; the model sees the harness marker
   contract.
+- `run_in_background: true` starts long-running commands as background jobs
+  (`kind: fish`) and returns a job id immediately; read output with
+  `job_output` and stop it with `job_kill`. Requires the jobs services
+  (`@deepseek-ai/dsh-jobs` + `@deepseek-ai/dsh-tool-jobs`) to be composed;
+  the tool fails loud when they are not.
+- Under a sandboxing executor, a denied command can be re-run wider in the
+  same turn with `sandbox_permissions` (the narrowest wider mode that
+  suffices) plus a one-sentence `justification`; the approval prompt raised
+  by that retry is how the user consents. Denials are final when approval
+  prompts are disabled or the escalation is rejected.
 - Requires `fish` on PATH; the executors fail loud when it is missing.
 
 ## Known Limitations
@@ -92,12 +186,28 @@ the profile tree).
 - Models default to bash idioms; the `fish` tool description teaches fish
   syntax, but a command written in bash dialect fails under fish. This is the
   intended trade of swapping the shell.
-- The `fish` tool has no `run_in_background` parameter and no sandbox
-  escalation (`sandbox_permissions`) parameters yet; long commands must
-  finish within the timeout, and a denied command cannot be re-run wider
-  (the executor's `start()` and the approval stack are available to
-  in-process consumers).
-- Upstream presets (`standard`, `code`) are not fish-safe; see
-  Per-surface behavior.
+- **The legacy bundled `fish` agent preset was removed**: this bundle ships
+  no `presets/fish/` directory, the sync script no longer deploys or
+  drift-checks one, and no user copy is written under
+  `$DSH_HOME/.agent-presets/fish`. A stale user copy of that directory from
+  an older bundle version is inert (the roster no longer points at it) and
+  can be deleted manually.
+- **Persistent semantics under `minimal`** are provided by the persistent
+  `fish` tool (cwd, exported variables, and defined functions survive across
+  calls). Like the official persistent bash, a command that overruns the
+  deadline is interrupted and the shell is reset; an agent-scoped `fish`
+  tool shadows the host-global one-shot tool, so escalation fields
+  (`sandbox_permissions`/`justification`) and background execution
+  (`run_in_background`) are not part of the persistent surface.
+- **Third-party preset boundaries**: the policy hides a `bash`-named tool
+  inherited from the preset. A preset that deliberately excludes the global
+  `fish` tool (an allowlist that filters it out) or registers its shell tool
+  under a different name is left exactly as authored, with a one-time
+  warning per agent — the bundle never mutates a third-party preset.
+- The `fish` tool's model-facing surface is aligned with the official bash
+  tool: background execution (`run_in_background` via `ctx.jobs`), sandbox
+  escalation (`sandbox_permissions`/`justification` via `ctx.approval`),
+  terminal/generic UI presentation, and the `tool:fish` exit-code prompt
+  section are all supported.
 - POSIX only: the `fish` binary and the underlying process-group semantics
   are not available on Windows (the pwsh family covers Windows).

package/cordis.patch.yml

@@ -1,19 +1,42 @@
-# @banbolee/dsh-fish-shell bundle: make fish the default shell executor instead of bash.
+# @banbolee/dsh-fish-shell bundle: run commands with fish instead of bash,
+# on every surface and under every agent preset.
 #
-# Works across every surface:
-#   - dsh-tui / web (agent-preset roster): disables the base bash executor
-#     (`bash-sandbox`) and the host bash tool (`tool-bash`), mounts the fish
-#     executor (ctx.shell) and a host-global `fish` tool, and points the
-#     roster default at the bundled `fish` agent preset (discovered through
-#     the package's own `presets/` directory, registered below as a system
-#     preset root).
-#   - headless (no preset roster; the agent uses host-plane tools): the
-#     host-global `fish` tool and the disabled `tool-bash` already make fish
-#     the agent's only shell tool.
+# How it works now:
+#   - The base bash executor (`bash-sandbox`) and the host bash tool
+#     (`tool-bash`) are disabled at the host plane, the fish executor
+#     (ctx.shell) is mounted, and a host-global `fish` tool is registered
+#     (`fish-shell` + `tool-fish` rows below). Headless (no preset roster)
+#     agents therefore see only the `fish` tool.
+#   - Presets are NOT touched: the roster default stays `standard`, and no
+#     bundled preset root or user copy is installed. Standard/ptc/cordis/
+#     minimal/third-party presets keep registering their own `bash`-named
+#     tool at the preset standing scope.
+#   - `fish-preset-policy` fixes that per agent at the agent boundary: on
+#     `agent/created` and on every `tools/change` (preset recompose) it
+#     calls `agent.ctx.tools.restrict({ deny: ['bash'] })` to hide the
+#     preset-inherited bash tool and registers an empty agent-scoped
+#     `tool:bash` prompt section that shadows the preset's static bash
+#     guidance. The agent ends up with exactly one shell tool: `fish`.
 #
-# The model-facing `fish` tool is host-global so every surface sees it; the
-# bundled `fish` preset (standard with the shell rows removed) keeps agents
-# that select it free of a duplicate or bash shell tool.
+# Boundaries:
+#   - `minimal` keeps its persistent PTY bash machinery mounted. When the
+#     policy detects the persistent bash form (a `bash` tool whose
+#     parameters carry only `command` and whose output schema is a plain
+#     string), it registers a persistent `fish` tool at the agent scope
+#     (shadowing the host one-shot fish) before hiding bash, so minimal
+#     sessions keep their persistent semantics — cwd, variables, and
+#     functions survive across calls — in fish.
+#   - The persistent fish PTY is SELF-MANAGED by the policy: `persistent.js`
+#     owns a `FishTerminalBackend` instance and calls `backend.spawn(...)`
+#     directly. Nothing is registered in the `terminals` registry (which is
+#     entry-local to the `minimal` preset and invisible at the host/agent
+#     plane), so the bundle must NOT mount the `terminal-fish` plugin row
+#     here — that would leave the entry pending forever in host-plane
+#     profiles (headless, dsh-tui, composition tests) that have no
+#     `terminals` service.
+#   - A third-party preset that allowlists the global `fish` tool out (or
+#     registers its shell tool under a non-`bash` name) is left as authored,
+#     with a one-time warning per agent.
 - id: bash-sandbox
   disabled: true
 
@@ -27,21 +50,5 @@
     - id: tool-fish
       name: '@banbolee/dsh-fish-shell/tool'
 
-- id: dsh-tui-agent-presets
-  config:
-    default: fish
-    roots: !!js >-
-      (() => {
-        const base = ctx.baseUrl
-        if (!base) return []
-        const resolvePath = (url) => {
-          const path = decodeURIComponent(url.pathname)
-          return /^\/[A-Za-z]:/.test(path) ? path.slice(1) : path
-        }
-        const system = new URL('../node_modules/@deepseek-ai/dsh/config/agent-presets/', base)
-        const own = new URL('./node_modules/@banbolee/dsh-fish-shell/presets/', base)
-        return [
-          { path: resolvePath(system), trust: 'system' },
-          { path: resolvePath(own), trust: 'system' },
-        ]
-      })()
+    - id: fish-preset-policy
+      name: '@banbolee/dsh-fish-shell/policy'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banbolee/dsh-fish-shell",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Fish shell executors and tool for DeepSeek Harness: run commands with fish instead of bash.",
   "type": "module",
   "main": "index.js",
@@ -8,14 +8,19 @@
     ".": "./index.js",
     "./local": "./local.js",
     "./tool": "./tool.js",
+    "./policy": "./policy.js",
+    "./terminal-fish": "./terminal-fish.js",
+    "./persistent": "./persistent.js",
     "./package.json": "./package.json"
   },
   "files": [
     "index.js",
     "local.js",
     "tool.js",
+    "policy.js",
+    "terminal-fish.js",
+    "persistent.js",
     "cordis.patch.yml",
-    "presets/",
     "README.md"
   ],
   "dsh": {
@@ -25,18 +30,49 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-bash-local": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-bash-sandbox": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-home-paths": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-home-paths": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell-env": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-terminal": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-terminal-bash": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-user-approval": "^0.1.5-rc.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-bash-local": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-bash-sandbox": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-home-paths": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-invariants": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-pwsh-local": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.1",
     "@deepseek-ai/dsh-scope": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-shell": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-shell-env": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-terminal": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-terminal-bash": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.1",
+    "@deepseek-ai/dsh-user-approval": "^0.1.5-rc.1",
+    "yaml": "^2.8.0"
   },
   "keywords": [
     "dsh",