@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,409 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: PROP-0049
|
|
3
|
+
title: Context attribution as a built-in capability
|
|
4
|
+
status: Implemented
|
|
5
|
+
created: 2026-10-28
|
|
6
|
+
updated: 2026-10-28
|
|
7
|
+
affects: [INV-PRM-6, INV-SRV-1, INV-PAR-1, INV-PAR-2, INV-RUN-7, 04-prompt.md, 10-server-protocol.md, 11-terminal.md, 14-surfaces-and-parity.md, parity.md]
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# PROP-0049: Context attribution as a built-in capability
|
|
11
|
+
|
|
12
|
+
## Problem
|
|
13
|
+
|
|
14
|
+
A person can see that a run is expensive but not where the context goes. The harness already
|
|
15
|
+
records every fact needed to answer it, and no surface shows the answer:
|
|
16
|
+
|
|
17
|
+
- `runs/<id>/context.json` holds the pack the run was given: each section's `title`, `size`
|
|
18
|
+
(characters), `budget`, `cut` and `sources`, plus `toolGroups` and the variant fingerprint
|
|
19
|
+
(`src/prompt/compile.ts`).
|
|
20
|
+
- `runs/<id>/events.jsonl` holds `context.snapshot` — the verbatim `systemPrompt`, the
|
|
21
|
+
`contextUpdate`, and every tool's `{name, description, parameters}` — and `usage.updated`, whose
|
|
22
|
+
`contextTokens` is the provider-measured size of the latest request and `contextWindow` the
|
|
23
|
+
model's limit (`src/sessions/contracts.ts`, emitted by `src/sessions/runner.ts`).
|
|
24
|
+
- `Pi` computes a live `{ tokens, contextWindow, percent }` for the session
|
|
25
|
+
(`getContextUsage()`), and its estimator is `ceil(chars / 4)`
|
|
26
|
+
(`node_modules/@earendil-works/pi-coding-agent/dist/core/compaction/compaction.js`).
|
|
27
|
+
|
|
28
|
+
What is missing is the attribution: a row per contributor, tokens, share of the window, and a
|
|
29
|
+
stack that reconciles to the measured total. The App shows a reply's context pack as a collapsed
|
|
30
|
+
`<details>` list of character counts (`App/src/modes/shared/ContextPackView.tsx`), and a single
|
|
31
|
+
`Meter` for "context at the end" (`App/src/modes/shared/SessionContextInspector.tsx`). The terminal
|
|
32
|
+
declares `model.contextWindow` on its status band and never renders it
|
|
33
|
+
(`src/terminal/tui/status.ts`). `usage.summary` carries no context fields at all
|
|
34
|
+
(`src/usage/types.ts`).
|
|
35
|
+
|
|
36
|
+
Attribution is something a person uses, so it belongs in the Harness with a terminal surface
|
|
37
|
+
before an App screen (`INV-PAR-1`, `INV-PAR-2`).
|
|
38
|
+
|
|
39
|
+
## What other harnesses show
|
|
40
|
+
|
|
41
|
+
Evidence is from the checkout in `external/` for open repositories, and from official docs for
|
|
42
|
+
Claude Code, Codex CLI and Gemini CLI. "Third-party" marks a claim read from a user report rather
|
|
43
|
+
than a vendor document.
|
|
44
|
+
|
|
45
|
+
| Harness | Where it shows | Rows / categories | % of window | Visual | Measured vs estimated | Thresholds | Actions from the view |
|
|
46
|
+
|---|---|---|---|---|---|---|---|
|
|
47
|
+
| **Claude Code** | `/context` command in the transcript; ring in the desktop panel; scriptable status line | `System prompt`, `System tools`, `MCP tools`, `Custom agents` (with source), `Memory files`, `Skills`, `Messages`; plus `Autocompact buffer` and `Free space` | Per row and in the header `598.5k / 1M (60%)` | "Colored grid" (docs); a table of tokens + % in the panel (**third-party**, [issue #94436](https://github.com/anthropics/claude-code/issues/94436)) | Estimated per row; header from measured | Ring blue → yellow → red; over-limit banner naming `/compact` | Text suggestions only ("trim CLAUDE.md · 49k per request"); `/usage` can apply some |
|
|
48
|
+
| **Pi** (the engine under this harness) | TUI footer segment | One aggregate: `45.3%/200K (auto)` plus `↑in ↓out R<cache> W<cache> CH<hit>% $cost` (`dist/modes/interactive/components/footer.js:133-200`) | Yes, one decimal | Text, coloured | `getContextUsage()` = measured usage anchored, tail estimated at chars/4 | `>70` warning, `>90` error; `?/window` when unknown | `/compact` |
|
|
49
|
+
| **opencode** | Sidebar block + prompt footer (`external/opencode/packages/tui/src/feature-plugins/sidebar/context.tsx:20-51`, `prompt/footer.tsx:38-55`) | One aggregate: `N tokens`, `N% used`, `$cost` | Rounded integer | Plain text, no bar, no colour | Last provider usage only (`util/session.ts:46-61`) | None | `<leader>c` / `/compact`; auto-compact reserves 15% or 16k |
|
|
50
|
+
| **oh-my-pi (omp)** | Status-line segment system (`external/omp/packages/tui/src/status-line/footer.ts:171-260`) | One aggregate: `45.3%/200K`, per-direction counters, billing | One decimal | Coloured text, segment priorities | Provider-anchored, tail estimated; strict/approximate/upperbound tokenizer modes | Percent **or** absolute tokens, whichever first: 50%/150k, 70%/270k, 90%/500k (`chrome/context-thresholds.ts:6-11`) | `/compact` modes, `/shake` (drop heavy tool results), `/handoff` |
|
|
51
|
+
| **DeepSeek Harness** | Web chat statistics dock; per-turn disclosure (`external/deepseek-harness/packages/client/ui-chat`) | `systemTokens`, `toolsTokens`, `messageTokens` — exactly three (`packages/llm/token-meter/README.md`) | Separate `contextPressure.pressureTokens`; the division is client-side | Not confirmed | Explicit: provider usage reused only on an identical request envelope, else estimated; rows are "approximate composition, never a total" | Compaction at `min(W×0.8, W−O−65536)` | `/compact`; tool-result pruning |
|
|
52
|
+
| **Kimi CLI** | Status bar, right-aligned (`external/kimi-cli/src/kimi_cli/ui/shell/prompt.py:2251`, `soul/__init__.py:80`) | One aggregate: `context: 42.0% (4.2k/10.0k)` | Percent first | Plain text | Last provider usage (lags one request) | Ratio 85% **or** 50k reserve (`soul/compaction.py:59`) | `/compact`, `/clear` |
|
|
53
|
+
| **Orca** | 16px SVG ring in the composer row, click/hover opens a popover (`external/orca/src/.../NativeChatContextUsageRing.tsx`) | Passes the underlying CLI's own categories through verbatim, with a `deferred` flag for on-demand context | Row % only, one decimal; ring clamps, stored value does not | Ring + `Progress` bar in the popover | Three states: `report`, `estimate`, `unknown`; window held separately from used | `CRITICAL_PERCENTAGE = 90` turns the ring destructive | None — read-only |
|
|
54
|
+
| **Codex CLI** | `/status` prints configuration and "remaining context capacity"; `/statusline` picks footer fields (`developers.openai.com/codex/cli/slash-commands`) | No breakdown | Remaining capacity | Configurable footer items: model / context / limits / git / tokens / session | Not documented | Not documented | `/compact` |
|
|
55
|
+
| **Gemini CLI** | `/stats` full-screen report (`external`-free; `docs/reference/commands.md:438-450`) | `session` (duration, tool calls), `model` (token counts, quota), `tools` (per-tool) | Not in the documented output | Text tables | Not documented | Not documented | `/compress` |
|
|
56
|
+
|
|
57
|
+
Distinctive ideas worth keeping, by harness: **Claude Code** — a stack closed by `Autocompact
|
|
58
|
+
buffer` + `Free space`, and the remedy named inside the view. **Pi** — `?` when the window is
|
|
59
|
+
unknown rather than `0%`. **opencode** — one `formatContextUsage` helper shared by every surface, so
|
|
60
|
+
they cannot disagree. **omp** — warn on percent *or* absolute tokens (small windows warn at the
|
|
61
|
+
same absolute size) and a declared drop order for narrow terminals. **DeepSeek** — three separate
|
|
62
|
+
projections (billing, occupancy, composition), never mixed into one number. **Kimi** — percent
|
|
63
|
+
first, `used/total` in parentheses, readable at 30 columns. **Orca** — show the provider's own
|
|
64
|
+
category names instead of inventing a taxonomy, and mark deferred context as deferred. **Codex** —
|
|
65
|
+
the person chooses which fields the always-on strip carries.
|
|
66
|
+
|
|
67
|
+
## Affected rules
|
|
68
|
+
|
|
69
|
+
- **INV-PRM-6** Each run's pack is recorded beside the run; failing to record it never fails the
|
|
70
|
+
session. Attribution reads that record and adds per-section rendered sizes to it. Recording
|
|
71
|
+
stays best-effort.
|
|
72
|
+
- **INV-SRV-1** `src/server/methods.ts` is the contract for every non-Node host. `context.attribution`
|
|
73
|
+
is additive: no existing method, param or result shape changes.
|
|
74
|
+
- **INV-RUN-7** Token accounting keeps its meaning. `usage.updated.contextTokens` stays the
|
|
75
|
+
provider's figure for the latest request; attribution never rewrites it, and marks every row it
|
|
76
|
+
derived as estimated.
|
|
77
|
+
- **INV-PAR-1 / INV-PAR-2** The capability lands in the Harness with a terminal surface, and the App
|
|
78
|
+
presents the same rows from the same method.
|
|
79
|
+
- **INV-PRM-1** The prompt is still assembled only in `src/prompt/compile.ts`. Attribution measures
|
|
80
|
+
what that compiler produced; it never assembles text.
|
|
81
|
+
|
|
82
|
+
## Proposal
|
|
83
|
+
|
|
84
|
+
### 1. The measurement model
|
|
85
|
+
|
|
86
|
+
Three facts are read, and nothing new is written per request:
|
|
87
|
+
|
|
88
|
+
| Fact | Source | Kind |
|
|
89
|
+
|---|---|---|
|
|
90
|
+
| `systemPrompt`, `contextUpdate`, `tools[]` | `context.snapshot` event | recorded verbatim |
|
|
91
|
+
| `contextTokens`, `contextWindow` | latest `usage.updated` event | **measured** by the provider |
|
|
92
|
+
| sections, `toolGroups`, variant, `delivery` | `runs/<id>/context.json` | recorded at compile time |
|
|
93
|
+
|
|
94
|
+
One constant, `CHARS_PER_TOKEN = 4`, the same ratio Pi, opencode, DeepSeek and Kimi use, so a row
|
|
95
|
+
in this view and the terminal's status band never disagree by more than rounding.
|
|
96
|
+
|
|
97
|
+
`compile.render()` records the rendered size of each section (including the `## Title` framing and
|
|
98
|
+
the gaps between sections) and, inside a section, the characters contributed by each `Source`. That
|
|
99
|
+
is the only change to recorded data: it removes the need to re-parse a prompt later, which cannot
|
|
100
|
+
be done safely because a variant section's body may itself contain `## ` headings.
|
|
101
|
+
|
|
102
|
+
Rows are built in this order, and the last one is a subtraction rather than an estimate:
|
|
103
|
+
|
|
104
|
+
1. **System prompt sections** — each `Section`'s rendered characters ÷ 4, attributed to the group
|
|
105
|
+
that owns it.
|
|
106
|
+
2. **Tool schemas** — `JSON.stringify({name, description, parameters})` ÷ 4 for each recorded tool,
|
|
107
|
+
grouped by the pack's `toolGroups`; a tool in no group becomes `Other tools`.
|
|
108
|
+
3. **This request's update** — the recorded `contextUpdate` ÷ 4.
|
|
109
|
+
4. **Conversation** — `contextTokens − tokens(1..3)`, floored at zero. When the subtraction would go
|
|
110
|
+
negative the prefix rows are scaled down and the view says the prefix estimate exceeded the
|
|
111
|
+
measured total; it never shows a negative row.
|
|
112
|
+
5. **Compaction reserve** — Pi's `settings.compaction.reserveTokens` (default 16 384) when
|
|
113
|
+
auto-compaction is on.
|
|
114
|
+
6. **Free space** — `contextWindow − contextTokens − reserve`, so the stack sums to the window with the
|
|
115
|
+
reserve shown as its own row (the reserve is headroom the next request may not use, not free space).
|
|
116
|
+
|
|
117
|
+
The rows therefore always add up to the window, and the number in the header is always the
|
|
118
|
+
provider's. A run with no `usage.updated` yet shows estimated rows and marks the header
|
|
119
|
+
`estimate only`; a session whose window is unknown shows `/ ?` like Pi, never `0%`.
|
|
120
|
+
|
|
121
|
+
### 2. The row taxonomy: foundation, variant, application, conversation
|
|
122
|
+
|
|
123
|
+
This is where the harness can say something no other harness can. Rows group by *who owns the
|
|
124
|
+
text*, and variant rows say whether they cost every request:
|
|
125
|
+
|
|
126
|
+
| Group | Members | Owner |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| **Foundation** | Harness identity, tool guidance, tool schemas (History, Wiki, Native, World, Progress, Session, Annotations), Wiki pointer, session state, references, reporting rules | released harness |
|
|
129
|
+
| **Variant c1–c8** | Instructions (c1), Guardrails (c2), Memory (c3), Tool guidance (c4), subagent index (c5), skills index (c6), scripts index (c7) | `variant/`, refinable |
|
|
130
|
+
| **Your application** | Identity, role, working folder, skills, plugin descriptions, connected apps, annotations | the host's sections and tool groups |
|
|
131
|
+
| **Conversation** | Messages and tool results (measured residual), context updates | the run |
|
|
132
|
+
| **Reserved and free** | Compaction reserve, free space | Pi, the model |
|
|
133
|
+
|
|
134
|
+
Two facts make the variant rows actionable: `alwaysOnMax` caps always-on variant text at 24 000
|
|
135
|
+
characters (`src/variant/surface.ts`), and only components with `reach: 'always'` occupy the prompt
|
|
136
|
+
on every request. The view therefore shows a **budget meter per variant row** (`3.6K of 24K`) and a
|
|
137
|
+
separate **on demand** list — skills, subagents, scripts — which are not in this request but will
|
|
138
|
+
cost about *n* tokens when loaded. Claude Code shows a `Skills` row without that distinction; Orca
|
|
139
|
+
has the `deferred` flag but no per-row cost. Showing both is the improvement.
|
|
140
|
+
|
|
141
|
+
The foundation/variant split also gives the view its one obvious action: a variant row deeper than
|
|
142
|
+
the cap, or plainly oversized, links to the Harness screen where it is edited or refined.
|
|
143
|
+
|
|
144
|
+
### 3. Surfaces
|
|
145
|
+
|
|
146
|
+
**Harness (reference terminal).** A `/context` full-screen page built like `/usage`:
|
|
147
|
+
`src/terminal/tui/pages/contextPage.ts`, registered in `commandPages.ts` as a command page, reading
|
|
148
|
+
`context.attribution`. It also fills the gap in `src/terminal/tui/status.ts`, whose band declares
|
|
149
|
+
`model.contextWindow` and never paints it: the band gains `45.3%/200K` in the same place Pi puts it.
|
|
150
|
+
|
|
151
|
+
**Server.** One additive method:
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
context.attribution { runId }
|
|
155
|
+
→ {
|
|
156
|
+
runId, model, provider, window, used, share, // numbers the provider reported
|
|
157
|
+
source: 'measured' | 'estimate', // which of the above is trusted
|
|
158
|
+
compaction: { enabled, reserveTokens, thresholdTokens } | null,
|
|
159
|
+
rows: [{ id, title, group, tokens, chars, share, always, estimated, cut?,
|
|
160
|
+
budget?, sources?, tools?, note? }],
|
|
161
|
+
onDemand: [{ id, title, tokens, items }],
|
|
162
|
+
totals: { foundation, variant, application, conversation, reserved },
|
|
163
|
+
recordedAt
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`context.runPack` keeps returning the text; the App already calls it from
|
|
168
|
+
`App/src/bridge/commands.ts:642`, and the new page uses it to show a row's actual prompt slice.
|
|
169
|
+
|
|
170
|
+
**App.** A full-width page, not a sidebar tab — the sidebar is ~360–420 px wide, and a 6-column
|
|
171
|
+
accounting sheet needs the main pane:
|
|
172
|
+
|
|
173
|
+
- `ContextAttributionPage` in the main pane, opened from (a) the Context view's header, (b) a
|
|
174
|
+
compact meter in the composer footer, (c) the command palette. It uses the same host pattern as
|
|
175
|
+
agent configuration: a header strip with a close control
|
|
176
|
+
(`App/src/modes/solo/SoloWorkspace.tsx:263-265`).
|
|
177
|
+
- The compact meter reuses `Meter` (`variant="ring"`) from `@xingular/ui` and opens the page.
|
|
178
|
+
- The stack and its legend reuse `SegmentedBar` from `@xingular/ui/ui/charts`, whose `Segment` type
|
|
179
|
+
is already `{ key, label, value, color, display, share, title, recorded }` — exactly this page.
|
|
180
|
+
- A cache strip uses `CacheUsageBadge` and `formatTokens` from
|
|
181
|
+
`App/src/modes/shared/usage/usageModel.ts`.
|
|
182
|
+
|
|
183
|
+
### 4. Sketches
|
|
184
|
+
|
|
185
|
+
A rendered version of these sketches, in the dark theme with the shared tokens, is
|
|
186
|
+
[`outputs/context-attribution-sketch.html`](../../../../outputs/context-attribution-sketch.html)
|
|
187
|
+
(open it in a browser; four tabs, switchable). All three options use one dataset, and the rows add
|
|
188
|
+
to the provider's measured total.
|
|
189
|
+
|
|
190
|
+
**Option A — accounting sheet (Claude Code's shape, this harness's rows).** Recommended.
|
|
191
|
+
|
|
192
|
+
```
|
|
193
|
+
┌─ Context ────────────────────────────────────────────────────────────────────────────────┐
|
|
194
|
+
│ claude-sonnet-4-6 · 1M window · run r-8f21 auto-compact at 983.6K [x] │
|
|
195
|
+
│ │
|
|
196
|
+
│ 183.4K / 1M · 18.3% measured · provider-reported │
|
|
197
|
+
│ ████████▓▓▓▓▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
|
|
198
|
+
│ ├ foundation 13.1K ┤├ variant 18.4K ┤├ app 9.8K ┤├ conversation 142.1K ┤ │
|
|
199
|
+
│ │
|
|
200
|
+
│ ALWAYS IN CONTEXT TOKENS SHARE OF BUDGET │
|
|
201
|
+
│ v Foundation · harness 13.1K 1.3% │
|
|
202
|
+
│ Harness identity 29 0.0% 29 / 1.0K chars │
|
|
203
|
+
│ Tool guidance 1.9K 0.2% 1.9K / 8.0K chars │
|
|
204
|
+
│ Tool schemas · 34 tools 9.4K 0.9% │
|
|
205
|
+
│ History 3 · Wiki 6 · Native 6 · World 5 · Connections 7 · Other 7 │
|
|
206
|
+
│ Wiki pointer 1.1K 0.1% 1.1K / 2.5K chars │
|
|
207
|
+
│ Reporting rules 712 0.1% 712 / 2.0K chars │
|
|
208
|
+
│ Session state · references 0 0.0% no update this request │
|
|
209
|
+
│ v Variant · c3 · 9a1f 18.4K 1.8% │
|
|
210
|
+
│ Instructions (c1) 8.2K 0.8% 8.2K / 24K chars │
|
|
211
|
+
│ Guardrails (c2) 4.1K 0.4% │
|
|
212
|
+
│ Memory (c3) 3.6K 0.4% │
|
|
213
|
+
│ Tool guidance (c4) 2.5K 0.3% │
|
|
214
|
+
│ v Your application 9.8K 1.0% │
|
|
215
|
+
│ Identity · Role · Working folder 2.4K 0.2% │
|
|
216
|
+
│ Skills index · 12 skills 1.1K 0.1% │
|
|
217
|
+
│ Connected apps · 7 tools 6.3K 0.6% │
|
|
218
|
+
│ v Conversation 142.1K 14.2% measured by subtraction │
|
|
219
|
+
│ Messages and tool results 142.1K 14.2% │
|
|
220
|
+
│ │
|
|
221
|
+
│ RESERVED AND FREE │
|
|
222
|
+
│ Compaction reserve 16.4K 1.6% Pi, auto-compaction │
|
|
223
|
+
│ Free space 800.2K 80.0% │
|
|
224
|
+
│ │
|
|
225
|
+
│ ON DEMAND · not in this request when loaded │
|
|
226
|
+
│ Skills c6 · 12 available ~ 4.2K per skill │
|
|
227
|
+
│ Subagents c5 · 3 available own context each │
|
|
228
|
+
│ │
|
|
229
|
+
│ Rows are estimated from recorded character counts (÷ 4) and reconciled to │
|
|
230
|
+
│ the provider measured 183.4K; Conversation is the remainder, so the rows add │
|
|
231
|
+
│ to the whole. │
|
|
232
|
+
└──────────────────────────────────────────────────────────────────────────────────────────┘
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
**Option B — ledger plus detail pane.** The same rows on the left; selecting one shows what it is
|
|
236
|
+
on the right: the prompt text, the section's sources and revision, and the actions that apply.
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
┌───────────────────────────────────────────────┬──────────────────────────────────────────┐
|
|
240
|
+
│ CONTEXT ██████████░░░░░░░░░░ 18.3% │ Instructions (c1) │
|
|
241
|
+
│ 183.4K of 1M · sonnet-4-6 · 34 tools │ ───────────────────────────────────── │
|
|
242
|
+
│ │ 8.2K tokens · 0.8% of the window │
|
|
243
|
+
│FOUNDATION 13.1K 1.3%│ always in context · 8.2K / 24K chars │
|
|
244
|
+
│ Harness identity 29 0.0%│ variant c3 · fingerprint 9a1f │
|
|
245
|
+
│ Tool schemas 9.4K 0.9%│ source systemprompt.md │
|
|
246
|
+
│ Tool guidance 1.9K 0.2%│ +----------------------------------+ │
|
|
247
|
+
│ Wiki pointer 1.1K 0.1%│ | You are the person's assistant, | │
|
|
248
|
+
│ Reporting 712 0.1%│ | working with them directly in | │
|
|
249
|
+
│VARIANT · c3 18.4K 1.8%│ | this session: research, writing | │
|
|
250
|
+
│ Instructions c1 8.2K 0.8%│ | and coding in its working folder | │
|
|
251
|
+
│ Guardrails c2 4.1K 0.4%│ +----------------------------------+ │
|
|
252
|
+
│ Memory c3 3.6K 0.4%│ [Open in Harness] [Refine this] │
|
|
253
|
+
│ Tool guidance c4 2.5K 0.3%│ │
|
|
254
|
+
│YOUR APPLICATION 9.8K 1.0%│ │
|
|
255
|
+
│CONVERSATION 142.1K 14.2%│ │
|
|
256
|
+
│RESERVED 16.4K 1.6%│ │
|
|
257
|
+
│FREE 800.2K 80.0%│ │
|
|
258
|
+
└───────────────────────────────────────────────┴──────────────────────────────────────────┘
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
**Option C — growth over the session.** A second tab for the same page: the stack at each request,
|
|
262
|
+
so "what grew" is visible. Compaction markers come from `compaction.ended` (`tokensBefore`,
|
|
263
|
+
`tokensAfter`), which the run already records.
|
|
264
|
+
|
|
265
|
+
```
|
|
266
|
+
┌ Growth ───────────────────────────────────────────────────────────────────────────────────┐
|
|
267
|
+
│ 1M ┤│
|
|
268
|
+
│ │ ╭── 44.2K│
|
|
269
|
+
│ 20% ┤ ╭──╮ ╭──╮ ╭───╮ ╭────╮ ╭─────╯│
|
|
270
|
+
│ │ ╭──╮ │ │ │ │ │ │ │ │ │ │
|
|
271
|
+
│ 0% ┼──────┴──┴────┴──┴───┴──┴───┴───┴───┴────┴───┴─────┬─────────────── requests →│
|
|
272
|
+
│ r1 r2 r3 r4 r5 r6 r7 r8 ⧗ compacted 112K → 31K│
|
|
273
|
+
│ │
|
|
274
|
+
│ foundation ▓ variant ▒ application ░ conversation █ each segment a group│
|
|
275
|
+
└──────────────────────────────────────────────────────────────────────────────────────────┘
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
**The compact meter** — one always-visible readout, everywhere, opening the page:
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
App composer footer Terminal status band
|
|
282
|
+
┌────────────────────────────────────┐ ~/project (main) · account · sonnet-4-6
|
|
283
|
+
│ ▸ model sonnet-4-6 ◔ 18% ↑ ⏎ │ ↑12.1k ↓3.4k R84.9k 18.3%/1M
|
|
284
|
+
└────────────────────────────────────┘ └─ click / /context ─────────────────
|
|
285
|
+
ring colour: 18% data-1 · 80% warning · 95% destructive
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
**The terminal page** (`/context`), for reference:
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
Context sonnet-4-6 · 1M 18.3% used · measured
|
|
292
|
+
████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
|
|
293
|
+
foundation 13.1K 1.3% ██
|
|
294
|
+
variant 18.4K 1.8% █
|
|
295
|
+
your app 9.8K 1.0% ▌
|
|
296
|
+
conversation 142.1K 14.2% ██████
|
|
297
|
+
reserved 16.4K 1.6% █
|
|
298
|
+
free 800.2K 80.0% (dim)
|
|
299
|
+
j/k move · enter open · v variant · c compact · r refresh · q close
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### 5. Honesty rules the view must keep
|
|
303
|
+
|
|
304
|
+
Taken from the mistakes of the harnesses above, and from `INV-RUN-7`:
|
|
305
|
+
|
|
306
|
+
1. The header number is the provider's, or the word `estimate`.
|
|
307
|
+
2. `Conversation` is a subtraction, never a guess, and is labelled `measured by subtraction`.
|
|
308
|
+
3. Free space is `window − measured − reserve`, never `window − listed rows` — the Claude Code #94436
|
|
309
|
+
report is exactly that bug.
|
|
310
|
+
4. A row that could not be measured is `not recorded`, not `0`.
|
|
311
|
+
5. An unknown window is `/?`, never `0%`.
|
|
312
|
+
6. Rows are `approx` in the copy, and the page states the ratio once.
|
|
313
|
+
7. No number is recomputed from a provider's figure in a way that changes its meaning; a scaled row
|
|
314
|
+
is marked scaled.
|
|
315
|
+
|
|
316
|
+
### 6. What this proposal does not do
|
|
317
|
+
|
|
318
|
+
- No tokenizer. `chars / 4` is the house constant; a real tokenizer would need the provider's
|
|
319
|
+
encoding per model and would still not reconcile with the measured total.
|
|
320
|
+
- No new storage. Everything is read from files the harness already writes, plus the rendered sizes
|
|
321
|
+
added to the pack (`INV-PRM-6`, `INV-MEM-5` untouched).
|
|
322
|
+
- No new writer for run records or the ledger.
|
|
323
|
+
- No cost attribution per row in the first surface. Cost per request exists (`pricing.ts`) and can
|
|
324
|
+
be added as a column later without changing the model.
|
|
325
|
+
|
|
326
|
+
## Alternatives
|
|
327
|
+
|
|
328
|
+
- **Do nothing.** The App already shows a pack's character counts and one meter. The gap is the
|
|
329
|
+
share of the window per contributor, the free space, and the variant's always-on cost — the three
|
|
330
|
+
questions a person actually asks.
|
|
331
|
+
- **A tab in the existing sidebar Context view.** Rejected: the sidebar is too narrow for a six
|
|
332
|
+
column table, and the request is explicitly a full-width page.
|
|
333
|
+
- **Client-side computation in the App.** Rejected by `INV-PAR-1`: the terminal needs the same rows,
|
|
334
|
+
and two implementations of the subtraction rule would drift.
|
|
335
|
+
- **Reuse `usage.summary`.** Rejected: that is a period aggregate over the ledger. Attribution is
|
|
336
|
+
one request's composition, and `UsageTotals` has no context fields.
|
|
337
|
+
- **Full tokenizer.** Rejected: see above; it would also make the view disagree with Pi's own
|
|
338
|
+
footer, which is the number a person already sees.
|
|
339
|
+
|
|
340
|
+
## Consequences
|
|
341
|
+
|
|
342
|
+
- **Applications.** One new method, additive. A host that shows the page reads
|
|
343
|
+
`context.attribution`; a host that does not is unaffected.
|
|
344
|
+
- **Stored data.** `runs/<id>/context.json` gains a `rendered` size per section (and per source).
|
|
345
|
+
Older packs lack it; the view falls back to `size` and marks the section `approximate`.
|
|
346
|
+
- **Protocol.** One new method name and result shape; no `PROTOCOL_VERSION` change.
|
|
347
|
+
- **Spec.** `04-prompt.md` gains the recorded rendered sizes; `11-terminal.md` gains `/context`;
|
|
348
|
+
`14-surfaces-and-parity.md` and `parity.md` gain the row.
|
|
349
|
+
|
|
350
|
+
## Migration
|
|
351
|
+
|
|
352
|
+
Nothing to migrate. Packs recorded before this change stay readable; the only difference is the
|
|
353
|
+
`approximate` marker on rows whose rendered size was not recorded. The capability can be removed by
|
|
354
|
+
deleting the page, the method and the extra pack field; no data depends on it.
|
|
355
|
+
|
|
356
|
+
## Checks
|
|
357
|
+
|
|
358
|
+
- Harness: `npm run typecheck`, `npm test`, `npm run prove`.
|
|
359
|
+
- New unit tests: the reconciliation (rows sum to `contextTokens`), the negative-prefix case, a pack
|
|
360
|
+
with no `usage.updated`, a pack with no `delivery`, and a run with unknown `contextWindow`.
|
|
361
|
+
- Terminal: a page test in the style of `usagePage.test.ts`.
|
|
362
|
+
- App: `npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`, and
|
|
363
|
+
`cd src-tauri && cargo test`.
|
|
364
|
+
- A visual check of both surfaces against one real run, comparing the header figure with the
|
|
365
|
+
terminal status band and with Pi's own footer.
|
|
366
|
+
|
|
367
|
+
## What shipped
|
|
368
|
+
|
|
369
|
+
- `prompt/compile.ts` renders the pack with `renderSized` and records `delivery.sizes` (system and
|
|
370
|
+
update maps plus framing); `render()` is unchanged byte for byte. The sizes are recorded in place of
|
|
371
|
+
the per-section `rendered?: number` the design proposed: one map, keyed by the ids that already
|
|
372
|
+
name the sections.
|
|
373
|
+
- `sessions/contracts.ts` records `compaction: { enabled, reserveTokens }` in `context.snapshot`, read
|
|
374
|
+
from the Pi session's own settings; absent stays absent.
|
|
375
|
+
- `context/attribution.ts` builds the rows, the measured reconciliation, the reserve and free space,
|
|
376
|
+
the per-request history, the compaction markers and the on-demand list. `context.attribution` is a
|
|
377
|
+
new server method; `terminal.context` resolves the terminal's latest run, so no surface passes a
|
|
378
|
+
run id it could not verify.
|
|
379
|
+
- The bar is segmented: one colour per kind of context (the App's `--data-1..4` on both surfaces), the
|
|
380
|
+
track for free space, and a `│` where the reserve begins. The terminal's palette lives in
|
|
381
|
+
`terminal/tui/theme.ts` as `SERIES_COLORS`; the shared `SegmentedBar` grew `track`, `marker` and
|
|
382
|
+
`height` so the App draws one bar instead of a single-tone meter above a split. Severity moved to
|
|
383
|
+
the percentage text, on one rule for both surfaces: amber at 80, red at 95.
|
|
384
|
+
- The terminal `/context` page shipped with the one-column ledger and the detail replacing the list on
|
|
385
|
+
`enter` (the side-by-side panes in Option B were not built); `g` regroups by owner or kind, `c`
|
|
386
|
+
compacts after a confirmation, `v` navigates to `/harness`. The band and the OpenTUI status bar
|
|
387
|
+
gained the reading, shown only when the session knows it.
|
|
388
|
+
- The App gained `context.attribution` on the bridge, a full-width `ContextAttributionPage` opened from
|
|
389
|
+
the Context tab, and a context ring in the composer footer. The ring reports; it does not open the
|
|
390
|
+
page yet, so the Context tab is the only App entry point.
|
|
391
|
+
- `context.attribution` takes `{ runId }` only; the session-scoped case is `terminal.context`, which is
|
|
392
|
+
the surface that has a session rather than a run.
|
|
393
|
+
|
|
394
|
+
## Open questions
|
|
395
|
+
|
|
396
|
+
1. **Placement.** Full-width page in the main pane (recommended), a new workspace view tab that
|
|
397
|
+
renders full width, or a tab beside `Usage` in the sidebar? The sketches assume the first.
|
|
398
|
+
2. **Shape.** Option A (accounting sheet), A plus Option B's detail pane on wide windows, or all
|
|
399
|
+
three as tabs of one page?
|
|
400
|
+
3. **Rows.** Group by owner (foundation / variant / application / conversation), as proposed, or by
|
|
401
|
+
kind (`System prompt`, `Tools`, `Skills`, `Memory`, `Messages`) as Claude Code does? Owner
|
|
402
|
+
grouping is what makes the variant actionable; kind grouping is what a person coming from Claude
|
|
403
|
+
Code expects.
|
|
404
|
+
4. **Cost per row.** Show `cost per request` beside tokens from the first version, or keep the view
|
|
405
|
+
token-only?
|
|
406
|
+
5. **Live updates.** Refresh on every `usage.updated` while a reply streams, or on open and on
|
|
407
|
+
`completed` only?
|
|
408
|
+
6. **The compact meter.** Add the ring to the App composer footer, the terminal status band, or
|
|
409
|
+
both? Pi's footer already shows `45.3%/200K` and this harness's band shows neither.
|
|
@@ -75,9 +75,10 @@ it to the index and update its status as the work progresses.
|
|
|
75
75
|
| [PROP-0043](PROP-0043-read-only-plan-bash.md) | Read-only Bash in plan mode, enforced by the OS sandbox | Accepted; implemented | INV-RUN-8, INV-GATE-3/8, 02, 07, 11, terminal-tui, parity, ADR-0038 | 2026-10-26 |
|
|
76
76
|
| [PROP-0044](PROP-0044-work-slice-defaults.md) | Raise the work-slice defaults to 320 tool calls and 60 minutes, with no token cap | Accepted; implemented | INV-RUN-13, 02, 10, 11, PROP-0041 | 2026-10-26 |
|
|
77
77
|
| [PROP-0045](PROP-0045-rename-checklist-to-todo.md) | Rename the run checklist to todo and add the /todo command | Accepted; implemented | 02, 04, 06, 07, 10, 11, 14, parity, terminal-tui, README, PROP-0006 | 2026-10-26 |
|
|
78
|
-
| [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
|
|
78
|
+
| [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039, targeted protections superseded by ADR-0053 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
|
|
79
79
|
| [PROP-0047](PROP-0047-plugins-hub-separation.md) | Separate local plugin management from Community Hub discovery | Implemented; ADR-0041 | INV-MCP-4, INV-TUI-2/4, INV-PAR-1/2, 06, 09, 10, 11, 14, terminal-tui.md, parity.md | 2026-10-27 |
|
|
80
80
|
| [PROP-0048](PROP-0048-simple-annotate.md) | One annotate page, two actions, and easy app attach | Implemented; ADR-0044 | PROP-0018, 07, 10, 11, 13, terminal-tui.md, parity.md | 2026-10-27 |
|
|
81
|
+
| [PROP-0049](PROP-0049-context-attribution.md) | Context attribution: what fills the context window, by foundation, variant and application | Implemented | INV-PRM-6, INV-SRV-1, INV-PAR-1/2, INV-RUN-7, 04, 10, 11, 14, parity.md | 2026-10-28 |
|
|
81
82
|
|
|
82
83
|
Numbers are four digits, start at `0001`, and are never reused.
|
|
83
84
|
|
|
@@ -2,12 +2,16 @@
|
|
|
2
2
|
id: ADR-0039
|
|
3
3
|
title: Progress-aware stall guards and bounded plan research children
|
|
4
4
|
status: Accepted
|
|
5
|
+
superseded_by: ADR-0053 (targeted protections only)
|
|
5
6
|
created: 2026-10-27
|
|
6
7
|
proposal: PROP-0046
|
|
7
8
|
---
|
|
8
9
|
|
|
9
10
|
# ADR-0039: Progress-aware stall guards and bounded plan research children
|
|
10
11
|
|
|
12
|
+
The targeted repeated-call, repeated-failing-check and edit-churn protections decided here are
|
|
13
|
+
superseded by [ADR-0053](ADR-0053-no-repeated-work-guard.md); the rest of the decision stands.
|
|
14
|
+
|
|
11
15
|
## Decision
|
|
12
16
|
|
|
13
17
|
Remove the global file-change/check no-progress trigger. Keep the targeted protections for repeated
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0048
|
|
3
|
+
title: A skill named anywhere in a message is required for that request
|
|
4
|
+
status: Accepted
|
|
5
|
+
created: 2026-11-20
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# ADR-0048: A skill named anywhere in a message is required for that request
|
|
9
|
+
|
|
10
|
+
## Decision
|
|
11
|
+
|
|
12
|
+
- `$name` is a skill invocation at any word start in a message, not only as its first token. The
|
|
13
|
+
composer's palette opens at the caret and replaces only the token being typed; the rest of the
|
|
14
|
+
draft and its caret stay in place.
|
|
15
|
+
- Every `$name` that names a skill the session can load makes that skill required for the request.
|
|
16
|
+
The named skills travel as `Launch.requiredSkills`, and the prompt compiler renders them as the
|
|
17
|
+
dynamic `required-skills` section: the skill's text from the pinned variant, the directive to
|
|
18
|
+
follow it, and an honest line for a name the variant does not have. The shipped
|
|
19
|
+
`plugin-authoring` skill fills in when the variant has none.
|
|
20
|
+
- The section belongs to the request. `sessionLaunch` resends it like `references`, even when it is
|
|
21
|
+
identical to the previous snapshot.
|
|
22
|
+
- The terminal builds the same text with `requiredSkillsText` from Pi's loaded skills and appends it
|
|
23
|
+
as a hidden `xingular-required-skills` custom message. It no longer rewrites a leading `$name` to
|
|
24
|
+
`/skill:name`; the person's message reaches the model unchanged and the requirement is enforced at
|
|
25
|
+
every position.
|
|
26
|
+
- A required skill changes no tool and no permission: the run's callable set and the gate are
|
|
27
|
+
untouched. It is a prompt-level requirement, not a capability narrowing.
|
|
28
|
+
|
|
29
|
+
## Rationale
|
|
30
|
+
|
|
31
|
+
Pi expands only a leading `/skill:name`, so a mid-message skill was plain text and had no effect.
|
|
32
|
+
Moving the requirement into the request-scoped prompt text makes the same promise at every position,
|
|
33
|
+
keeps the stable prefix (and therefore the provider cache) intact, and gives the terminal and a host
|
|
34
|
+
one shared wording through `requiredSkillsText`.
|
|
35
|
+
|
|
36
|
+
## Consequences
|
|
37
|
+
|
|
38
|
+
A leading `$name` no longer depends on Pi's `/skill:name` expansion. The skill's text is delivered
|
|
39
|
+
once per request that names it, so repeating the same skill in several turns repeats its text in
|
|
40
|
+
native history; the model sees the most recent copy. The App's composer already inserts `$` chips
|
|
41
|
+
anywhere; its reference path now sends skills as `requiredSkills` rather than as pinned notes.
|
|
42
|
+
Skills that a variant does not contain are reported as unavailable rather than silently dropped.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# ADR-0050: Approved-window screenshot contract
|
|
2
|
+
|
|
3
|
+
## Decision
|
|
4
|
+
|
|
5
|
+
A host may supply `computer_screenshot` through the existing tool-provider extension point using
|
|
6
|
+
the Harness contract in `src/computer/screenshot.ts`. The backend must capture one currently
|
|
7
|
+
approved window and exclude the desktop, other windows and overlays, including overlapping ones.
|
|
8
|
+
If it cannot guarantee that scope it refuses without returning pixels; it never silently captures a
|
|
9
|
+
display instead. The adapter is opt-in, goes through the ordinary tool gate, and does not make
|
|
10
|
+
capture plan-mode safe. A host that also offers coordinate-based interactions interprets their
|
|
11
|
+
coordinates relative to the returned image pixels.
|
|
12
|
+
|
|
13
|
+
## Consequences
|
|
14
|
+
|
|
15
|
+
Browser screenshots remain a separate capability with their own tab isolation. The contract cannot
|
|
16
|
+
verify native backend isolation; each host must implement and test it. The existing macOS display
|
|
17
|
+
capture has not adopted this contract and is not evidence of approved-window isolation. The
|
|
18
|
+
standalone terminal has no such backend. The contract adds no automatic provider registration or
|
|
19
|
+
new extension point.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# ADR-0051: Revisioned terminal decision waits
|
|
2
|
+
|
|
3
|
+
The terminal needs timely approval and question updates while avoiding a control request every
|
|
4
|
+
100 ms in every idle session. The controller owns the pending inbox, so it exposes a private,
|
|
5
|
+
control-key-protected revisioned snapshot with a bounded wait. Every inbox mutation wakes waiters;
|
|
6
|
+
the frontend resynchronizes on reconnect. The existing immediate snapshot remains available.
|
|
7
|
+
|
|
8
|
+
The wait uses a separate socket request, so it does not block other terminal control calls.
|
|
9
|
+
Waits time out after 20 seconds and are woken on controller disposal. Client shutdown cancels its
|
|
10
|
+
request. No persisted state or public server protocol changes.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# ADR-0052: Per-profile and total subagent budgets
|
|
2
|
+
|
|
3
|
+
A run could start any number of children: `maxDepth` bounded nesting only. Run `90906235`
|
|
4
|
+
("Implement the plan: Safe screenshot capability", 2026-10-28) started 11 children in nine
|
|
5
|
+
minutes for a five-step plan — three spawns before the parent had read a file, five children that
|
|
6
|
+
returned no change, and two tasks retried as fresh children. The shape of delegation was left to
|
|
7
|
+
the prompt.
|
|
8
|
+
|
|
9
|
+
A run now starts only a bounded number of distinct child conversations. Foundation defaults: four
|
|
10
|
+
children in total, two `worker`, three `explorer`, one of any other named profile and one with no
|
|
11
|
+
profile. A host overrides them through `SessionRunInput.subagents` (`maxChildren`, `maxByProfile`,
|
|
12
|
+
`maxOther`, `maxUnprofiled`), so the terminal and the App receive the same defaults; every value
|
|
13
|
+
is an integer clamped to 0–50.
|
|
14
|
+
|
|
15
|
+
`Subagents.spawn` counts the run's recorded children in `subagents.json`, the children of the
|
|
16
|
+
parent runs it was continued from (`resumedFromRunId`), and slots reserved by concurrent calls. It
|
|
17
|
+
deduplicates a continuation to its first link, so continuing a stopped child uses no new slot,
|
|
18
|
+
while a child whose startup failed still counts. A refused spawn returns an `invalid_request`
|
|
19
|
+
tool result telling the model to do the work itself; it creates no run. `continue` bypasses the
|
|
20
|
+
check because it is the same child.
|
|
21
|
+
|
|
22
|
+
The budget is per run, not per conversation, so a long chat is not starved. It lives in the
|
|
23
|
+
foundation because it bounds what every application built on the harness may spend, and changing
|
|
24
|
+
it needs a release. A host that legitimately needs more children raises the limits for its
|
|
25
|
+
session; the spawn tool's description states the effective numbers.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0053
|
|
3
|
+
title: No repeated-work guard in the work slice
|
|
4
|
+
status: Accepted
|
|
5
|
+
created: 2026-10-28
|
|
6
|
+
supersedes: ADR-0039 (targeted protections only)
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# ADR-0053: No repeated-work guard in the work slice
|
|
10
|
+
|
|
11
|
+
## Decision
|
|
12
|
+
|
|
13
|
+
Remove the repeated-work rules from the shared work-slice guard (`src/sessions/workSlice.ts`). A
|
|
14
|
+
reply is no longer refused for calling the same tool with the same arguments three times, for
|
|
15
|
+
running a Bash check that failed twice, or for more than four successful `edit`/`write` results on
|
|
16
|
+
one path. Nothing ends a reply as `stuck`.
|
|
17
|
+
|
|
18
|
+
The bounds that remain are the configured tool-call, minute and new-token budget and the
|
|
19
|
+
third-compaction thrash rule, both of which still ask for a checkpoint handoff and end the reply on
|
|
20
|
+
further calls. A budget-ended reply is `interrupted` with terminal reason `slice_complete` in both
|
|
21
|
+
surfaces. Slice continuation, the plan-research child bound and the model-written `blocked`
|
|
22
|
+
checkpoint gate are unchanged.
|
|
23
|
+
|
|
24
|
+
`checkpointReasonSchema` keeps `stuck` so stored `checkpoint` events stay readable and the
|
|
25
|
+
`checkpoint_write` argument set does not change; nothing produces it any more.
|
|
26
|
+
|
|
27
|
+
## Rationale
|
|
28
|
+
|
|
29
|
+
The rules fired on calls that are ordinary work. Reading a file again, editing one file several
|
|
30
|
+
times, or re-running a check after a partial fix are not loops, and a refusal there costs a reply
|
|
31
|
+
plus the checkpoint and continuation round trip. Tool arguments are not a reliable signal of a loop:
|
|
32
|
+
a changed argument is different work, an identical argument can be legitimate (a poll, a re-read
|
|
33
|
+
after an edit, a retried check), and the guard cannot tell them apart. The reply budget already
|
|
34
|
+
bounds a model that never stops, which is the failure the guard existed to catch; the compaction
|
|
35
|
+
rule covers the other observed thrash.
|
|
36
|
+
|
|
37
|
+
## Consequences
|
|
38
|
+
|
|
39
|
+
A reply may repeat any call until its budget, so a genuinely stuck model runs up to 320 calls or 60
|
|
40
|
+
minutes instead of being stopped earlier. No run-event schema, stored-data layout, server method or
|
|
41
|
+
App presentation changes: `stuck` remains a readable checkpoint reason and `stalled` remains the
|
|
42
|
+
watchdog's reason for a silent run. This supersedes the targeted repeated-call, repeated-failing-check
|
|
43
|
+
and edit-churn protections in [ADR-0039](ADR-0039-progress-aware-stall-guards.md); the rest of that
|
|
44
|
+
decision, including the bounded plan-research child, stands. See also
|
|
45
|
+
[PROP-0041](../architecture/proposals/PROP-0041-bounded-work-slices.md).
|