@xingular/harness 1.3.1-unstable.5 → 1.3.1-unstable.9

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 ## Unreleased
 
+- **A completion check replaces `finish` (ADR-0071).**
+  - **The check.** When a reply that did work ends with its todo list closed or absent, the run's
+    own model, at low effort and with a fresh context, judges the person's request against what the
+    reply did: `done`, `continue` (the reply is sent back with the reason and next step), or
+    `needs_person`. The request is the goal; there is no `/goal` command.
+  - **Shared cap.** It shares the stop gate's cap of three nudges per reply and its no-progress rule.
+  - **Usage and failure.** Its request counts in the run's usage, and any failure leaves the reply
+    as it was.
+  - **`finish` is removed.** A live GPT 6 Luna run used `needs_decision` after 23 seconds to ask
+    something the handoff already answered. Only the check can now decide that the person is needed.
+  - **Prompt.** The `role` paragraph names which decisions are the agent's own, says a document the
+    request points to is the request, and says a question the request or files already answer is not
+    a question for the person. Its budget rises from 1,500 to 2,200 characters, so it fits uncut with
+    the subagent paragraph.
+  - **Kill switches.** `XINGULAR_STOP_GATE=off` and `XINGULAR_COMPLETION_CHECK=off` at launch switch a
+    layer off, for experiments.
+- **The model is told it has `edit` and `write`.** Pi's `createEditTool` and `createWriteTool` drop
+  the definition's prompt line and guidelines, and Pi lists only tools with a prompt line, so every
+  terminal and headless run's system prompt named only `read` and `bash`. Models edited files
+  through shell scripts instead: one 2-hour terminal run made 156 script edits (14 failed) and no
+  `edit` call. `createWorkspaceFileTools` now restores the prompt line and guidelines, as Pi's own
+  `createBashTool` does, for both the terminal and the runner. The stable prefix changes once.
+- **A plan no longer leaks its tools into normal mode.** A terminal plan request narrows the active
+  tools, and Pi records the restored normal set only with the next request. A rebuild before then
+  (a new runtime, resume, switch, fork or tree navigation) replayed the plan set, so normal work ran
+  without `edit`, `write`, browser and connected-app tools. One recorded session implemented a whole
+  plan that way. The terminal now marks each plan request in the session and restores the normal
+  set after any rebuild.
+- **Terminal replies continue across work slices (ADR-0070).** A terminal reply that reaches its
+  320-call or 60-minute budget after doing work now continues in place as the next slice, with a
+  checkpoint and a notice, up to 8 slices, instead of waiting for "continue" and re-sending the
+  whole context uncached. Fruitless, blocked, failed, aborted and plan slices still stop.
+  `XINGULAR_WORK_SLICE` also accepts key=value pairs such as `maxToolCalls=15,maxSlices=3`.
+- **One copy of each credential: no more `invalid_grant` from terminals.** A terminal's Pi kept the
+  account's tokens in `auth.json` under its own lock while the host, its subagents and usage probes
+  refreshed the same token in the Keychain under another, and `terminalEnd` copied the file back
+  over whatever the Keychain held. OpenAI rotates refresh tokens, so whichever side refreshed second
+  failed with `invalid_grant` and the account needed a new sign-in. A terminal now reads and refreshes
+  through the host store (`accounts.credentials.*`, INV-ACC-5), holding its lock for the refresh. An
+  `auth.json` left by an older terminal is folded in, newest token first.
+- **A stalled terminal reply is recorded as `stalled`.** Pi's abort reports back through
+  `terminal.interrupt` like a person's Esc, which closed the run as `user_abort` before the reply
+  settled as `stalled`; one silent 15-minute hang was recorded as the person's abort. The interrupt
+  now carries the stall. An interrupt also ends a settling reply's wait for its subagents.
+
+- **A reply can no longer quietly stop with work open (ADR-0069).**
+  - **Stop gate.** In attended top-level runs, terminal included, a reply that ends while its todo
+    list has open items is sent back to the model, naming the items, up to three times per reply,
+    and never after a nudge that produced no work.
+  - **`finish`.** Added here as the one explicit way to stop with work open; removed again by ADR-0071
+    above.
+  - **Honest stop codes.** Such a reply settles `interrupted` with the new stop codes `needs_person`
+    or `unfinished`, never `completed`, with a checkpoint the harness writes from the todo list,
+    files and checks.
+  - **`checkpoint_write` is removed.** A run used it as a sign-off and stopped with work open. At a
+    work-slice budget the harness now writes the checkpoint itself.
+  - **One budget per reply.** The work-slice budget now covers the whole reply: Pi's own
+    continuations (nudges, delivered subagent results, plan repair) no longer reset it.
+  - **Prompt wording.** The texts that read as permission to stop were rewritten: the todo guidance's
+    "final update before your final reply", and `## What would make this complete` "when the run
+    could be more complete".
+  - **Subagents.** `spawn_subagent` now returns the child's tools, and the read-only profiles say up
+    front when a brief needs a tool they lack.
+  - **Hosts.** Accept the two new stop codes and offer Continue for them.
+  - **Restart required.** A live terminal session keeps the code it started with, so restart it to
+    get the gate.
+- Do the job the request implies, and report it apart from the request. A standard session's role
+  paragraph now sets the scope of the work — the obvious adjacent step, what the work itself exposes,
+  the check it needs, inside the working folder and away from what a person must decide (a deploy, a
+  secret, remote data, money), without asking first inside those bounds — and the reporting guidance
+  requires two headings when they apply: `## Beyond what you asked` and
+  `## What would make this complete` (ADR-0068). The reporting budget rises from 2,000 to 2,400
+  characters so both fit uncut. All of it is stable-prefix text, so the cached prefix changes once
+  per session.
+- Say in the prompt when a reply may end. The standard session's role paragraph, the opening of the
+  reporting guidance and the todo guidance now say that an open todo item, a passing check or a
+  partial result is not a reason to end the turn, and name the reasons that are: the request is done,
+  the work-slice guard hands the reply back, a person's decision is needed, or the person interrupts.
+  ADR-0069 below now enforces it in the runner. A sweep of 822 runs in seven days found 207 that ended with work left
+  (137 within 30 tool calls, median 17, and 191 with no checkpoint), which is what the wording is
+  for. All three texts are in the stable prefix, so this changes the cached prefix once.
+- Reword the final-reply guidance so the outcome leads and structure follows what the answer needs. The
+  reporting guidance is part of every request's stable prefix, so this changes the cached prefix.
+- Keep the provider cache working after a compaction (ADR-0067). The compaction checkpoint now arms only
+  for a compaction during the running reply, is built once, and sits right after the summary instead
+  of being rebuilt at the end of every request. A request after a compaction is again the previous
+  request plus new items, so Codex WebSocket continuation and prefix caching apply. Before, every later
+  turn of a compacted session resent its whole context: one measured session fell from 94–99% to
+  18–24% cache hits after its first compaction.
+- Flag a low prompt-cache hit rate in the terminal's composer status bar. `R<percentage>%` now covers the
+  last 10 model responses instead of the whole session (`recentCacheUsage`, `CACHE_HIT_WINDOW`), and
+  gets a yellow `⚠` below 70 percent and a red one below 40 percent. Each drop to a worse level posts
+  one transcript notice. A window of one response, or one with no cache reads or writes, is not judged
+  (`cacheHitLevel`, `CACHE_HIT_WARNING_PERCENT`, `CACHE_HIT_CRITICAL_PERCENT`).
+
+- Refine a variant from the terminal and keep checkpoints of it (PROP-0052, ADR-0065, ADR-0066).
+  `/refine [what to look at]` replays the latest request typed in this chat from a snapshot of the
+  folder as that turn found it, in throwaway shared clones, after a confirmation that shows the run
+  count and models; it runs in the background, and `/refine review` shows every candidate's changes
+  and output and adopts any of them. Guidance reaches improvers and composers only, never the blind
+  selector. Task runs default to this chat's model; `--model` sets the improver's, and an adopted
+  version records the model it was tuned on. `/variant` switches this conversation to another
+  version at the next turn (resuming the same conversation), restores, compares, tags, and takes
+  single components back from an earlier version. New methods: `refine.fromRun`,
+  `refine.candidateDiff`, `refine.candidateOutput`, `variants.tag|untag|tags|resolve|revert`. Run
+  records gain `workspaceSnapshot`, version records `tunedFor`, and scopes `tags.json`.
+
+- Start a conversation this account cannot use on the account's newest selection. A resumed
+  conversation keeps its model while the account offers it and holds its provider's credentials;
+  otherwise the terminal starts it on the mode's choice, then normal's, then the newest selection in
+  any mode, with that selection's effort, writes the model change into the conversation, and says in
+  one notice which model it replaced. A fallback is never saved as the person's choice, and with no
+  usable saved model Pi's own fallback message stands (ADR-0064).
+
+- Make unfinished-work handoffs actionable: the stable reporting guidance now names the person’s
+  concrete decision or the next action and its owner for each material blocker, without imposing a
+  fixed heading (PROP-0051, ADR-0063).
+
+- Share the account sign-in between `npm run dev` and the installed `xagent`. A standalone launch
+  can now take its account identity from another state directory with `--account-state <dir>`
+  (`HarnessOptions.accountsDir` plus that state's `secrets.json`), and `npm run dev` passes the
+  installed one, so one provider sign-in serves both while development keeps its own data,
+  approvals and plugin trust (ADR-0062).
+
 - Require owner-prefixed plugin commands on terminal and structured sessions. Plugin-owned prompt
   templates join extension commands under `/<owner-prefix>:<name>`, with no bare plugin aliases.
   A package can select a root template with `harness.defaultPrompt`; owner and route collisions fail

package/README.md

@@ -294,11 +294,13 @@ npm run dev
 
 `npm run dev` rebuilds the CLI and opens the Harness terminal in the current working directory.
 It uses separate development directories by default: `~/.xingular-harness-dev/data` and
-`~/.xingular-harness-dev/state`. This keeps development harness data and device settings—including
-accounts, Pi settings, approvals, and connections—separate from the installed command. Press
-`/quit`, Ctrl+C or Ctrl+D to close it. Override either directory with `--data <dir>` or
-`--state <dir>`; for example: `npm run dev -- --data <dir> --state <dir>`. An omitted option keeps
-its development specific default.
+`~/.xingular-harness-dev/state`, so development harness data, approvals, plugin trust and
+connections stay separate from the installed command. It signs in as the installed command's
+accounts, though: one provider sign-in serves both launches. Press `/quit`, Ctrl+C or Ctrl+D to
+close it. Override either directory with `--data <dir>` or `--state <dir>`; choose the accounts a
+launch signs in as with `--account-state <dir>`, for example
+`npm run dev -- --account-state ~/.xingular-harness-dev/state` for a fully separate identity. An
+omitted option keeps its development specific default.
 
 The OpenTUI/Solid frontend is the only terminal. Install Bun 1.3.14 or newer and run
 `npm run build:tui` (or `npm run build`); without Bun the build fails rather than producing a
@@ -404,10 +406,13 @@ still be removed; that session then asks for another account the next time it st
 The installed standalone command defaults to `~/.xingular-harness/data` and
 `~/.xingular-harness/state`; `npm run dev` instead defaults to the separate
 `~/.xingular-harness-dev/data` and `~/.xingular-harness-dev/state`. Override either with
-`--data <dir>` and `--state <dir>`. Session history is stored per working directory and can be
-reopened with the terminal's `/resume` command. The explicit `terminal` command is an alias for
-the default launch. Use `--help` to see the commands; `serve` remains the host-facing RPC service
-for integrations such as Xingular Agent/App.
+`--data <dir>` and `--state <dir>`. A launch signs in as the accounts kept in the state directory
+it uses; `--account-state <dir>` takes them from another state directory instead (its `accounts`
+folder and its `secrets.json`), which is how `npm run dev` reaches the installed command's sign-in.
+Session history is stored per working directory and can be reopened with the terminal's `/resume`
+command. The explicit `terminal` command is an alias for the default launch. Use `--help` to see
+the commands; `serve` remains the host-facing RPC service for integrations such as Xingular
+Agent/App.
 
 ## Storage