@xingular/harness 0.1.7 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 2.1.0 - 2026-10-19
+
+- Add per-request plan mode to SDK session runs: instructions arrive as a dynamic context update, and the tool gate refuses calls outside the read-only set. The terminal uses `/plan`, `/plan on`, and `/plan off` to narrow its active tools.
+- Add bounded, UTF-8-safe Hub payload previews, explicit installed/changed/incomplete receipt states, and receipt-scoped uninstall that removes owned resources, including local edits within those paths.
+- Highlight recognized leading slash commands in the terminal composer with the selected theme's link color, including enabled `/skill:name` invocations; unknown commands remain plain.
+
+## 2.0.0 - 2026-10-18
+
+- Let a connected app sign in with an OAuth client the application registered itself (`oauthClient: 'app'`), supplied through `HarnessOptions.oauthClients` and never stored; `connections.appClients` reports which catalog entries a build can sign in for. See [ADR-0005](docs/decisions/ADR-0005-app-provided-oauth-clients.md).
+- Invoke a skill in the terminal as `$name` instead of `/skill:name`: the completion offers the loaded skills at a `$`, and a leading `$name` is sent to the model as that skill. A typed `/skill:name` still works, and `$` followed by a number or an unknown name stays ordinary text.
+- Keep a stored key or sign-in when a terminal that began before it was saved ends, and let several terminals of one account share its auth.json across processes: a terminal saves only what its own Pi changed, and the last terminal out removes the file.
+- Give every session bounded `trajectory_search` and `trajectory_read` tools for inspecting recorded run events without exposing credentials, attachments, or provider reasoning.
+- Show terminal notices, such as mode changes, errors and the keyboard list, as rows in the conversation instead of above the composer; queued messages stay in the dock.
+- Step the terminal's thinking effort with Shift+Up and Shift+Down within the levels the model supports. Shift+Tab toggles a read-only plan mode that withdraws changing tools until it is switched back.
+- Show the product lockup above the terminal transcript only until the chat has a user message; a resumed session with history starts without it, and a header from a trusted extension is never hidden.
+- Keep the terminal composer on the last rows in fullscreen while the transcript scrolls above it; `tuiMode: regular` keeps the flowing layout, and leaving fullscreen copies the conversation into scrollback.
+- Add one native asynchronous subagent service for SDK, RPC and standalone terminal callers, with selective waits, parent joins, typed history receipts and explicit-resume recovery.
+- Preserve capability ceilings and route child approvals/questions through the owning terminal; release pending interactions before SDK abort.
+- Show a stable rotating work verb with an animated status glyph and keep the completion duration until the next turn.
+
 - Harness owns the standalone terminal frontend, using persistent Pi 1.2.0 sessions and the inspected Oh My Pi 18.11.3 presentation.
 - Add titanium and light themes, native session navigation, local command help and completion, account/plugin/Hub controls, and trusted extension UI hosting.
 - Keep account isolation, exact prepared context and resource selection, the final tool gate, native histories and Harness run recording.

package/README.md

@@ -8,7 +8,7 @@ needs to work for someone over time, and nothing about any particular applicatio
 | Accounts | `src/accounts/` | Several isolated Pi accounts and pools, sign-in, model lists, health and limits. A session keeps the account it started with. |
 | Sessions | `src/sessions/` | Pi SDK turns, run records and `events.jsonl`, interrupt, approvals, questions, recovery after a crash. |
 | Prompt | `src/prompt/` | The system prompt compiled from sections with budgets and profiles; a stable prefix, and changing state delivered as updates in native history. |
-| Memory | `src/memory/` | The Wiki: pages, facts, memory blocks, revisions, proposals with an evidence gate, undo, an Inbox, recall over past runs, and sleep-time consolidation. |
+| Memory | `src/memory/` | The Wiki: pages, facts, memory blocks, revisions, proposals with an evidence gate, undo, an Inbox, history recall, run trajectory inspection, and sleep-time consolidation. |
 | Skills | `src/skills/` | Skills, prompts, and rules: a person's own in the data root, and built-in ones shipped with the harness or the application. |
 | Plugins | `src/plugins/` | What a Pi session loads, chosen by the harness and never by Pi's own discovery; trust for a working folder's code; the list of every plugin and what reaches one caller. |
 | Tools | `src/tools/` | Tool definitions, the memory tools, `ask_user`; a gate that asks the application's policy, then standing approvals, then the person. |
