Drop the bare `dsh <config>` positional in favor of a `--config <path>` flag.
Without a root positional, `web` can be a real Commander subcommand in one
program instead of the reserved-first-token dispatch to a second parser, so
`dsh --help` lists every mode natively (no hand-pasted command text) and the
second parser + reserved-token machinery are gone.
Grammar:
dsh TUI (shipped tree + ~/.dsh overlay)
dsh --config <path> TUI, alternate tree (demos/tests only)
dsh --resume <id> TUI, resume a session
dsh -p "task" headless one-shot
dsh web [--host --port --dev]
`dsh` is the product front door with no positional; `--config` exists only so
demo:cordis, demo:code-mode, and the keyless PTY smokes can point the shipped
bin at an example tree. Those three sites and the /resume re-exec argv move to
`--config <path>`. The `-p` + `--config`/`--resume` mode-mixing guard and the
cordis.yml-owns-host/port-default fix are preserved.
Agent Note + Chinese pair, README, tui.ts docs updated. All 13 PTY smokes
(including code-mode via --config and the exec-replace resume handoff) green.
The merge's "always pass adapter-resolved host/port to AppCLIEntry" made the
adapter's 127.0.0.1/3080 shadow apps/cli/cordis.yml's webserver row — editing
the yml port would have had no effect, a duplicated default.
The adapter now assigns no host/port default: an absent --host/--port leaves the
field undefined (WebInvocation.host?/port?), runWeb forwards each to AppCLIEntry
only when present, and AppCLIEntry patches the webserver row only for an
explicit flag. cordis.yml is the single source of the host/port default; the
adapter still validates a flag when given. Removes the now-unused
DEFAULT_WEB_PORT; LOOPBACK_HOST/ALL_INTERFACES_HOST stay as the allowed-value
vocabulary (validation + the printed URL/LAN line).
Integrate the Commander argument adapter and dsh-front-door work with master's
config-tree `dsh web` (#601: AppCLIEntry + apps/cli/cordis.yml) and the
packages/ui/acp → packages/acp/acp relocation.
- web.ts: keep master's AppCLIEntry-based boot, but take the adapter's parsed
(host, port, dev) instead of an internal parseArgs. The adapter's host/port
defaults (127.0.0.1/3080) match cordis.yml, so always passing them is
behavior-equivalent to master's "undefined keeps the yml default".
- apps/cli/package.json: master's expanded config-tree dep set + commander.
- retire-readline Agent Note: point the TUI refusal proof at
apps/cli/tests/built-bin.e2e.ts (both languages), re-record the pair.
- READMEs reconciled (demo-bin removal + master's ACP/channel rewording).
Address review and cut ceremony: the adapter no longer models help/version/
errors as DshInvocation members. Commander owns those under exitOverride — it
prints usage or the diagnostic and one try/catch in parseDshArgs turns the
thrown CommanderError into process.exit with the intended code. bin.ts drops its
help/version/error cases; the union is the three real modes.
Domain checks bail via command.error(print + exit 1): --prompt rejects an empty
task or a stray config/--resume, empty --resume= fails loud, and --host/--port
are validated. A repeated --resume or a flag captured as a value is Commander's
standard behavior, left alone (a bad id fails loud downstream). dsh --help
discloses web via addHelpText. Net: args.ts 185 -> 112 lines.
Also fixes review nits: built-bin e2e resolves on `close`; the /resume handoff
uses `dsh --resume=<id> -- <config>` so a config named `web` stays a positional;
and stale prose (cordis.yml comment, app-boot module doc + duplicate JSDoc,
ui/README, two feature notes, an agent-loop test name) tracks the shipped state.
Removes tui-demo's now-dead plugin-include dep and vendor/loader + app-boot
tsconfig references.
Removing the dsh-tui-demo bin dropped the only test of the TUI's piped-launch
refusal. Add apps/cli/tests/built-bin.e2e.ts (apps/*/tests added to the e2e
vitest include) running the built lib/bin.js under plain Node with piped stdio,
and point the refusal message at `dsh -p "task"` for automation.
Remove the redundant dsh-tui-demo bin and the RESUME_SESSION_ID environment
variable, leaving dsh as the one terminal entrypoint.
The dsh-tui-demo package was a plugin (the TUI app bundle mounted by dsh's
config) plus a bin that booted a leaf cordis.yml — the same job `dsh [config]`
does. The bin, its ./bin export, its built-bin.e2e.ts, the tsdown bin entry,
and the now-unused dsh-app-boot dependency are removed; the package keeps its
plugin and invariant. demo:cordis, demo:code-mode, and the tui-agent and
cordis-agent keyless PTY smokes now launch through apps/cli/src/bin.ts with the
config as the positional argument. cli-demo/acp-demo/jsonrpc-demo keep their
bins (distinct surfaces).
RESUME_SESSION_ID was the only bridge from --resume into the shipped config;
--resume now provides the id on the boot context via ctx.provide(
RESUME_SESSION_ID_KEY, id), and the four configs read it as a bare identifier
through a quoted typeof-guarded !!js expression. The TUI resumeCommand fixtures
and docs move to `dsh --resume {session}`.
Agent Note and its Chinese pair updated; config-catalog regenerated.
Integrate the Commander argument adapter with master's safe session-resume
feature and dsh web --dev flag.
- args.ts: add --dev to the web parser.
- tui.ts: keep master's process.execve in-place resume handoff, but take the
adapter's parsed (config, resume); inject the resume id through boot's
prepare(ctx) hook via ctx.provide(RESUME_SESSION_ID_KEY, id) instead of the
RESUME_SESSION_ID env var; rebuild the re-exec argv as `dsh --resume <id>`.
- app-boot: drop master's replaceResumeArg (no longer needed) alongside the
already-removed parseResumeArg; add RESUME_SESSION_ID_KEY.
- the four tui-agent/cordis configs read the ctx-provided resumeSessionId via a
typeof-guarded !!js expression, so resume needs no env var.
- web.ts: keep master's client roster and --dev watch, take parsed host/port/dev.
Simplify the Commander adapter now that behavior can change: dispatch a leading
`web` token to its own parser instead of a subcommand of the root program, and
read opts()/processedArgs after parse() instead of action closures with a
mutable holder.
This removes enablePositionalOptions(), the parent-option leak guard, both
action closures, and the --resume/--prompt argParser threading. Behavior
changes: `dsh -p x web` is a headless prompt (extra positional dropped),
`dsh web -p x` fails loud (web has no -p), and a repeated --resume is natural
last-wins. The two real fail-loud invariants stay as post-parse checks: an empty
--resume= id (agent-loop treats '' as no-resume) and an empty -p task.
Trims args.spec.ts to the routing/fail-loud/help behavior that matters; the
tui-agent keyless PTY smoke still covers bin.ts dispatch end to end. Net ~114
fewer lines across adapter and tests.
Replace the dsh CLI's three hand-rolled parsing idioms (raw argv[0]/includes
dispatch in bin.ts, per-mode node:util parseArgs in headless.ts/web.ts, and the
bespoke parseResumeArg scanner in dsh-app-boot) with a single Commander adapter
in apps/cli/src/args.ts. parseDshArgs resolves argv into a discriminated
DshInvocation union; bin.ts switches on the mode and dynamic-imports the chosen
module, which now consumes already-parsed values.
- web is a real subcommand; --host uses choices and --port an argParser range
check, moving validation into the parser.
- --resume rejects empty and repeated forms; --prompt rejects empty; a config
positional after --prompt and a root flag placed before web fail loud.
- adds --help/--version; removes parseResumeArg from dsh-app-boot.
- new apps/cli/tests/args.spec.ts (apps/*/tests added to vitest include,
apps/cli/tests to tsconfig.host.json); the tui-agent keyless PTY smoke covers
bin.ts dispatch end to end unchanged.
The master merge introduced a tui goal-restore test and the guard parent
README that still used the removed context/message event. Point both at
the coalesced plugin-sourced user/message.
Address a fresh-eye review of the disposal/injection fixes:
- disposal now snapshots, clears, and marks disposed BEFORE emitting
agent/inbox/discard (mirroring cancel's snapshot→clear→emit), so a
re-entrant send/cancel from a discard listener throws 'disposed' or
finds an empty inbox instead of leaking or double-discarding an id.
The discard is unconditional (even on unpublished setup-rollback) to
match send's unconditional enqueue, keeping every id balanced.
- restore the turnRecorded guard on the idle-injection flush: a
turn/start rejected pre-commit (append reentrancy / internal-dispatch
veto) records nothing and owes no flush; the previous unconditional
flush emitted a phantom-turn agent/error. The isTurnOpen/turnRecorded
branches are reachable (reentrant inject from a session/event
listener) and now covered by a regression test rather than v8-ignored.
- rewrite the agent/inbox/discard event JSDoc to enumerate all three
emitters (cancel, terminal turn-stop, disposal) — every enqueued id
gets exactly one terminal dequeue-or-discard.
Per-file coverage stays 100%.
Address the review bot's five genuinely-new findings on the current code:
- disposal now discards any still-pending inbox items before the loop
exits, so every enqueued id gets a terminal lifecycle event.
- injection (next-step/no-wakeup) validates its payload up front, before
opening the idle one-shot turn, honoring 'invalid input throws before
any append'; and rejects attached contexts (which belong only to inbox
messages) rather than silently dropping them.
- agentMessage() freezes the agent/inbox/* payload so a listener cannot
mutate the shared correlation object mid-dispatch.
- refresh the package READMEs (compact, goal, guard, hook-protocol,
plan-mode, time-context, workspace-context) that still referenced the
removed context/message event, with the source-based user/message
distinction.
The up-front injection validation makes two finally branches unreachable
(v8-ignored as the turn-enclosure backstop). Adds regression tests for
disposal discard, context rejection, up-front validation, and the frozen
payload; per-file coverage stays 100%.
- tui.spec: exercise a goal-sourced injected context card (labels by
source kind, not plugin name), closing the last uncovered branch in
tui/src/index.ts that the CI coverage gate caught.
- time-context.e2e / goal.e2e: filter injected context by source now
that it is a user/message (plugin/goal source), and count goal
continuation rounds by round>0 rather than event type.
Address a second fresh-eye review of the review fixes:
- MAJOR: late steering that lands after runTurn returns terminally
stopped (e.g. during the post-turn flush) was drained by runLoop and
dropped without a discard, leaving a dangling outstanding id the
negative-only invariant can't catch. Emit agent/inbox/discard for it,
symmetric with the in-turn terminal-stop drop.
- remove the dead cancel() idle-settle branch: whenIdle's fast path
already resolves for a lone quiet item, so no waiter is ever left for
it to settle. Document why.
- gen-cordis-api classShape now drops private/protected/#private members
and strips getter/setter bodies, so Session no longer leaks private
fields and getter bodies into the model catalog.
- document that AgentMessage intentionally omits meta (durable-only).
Adds a regression test for the late-steering discard.
Resolve six review findings on the unified-send change:
- quiet (wakeup:false) queued items no longer un-park the driver; the
inbox distinguishes hasWakingQueued (drives the loop, idle/quiescence)
from hasQueued (anything to dequeue), so a lone quiet item parks at idle
and rides the next waking send. whenIdle/cancel settle off the waking
signal, so cancelling a parked quiet item no longer hangs whenIdle.
- SendOptions.meta on queued/steering sends now reaches the durable
user/message and steering/message (was dropped except on injection).
- a terminal agent/turn-stop that drops pending steering emits
agent/inbox/discard so the enqueue-dequeue-or-discard ledger balances.
- the loop-authored continuation reason is snapshotted and frozen like a
public send.
- gen-cordis-api collects exported classes (body-stripped) so the now-
abstract-class Agent and its transitive shapes reappear in the API
catalog.
Adds regression tests for each and re-records the affected snapshot.
Merge took master's snapshot fixtures; re-record the two keyless
scenarios so they reflect this branch's user/message coalescing and the
abstract Agent + AgentMessageId type dump.
Add a branded AgentMessageId assigned to each accepted send message and
returned from send/followup/steer/inject (was void). Rename the inbox
event payload InboxItemInfo to AgentMessage, carrying that id so a caller
can correlate a queued item with its enqueue/dequeue/discard events.
The FIFO-conservation invariant fired on the loop-authored continuation
reason path: a continue-with-reason decision entered the steering FIFO
without an agent/inbox/enqueue, so its later dequeue/discard had no
matching enqueue. Emit the enqueue for that steer too, add a regression
test that mounts the invariant over a continue-with-reason turn and a
cancel, and hoist the duplicated inboxInfo helper into inbox.ts.
Found by fresh-eye review.
Replace send/steer/inject with one Agent.send primitive over the
(target × wakeup) matrix; followup/steer/inject become fixed-preset
alias methods on the now-abstract Agent class. Coalesce context/message
into user/message (injected context is a non-user source). Replace
agent/queued with agent/inbox/enqueue/dequeue/discard, add cancel
keepInbox, and add a FIFO-conservation invariant.
demo:web and the README Web UI instructions ran only build:web (the Vite
frontend shell), never the root build that emits each web-client plugin's
lib/client.js. On a clean checkout every /plugins/<id>/client.js 404s and
the client loader shows "Failed to load plugins".
Run pnpm run build before build:web in both the demo:web script and the
README instructions for the installed ~/.dsh/source checkout.
- workspace-context: a transiently unavailable but still-effective candidate
keeps its cached trimmed digest in the directory's dedup slot, so an
identical later sibling is not emitted as a duplicate set until the next
successful reconciliation
- app-boot: --resume rejects a following token that is itself resume syntax
instead of accepting it as a session id
- tui: the queued-steering badge tracks per-entry sources and a drain removes
one matching entry, so loop-authored steering (no agent/queued) cannot
consume a pending user message's slot
Seven-chapter tutorial under docs/cordis-tutorial/ for agent developers
new to Cordis: first plugin, lifecycle/effects, services, events,
config, composition/HMR, and a final chapter registering a tool against
real harness services. Every transcript was produced by running the
chapter files in a gitignored tmp/ scratch directory.
Published to both website locales as mirrored English pages under a new
'Cordis tutorial' develop-sidebar section; a Chinese pair can be added
later without route changes.
Path expectations derive from join() per the cross-platform fixtures
convention; the fake fs resolves against the host root so drive-letter
targets match seeded keys; the unreadable-candidate cases use the provider
throwOnRead fixture (host chmod 0 is a no-op for the owner on Windows),
keeping the read-failure branch covered there, with a narrow win32 skip only
for the host-chmod discovery case.
The smoke's inline Python pty driver only ran on POSIX (no termios on
Windows). Rebuild every scenario — banner sweep, scripted conversation with
model switch, /skill:, Code Mode overlay, resume failure, and the dsh CLI
suite (default boot, personal overlay, invalid overlay, --resume flag,
source-path prompt) — as marker-gated action lists on pty-harness.ts, which
drives ConPTY via node-pty on Windows and the Python driver elsewhere. The
harness gains configArgs (bins with built-in default configs), prepare
(workspace seeding), and inspect (post-run log assertions); examples/
declares the session-title provider the shipped cordis.yml now mounts.
Master's log-backed session-title capability already titles sessions durably
(deterministic fallback in the spine, optional model providers). Remove the
TUI's own autoTitle generation — the latch, prompt, cap, and llm stream call —
and keep the terminal rename: the TUI folds the logged title on mount and sets
'<session title> — <configured title>' on every accepted session/title event.
The tui-agent example and the scripted PTY fixture mount
session-title-first-message-llm so titles stay model-made; the scripted
adapter's tool-less branch now answers that provider's auxiliary request.
See .agents/notes/implemented/simplification/2026-07-22-tui-titles-from-session-title-service.md
The acp escalation smoke advertises the shipped deepseek-v4-pro; the
workspace-context e2e asserts the per-candidate scope key. The PTY harness
drops COLORTERM (deterministic banner) and gains configArgs/prepare/inspect
for the dsh CLI scenarios.
pi-ai 0.80 restructured its entrypoints: the static catalog reads now
live on /providers/all as getBuiltinModels/getBuiltinProviders (keyed by
the catalog-only BuiltinProvider type, replacing KnownProvider at those
call sites), and the global streamSimple moved to /compat. The config
schema gains the new 'max' reasoning level.
The built-bin fail-loud test needs the TTY refusal before Loader boot (a
compose-time throw is logged per-entry, not rethrown); the PTY driver drops
COLORTERM so a developer's truecolor shell cannot flip the banner to the
gradient path mid-assertion; the scripted fixture persists raw JSONL so the
smoke's system-prompt inspection can read the log.
- acp/headless whole-config snapshot patches restate persistenceCompression:
none so raw JSONL fixtures stay harvestable, and re-pin the recorded
deepseek-v4-flash where the shipped config moved to pro
- depth-two overlay gains the app-config re-pin master's other overlays carry
- headless-agent stays on flash: goal/ralph overlays include it via a nested
include, which a config patch cannot reach to re-pin
- workspace-context scenarios re-record their session fixtures for the
per-candidate scope keys and both-siblings loading; acp session fixtures
otherwise return to master's (session/title + delegationDepth events)
workspace-context's abort-tool test uses agent.cancel({kind:'user'}) (master's
AgentCancelCause shape); tui-demo forwards no welcome when none is configured.
Post-rebase reconciliation of the two TUI lines that evolved in parallel:
- header subtitle prefers the latest logged session title over the configured
welcome; the process-local auto-title owns the whole terminal title while a
logged session/title still wins through the suffixed form
- footer keeps staging's model/cwd/usage/cache layout and gains master's
context-percent segment; per-step usage dedup carries cache buckets
- test harness only stubs the llm catalog when the test did not mount the
real LlmService, and defaults the TUI clock to the real Date.now
- the plugin-shaped /reload test composes commands+llm like the shipped app
Squashes feat/personal-config-dsh-home: personal config.yaml and .env move
from ~/.config/dsh to the Harness home (~/.dsh), plus the module-graph,
lockfile, and i18n pairing regeneration that followed.
Make todo_write opt-in for the tui-agent example (disabled by default; TUI
still renders plans when the tool is loaded). Both enabled and disabled cases
covered by tests.
Squashes feat/install-script, feat/install-default-master, and
install-skip-clone: DSH_REF defaults to master, and running the script from
inside an existing checkout reuses it and skips the clone.
Squashes feat/tui-cache-hit-rate and feat/tui-verbose-status: the footer
shows cache hit rate and the running status line reports turn phase with
elapsed timing.
Load a per-directory local overlay in addition to the base instruction
file, matching the Claude Code AGENTS.local.md / CLAUDE.local.md
convention for git-ignored personal guidance.
- New config `localInstructionFileCandidates`, default
`['AGENTS.local.md', 'CLAUDE.local.md']`; empty disables the overlay.
The default lives in the plugin Config schema, so every front door
(TUI/ACP/headless) reads .local. files consistently.
- Per project directory the plugin loads the first-existing base
candidate, then additively the first-existing local candidate,
rendered after the base so it takes precedence within the byte budget.
- Base and local tiers get distinct scope keys via a NUL sentinel
(scopeKey/decodeScopeKey) so they never collide in the baseline map,
pending window, or version cache.
- The fixed user-global $DSH_HOME/AGENTS.md stays base-only.
Docs: README (config, lifecycle, Known Limitations), regenerated
config-catalog, and a new bilingual Agent Note cross-linked to the
owning workspace-context note. 100% per-file coverage retained.
Squashes three linearized steps (feat/tui-startup, feat/banner-reveal,
feat/remove-banner): the banner experiment converged on removing the
startup banner entirely; later commits restore it borderless and add the
brand gradient.
Squash of the linearized fix/tui-color-scheme-v2 merge and the follow-up
catalog regeneration. Renders error cause chains at every diagnostic seam
(origin/fetch-failed-diagnostics) and adds color scheme detection with a
light-terminal palette.
Delete packages/ui/stdio and examples/repl-agent; rename stdio-demo to
@deepseek-ai/dsh-tui-demo (TUI-only, refuses pipes before Loader boot).
tui-agent owns the coding composition inline; echo-agent and the CI demo
smoke move to the one-shot cli-demo bin, which gains -p/--prompt. The
UI-independent with-key e2es move verbatim to tui-agent. SDK wizard's
'stdio' interface becomes 'tui'. PTY testing stays confined to TUI
surfaces; all other subprocess tests ride pipes.
See .agents/notes/implemented/simplification/2026-07-20-retire-readline-front-door.md
The consolidated resolver scopes the anonymous id to $DSH_HOME rather
than the machine. Update the module contract, README, and Agent Note to
say per-harness-home explicitly instead of over-claiming a machine-global
identity, and record why DSH_HOME scoping is the intended single-root
meaning rather than a regression.
Review fixes for #462:
- resolveDshHome now treats an empty or whitespace-only $DSH_HOME as
unset, so a blank override never resolves the home to cwd via
resolve(''). Restores the guard telemetry's old resolver carried.
- The default-env telemetry test asserts only that globalConfigDir()
returns an absolute path, so a machine DSH_HOME without a .dsh suffix
cannot break it.
Automatic compaction fires mid-conversation, right after the loop warmed
the provider's KV cache with the last routed request. The default
summarizer then issued a separate request whose prefix shared nothing
with that warm request — a bespoke summarizer system prompt followed by
the older history flattened to one rendered transcript string — so a
differing first token invalidated the entire cached prefix and every
compaction re-processed the whole replayed history twice.
Move the compaction directive from the FRONT (a fresh system prompt) to
the END (a trailing user message), and replay the last routed request's
own system prompt, tools, message prefix, and shadowed-region messages
verbatim via session.requestHeader() + deriveEventMessage. The auxiliary
call is now a genuine prefix-extension of the warm request, so the
provider reuses the cached tokens up to the trailing instruction.
SummarizationInput carries the replayed prefix instead of a flat string;
the now-unused renderTranscript/renderContentBlocks path is removed with
its spec. Cache reuse is best-effort (head compaction guarantees a hit;
a mid-range compaction or a differently-routed summarizer forgoes it),
correctness is not.
Delete @deepseek-ai/dsh-home and make dsh-paths the sole owner of the
single-root harness home ($DSH_HOME || ~/.dsh). Migrate tool-bash,
skill-local, and agent-spine-demo off dsh-home, and fold telemetry's
divergent globalConfigDir onto the shared resolver, dropping its second
XDG/APPDATA policy and the deepseek-harness namespace so the anonymous
id lives under the harness home. Add dshHomeDisplay() for symbolic
user-facing paths, replacing workspace-context's bespoke check.
The earlier fix only widened the vitest timeout, but the real race is the
patient probe reading the 1s launcher under the 5000ms *default* probe budget:
under a full parallel run spawnSync blocks the worker and fork/exec latency can
push the launcher's wall-clock past 5000ms, so the patient probe wrongly reads
unusable and the assertion fails. Give the patient probe a generous explicit
15000ms budget (still far below its 1s launcher runtime margin) so only the
250ms impatient probe races the launcher; keep a 30s vitest timeout above the
patient budget.
Resolve conflicts:
- packages/ui/tui/src/index.ts: keep the color-scheme detection block; drop the
obsolete static autocomplete list (master moved to refreshCommandAutocomplete).
- docs/config-catalog.md: regenerate (tui Config source line shifted to :104).
`bounds the default probes` runs a real launcher that sleeps 1s under the
5000ms default probe budget, all wrapped in vitest's 5000ms default test
timeout. The blocking spawnSync races that wrapper and tips over under the
load spike of a full parallel run — a pre-existing, load-sensitive flake
(noted as unrelated in this PR's original description). Give the test an
explicit 20s timeout so its bounded subprocess work never races the default.
The color-scheme detection block left packages/ui/tui/src/index.ts below
the 100% per-file coverage gate on three counts: the .then callback's
`scheme === undefined` branch was reachable only via the 2s query
timeout, the .catch only via a query-write failure, and the
`editor.borderColor` assignment inside applyColorScheme was dead code —
the next line's setStatus() immediately reassigns editor.borderColor.
Register the scheme listener before firing the startup query so the
query's own reply is delivered through the listener (the same path as
later theme switches), which removes the redundant .then re-application
and its uncoverable undefined branch, and closes the theoretical window
where a synchronous reply lands before the listener exists. Drop the
dead editor.borderColor line. Cover the rest: a same-scheme report
(early return) and a terminal that throws on the query write (the
swallowed .catch).
Turtle