@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +82 -0
- package/README.md +1 -1
- package/dist/cli.js +3680 -1947
- package/dist/sdk/cli.js +2 -0
- package/dist/sdk/commands/registry.d.ts +15 -0
- package/dist/sdk/commands/registry.js +2 -0
- package/dist/sdk/computer/screenshot.d.ts +32 -0
- package/dist/sdk/computer/screenshot.js +35 -0
- package/dist/sdk/context/attribution.d.ts +18 -0
- package/dist/sdk/context/attribution.js +295 -0
- package/dist/sdk/context/types.d.ts +94 -0
- package/dist/sdk/context/types.js +10 -0
- package/dist/sdk/index.d.ts +2 -1
- package/dist/sdk/index.js +2 -1
- package/dist/sdk/plugins/builtin.js +1 -0
- package/dist/sdk/prompt/compile.d.ts +42 -2
- package/dist/sdk/prompt/compile.js +87 -15
- package/dist/sdk/remote/addresses.d.ts +19 -0
- package/dist/sdk/remote/addresses.js +52 -0
- package/dist/sdk/remote/pairing.d.ts +59 -0
- package/dist/sdk/remote/pairing.js +160 -0
- package/dist/sdk/remote/seal.d.ts +28 -0
- package/dist/sdk/remote/seal.js +84 -0
- package/dist/sdk/remote/server.d.ts +28 -0
- package/dist/sdk/remote/server.js +158 -0
- package/dist/sdk/remote/service.d.ts +125 -0
- package/dist/sdk/remote/service.js +330 -0
- package/dist/sdk/remote/webClient.d.ts +4 -0
- package/dist/sdk/remote/webClient.js +444 -0
- package/dist/sdk/server/methods.js +3 -0
- package/dist/sdk/sessions/contracts.d.ts +4 -0
- package/dist/sdk/sessions/contracts.js +2 -0
- package/dist/sdk/sessions/planMode.d.ts +26 -1
- package/dist/sdk/sessions/planMode.js +48 -1
- package/dist/sdk/sessions/runner.d.ts +12 -0
- package/dist/sdk/sessions/runner.js +34 -2
- package/dist/sdk/sessions/sessions.js +1 -0
- package/dist/sdk/sessions/subagentService.d.ts +11 -1
- package/dist/sdk/sessions/subagentService.js +120 -38
- package/dist/sdk/sessions/subagents.d.ts +31 -0
- package/dist/sdk/sessions/subagents.js +45 -0
- package/dist/sdk/sessions/workSlice.d.ts +5 -9
- package/dist/sdk/sessions/workSlice.js +8 -149
- package/dist/sdk/terminal/client.d.ts +3 -1
- package/dist/sdk/terminal/client.js +15 -6
- package/dist/sdk/terminal/control.d.ts +1 -1
- package/dist/sdk/terminal/control.js +2 -2
- package/dist/sdk/terminal/controller.d.ts +22 -0
- package/dist/sdk/terminal/controller.js +104 -13
- package/dist/sdk/terminal/piExtension.js +106 -4
- package/dist/sdk/terminal/stallWatch.d.ts +13 -0
- package/dist/sdk/terminal/stallWatch.js +16 -0
- package/dist/sdk/terminal/standalone.d.ts +2 -0
- package/dist/sdk/terminal/standalone.js +9 -2
- package/dist/sdk/terminal/terminals.d.ts +14 -0
- package/dist/sdk/terminal/terminals.js +98 -2
- package/dist/sdk/terminal/tui/commandPages.d.ts +4 -1
- package/dist/sdk/terminal/tui/commandPages.js +12 -0
- package/dist/sdk/terminal/tui/commands.d.ts +3 -2
- package/dist/sdk/terminal/tui/commands.js +19 -5
- package/dist/sdk/terminal/tui/dialogs.d.ts +3 -2
- package/dist/sdk/terminal/tui/dialogs.js +4 -3
- package/dist/sdk/terminal/tui/keybindings.d.ts +1 -1
- package/dist/sdk/terminal/tui/keybindings.js +1 -1
- package/dist/sdk/terminal/tui/markdown.d.ts +16 -0
- package/dist/sdk/terminal/tui/markdown.js +55 -0
- package/dist/sdk/terminal/tui/modeChoices.d.ts +3 -2
- package/dist/sdk/terminal/tui/modeChoices.js +4 -4
- package/dist/sdk/terminal/tui/mouseReport.d.ts +30 -0
- package/dist/sdk/terminal/tui/mouseReport.js +80 -0
- package/dist/sdk/terminal/tui/pages/annotatePage.js +3 -2
- package/dist/sdk/terminal/tui/pages/browserPage.d.ts +1 -1
- package/dist/sdk/terminal/tui/pages/contextPage.d.ts +62 -0
- package/dist/sdk/terminal/tui/pages/contextPage.js +484 -0
- package/dist/sdk/terminal/tui/pages/remoteControlPage.d.ts +32 -0
- package/dist/sdk/terminal/tui/pages/remoteControlPage.js +170 -0
- package/dist/sdk/terminal/tui/pages/trajectoryPage.js +5 -4
- package/dist/sdk/terminal/tui/qr.d.ts +4 -0
- package/dist/sdk/terminal/tui/qr.js +35 -0
- package/dist/sdk/terminal/tui/runtime.js +8 -2
- package/dist/sdk/terminal/tui/search.js +3 -2
- package/dist/sdk/terminal/tui/sideQuestion.d.ts +1 -0
- package/dist/sdk/terminal/tui/sideQuestion.js +8 -3
- package/dist/sdk/terminal/tui/skillInvocation.d.ts +21 -2
- package/dist/sdk/terminal/tui/skillInvocation.js +31 -11
- package/dist/sdk/terminal/tui/status.d.ts +6 -0
- package/dist/sdk/terminal/tui/status.js +15 -1
- package/dist/sdk/terminal/tui/theme.d.ts +9 -0
- package/dist/sdk/terminal/tui/theme.js +9 -0
- package/dist/sdk/tools/defaultSkills.d.ts +19 -0
- package/dist/sdk/tools/defaultSkills.js +27 -1
- package/dist/sdk/tools/dispatch.js +8 -9
- package/dist/sdk/tools/spawnSubagent.d.ts +1 -1
- package/dist/sdk/tools/spawnSubagent.js +4 -2
- package/dist/terminal-opentui.js +1607 -492
- package/dist/terminal-pi.js +256 -144
- package/docs/README.md +1 -0
- package/docs/architecture/02-sessions-and-runs.md +55 -22
- package/docs/architecture/04-prompt.md +23 -4
- package/docs/architecture/07-tools-and-gate.md +4 -2
- package/docs/architecture/10-server-protocol.md +24 -0
- package/docs/architecture/11-terminal.md +52 -10
- package/docs/architecture/12-storage.md +5 -2
- package/docs/architecture/13-world-tools.md +17 -3
- package/docs/architecture/14-surfaces-and-parity.md +7 -3
- package/docs/architecture/15-remote-control.md +118 -0
- package/docs/architecture/README.md +3 -0
- package/docs/architecture/proposals/PROP-0049-context-attribution.md +409 -0
- package/docs/architecture/proposals/README.md +2 -1
- package/docs/decisions/ADR-0039-progress-aware-stall-guards.md +4 -0
- package/docs/decisions/ADR-0048-required-skills-from-a-message.md +42 -0
- package/docs/decisions/ADR-0050-approved-window-screenshots.md +19 -0
- package/docs/decisions/ADR-0051-terminal-decision-wait.md +10 -0
- package/docs/decisions/ADR-0052-per-profile-subagent-budgets.md +25 -0
- package/docs/decisions/ADR-0053-no-repeated-work-guard.md +45 -0
- package/docs/decisions/ADR-0054-terminal-reply-heartbeat-and-stall.md +52 -0
- package/docs/decisions/ADR-0055-plan-output-repair.md +51 -0
- package/docs/decisions/ADR-0056-remote-control.md +53 -0
- package/docs/decisions/ADR-0057-structured-plan-outcomes.md +39 -0
- package/docs/decisions/ADR-0058-ask-user-only-plan-clarification.md +36 -0
- package/docs/parity.md +14 -10
- package/docs/releases/1.3.1-unstable.3.md +54 -0
- package/docs/releases/1.3.1-unstable.4.md +56 -0
- package/docs/terminal-tui.md +43 -18
- package/package.json +3 -1
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0054
|
|
3
|
+
title: A live terminal reply reports a heartbeat and ends when it stops making progress
|
|
4
|
+
status: Accepted
|
|
5
|
+
created: 2026-10-28
|
|
6
|
+
proposal: PROP-0041
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# ADR-0054: A live terminal reply reports a heartbeat and ends when it stops making progress
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
A structured run emits a `heartbeat` every 30 seconds while it works, and the run sweep uses it to
|
|
14
|
+
settle a reply that stopped reporting (INV-RUN-14). A terminal reply emitted none: the extension sent
|
|
15
|
+
tool, message and usage telemetry, but never a heartbeat. Two consequences followed.
|
|
16
|
+
|
|
17
|
+
The sweep could not tell a wedged reply from one written before heartbeats existed, so it waited the
|
|
18
|
+
full 30-minute silence window, and then recorded `owner_gone` — "the owner process is gone" — while
|
|
19
|
+
the owner was alive and its turn was still pending. On 2026-10-28 a `deepseek-v4.1-flash` request in
|
|
20
|
+
a terminal session produced a partial tool call and then nothing for 38 minutes; a request earlier in
|
|
21
|
+
the same session stayed open for 2 h 13 min and ended only when the person typed the next message.
|
|
22
|
+
The run showed as `running` the whole time.
|
|
23
|
+
|
|
24
|
+
## Decision
|
|
25
|
+
|
|
26
|
+
A terminal reply reports a `heartbeat` every 30 seconds for as long as its turn is live, with the
|
|
27
|
+
counters its work slice already keeps: steps, elapsed time, last tool, compactions, slice and the
|
|
28
|
+
call budget. The controller records it on the active run like any other telemetry, so the sweep's
|
|
29
|
+
existing five-minute heartbeat rule now applies to terminal replies.
|
|
30
|
+
|
|
31
|
+
A heartbeat proves the turn is alive, not that it is working, so the terminal controller also ends a
|
|
32
|
+
reply that produced no event other than heartbeats for fifteen minutes. It does that by asking the
|
|
33
|
+
native turn to abort through the command the extension already polls; the run records `interrupted`
|
|
34
|
+
with reason `stalled`. A reply whose oldest running tool has run for thirty minutes is ended the same
|
|
35
|
+
way. A reply with an unanswered approval or question is never cut short, because it is waiting on the
|
|
36
|
+
person, not on the model.
|
|
37
|
+
|
|
38
|
+
## Rationale
|
|
39
|
+
|
|
40
|
+
The two windows are different questions. Five minutes of silence with no heartbeat means the process
|
|
41
|
+
stopped reporting, which the sweep settles; fifteen minutes of heartbeats with no progress means the
|
|
42
|
+
process is alive but the reply is not moving, which only the controller can end. Keeping both avoids
|
|
43
|
+
weakening the rule that protects a live but quiet turn: a long tool or a long reasoning stream still
|
|
44
|
+
reports its heartbeat, and the person answering a decision is never timed out.
|
|
45
|
+
|
|
46
|
+
## Consequences
|
|
47
|
+
|
|
48
|
+
A model request that never returns is ended after fifteen minutes instead of running for hours, and
|
|
49
|
+
the record carries a reason that is true. Terminal replies now write one small event every 30
|
|
50
|
+
seconds (about 60 KB an hour), the same as a bounded structured reply. No tool, permission, run-event
|
|
51
|
+
schema or stored-data layout changes: `heartbeat` already exists in the stream, and the reason
|
|
52
|
+
`stalled` is already part of the contract.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0055
|
|
3
|
+
title: An attended plan run repairs a missing plan block once, in the same run
|
|
4
|
+
status: Accepted
|
|
5
|
+
created: 2026-10-28
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# ADR-0055: An attended plan run repairs a missing plan block once, in the same run
|
|
9
|
+
|
|
10
|
+
## Context
|
|
11
|
+
|
|
12
|
+
Plan mode ends with a `<proposed_plan>` block that both the terminal and the App parse into a plan
|
|
13
|
+
card and the Implement choice. The block is an instruction to the model, not a schema, and a model
|
|
14
|
+
can omit it while still writing a correct plan body. On 2026-10-28 two attended plan runs in one
|
|
15
|
+
terminal session did exactly that: the plan instructions and the plan-only tool set were present,
|
|
16
|
+
the model's reasoning said it would tag the plan, and the final text had no block. The renderer then
|
|
17
|
+
showed ordinary assistant text with no card, no plan choice and no Implement.
|
|
18
|
+
|
|
19
|
+
The tag contract is deliberately text-only: it keeps the plan tool list and the cached prompt prefix
|
|
20
|
+
unchanged when the mode switches. Replacing it with a plan tool or a plan artifact would change that
|
|
21
|
+
boundary, the protocol and both renderers for a rare omission.
|
|
22
|
+
|
|
23
|
+
## Decision
|
|
24
|
+
|
|
25
|
+
When a top-level attended plan run ends without a complete plan block, the harness makes one hidden
|
|
26
|
+
format-repair turn in the same run. The custom message is not displayed, carries no new user
|
|
27
|
+
request, and asks the model to re-send its own plan, unchanged, in one complete block; a model that
|
|
28
|
+
was asking for input answers `No plan:` instead. The repair is attempted once, uses the same plan
|
|
29
|
+
tool set and gate, and is skipped for plan-research children, commands, probes, improvers,
|
|
30
|
+
reflections and other unattended runs.
|
|
31
|
+
|
|
32
|
+
If the repair also fails, the plan run still completes: the original reply stays in the transcript,
|
|
33
|
+
the harness records an `extension.notice` warning, and the terminal shows a warning instead of a
|
|
34
|
+
plan choice. The App shows the repaired card when the repair succeeds and otherwise keeps the
|
|
35
|
+
untagged reply.
|
|
36
|
+
|
|
37
|
+
## Rationale
|
|
38
|
+
|
|
39
|
+
The repair is the smallest change at the ownership layer that preserves the existing plan contract and
|
|
40
|
+
both surfaces. It does not fabricate a plan or guess where one starts, and it leaves the plan tool
|
|
41
|
+
list, the prompt prefix and the run event schema unchanged. Asking the model to re-send its own
|
|
42
|
+
answer is cheaper and less disruptive than re-planning, and a single bounded attempt keeps the extra
|
|
43
|
+
cost and latency predictable.
|
|
44
|
+
|
|
45
|
+
## Consequences
|
|
46
|
+
|
|
47
|
+
An attended plan run may make one additional model request and produce a second assistant message;
|
|
48
|
+
the first untagged reply remains visible. The extra request is counted in the run's usage, and the
|
|
49
|
+
run record, status and event types are unchanged. If the repair proves insufficient, a structured
|
|
50
|
+
plan tool or artifact remains the durable follow-up, but it changes the tool list, the cached prefix
|
|
51
|
+
and both renderers and is not part of this decision.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0056
|
|
3
|
+
title: Remote control connects a phone directly to the terminal session, with sealed frames
|
|
4
|
+
status: Accepted
|
|
5
|
+
created: 2026-10-28
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# ADR-0056: Remote control connects a phone directly to the terminal session, with sealed frames
|
|
9
|
+
|
|
10
|
+
## Context
|
|
11
|
+
|
|
12
|
+
A person wants to keep a terminal session going from a phone or iPad, the way Claude Code's
|
|
13
|
+
`/remote-control` (`/rc`) does: the session keeps running on the computer, and the phone sends
|
|
14
|
+
messages, watches the reply, stops it and answers approvals. Claude Code reaches the phone through
|
|
15
|
+
Anthropic's cloud relay. The harness has no cloud service, and every listener it had bound only
|
|
16
|
+
127.0.0.1.
|
|
17
|
+
|
|
18
|
+
## Decision
|
|
19
|
+
|
|
20
|
+
`/remote-control` (`/rc`) starts a small HTTP server in the `xagent` parent process, bound to one
|
|
21
|
+
address: the computer's Tailscale address when it has one, otherwise its private Wi-Fi or LAN
|
|
22
|
+
address. The terminal shows a QR code for a pairing link whose key is in the URL fragment. A phone
|
|
23
|
+
that opens it asks to pair; the person at the terminal allows it; the phone receives its own key.
|
|
24
|
+
The phone then becomes a second person at the terminal, with the same powers and the same paths:
|
|
25
|
+
`Terminals.send` and the terminal controller's interrupt and decision calls (page 15).
|
|
26
|
+
|
|
27
|
+
Every request and event body is a NaCl `secretbox` frame under the link or device key, with a
|
|
28
|
+
replay counter. All keys live in memory and end with the session.
|
|
29
|
+
|
|
30
|
+
## Rationale
|
|
31
|
+
|
|
32
|
+
- **Direct, not relayed.** A relay is a service to build, run and trust. A direct connection
|
|
33
|
+
needs nothing outside the computer, and Tailscale covers the "away from home" case with its own
|
|
34
|
+
end-to-end encryption.
|
|
35
|
+
- **Sealed frames, not TLS.** A LAN page cannot have a trusted certificate, and a self-signed one
|
|
36
|
+
shows a warning a person learns to click through. Over plain HTTP the browser has no WebCrypto,
|
|
37
|
+
so the page uses `tweetnacl`, served beside it. The key never crosses the network: it reaches the
|
|
38
|
+
phone in the QR code's fragment.
|
|
39
|
+
- **Confirmation at the terminal.** A photographed QR code is not enough to pair; the person at the
|
|
40
|
+
terminal sees the device and allows it.
|
|
41
|
+
- **In-memory keys.** Nothing to revoke later, nothing on disk (INV-ACC-3), and the link dies with
|
|
42
|
+
the session.
|
|
43
|
+
|
|
44
|
+
## Consequences
|
|
45
|
+
|
|
46
|
+
- New harness module `src/remote/`, a new spec page (15), and two dependencies: `tweetnacl` (also
|
|
47
|
+
served to the phone) and `uqr` (QR encoding).
|
|
48
|
+
- The terminal extension now reports streamed assistant text, batched, as `delta` telemetry, and
|
|
49
|
+
terminal runs record `message.delta` events the way structured runs already do.
|
|
50
|
+
- An attacker who can change LAN traffic could serve a changed page to the phone; the terminal
|
|
51
|
+
confirmation and the advice to use Tailscale on untrusted networks are the mitigation.
|
|
52
|
+
- The App presents remote control only as a stub for now (`PAR-018`): its sessions are not
|
|
53
|
+
terminal sessions.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0057
|
|
3
|
+
title: Structured outcomes for attended plan requests
|
|
4
|
+
status: Accepted
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# ADR-0057: Structured outcomes for attended plan requests
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
A reply asking for a decision is not a finished plan. ADR-0055 prescribes one repair for a missing
|
|
12
|
+
plan block, but the prior server parser recognized only `<proposed_plan>` and could treat a request
|
|
13
|
+
for input as a format failure. The terminal did not run that repair. D-22 records the prior
|
|
14
|
+
implementation gap and documentation ambiguity.
|
|
15
|
+
|
|
16
|
+
## Decision
|
|
17
|
+
|
|
18
|
+
An attended top-level plan reply has one classified outcome: `plan_ready` for a complete existing
|
|
19
|
+
`<proposed_plan>` block, `needs_input` for a complete `<plan_clarification>` block containing the
|
|
20
|
+
needed question or explanation, and `invalid` for missing, incomplete, conflicting or malformed
|
|
21
|
+
outcome blocks. Only `plan_ready` permits a plan card and Implement. `needs_input` is displayed as
|
|
22
|
+
input needed, never as an actionable plan. The same classification and bounded repair belong to the
|
|
23
|
+
Harness and apply to both server and terminal, rather than independent surface heuristics.
|
|
24
|
+
|
|
25
|
+
When `ask_user` is available, it blocks for the person's answer and the same run continues; the
|
|
26
|
+
clarification outcome describes input still needed at the end, including when interaction is not
|
|
27
|
+
available. The model must not invent a decision. For an eligible run ending in `invalid`, one hidden
|
|
28
|
+
repair turn in the same run requests a valid outcome without changing substance or inventing
|
|
29
|
+
answers. Either valid outcome ends repair. If repair fails, retain the original text, complete with
|
|
30
|
+
a warning, and offer no Implement. Skip repair for unattended or child runs, commands, aborts,
|
|
31
|
+
errors and work-slice termination. The plan gate remains in force.
|
|
32
|
+
|
|
33
|
+
## Compatibility and consequences
|
|
34
|
+
|
|
35
|
+
This supersedes ADR-0055's plan-only repair criterion, not its bounded same-run mechanism. Existing
|
|
36
|
+
`<proposed_plan>` output and cards remain valid; no new tool, mandatory event type, changed stable
|
|
37
|
+
prompt prefix or widened permissions are required. Older clients may show clarification as ordinary
|
|
38
|
+
text, but must not interpret it as a plan. Historical untagged replies remain visible without being
|
|
39
|
+
fabricated into plans. D-22 is resolved by shared classification and bounded repair on both paths.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0058
|
|
3
|
+
title: Ask-user-only plan clarification
|
|
4
|
+
status: Accepted
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# ADR-0058: Ask-user-only plan clarification
|
|
8
|
+
|
|
9
|
+
## Context
|
|
10
|
+
|
|
11
|
+
ADR-0057 allowed a final `<plan_clarification>` containing a question or explanation. That creates
|
|
12
|
+
another clarification channel alongside the blocking `ask_user` tool and can end a run instead of
|
|
13
|
+
continuing planning after the person's answer.
|
|
14
|
+
|
|
15
|
+
## Decision
|
|
16
|
+
|
|
17
|
+
For new attended top-level plan final replies, the shared server and terminal classification is
|
|
18
|
+
`plan_ready`, `blocked`, or `invalid`. A complete `<proposed_plan>` is `plan_ready` and alone offers
|
|
19
|
+
a plan card and Implement. If a required user decision cannot be obtained because `ask_user` is
|
|
20
|
+
unavailable, the reply is `blocked`: explain the blocker without inventing the decision, asking a
|
|
21
|
+
free-text question, or offering Implement. Malformed, missing or conflicting outcomes are `invalid`.
|
|
22
|
+
New final replies do not use `<plan_clarification>` or free-text questions for clarification.
|
|
23
|
+
|
|
24
|
+
When `ask_user` is available and clarification is needed, call it: it blocks the active run for the
|
|
25
|
+
answer, after which the same run continues. The existing one bounded hidden repair for an eligible
|
|
26
|
+
`invalid` outcome remains in the same run and under the same plan gate; it may call `ask_user` and
|
|
27
|
+
wait for the answer. If repair remains invalid, retain the original reply, warn and offer no
|
|
28
|
+
Implement. The existing repair exclusions remain in force.
|
|
29
|
+
|
|
30
|
+
## Compatibility and consequences
|
|
31
|
+
|
|
32
|
+
This supersedes ADR-0057's `needs_input` and `<plan_clarification>` final-outcome decision, not its
|
|
33
|
+
shared classification, bounded repair or other safeguards. Old transcripts remain intact and
|
|
34
|
+
visible, including historical clarification blocks; they are not rewritten or promoted into plans.
|
|
35
|
+
Existing plan cards, run events, permissions and the cached prompt boundary remain compatible. This
|
|
36
|
+
is an approved contract; implementation and surface acceptance must be verified separately.
|
package/docs/parity.md
CHANGED
|
@@ -22,27 +22,27 @@ implemented is not a parity claim; acceptance is tracked per command.
|
|
|
22
22
|
| Capability | Harness owner | Method or tool | Terminal surface | App surface | Status | Gap |
|
|
23
23
|
|---|---|---|---|---|---|---|
|
|
24
24
|
| Sessions and turns | `sessions/` | `sessions.run`, `terminal.*` | the terminal itself | Solo chat | parity | — |
|
|
25
|
-
| Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card; bounded plan/todo context
|
|
25
|
+
| Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card; shared outcome and bounded repair; plan/todo context restored after compaction | plan request, PlanCard; shared Harness classification and checkpoint behavior | ADR-0058 clarification contract approved; implementation and surface acceptance not verified | — |
|
|
26
26
|
| Capability discovery | `tools/getCapabilities.ts` | read-only `get_capabilities` | terminal extension reports Pi's active tools and schemas; shared plan allowlist includes it | structured Harness run uses the same tool; no duplicate App-owned tool | implemented; acceptance not recertified | — |
|
|
27
27
|
| Bash command mode | `sessions/sessions.ts`, `sessions/initialBash.ts` | `initialBashCommand`; Bash `workspaceWriteScope` | `!command` defaults to workspace; `!outside command` asks before running once | same `!command` and `!outside command` composer semantics | parity | — |
|
|
28
28
|
| Workspace-scoped writes | `core/workspace.ts`, `sessions/workspaceBoundary.ts`, `core/workspaceBashTool.ts`, `core/workspaceSandbox.ts`, `core/workspaceWriteOperations.ts` | pinned non-root `RunRecord.workspaceRoot`; native `edit`/`write`; Bash scope | revalidated atomic native writes; external-hard-link scan and Bash sandbox (Windows: no sandbox, each Bash call asks once, plan-mode Bash refused; ADR-0042); complete escaped outside command in scrollable approval details (deny if too small); no output-triggered retry | same Harness gate and full approval action in scrollable App details; App policy can tighten scope; Full Permission remains the eligible explicit bypass | parity | — |
|
|
29
|
-
| Side questions | `sessions/sideQuestions.ts` | `sideQuestions.start/read/interrupt`; terminal `terminal.sideQuestions.*` | `/btw` contextual dock with scroll and copy | side-question dock through the shared service | parity | — |
|
|
29
|
+
| Side questions | `sessions/sideQuestions.ts` | `sideQuestions.start/read/interrupt`; terminal `terminal.sideQuestions.*` | `/btw` contextual dock; the answer renders as Markdown, with scroll and copy | side-question dock through the shared service | parity | — |
|
|
30
30
|
| Approvals and standing approvals | `sessions/approvals.ts` | `approvals.*` | decision dock, `/permissions` | approvals dock, settings | parity | — |
|
|
31
31
|
| Opening a link | `core/links.ts` | `links.open`; `HarnessOptions.linkOpener` (ADR-0047) | hover shows the hand pointer and recolours the link, Ctrl+click (the primary click on macOS, whose ⌘ the mouse protocol cannot report) opens web, `mailto:`, file and folder targets with the system handler, a refused link posts a notice | ⌘-click on macOS and Ctrl+click elsewhere opens with the system handler, a plain click keeps the sidebar and falls back to the system for what it cannot show, `a:hover` uses `--link-hover` | implemented; acceptance not certified | — |
|
|
32
|
-
| Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, 80×24 source sketch viewport; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028) | plan-mode form accepts the same 80×24 ASCII source contract with literal preview and accessible overflow; no typography change required | parity;
|
|
33
|
-
| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
|
|
32
|
+
| Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, 80×24 source sketch viewport; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028) | plan-mode form accepts the same 80×24 ASCII source contract with literal preview and accessible overflow; no typography change required | existing question surface parity; ADR-0058 plan clarification contract not verified | — |
|
|
33
|
+
| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles; per-profile and total child budgets enforced in `Subagents.spawn` (ADR-0052), with the same refusal result in both surfaces | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
|
|
34
34
|
| Agent profiles | `agents/profiles.ts` | `spawn_subagent { agent }`, `agents.list/get/create/remove`; terminal `terminal.agents.*`; package profiles through `Loading.profilePaths` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete; package profiles listed under "From a plugin" and switched on `/plugins` | Solo `/agents` lists profiles; profile details and management are not wired | partial | PAR-010 |
|
|
35
35
|
| Run todo list | `tools/todo.ts` | `todo_write`, `runs.todo` (`runs.checklist` deprecated); terminal `todo` telemetry | registered in terminal sessions and their subagents; each write shows as a todo block in the transcript; `/todo` shows the current list; a subagent row shows its `n of m tasks` | `/todo` shows the current list on demand; each write is not rendered inline | terminal done; App shows it on demand | PAR-001 |
|
|
36
36
|
| Continuation of a stopped run | `sessions/continuation.ts` | `continueFrom`, `runs.continuation` | not offered (`/resume` reopens history only) | not offered | planned | PAR-003 |
|
|
37
|
-
| Bounded replies and checkpoints (PROP-0041) | `sessions/workSlice.ts`, `tools/checkpoint.ts`, `sessions/runner.ts` | `checkpoint_write`, `workSlice`, `runs.continuation.checkpoint`, `checkpoint`/`heartbeat` events | guard on every terminal reply with the shared tool; the handoff is recorded on the run; no checkpoint card or slice control yet | not wired | implemented; terminal card, App presentation and `/slices` open | PAR-004 |
|
|
37
|
+
| Bounded replies and checkpoints (PROP-0041) | `sessions/workSlice.ts`, `tools/checkpoint.ts`, `sessions/runner.ts`, `terminal/stallWatch.ts` | `checkpoint_write`, `workSlice`, `runs.continuation.checkpoint`, `checkpoint`/`heartbeat` events | guard on every terminal reply with the shared tool; every live reply heartbeats and a reply with no progress for fifteen minutes ends as `stalled`; the handoff is recorded on the run; no checkpoint card or slice control yet | not wired | implemented; terminal card, App presentation and `/slices` open | PAR-004 |
|
|
38
38
|
| Accounts | `accounts/` | `accounts.*` | `/accounts` | Accounts | parity | — |
|
|
39
39
|
| Models and effort | `accounts/choices.ts` | — | `/model`, `/effort` | composer pickers | parity | — |
|
|
40
|
-
| Skills | `plugins/`, `tools/dispatch.ts` | `skill_load` | `$name
|
|
40
|
+
| Skills | `plugins/`, `tools/dispatch.ts`, `prompt/compile.ts` | `skill_load`; `Launch.requiredSkills` | `$name` at any word start (required for that request), `/skill:name`, browser Skills tab | composer `$` chip with `requiredSkills`; Capability | implemented; acceptance not recertified | — |
|
|
41
41
|
| Plugins and Hub | `plugins/`, `hub/` | `plugins.*`, `hub.*` | full-screen `/plugins` local manager; separate full-screen `/hub` Community catalog with bounded registry/document Preview (no Pi-package Preview) | local Plugins manager; Community Hub with payload Preview for non-package entries | parity | — |
|
|
42
42
|
| Plugin authoring and proposal review | `plugins/proposals.ts`, `tools/defaultSkills.ts` | `plugin_propose`, `plugins.proposals.*` | `/plugins` Proposals tab: preview, accept or reject | structured model tool and skill; review UI not implemented | partial; App review pending | PAR-017 |
|
|
43
43
|
| Connected apps (MCP) | `mcp/` | `connections.*`, broker tools | resource browser Connections tab | Connections | parity | — |
|
|
44
44
|
| Web search and page reading | `web/` | `web_search`, `web_fetch` | world tools | world tools | parity | — |
|
|
45
|
-
| Isolated browser | `browser/` | shared `browser_*` schemas | isolated world tools, headed on request, `/settings` Browser tab | native WebKit: navigate, tabs, visible-text read and page scroll without refs; unsupported operations refuse explicitly | partial; native backend gap | PAR-015 |
|
|
45
|
+
| Isolated browser | `browser/` | shared `browser_*` schemas | isolated world tools, headed on request, `/settings` Browser tab | native WebKit: navigate, tabs, visible-text read, page screenshot and page scroll without refs; unsupported operations refuse explicitly; live screenshot acceptance pending | partial; native backend gap | PAR-015 |
|
|
46
46
|
| Web annotations | `annotations/` (PROP-0017, PROP-0018, PROP-0038, PROP-0048) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/annotate:` page (Annotate and All annotations tabs; DevTools app list and launch), `/annotate:notes`, `/annotate:submit`, `/annotate:clear` | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | App behind PROP-0048 (queue methods removed); native WKWebView gestures unaccepted | PAR-011 |
|
|
47
47
|
| Managed worktrees | `worktrees/` (PROP-0016) | `worktrees.*` | `--worktree`, `/worktree`, `xagent worktree` | Solo `/worktree` lists records only; Solo starts sessions in the project folder and has no worktree level | partial | PAR-012 |
|
|
48
48
|
| Wiki notes (model tools) | `wiki/`, `tools/` | `wiki_*` | `Terminals.ownTools` registers Wiki-read tools through the session socket; `xagent-wiki` remains a person-facing shell utility | structured Harness tools | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
|
|
@@ -53,10 +53,12 @@ implemented is not a parity claim; acceptance is tracked per command.
|
|
|
53
53
|
| Doctor | `doctor/` | `doctor.*` | `/doctor` | diagnostics | parity | — |
|
|
54
54
|
| Run inspection | `sessions/runStore.ts` | `runs.*` | `/trajectory`, `/log` | run views, analytics | parity | — |
|
|
55
55
|
| Usage analytics | `usage/` (PROP-0042) | `usage.summary`, `usage.sync` | `/usage:`, `/usage:analysis` page (Analysis tab) | not wired | terminal implemented; host planned | PAR-016 |
|
|
56
|
+
| Remote control (ADR-0056) | `remote/` | protected `terminal.remoteControl.*`; phone calls through `Terminals.send` and the terminal controller | `/remote-control` (`/rc`) page with link, QR code, devices and pair confirmation; `rc` status-bar group; `--remote-control`; the served phone page | stub: App sessions are not terminal sessions | terminal only | PAR-018 |
|
|
57
|
+
| Context attribution (PROP-0049) | `context/` | `context.attribution`; protected `terminal.context` | `/context` page with Request and Growth tabs, a four-colour context bar with a free track and a compaction marker, `space` fold, `enter` row text, `g` grouping, `c` compact; the status band reads `18.3%/1M` | full-width Context page opened from the Context tab with the same four-colour bar and a screen-reader reading of it, composer ring reading the same share | implemented on both; acceptance not recertified | — |
|
|
56
58
|
| Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` (current account), `/usage:accounts` (all accounts) | not wired | terminal implemented; host planned | PAR-016 |
|
|
57
59
|
| Session catalog (sessions per folder) | `sessions/` saved-history controls; shared catalog not implemented | `sessions.*` controls; no cross-surface catalog method | `/session` selects native Pi histories in the current folder | `/session` reads `bridge.agent.threads(SOLO_ID)`, maps each thread to its project folder, and filters by current effective account; `all` broadens only this App list | planned; catalogs differ | PAR-008 |
|
|
58
60
|
| Folder choice and recent folders | project/worktree selection remains surface-specific | launch `cwd`, `--worktree`, `/worktree` | starts in launch folder; explicit worktree commands | Solo sidebar is Project › Session; new sessions use the project's folder, with no folder/worktree level | planned; no shared recent-folder picker | PAR-009 |
|
|
59
|
-
| Computer control |
|
|
61
|
+
| Computer control | `computer/screenshot.ts` defines an opt-in approved-window screenshot contract; other tools remain host-owned | `computer_*` (host tools) | no computer screenshot backend | macOS bridge (host-backed); its display capture has not adopted the approved-window contract | partial; screenshot contract not integrated | PAR-007 |
|
|
60
62
|
| Shared files vault | — | `files_*` (host tools) | none | Files | host only | PAR-007 |
|
|
61
63
|
|
|
62
64
|
## Core slash-command surfaces (PROP-0040)
|
|
@@ -77,6 +79,7 @@ this fixed table.
|
|
|
77
79
|
| `/session` (`/resume`) | Search/select native saved history in the current folder | Lists App Solo threads by folder and effective account; `all` widens only within that App list | PAR-008: separate catalogs; no native-history path opening; not certified |
|
|
78
80
|
| `/history` (`/tree`) | Navigate branches in the current native session | Calls `session.navigate` with stable native entry ID; same-session navigation, optional summary, no fork fallback | Route uses Harness `sessions.navigate`; per-command acceptance pending |
|
|
79
81
|
| `/fork` | Fork from a user message | Uses session tree/fork and opens the new session | Not certified per command |
|
|
82
|
+
| `/remote-control` (`/rc`) | Pairing link, QR code and devices; phone page served by the harness | Stub notice: remote control runs from an `xagent` terminal session | PAR-018; terminal only |
|
|
80
83
|
| `/clone` | Clone the current branch | Uses session clone and opens the copy | Not certified per command |
|
|
81
84
|
| `/model` | Choose model | App model picker updates session runtime | Not certified per command |
|
|
82
85
|
| `/effort` | Choose reasoning effort | Updates session runtime effort | Not certified per command |
|
|
@@ -118,6 +121,7 @@ or live-model sketch quality.
|
|
|
118
121
|
|
|
119
122
|
| ID | Gap | Planned change |
|
|
120
123
|
|---|---|---|
|
|
124
|
+
| PAR-018 | Remote control from the App | `/remote-control` drives an `xagent` terminal session from a phone (page 15). App sessions are structured runs, not terminal sessions; the App would need the same pairing over its own session controls, or to present a terminal session's remote control. |
|
|
121
125
|
| PAR-017 | Plugin proposal review surfaces | The terminal provides hash-bound review in `/plugins`; the App has no proposal review UI yet. |
|
|
122
126
|
| PAR-001 | Todo list not rendered inline in the App | Both surfaces can show the current list: the terminal renders each write as a todo block and `/todo` shows a snapshot; the App's `/todo` shows a read-only list. The App still does not draw an inline block for each write. |
|
|
123
127
|
| PAR-002 | Acceptance of terminal-model History/Wiki/skill tools | Source gap resolved: `Terminals.ownTools` registers History/trajectory, Wiki-read and skill tools over the session socket; `xagent-wiki` is a user-facing shell utility, not the model's only route. Acceptance has not been recertified in this documentation pass. |
|
|
@@ -125,7 +129,7 @@ or live-model sketch quality.
|
|
|
125
129
|
| PAR-004 | Refinement and adoption only in the App | Variant tab actions: start, candidates, adopt, trust. |
|
|
126
130
|
| PAR-005 | Wiki browsing only in the App | A `/wiki` page over `wiki.*`. |
|
|
127
131
|
| PAR-006 | Acceptance of terminal first-party hooks | Source gap resolved: enabled hooks are returned by protected `firstParty.list` and loaded by `terminal/piExtension.ts`. Acceptance has not been recertified in this documentation pass. |
|
|
128
|
-
| PAR-007 | Host tools without a Harness
|
|
132
|
+
| PAR-007 | Host tools without a complete Harness surface | The opt-in screenshot contract exists, but terminal availability reporting and a conforming host backend are not wired. The current macOS host captures a display, not an isolated approved window. The remaining computer controls are host-owned; the files vault becomes a Harness capability or is dropped. |
|
|
129
133
|
| PAR-008 | Separate session catalogs | Proposal approved; shared catalog is not implemented. Terminal `/session` selects native Pi history in the current folder. App `/session` reads Solo `agent.threads`, maps threads through Solo project groups, and filters to the current effective account and folder; `/session all` broadens only within that App catalog. It cannot open an arbitrary native session path. No cross-surface catalog or visibility guarantee exists. |
|
|
130
134
|
| PAR-009 | Shared folder/recent-project choice | Terminal starts from its launch `cwd` and can switch through its worktree surface. App Solo uses Project › Session and starts new sessions in the selected project's folder; it has no folder/worktree level or shared recent-folder picker. |
|
|
131
135
|
| PAR-010 | Agent profile management in Solo | App Solo `/agents` can list profiles. Although the renderer allowlist includes `agents.get`, Solo does not wrap it; `agents.create/remove` are not exposed there. Profile details and management actions are unavailable, unlike terminal `/agents`. |
|
|
@@ -134,4 +138,4 @@ or live-model sketch quality.
|
|
|
134
138
|
| PAR-013 | Expanded question wireframes and terminal layout | Closed by [PROP-0025 verification](evidence/terminal-question-wireframes/README.md): four-size production PTY acceptance covers aligned compact columns, body scrolling, pinned controls, Shift+arrow sketch panning and live resizing. Host contracts accept 80×24 literal ASCII sketches (1,943 bytes); six isolated browser tests include exact-boundary content, accessible overflow and unchanged selection/answers. This is controlled fixture acceptance, not live-provider or native Tauri evidence. |
|
|
135
139
|
| PAR-014 | Connected terminal sketch display | Closed by [PROP-0026 verification](evidence/terminal-connected-sketches/README.md) and extended by [PROP-0028 verification](evidence/terminal-wireframe-normalization/README.md): production PTY fixtures cover connected corners/tees, title-bearing rules, missing and whitespace-shifted side edges, internal table widths, frame-attached dividers, resize/panning and unchanged raw persistence/answers. Harness and host checks passed. Host literal rendering remains permitted; no host implementation change was required. This is fixture verification, not an every-font or live-model guarantee. |
|
|
136
140
|
| PAR-016 | Usage analytics and provider limits in the App | The terminal has `/usage:analysis` and `/usage:limit` over `usage.*`. The App presents the same capability: an analytics view and a per-account provider limit view. |
|
|
137
|
-
| PAR-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads and scrolling without refs. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll),
|
|
141
|
+
| PAR-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads, page screenshots and scrolling without refs; live screenshot acceptance is pending. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll/ref-screenshot), waits and keyboard presses return an explicit `browser_unsupported` refusal before effects; there is no automatic switch to the isolated Harness browser. See page 13 and the native backend's `surfaces` note. |
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Xingular Harness 1.3.1-unstable.3
|
|
2
|
+
|
|
3
|
+
Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
|
|
4
|
+
|
|
5
|
+
- Name a skill anywhere in a message: `$name` at any word start makes that skill required for the
|
|
6
|
+
request (ADR-0048). `Launch.requiredSkills` carries it, and the compiler renders a
|
|
7
|
+
`required-skills` section at order 52 from the pinned variant through `readSkillFile`, bounded at
|
|
8
|
+
12,000 characters. An unavailable skill is named honestly instead of invented, and the built-in
|
|
9
|
+
`plugin-authoring` skill stands in when the variant ships no skills. The section belongs to the
|
|
10
|
+
request, so an identical one is delivered again rather than deduplicated. The terminal builds the
|
|
11
|
+
same text with `requiredSkillsText` and appends it as a hidden `xingular-required-skills` message,
|
|
12
|
+
so the person's own wording reaches the model unchanged. In the composer the `$` palette opens at
|
|
13
|
+
the caret and inserts there, keeping the rest of the draft.
|
|
14
|
+
- Bound delegation per run and per profile (ADR-0052). A run now starts at most four distinct child
|
|
15
|
+
conversations: two `worker`, three `explorer`, one of any other named profile and one with no
|
|
16
|
+
profile. `SessionRunInput.subagents` / the SDK's `Subagents` options override them with
|
|
17
|
+
`maxChildren`, `maxByProfile`, `maxOther` and `maxUnprofiled` (clamped to 0–50), and the model's
|
|
18
|
+
`spawn_subagent` description states the budget it has left. `Subagents.spawn` refuses a child past
|
|
19
|
+
a limit with `invalid_request` and starts no run; continuing a stopped child costs no slot, and a
|
|
20
|
+
work-slice continuation keeps the parent's budget.
|
|
21
|
+
- Read what a request was made of. `context.attribution` returns one row per contributor with its
|
|
22
|
+
estimated tokens and share of the window, reconciled to the provider's measured total, and one
|
|
23
|
+
row's text on request; the terminal reaches it through `terminal.context`. The compiler now
|
|
24
|
+
records where its characters went: `renderSized` returns each section's size and the framing that
|
|
25
|
+
belongs to no section, `Delivery.sizes` stores them on the recorded pack, and `Source.chars`
|
|
26
|
+
attributes a variant's tool guidance inside the tools section. `context.snapshot` also records the
|
|
27
|
+
compaction headroom the run was held to (`compaction: { enabled, reserveTokens }`) from Pi's own
|
|
28
|
+
settings. The terminal page over this data arrives in a later preview; no `/context` command is
|
|
29
|
+
registered yet.
|
|
30
|
+
- Add an opt-in approved-window screenshot contract (ADR-0050). `src/computer/screenshot.ts` defines
|
|
31
|
+
`computer_screenshot` for a host-supplied backend: it captures exactly one currently approved
|
|
32
|
+
window, excludes the desktop, other windows and overlapping overlays, and refuses with
|
|
33
|
+
`COMPUTER_SCREENSHOT_UNAVAILABLE` rather than returning display pixels. It goes through the
|
|
34
|
+
ordinary tool gate, is not plan-mode safe, and adds no extension point. The standalone terminal
|
|
35
|
+
has no backend, and the existing macOS host capture has not adopted this contract.
|
|
36
|
+
- Deliver approvals and questions promptly without polling: the control-key-protected
|
|
37
|
+
`terminal.pending.wait` returns as soon as the pending revision changes and otherwise waits at most
|
|
38
|
+
20 s, waking on additions, removals and disposal (ADR-0051). `terminal.pending` is unchanged and
|
|
39
|
+
the server protocol is untouched.
|
|
40
|
+
- Swap the OpenTUI send keys back. `Return` sends, or queues a follow-up behind a running reply, and
|
|
41
|
+
`Cmd+Return`, `Ctrl+Return` or `Alt+Return` steers that reply. The `app.message.followUp` action is
|
|
42
|
+
`app.message.steer` again, so a `keybindings.json` entry under the newer name needs renaming.
|
|
43
|
+
- Keep a stray mouse report out of input. A report split across the input parser's timeout no longer
|
|
44
|
+
types its `<button;column;row>` tail into the composer or a single-line field, so a scroll cannot
|
|
45
|
+
become a run's prompt or a filter; typing and pastes are untouched and `/trajectory` no longer
|
|
46
|
+
prints a recorded report.
|
|
47
|
+
|
|
48
|
+
## Upgrading
|
|
49
|
+
|
|
50
|
+
- A leading `$name` is no longer rewritten to Pi's `/skill:name`. An embedding host sends required
|
|
51
|
+
skills as `Launch.requiredSkills`, and the message text reaches the model as written.
|
|
52
|
+
- Runs that spawned children freely now stop at the defaults above; set `subagents` explicitly to
|
|
53
|
+
change them.
|
|
54
|
+
- A `keybindings.json` entry named `app.message.followUp` is now `app.message.steer`.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Xingular Harness 1.3.1-unstable.4
|
|
2
|
+
|
|
3
|
+
Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
|
|
4
|
+
|
|
5
|
+
- Continue a terminal session from a phone or iPad with `/remote-control` (alias `/rc`), without a
|
|
6
|
+
cloud relay (ADR-0056, [page 15](../architecture/15-remote-control.md)). The harness serves a small
|
|
7
|
+
phone page on the computer's Tailscale address, or its private Wi-Fi address, and the terminal
|
|
8
|
+
shows a half-block QR code for a one-device pairing link. A paired phone sends messages, watches
|
|
9
|
+
the reply stream, stops it, and answers approvals and questions through the same `Terminals` and
|
|
10
|
+
controller methods the terminal uses. Bodies are sealed with NaCl `secretbox` and a replayed
|
|
11
|
+
counter is refused; device keys live in memory only, and remote control ends with the session.
|
|
12
|
+
`xagent --remote-control` (`--rc`) turns it on at start, `/rc off` stops it, and the status bar
|
|
13
|
+
reads `rc` while it is on and `rc ●` while a device is connected. Terminal runs now also record
|
|
14
|
+
streamed `message.delta` events. New dependencies: `tweetnacl`, `uqr`.
|
|
15
|
+
- Classify a plan reply instead of guessing at it, and repair one bad reply. An attended top-level
|
|
16
|
+
plan run has one shared outcome: `plan_ready` for a complete `<proposed_plan>`, `blocked` when a
|
|
17
|
+
required decision cannot be obtained, and `invalid` for missing, incomplete, conflicting or
|
|
18
|
+
malformed blocks; only `plan_ready` offers a plan card and Implement (ADR-0055, ADR-0057,
|
|
19
|
+
ADR-0058). An `invalid` reply gets one hidden format-repair turn in the same run, and a failed
|
|
20
|
+
repair leaves the run completed with a warning instead of a plan choice. Clarification now goes
|
|
21
|
+
through the blocking `ask_user` tool, so new final replies no longer use `<plan_clarification>` or
|
|
22
|
+
free-text questions. Both the server and the terminal use the same classification rather than
|
|
23
|
+
separate heuristics. The App's plan card has not adopted the classification yet.
|
|
24
|
+
- Report a live reply's heartbeat every 30 seconds, and end a reply that produces nothing but
|
|
25
|
+
heartbeats for 15 minutes as `interrupted` with reason `stalled`, instead of showing a run that
|
|
26
|
+
never settles (ADR-0054). A running tool gets 30 minutes, and an unanswered approval or question is
|
|
27
|
+
never cut short. Before this, a terminal reply reported no heartbeat at all, so the run sweep
|
|
28
|
+
waited the full 30-minute silence window and recorded `owner_gone` while the process was alive.
|
|
29
|
+
- Stop refusing repeated work (ADR-0053). A reply is no longer refused or ended for calling the same
|
|
30
|
+
tool with the same arguments three times, for a Bash check that keeps failing, or for editing one
|
|
31
|
+
path more than four times: those calls are ordinary work and the reply budget is the single bound.
|
|
32
|
+
The 320-call/60-minute budget, its checkpoint handoff, slice continuation and the
|
|
33
|
+
three-compaction thrash rule are unchanged, and the `stuck` checkpoint reason stays readable in
|
|
34
|
+
existing runs.
|
|
35
|
+
- Answer what the latest request was made of with `/context`. The page has a Request tab (one row per
|
|
36
|
+
contributor with its estimated tokens and share of the window, four-colour ownership bar with a
|
|
37
|
+
free track and a compaction marker) and a Growth tab (how the window filled over the session).
|
|
38
|
+
`space` folds a group, `enter` shows one row's text, `g` switches grouping between owner and kind,
|
|
39
|
+
and `c` asks the session to compact. `terminal.context` serves it from `context.attribution`; the
|
|
40
|
+
status band reads the same share, such as `18.3%/1M`.
|
|
41
|
+
- Render the `/btw` side answer as Markdown instead of plain text. Headings, emphasis, lists, quotes,
|
|
42
|
+
links, tables and fenced code use the theme's markdown colours, a streaming answer re-renders in
|
|
43
|
+
place, and terminal control sequences in model output are still removed.
|
|
44
|
+
|
|
45
|
+
## Upgrading
|
|
46
|
+
|
|
47
|
+
- Two new runtime dependencies arrive with remote control: `tweetnacl` and `uqr`.
|
|
48
|
+
- A plan reply that ends in `<plan_clarification>` or a free-text question is now `invalid` and gets
|
|
49
|
+
the single repair turn; use `ask_user` for a decision the run needs before it can plan.
|
|
50
|
+
- The `stuck` checkpoint reason is no longer produced, but it stays readable in existing run records.
|
|
51
|
+
|
|
52
|
+
## Publication note
|
|
53
|
+
|
|
54
|
+
This preview was published with the test job removed and without waiting for the smoke job, by
|
|
55
|
+
request. The `check` job and the smoke gate are restored in the next commit; the candidate pack,
|
|
56
|
+
integrity check, preflight, provenance and registry verification in the publish job still ran.
|
package/docs/terminal-tui.md
CHANGED
|
@@ -29,10 +29,11 @@ overrides the Bun executable.
|
|
|
29
29
|
[`app.ts`](../src/terminal/opentui/app.ts) owns the terminal lifecycle and reuses the shared
|
|
30
30
|
`TerminalRuntime`, session replacement, commands, decisions, account pinning and run records. It
|
|
31
31
|
projects the runtime's snapshot and transcript into an OpenCode-inspired view, with a native
|
|
32
|
-
OpenTUI textarea for the prompt and `Ctrl+K` for the command palette. `Return` sends or
|
|
33
|
-
|
|
34
|
-
inserts a newline. Typing `/`
|
|
35
|
-
matching
|
|
32
|
+
OpenTUI textarea for the prompt and `Ctrl+K` for the command palette. `Return` sends or queues a
|
|
33
|
+
follow-up; `Cmd+Return`, `Ctrl+Return` or `Alt+Return` steers a running reply, and `Shift+Return`
|
|
34
|
+
inserts a newline. Typing `/` at the start of the draft filters matching commands, and typing `$` at any word start
|
|
35
|
+
filters matching skills; `Tab` inserts the selected entry and leaves the cursor after it. A `$`
|
|
36
|
+
entry replaces only the token being typed, so text before and after it stays in place.
|
|
36
37
|
With an empty composer, unmodified Up recalls the latest non-empty user message from the active session.
|
|
37
38
|
With a draft, unmodified Up browses older history and Down browses newer history when the caret is at
|
|
38
39
|
either absolute draft endpoint (start or end). Down past the newest entry restores the draft, cursor
|
|
@@ -95,7 +96,7 @@ The frontend is verified with a real isolated PTY and a loopback provider. Run
|
|
|
95
96
|
`python3 scripts/verify-terminal.py --welcome-only --sizes 40x20,80x24,120x40` to check the empty
|
|
96
97
|
welcome, product label, accent colors and `/help` transition. Run
|
|
97
98
|
`python3 scripts/verify-terminal.py --composer-only` for recognized slash-command colors in the composer
|
|
98
|
-
and a user bubble, enabled-skill colors in the composer, unknown-token and argument colors,
|
|
99
|
+
and a user bubble, enabled-skill colors in the composer (leading and after text), unknown-token and argument colors,
|
|
99
100
|
explicit-newline and soft-wrap checks of both prompt gutters, and normal/plan/Bash mode exclusivity.
|
|
100
101
|
Run it with `--sizes 40x20,80x24,120x40` for compact through wide layouts. Use `--dialog-paste-only` to verify bracketed paste into a centered
|
|
101
102
|
input dialog, `--file-completion-only` for filesystem completion and insertion,
|
|
@@ -246,8 +247,9 @@ end. A narrow `▕` thumb marks transcript position at the right edge; its mouse
|
|
|
246
247
|
thinking, tools, image results, notices, summaries, custom messages, user messages, plan cards and
|
|
247
248
|
Bash entries. User, plan and Bash bubbles also have one blank row of internal padding above and below
|
|
248
249
|
their content; other entries have no internal vertical padding. Bubble padding is additional to the
|
|
249
|
-
inter-entry gap.
|
|
250
|
-
|
|
250
|
+
inter-entry gap. A plan card carries its title as an underlined header in the plan blue, then one
|
|
251
|
+
blank row before the plan body. Internal lines within an entry stay together. The transcript stays
|
|
252
|
+
pinned to the latest message until you scroll away. While scrolled away, a `↓ Jump to latest` badge overlays the
|
|
251
253
|
transcript's lower-right corner; clicking it returns to the newest message and hides the badge.
|
|
252
254
|
`Ctrl+End` remains an alternate way to jump to the end. A primary click in the transcript or empty
|
|
253
255
|
welcome area focuses the composer. Dragging to select text anywhere in the TUI—including the
|
|
@@ -263,6 +265,12 @@ question's action is clicked. Dialogs preserve their existing confirmation safeg
|
|
|
263
265
|
hover; terminals or multiplexers that do not report motion retain keyboard navigation. ANSI-only
|
|
264
266
|
custom UI without a mouse handler remains keyboard-driven.
|
|
265
267
|
|
|
268
|
+
A mouse report the terminal delivers in two pieces across the input parser's timeout arrives as
|
|
269
|
+
printable keys. The composer and every single-line field drop the report's `<button;column;row>`
|
|
270
|
+
tail instead of keeping it, so a stray scroll never becomes a draft, a filter or a prompt; text typed
|
|
271
|
+
at human speed is untouched even when it spells the same shape. Recorded text never prints a
|
|
272
|
+
reported sequence on a page, and a bare tail that was recorded stays visible as recorded evidence.
|
|
273
|
+
|
|
266
274
|
Page dialogs and blocks are absolute overlays, so the transcript stays behind them. The screen
|
|
267
275
|
restores the terminal's alternate-screen state when the application exits.
|
|
268
276
|
|
|
@@ -316,6 +324,14 @@ of two rule-based shapes, using the 2-cell composer gutter on each side and a di
|
|
|
316
324
|
`/plugins` and `/hub` menus are pages. Section labels inside a page are plain bold headings, never
|
|
317
325
|
text set into a rule. `/trajectory` is a full-screen page with searchable Runs and Events
|
|
318
326
|
tabs; its Events view keeps the event list beside the selected event's JSON on wide terminals.
|
|
327
|
+
`/context` is a full-screen page with Request and Growth tabs: one bar that gives each kind of
|
|
328
|
+
context its own colour — foundation blue, variant orange, your application green, conversation
|
|
329
|
+
amber, the same four values as the App's `--data-1..4` tokens — with the track for free space and a
|
|
330
|
+
`│` where Pi would start compacting, a legend naming every run, then one row per contributor (`❯` on the selected one, `·` for a section that arrives per request) reading
|
|
331
|
+
`tokens` and `share`, group headings carrying their own total, the reserve and free space, and an
|
|
332
|
+
On demand list. `space` folds a group, `enter` shows the text a row contributed, `g` regroups rows
|
|
333
|
+
by owner or by kind, `c` compacts after a confirmation, and `v` opens `/harness`. It reads
|
|
334
|
+
`terminal.context` and draws no figure it did not receive.
|
|
319
335
|
|
|
320
336
|
`DialogPanel` takes a `variant` (`block` by default). `ui.select` accepts a harness-owned `page`
|
|
321
337
|
option, which Pi's own dialogs ignore, so the same extension code runs in either terminal. Selected
|
|
@@ -377,10 +393,9 @@ snapshot and compares their text with the latest saved version. No in-place edit
|
|
|
377
393
|
is added. Library skills and rules are added through `terminal.components.add`, which commits a
|
|
378
394
|
validated future version. Directory-backed variants stay read-only.
|
|
379
395
|
|
|
380
|
-
Skill browsing is independent of the Skill commands setting. Use inserts a
|
|
381
|
-
without submitting. Ctrl+K opens a separate command filter; choosing a browser section keeps
|
|
396
|
+
Skill browsing is independent of the Skill commands setting. Use inserts `$name` without submitting. Ctrl+K opens a separate command filter; choosing a browser section keeps
|
|
382
397
|
the existing draft text and attachment labels. Canceling the filter restores that draft. OpenTUI completes
|
|
383
|
-
loaded skills for a
|
|
398
|
+
loaded skills for a `$` at any word start; Enter or Tab inserts the selected skill rather than sending.
|
|
384
399
|
Plugin contributions, settings, attachment and code trust share one detail flow. Package install
|
|
385
400
|
and removal delegate to existing services; installing never trusts or activates code.
|
|
386
401
|
|
|
@@ -466,7 +481,8 @@ request-scoped prompt section, which the next ordinary request withdraws.
|
|
|
466
481
|
Each mode keeps its own model and effort for the account. Every selection the person makes (the model
|
|
467
482
|
picker, `/effort`, Shift+Up/Down, Ctrl+P) is saved against the mode it was made in, so Shift+Tab switches to that
|
|
468
483
|
mode's model and effort, and a new conversation starts on the normal mode's latest choice. A mode with no
|
|
469
|
-
choice of its own takes normal's, field by field
|
|
484
|
+
choice of its own takes normal's, field by field; when neither has a saved effort, the mode uses Pi's
|
|
485
|
+
default level rather than keeping the level chosen in the other mode. A resumed conversation keeps the model in its history,
|
|
470
486
|
and a saved model the account cannot use is skipped. The choices live in the account's `choices.json`,
|
|
471
487
|
and the App reads and writes them through `accounts.choices` and `accounts.choose`.
|
|
472
488
|
|
|
@@ -485,7 +501,9 @@ dismisses it; the block yields to the composer as soon as the draft has text.
|
|
|
485
501
|
Implement leaves plan mode, so the normal tools and the mode's own model and effort come back, and sends
|
|
486
502
|
`Implement the plan: <title>`; the plan itself is already in the conversation. Edit the plan stays in plan
|
|
487
503
|
mode and focuses the composer, so the next message revises the plan and offers a new choice. A plan run
|
|
488
|
-
that was interrupted, failed, or had work queued behind it is not offered.
|
|
504
|
+
that was interrupted, failed, or had work queued behind it is not offered. If a completed plan run still
|
|
505
|
+
has no complete block after the harness's one repair attempt, the terminal shows a warning notice instead
|
|
506
|
+
of a plan choice; the plan request can be sent again.
|
|
489
507
|
|
|
490
508
|
A recognized leading slash command uses the selected theme's link color while typing and in its
|
|
491
509
|
user-message bubble. Only the command token is accented; arguments and unknown slash tokens keep the
|
|
@@ -652,12 +670,14 @@ second key once with `control.claim`, before plugin code loads. [`control.ts`](.
|
|
|
652
670
|
retains it in a process-local promise shared with the bridge; it is never written to disk or
|
|
653
671
|
placed in the environment. It survives `/new`, resume, fork and reload.
|
|
654
672
|
|
|
655
|
-
The private key is required for `terminal.policy`, `terminal.approval`, `terminal.pending`,
|
|
673
|
+
The private key is required for `terminal.policy`, `terminal.approval`, `terminal.pending`, `terminal.pending.wait`,
|
|
656
674
|
`terminal.approve`, `terminal.answer`, `terminal.draft`, `terminal.interrupt` and
|
|
657
675
|
`terminal.resources`, as well as existing account and plugin mutations. A model-spawned shell with
|
|
658
676
|
only the environment token cannot submit policy or approval decisions, change permissions, or
|
|
659
677
|
answer its own pending questions. The application renders decisions obtained from the existing
|
|
660
678
|
controller and returns the person's answer through these calls.
|
|
679
|
+
The frontend waits on revisioned decision snapshots instead of polling continuously; a bounded wait
|
|
680
|
+
and reconnect resynchronize the inbox after a lost connection.
|
|
661
681
|
|
|
662
682
|
Approval prompts offer **Allow once**, **Always allow this tool everywhere** when the host policy
|
|
663
683
|
marks the decision rememberable, and **Deny**. A tool grant covers every call with that tool name
|
|
@@ -768,9 +788,12 @@ file size separated by ` · `. One blank line separates each session. Enter resu
|
|
|
768
788
|
session; account and folder scope checks
|
|
769
789
|
remain enforced. Supplying an explicit path continues directly without opening the picker.
|
|
770
790
|
The `$` palette completes enabled skill invocations using the same two-column palette as slash
|
|
771
|
-
commands; `/skills` always browses skills. Choosing a skill inserts
|
|
772
|
-
|
|
773
|
-
|
|
791
|
+
commands, at any word start in the draft; `/skills` always browses skills. Choosing a skill inserts
|
|
792
|
+
`$name` at the caret without submitting. Every recognized `$name` that names a loaded skill uses the
|
|
793
|
+
blue accent in the composer, while its arguments, unavailable names and ordinary currency text keep
|
|
794
|
+
the normal color. Sending a message that contains `$name` makes that skill required for the request:
|
|
795
|
+
the terminal appends its text and the requirement as a hidden request-scoped message, and the
|
|
796
|
+
person's wording is sent unchanged. `/help` renders the command list as one
|
|
774
797
|
transcript entry, grouped under Core, Run, Model, Session, Inspect, Harness, Plugins and Prompts;
|
|
775
798
|
command names and descriptions wrap in aligned columns, with no blank rows between choices. `/plugins`
|
|
776
799
|
opens the focused local manager; its Packages tab installs, updates and removes packages with protected
|
|
@@ -781,8 +804,10 @@ terminal no longer has separate `/login`, `/trust`, `/bug`, `/changelog`, `/shar
|
|
|
781
804
|
`/import` commands. `/btw <question>` (or `/side <question>`) starts a separate Harness run with the
|
|
782
805
|
main run's effective instructions, visible conversation and redacted public tool inputs/results.
|
|
783
806
|
Hidden reasoning and image bytes are excluded; the side run has no tools. Its block puts the
|
|
784
|
-
question after `/btw`, shows the normal animated spinner while answering,
|
|
785
|
-
and hint by one blank row; it has no status labels.
|
|
807
|
+
question after `/btw`, shows the normal animated spinner while answering, renders the answer as
|
|
808
|
+
Markdown, and separates the answer and hint by one blank row; it has no status labels. Headings,
|
|
809
|
+
emphasis, lists, quotes, links, tables and fenced code keep the theme's markdown colours, and a
|
|
810
|
+
streaming answer re-renders as it grows. PageUp/PageDown browse a long answer and Ctrl+X
|
|
786
811
|
copies the full answer. Escape or either command with no question dismisses the dock and interrupts
|
|
787
812
|
only that side run; the main reply continues. `/stop` interrupts the current main reply. The `/accounts` page handles sign-in
|
|
788
813
|
and sign-out. `/components` browses reusable skills, prompts and rules; a confirmed skill or rule addition
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xingular/harness",
|
|
3
|
-
"version": "1.3.1-unstable.
|
|
3
|
+
"version": "1.3.1-unstable.4",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Xingular Harness — a Pi agent harness built on recursive harnessing (Harness²): versioned eight-component variants, refinement from evidence, multi-account sessions, a compiled prompt, project notes, tools, and MCP",
|
|
6
6
|
"repository": {
|
|
@@ -54,7 +54,9 @@
|
|
|
54
54
|
"solid-js": "^1.9.12",
|
|
55
55
|
"turndown": "^7.2.4",
|
|
56
56
|
"turndown-plugin-gfm": "^1.0.2",
|
|
57
|
+
"tweetnacl": "1.0.3",
|
|
57
58
|
"typebox": "^1.3.7",
|
|
59
|
+
"uqr": "0.1.3",
|
|
58
60
|
"yaml": "^2.8.1",
|
|
59
61
|
"zod": "^4.1.11"
|
|
60
62
|
},
|