@@ -21,11 +21,23 @@ The [documentation index](docs/README.md) links current terminal architecture an
 
 ### Session options for applications
 
-- `subagents: { maxDepth }` offers `spawn_subagent`: the model may start a child run of the same caller (`relation: 'subagent'`). The child has no more tools than the parent and settles before the tool returns.
+- Interactive sessions offer `spawn_subagent` and `wait_subagents` by default. `subagents: null` disables them; `{ maxDepth }` configures native nesting (default one, maximum three), independently of the host caller depth. Unattended sessions remain disabled unless the host explicitly supplies subagent options. A frozen capability set can narrow these tools further.
+- `harness.subagents.spawn({ parentRunId, brief, tools?, wait? })` opens a fresh child of the same caller with no wider capabilities. It returns `{ runId, nativeSessionId }` once open; `wait: true` also waits for settlement. `harness.subagents.wait({ parentRunId, runIds? })` joins selected direct children, or the current children when omitted, and returns their outcomes. `results` reads the same bounded outcome records without waiting. RPC exposes `subagents.spawn`, `subagents.wait`, and `subagents.results`; `sessions.spawnSubagent` remains a compatibility alias.
+- The model's `spawn_subagent` returns immediately by default; `wait: true` returns an inline result. `wait_subagents` joins selected children. The SDK and standalone terminal share this execution service. Terminal calls use its private control channel, including when connected apps are disabled.
+- Parents receive results at native turn boundaries and join outstanding children before completing. Typed native-history receipts prevent duplicate automatic delivery; explicit waits can reread results. Ownership is recorded before startup so an explicit resume can recover even a lost spawn return. Startup reservations without a run become interrupted outcomes. A restarted Harness never restarts model work automatically. Recovery requires the same recorded account, caller, working folder, and selected history branch. Session IDs are opaque; consumers follow `parentRunId` and `relation`.
 - `providers: false` runs a session with the harness's own tools only.
-- On the caller, `vaultAccess: 'propose'` writes no memory directly, and `recallExcludeAgents` hides those agents' conversations from recall.
+- On the caller, `vaultAccess: 'propose'` writes no memory directly, and `recallExcludeAgents` hides those agents' conversations from history and trajectory tools.
 - `maintenanceRunTrigger: false` (a harness option) leaves memory to explicit proposals and scheduled merges.
 
+Every session also gets `trajectory_search` and `trajectory_read` from the built-in History plugin.
+Search lists runs in the current data root, including active runs, with filters and a continuation
+cursor. Read returns pages of the canonical execution events, including captured prompt/context,
+tool, decision, retry, compaction, and usage evidence. Active runs show the latest events saved so
+far; settled reads stop at the first outcome. Payloads are bounded and marked when truncated, and
+the tools omit account identifiers, credential fields, attachment bytes, native adapter payloads,
+and provider reasoning text or summaries.
+They report recorded evidence without scoring runs, and do not backfill older records.
+
 ## Using it from Node
 
 ```ts
@@ -256,8 +268,8 @@ again to load the new frontend. A package version alone cannot distinguish an un
 build from an older installed build with the same version.
 
 This opens the Harness-owned terminal frontend in the current working directory. Its
-presentation follows the inspected Oh My Pi 18.11.3 titanium and light palettes, centered welcome, filled
-status band and curved `╰─` prompt, with Harness identity and existing capabilities. Harness
+presentation follows the inspected Oh My Pi 18.11.3 titanium and light palettes, centered welcome,
+colored text statusline and curved `╰─` prompt, with Harness identity and existing capabilities. Harness
 owns screen composition, editing/input dispatch, scrolling, command routing and plugin UI;
 Pi supplies the persistent execution runtime, native history and rich content components.
 The existing isolated account, compiled context, approval gate, telemetry and Wiki/socket
@@ -266,7 +278,10 @@ commands remain behind the terminal. No Pi `InteractiveMode` is constructed.
 `/resume` stays inside the prepared history and working folder; `/import` accepts an explicitly
 selected native JSONL file only for the same working folder. Cancel an active response before
 changing or reloading a session. Full OMP visual parity is not established by the current
-verification. See [terminal architecture and evidence](docs/terminal-tui.md),
+verification. `/permissions` reviews device-local Pi terminal grants and the Full Permission switch;
+tool grants apply across terminal sessions sharing this Harness state, and Full Permission requires
+confirmation. `/trajectory` opens recorded runs for the current native conversation, with event
+navigation and a detail inspector. See [terminal architecture and evidence](docs/terminal-tui.md),
 [the decision](docs/decisions/ADR-0001-owned-terminal.md), and [third-party notices](NOTICE.md).
 
 ### `/accounts` in the terminal
@@ -295,7 +310,7 @@ command. The explicit `terminal` command is an alias for the default launch. Use
   wiki/             home.md, library/, projects/<slug>/, facts/, blocks/, revisions, inbox, log
   registry/         skills/, prompts/, rules/   (a person's own; never copied)
   plugins/<name>/   packages kept with a person's data; each is found as an installed plugin
-  runs/<id>/        run.json, events.jsonl, context.json, caller.json
+  runs/<id>/        run.json, events.jsonl, context.json, caller.json, subagents.json (reserved child IDs)
   config/           context profiles, what is switched on for whom (plugin-attachments.json),
                     settings the harness reads
   index.sqlite      a rebuildable index of Wiki entries and runs (FTS5)
@@ -309,6 +324,7 @@ command. The explicit `terminal` command is an alias for the default launch. Use
   plugin-hooks.json       what each hooks file listens for and how its last run went
   connections.json  connected apps (secrets are in the SecretStore)
   run/              the session socket and the terminal commands
+  harness.log       diagnostics from the standalone terminal, kept off its screen
 ```
 
 The files are the source of truth; `index.sqlite` can be deleted and rebuilt
