Repository navigation
Releases
minidsh 1.2.0
Background work, a third provider, web search, skills and a real browser, built across four sessions; then the whole widened runtime was reviewed as one system and what that review found was fixed before release. Read the migration note at the end of this section before upgrading a deployment that sets a temperature, a base URL or an agent preset.
Added
-
A real browser to check a frontend. Where Chrome, Edge or Chromium is installed, the model gets five tools:
browser_navigateopens a page and waits for a dev server that is still starting;browser_snapshotreads the page as an accessibility tree with refs;browser_actclicks, hovers, types, presses keys and selects, as real input that is refused when the element is hidden, disabled or covered;browser_screenshotcaptures the page, on a vision-capable route only;browser_evaluateruns JavaScript in the page.
Every result opens with what the page logged, failed, blocked or asked since the previous one. Each session gets its own headless browser under a private profile in
~/.minidsh/browser/, started on first use and gone when the session ends, over a pipe rather than a debugging port. It reaches only localhost and the workspace's own files, plus anyallowHostsyou name in thetool-browserrow. This is enforced inside the browser (a proxy the harness owns, resolver rules and afile:filter) and proved each time it starts. Downloads are refused. A script still running at a call's deadline is stopped, and a page that still does not answer (a loop that re-arms itself) is replaced by a fresh one on the next call; the model is told either way. It asks no consent, so a delegated verifier child can use it: a text-only model hands the look to asubagententry routed to a vision model. -
Background jobs.
job_startruns a long command beside the session — a dev server, a slow test run — and returns at once;job_outputreads what it wrote since the last read (optionally waiting for it to end) andjob_cancelstops it and what it started. A job's start and its one end are durable facts in the log; when a job ends on its own its notice arrives in the session and wakes an idle agent, at most eight times in a row before a person says something, and a stop someone asked for never wakes it. A job runs under the session's own authority, never an escalation, a durable switch of the sandbox mode or acceptance ends it, and it ends with its session. If the MiniDSH process dies, the next resume (andsessions verifybefore it) closes each running job as lost and tells the model so. -
OpenAI as a third provider.
--provider openai --model gpt-6-luna(or/model openai/gpt-6-luna, orsession/model) routes a session to OpenAI's Responses API, mid-session included, withOPENAI_API_KEYin the environment orcredentials.json. Nothing is stored at OpenAI (store: false): a reasoning model's encrypted reasoning travels back to the same model inside the session log, and is dropped, never forged, for any other. The catalog covers the current GPT-6, GPT-5.6, GPT-5.5, GPT-5.4, GPT-5.2 and GPT-5 mini/nano models with their measured effort sets; an option a model would refuse or silently ignore — an effort it lacks, atemperaturewith reasoning on, an output cap above its own — is refused before anything is sent. -
Web search, opt-in. A
composition.jsonrow ({"patches": [{"insert": [{"id": "tool-web-search", "plugin": "tool-web-search"}]}]}) gives the modelweb_search, backed by Tavily (TAVILY_API_KEY). Every query asks first: the line you answer names the exact text that would leave the machine, where it goes and under which credential, and a session grant covers only that identical query. Results arrive as a numbered list of titles, URLs and snippets behind a fixed notice that they are untrusted content — never a provider's own summary. A delegated child is not offered the tool, and its pinned approvals would refuse every query anyway. There is noweb_fetch. -
Skills: know-how as data. A folder holding a
SKILL.md(the open agentskills.io format) in~/.minidsh/skills/, inside the package, or in a repository's.agents/skills/or.claude/skills/is listed to the model by name and description, and the model reads one with its ordinary file tools when a task fits. A skill is advice, never a permission: its scripts are shell commands under the session's own authority. A repository's skill never replaces yours or a bundled one (the operator is warned on stderr). Two ship, on Node alone:officebuilds, reads, unpacks and validly repacks .docx, .xlsx and .pptx, andpdfreads PDFs and writes simple ones. Real Word, Excel and PowerPoint open what they build. -
Jobs on every surface. The session view lists jobs;
job/cancelstops one over the protocol; the terminal has/jobsand/jobs cancel <id>; the browser shows a jobs strip with a stop button and per-session badges. A newcontrol/subscribesends every client a per-session summary (status, running jobs, held notices, pending approvals) whatever session it is watching, and a question stays answerable while such a client is connected.
Changed
- The default tool set grows by the five browser tools on a machine with a browser installed, and
minidsh configlists thetool-browserrow (flagged when a layer changes it, sinceallowHostswidens what it reaches). A refused image now says that a subagent starts with a conversation of its own; the image bound is the whole conversation's until a compaction. deepseek-flashsees images, as DeepSeek now serves it, in a user message or a tool result; the retireddeepseek-v4-flashnames resolve to it and take the same facts.deepseek-v4-prostays text-only (it accepts an image and ignores it). A DeepSeek id the catalog does not know is treated as text-only with a 131,072-token window rather than the full million.- Breaking: DeepSeek refuses
temperaturewhile thinking. Thinking is on unless the reasoning effort isoff, and in thinking mode DeepSeek ignores the temperature without saying so; a request that sets one is now refused before anything is sent, naming the two ways out: effortoff, or a route to a model that honours a temperature (a recorded temperature cannot be cleared). Asettings.jsonwithagent.temperatureand no effort will see its first DeepSeek step refused. - Breaking: the model's shell no longer sees
OPENAI_API_KEY. The OpenAI adapter is mounted by default, which makes its key one of the harness's own credentials, withheld from every shell command like the DeepSeek and Anthropic keys. A repository script that read it through MiniDSH's shell needs it passed another way. - A log written by this version may carry a consent subject 1.1.0 does not know (a web search's): 1.1.0's
sessions verifyreports such a log invalid rather than misreading it, and 1.1.0 will not resume it; 1.0.0, which records no subjects, ignores it. A homecomposition.jsonthat mounts web search stops 1.1.0 before it reads anything. - A key no HTTP header can carry (a stray line break, a NUL) is refused by its name before any request, for every provider and for web search: the platform's own error for it quoted the value.
- The consent line shows invisible characters escaped — zero-width and format characters, bidi controls, the Unicode tag block, private-use code points — in a shell command as in a web query, so what a person approves is every character that runs or leaves.
- A one-shot run stops what it started.
minidsh run(and a delegated child) stops a job still running when its task ends, records it, and says so on stderr; the exit code is unchanged. - On Windows a process is killed with its tree (
taskkill /T): a timed-out or cancelled command's children no longer outlive it. - PowerShell one-shot commands write UTF-8, as the persistent shell always did: on a host whose console code page is not UTF-8 their non-ASCII output arrived garbled.
- The Anthropic catalog follows Anthropic's own model listing (2026-10-25), and a live drift probe now holds it there, as the DeepSeek and OpenAI ones already were. The 5.5 models have rows of their own instead of their predecessors'. Effort
offis refused where the model cannot turn thinking off (Opus 5.5, Sonnet 5.5, Fable 5 and 5.1). The 4.6–4.8 models are asked to think at a named effort (Opus 4.8, measured, did not think without it); Opus 4.5 thinks on a budget beside its effort. Sonnet 4.5's window is 200K. A temperature beside thinking is refused before anything is sent, since the API refuses it. An id the catalog does not know gets no output cap of ours. - DeepSeek errors are classified by their HTTP status first: a 5xx is retried as a server error even when its text mentions "context"; DeepSeek running out of capacity mid-stream is retried; its content filter ends the turn as a refusal.
llm-retrygives up on a provider that asks for a long wait: aretry-afterpastmaxRetryAfterMs(default 60 s) ends the retries instead of holding the turn, and the failure says how long the provider asked for.- The editor reads big files in part.
viewof a file over 8 MiB shows its first 8 MiB and says how to read the rest with the shell;str_replaceandinsertrefuse such a file the same way; an emptyold_stris refused. Reading or writing a FIFO or a device is refused, never waited on. - A resume or fork composes the world its session was created in: under another agent preset it is refused, and over the wire (
serve,web) an explicit--sandbox,--approvalor--accepton the host now applies to a resumed session as it did on the CLI. minidsh configwarns about more: a provider row a layer changed (itsbaseURLdecides where every conversation and its key go) and any plugin loaded from a module path.- **The office helper st...
minidsh 1.1.0
The record and authority planes, built across three sessions, reviewed as one system and released: durable execution you can read cold, consent that says what will run, and a shell that runs on every platform under an honest boundary.
Added
- Read a stored session without resuming it.
minidsh sessions verify <id>says whether a log is intact —ok,interrupted(a crash a resume will close) andtornexit 0;damaged,invalid(a rule the runtime holds every write to is broken) and a newer, unreadable format exit 1 — andsessions inspect <id>reports what each part of the log was written under, the authority it ends under, undecided approvals, queued input, children, cost, and exactly what a resume would append. Neither takes the session's lock nor writes a byte, so both are safe on a log another process holds, and such a log reads as in flux rather than crashed.--jsonon each. - Salvage a damaged session.
minidsh fork <id> --salvagebranches a log whose bytes are unreadable past some point from what is still readable, leaving the original untouched; every tool call it cannot account for is marked outcome-unknown, the fork records where its source stopped, and the command says so on stderr, because damage between turns leaves the model nothing to see. - The audit shows what calls did.
sessions show --auditnow lists each file write and shell command the providers recorded (path and hash, mode, enforcement, exit status), each call whose outcome was lost with a crash, and, for a crashed session nobody has resumed, what a resume would record — marked as such, and never for a session another process is still running. - An approval says what the runtime will do, not what the model said about it. The line a person answers now carries a subject the harness builds from the validated call arguments — the command, and the mode and enforcement it would run under — plus the whole call as the log recorded it, up to a bound past which the surfaces refuse the shortcut and point at
sessions show <id> --jsonrather than hiding a command's tail. The model's justification sits beside that, never in place of it. Control characters in a subject are escaped rather than flattened, so two different commands can never render as one line. - A yes can outlive one call without outliving the run. Where the host offers it,
ain the terminal (or the browser's button) extends a one-shot approval to that exact action — same tool, same command, same authority — for the rest of that run of the session. It is a durable event, it is offered by the runtime rather than invented by a surface, it dies the moment any authority knob moves or the run ends (a resume or a fork asks again, once), and/grantsand/revoke <id>list and withdraw it. A near-miss asks again: this is not a policy language. - A session can accept the enforcement its host can actually deliver.
--accept none(or/accept none, or the browser's control, orsession/authority) records that this session will run a shell command a host cannot confine — under its own sandbox mode, with the in-process file fence intact. On Windows, which has no confinement backend, that replaces paying adanger-full-accessescalation per command, which used to drop the file fence as well. It is inert wherever a backend exists, it applies only to the mode it was given for, and a delegated child inherits it as a pin it cannot change. - Decisions record who made them: policy, a standing consent (and which one), a person, or an automatic answerer.
sessions show --auditand both clients print it. - An unattended run can approve exactly what a deployment declared.
approval-headlesstakes anallowlist of exact subjects, answeredauto— a middle rung between--approve(all of them) and the fail-closed default (none). - Crash repair closes every bracket the log left open (from the durable-execution work that preceded this): an interrupted delegation, an interrupted compaction, and the tool calls of an interrupted step, with a durable fact recorded between a tool's approval gate and its body so repair can tell "never started" from "outcome unknown". Effects that land — file writes and shell commands — are recorded by the provider that caused them, after the fact.
Security
--acceptonserve,webandchatnow does something. It was accepted, advertised and dropped before reaching the sandbox, so wire-hosted sessions kept refusing. It now applies, and a weakened acceptance is written into the log of every session it opens, for every mode a command can be confined under, so a stored session says what it accepted (a line, orfullby its absence), a resume keeps it, and an approved escalation never runs under one the log does not name. A delegated child's acceptance applies to the mode it was delegated for; any mode it narrows into is strict.- A shell refusal is on the record as a refusal. On a host that cannot confine the shell, an unescalated command's refusal is now a coded error result (
SANDBOX_UNAVAILABLE, same words) instead of a successful one, so the audit and every surface show it as refused. - A shell child no longer inherits this deployment's provider keys. The harness builds the child's environment instead of passing its own through, withholding every credential name a provider row declared (including one a config file renamed; the list is read at every spawn) and every
MINIDSH_*— and nothing for merely looking like a secret: aGOOGLE_APPLICATION_CREDENTIALSor an API key you set for your own tools is yours and reaches your shell. On Windows the names are compared the way the environment compares them. This is defence in depth, not a boundary: reads are still unfenced, so a credentials file remains readable, and any secret the deployment did not declare passes through. - Measured: a confined shell writes through a hard link that already exists in the workspace, because the operating system confines paths; the documents had said a confined host was unaffected. Under bubblewrap and under Seatbelt alike (a test in
pnpm checknow measures both), and neither lets a confined command create such a link across the workspace boundary, nor write an outside file by its outside path because it also has a workspace name. - The terminal neutralizes the streamed answer. Every line the terminal printed went through the control-character filter except the one a person reads most, the model's own streamed text; an escape sequence in it could repaint the line above the next
[y/N]. It is filtered like the rest, and the log is untouched. - A client can no longer answer an approval in a session it does not watch.
approval/answernow applies the same visibility rule that decides which connections are asked in the first place.
Fixed
- A detached session refuses appends. After a session was detached, an append still succeeded in memory while persistence had already closed its file and dropped the event without an error: the log in memory and the log on disk could part ways silently. The store now closes the session before
session/disposed, and a later append throwsSESSION_CLOSED. - The browser shows every event the terminal shows. The browser's event projection was an untested hand-copy of the terminal's and had drifted: a step's effective route (
request/context) and a delegated child's route never appeared in the browser. The projection is now a typed, DOM-free module (web/rows.js) that a test holds to the terminal's visibility, kind by kind. resume <id> --jsonandfork <id> --jsonwithout--headlessare refused instead of printing the interactive terminal where a script expected frames.- A content-less DeepSeek stream that named no finish reason ended as an empty message the retry policy never saw; it is
EMPTY_RESPONSE, and retried, like the same stream with one. sessions verifyandinspecton an odd log. A malformed salvage claim passedverifyand crashedinspect; the claim is now held to its shape at every append. A log whose only unfinished thing is a compaction bracket (an ordinary quit mid-/compact) is described as an open bracket, not as a crash.sessions show --auditwould list an escalation refused past a delegation ceiling with the other authority denials (no shipped path produces one: a delegated child's approval pin refuses the ask first).
Changed
- A checkpoint is on disk. The session log is
fdatasynced at every durability checkpoint (and a new log's directory entry, on Linux and macOS), so crash repair can tell a call that never passed its approval gate from one that may have run even after a power cut. Measured cost per checkpoint: 0.7–3.6 ms (median) on Windows NTFS, 2.4–10 ms under WSL 2, varying with host load; a tool call pays up to two. A flush never reports a write synced that no sync covered, and a torn tail is never truncated unless its sidecar copy is complete. - Forking a session another process is still running answers every tool call it left open as outcome-unknown, never "not started": that process may still run it.
- Each part of a log says what wrote it. Every new, resumed or forked session opens its segment with a record of what its writer guaranteed, and the composition record names the build (
minidsh 1.1.0); crash repair trusts only those claims, so logs from 1.0.0 are still read and repaired, conservatively, and 1.0.0 reads a 1.1.0 log (checked against the published package). The session format's rule is written down: the header's version is the only format mark, and a malformed line is damage, not a newer format. - The default model is
deepseek-flash, the id DeepSeek lists.deepseek-v4-flash, the 1.0.0 default, is unlisted but still accepted and served as the same model, so a stored session or a setting naming it keeps working; the log records the id that was...
MiniDSH 1.0.0
Minimal surface. Complete architecture.
MiniDSH 1.0.0 is the first public release: the smallest coding-agent harness a developer can install, point at a repository, and use daily without reading the architecture — and a reference architecture small enough to read in a sitting. It studies DeepSeek Harness as an architecture textbook and re-derives from it the minimum system that keeps the properties that matter. It is an independent educational and engineering project, not affiliated with DeepSeek.
npm install -g minidsh # Node ≥ 24; DEEPSEEK_API_KEY or ANTHROPIC_API_KEY in the environment
minidsh chat --cwd path/to/repoWhat ships
- One runtime, three ways in.
minidsh run(headless),minidsh chat(terminal) andminidsh web(browser), plusminidsh serve, a newline-delimited JSON-RPC host on stdio. The terminal and the browser are protocol clients that hold no semantics of their own. - The session log as the only truth. An append-only JSONL log with twenty-seven event kinds; resume and fork from any stored log; crash repair that closes an interrupted turn; a single-writer lease; and a runtime invariant that what the model sees is exactly what the log derives.
- Authority as a durable plane. Sandbox modes, an approval policy and named presets, every switch and decision an event. File writes are fenced inside the filesystem provider; shell commands are confined by bubblewrap on Linux and Seatbelt on macOS, each probed before it is claimed, with what the host delivered recorded on every session's opening stamp. Delegated children open under a ceiling they cannot widen.
minidsh sessions show <id> --auditreads the whole plane back. - Two providers, one vocabulary. DeepSeek and Anthropic adapters over a provider-neutral stream; the route is a durable fact a session can change mid-conversation, and a
model-rolesrow sends a purpose (a compaction summary, a delegated child, a vision verifier) down a different route. - Context that manages itself without losing anything. A pure meter over the log, compaction that replaces a range while the shadowed events stay, bounded recall of what was shadowed, spill for oversized output,
AGENTS.mdas context. - Composition from disk. Thirty-five built-in plugin rows layered by
~/.minidsh/composition.jsonand--patchfiles, with per-row provenance and a composition stamp in every session.
Verification behind this tag
pnpm check(typecheck, lint, the dependency gate, 676 tests) green on Ubuntu, macOS and Windows in CI, each followed by packing the tarball, installing it into an empty directory and starting the installed binary.- The eight live end-to-end arcs against the real providers, run three times on Windows and three times on Linux under bubblewrap before the tag;
live.ymlgreen on Ubuntu (bubblewrap) and macOS (Seatbelt), both driving a real task through the installed package. - The published tarball installed into an empty directory and driven through a real task.
Known limitations
The full register is ARCHITECTURE.md §13. The ones most likely to matter first: Windows has no shell confinement backend, so every command there asks; confinement bounds file effects only, not the network or the environment; the filesystem fence cannot follow hard links; tool execution is sequential and delegation is foreground.