@@ -332,14 +348,18 @@ Node 22.19 or newer.
 `xingular-harness hub list [--refresh]`, `hub show publisher/name@version`, and
 `hub install publisher/name@version` browse and install exact catalog versions. `/hub` offers the
 same review in the interactive terminal, using its private control key for installation. Both the
-terminal and embedding applications use `hub.list`, `hub.get`, `hub.install`, and `hub.readDocument`.
-`hub.get { id, version, preview: true }` verifies data payload bytes without installing them.
+terminal and embedding applications use `hub.list`, `hub.get`, `hub.preview`, `hub.install`,
+`hub.uninstall`, and `hub.readDocument`. `hub.get { id, version, preview: true }` verifies data
+payload bytes without installing them. `hub.preview { id, version, offset }` returns bounded,
+UTF-8-safe pages of up to 16 KiB from a verified payload.
 
 Registry bundles import complete skills or single Markdown prompts/rules, disabled. Pi packages
 reuse the existing installer and require an exact npm version or full GitHub commit. Documents
 are saved as inert JSON for a compatible host to interpret; the harness does not apply them.
 Installation grants no attachment, trust, credentials, or permission. Writes are serialized and
-existing registry files are never overwritten.
+existing registry files are never overwritten. Receipts report whether their resources are intact;
+uninstall removes only the exact receipt's resources, including local edits within those paths, and
+revokes its attachment choices.
 
 Installed documents and provenance live under `<data root>/hub/`; the catalog cache is
 `<state dir>/hub/catalog.json`. An offline snapshot ships with the package. Explicit refresh keeps
@@ -358,9 +378,12 @@ An embedding application may set `externalMaintenance: true`, supply trusted `Ca
 `vaultAccess` (`self` or `curator`), and register `maintenanceTools`/`MAINTENANCE_PLUGIN`.
 Self callers directly edit only their own writable persona/notes; shared knowledge and text-resource
 writes become persistent proposals. Curator tools read original evidence, compare captured target
-revisions, apply reviewed changes, persist receipts and undo without overwriting later edits.
+revisions, read all host-assigned requests together, and apply reconciled Wiki proposals as one
+undoable change set. Resource proposals keep their own receipts; executable proposals remain inert
+until the user reviews/trusts them. Later user edits are never overwritten.
 `maintenance.list`, `maintenance.review` and `maintenance.retry` let the host dispatch its own
 recorded sessions. Curator runs do not recursively queue maintenance. Optional assigned IDs freeze
 which requests a batch may claim. These fields are trusted host context, never model arguments.
-Executable proposals remain inert until the user reviews/trusts them. Standalone callers that omit
-this option retain the existing lifecycle and direct-write contract.
+`maintenance_read_batch` reads those assigned requests together; `maintenance_apply_batch` records
+one decision for each and applies the evidence-checked Wiki set atomically. Standalone callers that
+omit this option retain the existing lifecycle and direct-write contract.