dsh-github-copilot 0.4.0-alpha.87 → 0.4.0-alpha.91

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.
@@ -1,405 +1,194 @@
1
- # GitHub Copilot Auto model routing MVP
1
+ # GitHub Copilot Auto routing contracts
2
2
 
3
- **Tracking:** [#174](https://github.com/cloga/dsh-github-copilot/issues/174), [#192](https://github.com/cloga/dsh-github-copilot/issues/192), [#199](https://github.com/cloga/dsh-github-copilot/issues/199), [#258](https://github.com/cloga/dsh-github-copilot/issues/258)
4
-
5
- **Target:** official DSH and Windows Desktop `0.2.0-rc.2`
6
-
7
- **Boundary:** plugin-only; no Core source, artifact, registry, prototype, or history patch
8
-
9
- **Interactive mockup:** [`output/auto-model-mockup/index.html`](../output/auto-model-mockup/index.html)
3
+ Target: official DSH / Windows Desktop `0.2.0-rc.2`. Implementation is plugin-only.
4
+ For ordinary use, start with [task assessment and explanations](./auto-task-routing.md)
5
+ and [parent following](./parent-model-follow.md).
10
6
 
11
7
  ## User contract
12
8
 
13
- The managed `github-copilot-preview` provider contributes **Auto · Balance** (the existing `auto` ID), **Auto · Efficiency**, and **Auto · Intelligence** to the ordinary flat model picker. They never appear under another provider and never route across providers or accounts. Explicitly selecting another virtual preference preserves Auto intent; only a real model selection exits Auto.
14
-
15
- Selecting Auto uses normal Core selection behavior, including saving it as the future default selection. For every Core turn, the plugin resolves Auto to one real model from the authenticated account catalog:
16
-
17
- - one decision is made for the turn;
18
- - every model request, tool continuation, request-error retry, and compaction retry in that turn uses the same real model;
19
- - a later user turn or Goal continuation is a new turn and may select a different model;
20
- - an explicit real model selection always wins;
21
- - the actual model remains the provider transport, usage, replay, and billing identity.
22
-
23
- A Goal does not become one indefinitely frozen Auto decision. Each automatic continuation that Core opens as a new turn is classified independently. Tool steps inside that turn do not trigger another decision.
24
-
25
- ## Routing policy and input fit
26
-
27
- Image capability requirements cover all entered message content, including historical
28
- user and tool images, not only the latest user text. Actual projected MIME admission
29
- uses explicit account format evidence after native conversion; filenames and durable
30
- MIME are not wire-format proof. See [image compatibility and limits](./image-input-compatibility.md).
31
-
32
- The account `/models` catalog is authoritative for entitlement and hard capabilities: protocol, context and output limits, image input, tool support, reasoning efforts, and server policy. Unknown or incomplete capability metadata fails closed.
33
-
34
- The catalog supplies `model_picker_category` (`powerful`, `versatile`, `lightweight`), but not trustworthy measured quality, latency, price, or global-health rankings. Missing, invalid and new category values remain unclassified with diagnostics. The routing policy does **not** infer category from a marketing name, model-ID prefix, reasoning effort, context capacity or token price. It does not claim to reproduce GitHub's private Auto algorithm.
35
-
36
- ### Hard input fit check before preference
37
-
38
- Before applying soft preferences, routing checks whether each candidate can accommodate the estimated input tokens of the current turn:
39
-
40
- 1. **Input estimate:** `estimateTurnInputTokens` prices every entered Core message through the public native `tokenMeter.estimateMessage()`. Core reasoning, tool calls and tool results must not be passed to pi-ai's differently shaped message estimator or silently omitted on exceptions. The Host also retains `tokenMeter.measure(session).totalTokens` as a conservative floor for the current surface, native usage accounting and known tool envelope. Missing native measurement fails Auto with `COPILOT_AUTO_TOKEN_METER_UNAVAILABLE`; invalid numeric estimates fail with `COPILOT_AUTO_TOKEN_ESTIMATE_INVALID`. Explicit real-model selection does not require this Auto seam.
41
- 2. **Hard candidate budget:** For each candidate model, `calculateRequestBudget` calculates `hardInputLimit` given the model context window, output reservation, and safety allowance.
42
- 3. **Headroom filtering:** Candidates with insufficient headroom (`estimatedInputTokens > hardInputLimit`) are filtered out. If one or more fitting candidates exist, soft preference selects among the `fitting` subset.
43
- 4. **No-fit and compaction recovery:** If no candidate can fit the current messages:
44
- - Auto selects the candidate with the **largest input capacity** to give Core compaction maximum headroom.
45
- - Its in-memory routing decision includes a structured diagnostic (not a new durable event):
46
- - `fixed-content-cannot-fit`: the latest user turn alone exceeds maximum capacity and cannot be compacted away.
47
- - `compaction-unavailable`: compaction is disabled or has zero retries configured.
48
- - `attempted-but-still-oversized`: a compaction summary already exists in history and the turn remains oversized.
49
- - `compaction-eligible`: prior history is compressible and downstream dispatch will trigger compaction pressure.
50
- 5. **Final framing limitation:** The fresh entered-message estimate and current native envelope floor are not the final candidate-specific serialized request. Later framing, changed tools and native attachment projection can still exceed a candidate's budget. The native provider guard (`inspectRequest`) remains authoritative and truthfully rejects such a request with `COPILOT_CONTEXT_BUDGET_EXCEEDED` without bypassing safety boundaries.
51
-
52
- ### Task-aware supplier category preferences
53
-
54
- All three preferences use the *same* hard-eligible account pool. The default local
55
- assessment recognizes isolated greetings, explicit difficult reasoning or
56
- investigation, bounded explicit continuations of those difficult tasks, and
57
- isolated fenced mechanical transformations. Other tasks remain uncertain rather
58
- than guessing from length; insufficient local evidence does not mean the
59
- conversation lacks context.
60
- Default-enabled `github-copilot.autoSemanticAssessment` makes one
61
- bounded auxiliary native-adapter call to a concrete, non-excluded supplier
62
- Lightweight model only for locally unknown demand. It prioritizes the current
63
- and preceding user requests without removing omitted-context safeguards. It
64
- adds latency and supplier charges not included in native
65
- chat Usage. Set it to `false` to opt out; existing explicit false is preserved.
66
- This user-authorized default rollout does not claim labeled-corpus calibration.
67
-
68
- | Task demand | Efficiency | Balance (`auto`) | Intelligence |
69
- | --- | --- | --- | --- |
70
- | Proven simple | Lightweight | Lightweight | Lightweight |
71
- | Routine | Lightweight | Versatile | Powerful |
72
- | Complex | Powerful | Powerful | Powerful |
73
- | Unknown | Versatile | Versatile | Powerful |
74
-
75
- If the target category has no fitting model, follow the documented category
76
- fallback order, using unclassified models only last. Keep the previous managed
77
- model if it remains in the first available category and fits this turn.
78
- Otherwise use stable equal-weight Session/turn allocation within that category;
79
- ID ordering breaks ties, not quality rankings. Capacity and reasoning-effort
80
- bands no longer determine task quality. All steps/retries retain the decision.
81
-
82
- These are declared policies, not measured quality, speed or cost guarantees.
83
- Captured footer reasons show task evidence, selected/target category, fallback,
84
- continuity or equal tie-breaking, and no-fit recovery. Legacy records without
85
- details say the reasons were not retained; they never reconstruct history from
86
- today's settings. See [requirements, assessment limits and rollout](./auto-task-routing.md).
87
-
88
- The exact virtual preference stays in the Session's pending selection across turns, while each real request header and transport record the chosen account model. Switching to a real model ends automatic routing for subsequent turns. New turns no longer write a separate decision event; compatible historical events without a preference field remain Balance for display.
89
-
90
- ## Images
91
-
92
- Image input is part of the MVP.
93
-
94
- The virtual Auto picker entry advertises image input only when the current authenticated catalog contains at least one eligible image-capable model. At routing time, an image turn filters out every text-only candidate. If catalog changes leave no eligible image model, the turn fails with a named Auto routing error instead of sending the image to an unverified model.
95
-
96
- This preserves two separate checks:
97
-
98
- 1. Core's normal picker/admission path sees truthful aggregate Auto modalities.
99
- 2. The resolved real model is independently verified against the current account snapshot before transport.
100
-
101
- ## Context pressure and automatic compaction
102
-
103
- Auto may choose a model with a smaller context window than the previous turn. The plugin must not trim history, create a competing compaction service, or silently switch models during recovery.
104
-
105
- The resolved real model enters the existing managed-route request-budget path. If the estimated committed request exceeds that model's input budget, [`src/compaction-pressure.ts`](../src/compaction-pressure.ts) emits the normal `CONTEXT_WINDOW_EXCEEDED` signal before transport. Core's stock transactional compaction then:
106
-
107
- 1. summarizes and replaces eligible history;
108
- 2. rebuilds the request;
109
- 3. retries the same turn with the same resolved real model;
110
- 4. keeps the ordinary bounded overflow retry policy.
111
-
112
- The guarantee is limited to history whose summary request itself fits. Correcting the Auto estimate does not recover a session when every eligible model is too small for the existing summary input. A fixed prompt, current attachment, or indivisible content block that cannot fit after compaction remains an explicit error. See [Copilot compaction](./copilot-compaction.md).
113
-
114
- ## Search ownership
115
-
116
- Chat Auto does not own or alter the independent `github-copilot-hosted` search provider.
117
-
118
- - A nonempty explicit `searchModel` remains authoritative.
119
- - Automatic hosted-search candidate selection continues to use its own bounded account-owned Responses policy and capability proof.
120
- - Routed search that follows the initiating Chat request sees the durable real request header, not the virtual Auto ID.
121
- - The final query is still sent once; Chat Auto introduces no search replay or fallback.
9
+ The managed `github-copilot-preview` group provides **Auto · Balance** (`auto`),
10
+ **Auto · Efficiency** and **Auto · Intelligence** in Core's flat picker.
11
+ Only a real model selection exits Auto. Native selection also saves the future
12
+ global default; the plugin does not change that Core behavior.
13
+
14
+ Each admitted Core turn resolves to one real account model. Tool continuations,
15
+ native request retries and compaction retries retain it; a new user or Goal
16
+ turn can choose differently. Transport, replay, native Usage and billing retain
17
+ the actual model identity. Auto never crosses providers/accounts or changes an
18
+ explicit real-model selection.
19
+
20
+ The virtual preference remains the Session's pending selection while actual
21
+ request headers record real models. For an otherwise unselected Session that
22
+ inherits default Auto, the first request persists the exact virtual
23
+ `model/selection` intent. A later explicit selection wins. Existing fixed
24
+ Sessions are not converted because the global default changes.
25
+
26
+ ## Eligibility and input fit
27
+
28
+ Current authenticated account metadata establishes entitlement, endpoint,
29
+ context/input/output limits, tool/image support and reasoning capabilities.
30
+ Missing/invalid metadata produces diagnostics, not guessed capabilities.
31
+ Exact exclusions and independent account/proof/cancellation guards apply first.
32
+
33
+ The public native TokenMeter estimates every entered message, including
34
+ reasoning and tool history. Its current-surface measurement is an envelope
35
+ floor, not a substitute for candidate-specific final serialization.
36
+ Missing/invalid measurement fails with
37
+ `COPILOT_AUTO_TOKEN_METER_UNAVAILABLE` /
38
+ `COPILOT_AUTO_TOKEN_ESTIMATE_INVALID`.
39
+
40
+ Candidates fit when estimated input does not exceed the hard budget after
41
+ output reservation and safety allowance. If none fits, choose the largest
42
+ input budget for native recovery and explain whether content is fixed,
43
+ compaction unavailable, already attempted, or eligible. This is not permission
44
+ to dispatch an oversized request. The native managed `inspectRequest` guard
45
+ remains authoritative after final framing/attachment projection.
46
+
47
+ Task preference uses supplier `model_picker_category`, not capacity, model
48
+ names or reasoning effort as quality rankings. [Task policy](./auto-task-routing.md)
49
+ owns the demand matrix, default semantic assessment, category fallback,
50
+ continuity and stable same-category allocation.
51
+
52
+ ## Images, compaction and search
53
+
54
+ Image eligibility includes historical user/tool image blocks in all entered
55
+ messages, not only current user text. Text-only candidates are removed; Auto
56
+ advertises image input only with an eligible image model. Actual fixed/Auto
57
+ dispatch independently checks explicit account MIME restrictions against
58
+ Core's projected image. Missing MIME lists stay unverified.
59
+ [Image admission limits](./image-input-compatibility.md).
60
+
61
+ Auto does not trim history or own compaction transactions. Estimated pressure
62
+ uses the initiating Agent's public bound recovery service and preserves the
63
+ same real model. If the summary input already exceeds every eligible budget,
64
+ stock one-shot compaction cannot rescue it. [Budget admission](./copilot-compaction.md)
65
+ and [manual recovery](./manual-compaction-recovery.md) describe separate paths.
66
+
67
+ Chat Auto does not own independent hosted search. A nonempty `searchModel`
68
+ override remains authoritative; otherwise that provider uses bounded
69
+ account-owned Responses selection and capability proof. Auto-following search
70
+ sees the initiating real request route. No virtual model reaches transport,
71
+ and the final query is not replayed across candidates.
72
+ [Search routing](./session-search-routing.md).
122
73
 
123
74
  ## Attribution and explanation
124
75
 
125
- **Host binding follow-up (alpha.79, #254):** alpha.76 fixed Client argument
126
- projection, but the Host still provided selection reads as an ordinary
127
- `ctx.provide(..., { get })` object. That is not a Typert Remote service.
128
- The native strict Host gateway rejects it with `gateway/binding-invalid`
129
- before reading the store; source-mode discovery cannot expose the endpoint
130
- without a Remote binding and method marker. A fresh master reply can therefore
131
- show **Selection unavailable** even after the Client fix.
132
-
133
- `TurnSelectionController` now extends the published `TypertRemoteService` and
134
- marks `get` with `@Remote`, following the other plugin Host controllers. It wraps
135
- the same bounded `TurnSelectionStore`, with unchanged explicit Session/turn
136
- arguments, native Agent lookup/access checks, missing-evidence semantics and
137
- disposal. It does not append history, grant child access, infer a selection or
138
- alter Auto routing.
139
-
140
- Regression coverage crosses the actual Client gateway, in-process native Host
141
- connection and actual Host gateway in both source-discovery and strict modes.
142
- It reproduces the old registration failure and checks Auto, Manual, missing
143
- records, missing/denied identities, removal and service unload. An isolated
144
- process also exercised the unchanged rc.2 public modules bundled in the installed
145
- Desktop; this is contract evidence, not a query of the running Host or live
146
- model transport. The previous Client-only mock transport was insufficient
147
- evidence for Host reachability.
148
-
149
- **Fresh master/lead selection reads (alpha.76, #249):** the footer explicitly
150
- calls `get(viewedSessionId, turn)`. Its old Remote descriptor also declared an
151
- automatic `agent` scope projection. The unchanged rc.2 Client gateway prefers
152
- that projection when a Client context has an agent identity, removes the ID
153
- parameter from its expected arguments, and rejects this two-argument call with
154
- `expected 1 argument(s), got 2` before sending RPC. Existing root-context mocks
155
- did not exercise this behavior. This is a reproducible new-reply display failure,
156
- not evidence of missing historical decisions or an Auto routing failure.
157
-
158
- The descriptor now exposes only the direct two-argument Client call. Its native
159
- Host `agent` lookup, strict Session ID/turn/result codecs and method identity
160
- are unchanged. The viewed Session is never replaced by an ambient current
161
- Session. Native gateway regression runs the old descriptor to reproduce the
162
- rejection, then checks the fixed descriptor with both bound and unbound contexts.
163
- Host access checks are not bypassed: native child lookup restrictions remain a
164
- separate limitation, not the explanation for the reported master/lead case.
165
-
166
- Pending reads show **Loading selection…**; failed or invalid reads show
167
- **Selection unavailable** and an explicit **Retry**. Retry reads the same
168
- Session/turn, does not rerun inference, and never exposes a raw error response.
169
- Only a successful read with no retained decision shows **Selection unknown**.
170
- Compatible historical attribution can still supply an independently known Auto
171
- decision. This change does not persist decisions or recover evicted evidence.
172
-
173
- **Completed-turn fallback (alpha.71, #238):** a new Desktop Session was observed without the Auto label despite alpha.70 reporting all three components running. That status does not attest every optional Client dependency fiber. The reproducible defect is that the actions entry waited for `uiConversation` registration, and then required its optional provenance projection even when the Host retained the exact turn's selection. The original live Client trigger has not been established from console evidence.
174
-
175
- The actions entry now waits only for the selection Remote namespace and public slots. Historical attribution/provenance definitions register independently. A native `turn-tail` matching the displayed closing message, turn and valid completion sequence is independent completion evidence: a retained Auto/Manual selection can render without the optional projection. Native `tokenUsage.routes` can establish Copilot ownership for **Selection unknown** when projection data is absent. Missing projection evidence remains visibly incomplete; it never becomes guessed Manual, a guessed preference, or a reconstructed historical selection. Invalid/mismatched completion stays hidden. Projection failure cannot unregister the independent actions entry.
176
-
177
- Regression coverage includes absent/failed projections, exact Session/turn binding, stale responses, incomplete disclosure and pending Client dependencies. The existing exact-source UI fixture exercises native assistant/turn-tail assembly, cold replacement and incremental append, and the real session-scoped slot renderer without plugin projections. These are synthetic regressions, not proof of a newly loaded Desktop Client or live inference. No Core, history, settings, credentials, routing policy or native Usage changes are required.
178
-
179
- **Desktop collection compatibility (alpha.63, #222):** the assistant-actions selector reads the public `snapshot.nodes.values()` iterable. Official ChatNodeStore returns an array; a JavaScript Map returns an iterator. Neither requires class identity checks or private-store access. Unsupported collections emit `COPILOT_TURN_SELECTION_CHAT_NODES_UNAVAILABLE` once and suppress the footer without reading another turn. This fixes the missing label/disclosure without changing selection policy or restoring lost Host-lifetime evidence.
180
-
181
- **Compatibility fix (alpha.54):** new turns omit plugin-specific Auto decision events. Official `0.2.0-rc.2` cannot set an `ignorable` envelope through public `Session.append()`, and its reader rejects unknown required plugin events. The plugin therefore stops writing `github-copilot/auto-model-decision` rather than patching Core, mutating event objects, or borrowing an unrelated event type. Core's actual model/usage provenance and Auto routing remain unchanged. Restore new decision recording only when a supported public informational-event or equivalent storage seam has proven cold-read compatibility.
182
-
183
- Completed Copilot replies show **Auto (preference)** with an information button, **Manual** with captured explicit fixed-selection evidence, or **Selection unknown** when that evidence is absent. The public `conversation.chat.assistant-actions` slot places the plugin's own flex item after native Usage/time using `order: 1`. There is no separate Model details entry or repeated model name. The native parent is a fixed-height, non-wrapping row: the plugin can shrink/wrap its own item but cannot promise whole-row wrapping, and does not modify native ancestors. A turn without a closing message has no assistant-actions anchor.
184
-
185
- New Auto decisions and matching explicit fixed selections are captured at dispatch in a bounded in-memory store (64 Agents, 128 turns per Agent, first decision per turn). `githubCopilotTurnSelection.get` uses Core's native agent scope and lookup, with its existing Session resolution and ownership checks, rather than a plugin-owned arbitrary-session metadata endpoint. The lookup can use normal Core resume semantics; it is not a new access-control system. The Client reads once for the exact displayed Session/turn, cancels stale responses and never polls. Agent disposal, plugin disposal, eviction or Host restart removes evidence; no new Session event is emitted. Compatible historical Auto events can supply a recorded preference and reason; omitted historical preference is not guessed.
186
-
187
- The expandable explanation reports only the actual routing classification, capacity preference and eligible/fitting counts. It is selection evidence, **not proof of execution**. Absence of Auto evidence never implies Manual, and today's picker/request header never fills a historical gap. Native Usage remains the only model/usage display; its existing all-or-nothing missing-route behavior is not fixed here. A metadata-only projection flags incomplete attempts/history without duplicating or allocating tokens. The disclosure never reads message content, replay data or credentials.
76
+ Completed replies show **Auto (preference)** with captured reasons, **Manual**
77
+ only with explicit fixed-selection evidence, or **Selection unknown** when a
78
+ successful read has no record. Failed reads show **Selection unavailable → Retry**.
79
+ Retry rereads the same Session/turn; it never runs inference.
80
+
81
+ The public assistant-actions slot adds the plugin item after native Usage/time.
82
+ It cannot change the native fixed-height parent row, repeats no model name and
83
+ adds no Model details button. A turn without a closing message has no such
84
+ anchor. Optional conversation projections do not control selection mounting.
85
+
86
+ The bounded Host store retains 64 Agents and 128 turns per Agent. Disposal,
87
+ eviction and restart lose new records. Compatible historical Auto events remain
88
+ readable; missing historical preference/reasons are not reconstructed.
89
+ New optional `github-copilot/auto-model-decision` events are **not** emitted:
90
+ official rc.2 `Session.append()` has no public ignorable-envelope option.
91
+
92
+ `TurnSelectionController` extends public `TypertRemoteService` with `@Remote get`.
93
+ Client calls carry explicit viewed Session ID and turn, with no automatic
94
+ Client scope projection that would remove the ID. Native Host Agent lookup,
95
+ access checks and strict codecs remain. Actual Client/Host gateway regressions
96
+ cover reachability, bound contexts and missing/denied identities; mock RPC
97
+ success is not sufficient evidence.
98
+
99
+ Captured evidence includes task/category, eligible/fitting counts,
100
+ fallback/continuity and optional auxiliary milestones. It proves a decision,
101
+ not execution, current occupancy, usage or supplier billing. Native accounting
102
+ remains independent. [Usage limits](./copilot-usage.md).
188
103
 
189
104
  ### Recovering affected histories
190
105
 
191
- Upgrading prevents new incompatible events but does **not** rewrite existing logs. Repeated restarts cannot repair a stored missing marker.
192
-
193
- From a source checkout of this version, with Node 24 LTS and the pinned dependencies installed using `pnpm install --frozen-lockfile`, run:
106
+ Only histories containing the old incompatible decision event need this
107
+ compatibility utility. Upgrading prevents new writes but does not repair old logs.
108
+ From a source checkout, use Node 24 LTS and the pinned frozen dependencies:
194
109
 
195
110
  ```powershell
196
- # Read-only validation; prints counts, affected sequence numbers and hashes, never conversation content.
111
+ # Read-only validation; no conversation content is printed.
197
112
  node scripts\repair-auto-model-history.mjs 'C:\absolute\path\session.v4.jsonl.zstd'
198
113
 
199
- # Optional: create a NEW private recovery directory outside the live Session directory.
114
+ # Optional detached copy in a NEW private directory, never the live source.
200
115
  node scripts\repair-auto-model-history.mjs 'C:\absolute\path\session.v4.jsonl.zstd' --write-copy 'C:\private\new-recovery-directory'
201
116
  ```
202
117
 
203
- This is an explicit offline maintenance utility, not an installed plugin hook. It reads all concatenated zstd frames, uses the exact published official `0.2.0-rc.2` format catalog for strict whole-history validation, and adds only `ignorable: true` to recognized Auto decision envelopes. It preserves type, sequence, time, data and all other rows. Unknown required events, invalid decisions, torn tails, invalid relationships, non-v4 input and compressed/decoded inputs over 128 MiB fail closed. It never repairs or drops other errors.
204
-
205
- Copy mode creates `original.session.v4.jsonl.zstd` (byte-exact backup), `session.v4.jsonl.zstd` (validated repaired copy), and `repair.json` (SHA-256 receipt). It refuses existing destinations and never writes the source. Keep the directory private: both logs contain conversation history. A check/copy can become stale if an active writer appends later.
118
+ The utility validates the entire v4 log with the official rc.2 catalog, marks
119
+ only recognized decision envelopes `ignorable: true`, and preserves all other
120
+ logical fields. Unknown events, malformed relationships, torn tails and inputs
121
+ over 128 MiB fail closed. Copy mode refuses existing destinations and creates a
122
+ byte-exact original, validated copy and SHA-256 receipt; keep both logs private.
206
123
 
207
- The compressed output keeps the header in its own first zstd frame, as required by Desktop's persistence discovery and reader. The original alpha.54 utility incorrectly combined the header and events into one frame: those copies passed logical event validation but disappeared from Desktop discovery. Use the corrected utility on such a copy; `reframedHeader: true` reports this physical-layout repair even when `changedSeqs` is empty. No logical rows change during reframing, and the current source is backed up separately. A zero `changedSeqs` count alone from the original utility was not proof of Desktop readability.
124
+ The corrected writer preserves a separate first zstd header frame for Desktop
125
+ discovery. The original utility combined header/events and could make a copy
126
+ disappear despite logical validation. `reframedHeader: true` reports physical
127
+ repair; zero changed event sequences alone is not readability proof.
208
128
 
209
- **Applying a copy requires separate operator approval:** first stop all writers for that Session, verify the fixed plugin will load before resuming, and recheck the live log against `originalSha256`. If it changed, regenerate and validate a fresh copy. Preserve the backup, replace only the exact affected log, verify its hash against `repairedSha256`, then use the normal official history reader to reopen it. Do not replay business requests as a test. If recovery fails, stop writers before restoring the exact original backup. Neither this utility nor the plugin installs itself, replaces a live file, restarts Desktop, clears credentials, or automatically migrates histories.
210
-
211
- ## Subagents and Agent Teams
212
-
213
- General native subagent Auto inheritance is **not** in the base MVP.
214
-
215
- In official DSH 0.2.0-rc.2, `TeamRoster.spawn` calls `ctx.subagents.startContinuable` without `request.agentOptions`. Core initializes the child from the parent's latest recorded request route, falling back to the parent's creation options before it has made a request, and records the resulting child options in its descriptor. This is creation-time inheritance, not a live link to the parent's selection. A recorded concrete route alone does not establish whether it came from an inherited selection or an explicit child override, and a resolved route does not prove the parent had no pending Auto intent. The plugin must not relabel a child route as Auto or write fabricated selection history.
216
-
217
- With `followParentModel` off and no legacy `parentModelFollow` enrollment, the plugin preserves native child routing behavior:
218
-
219
- - a child with an explicit model override uses that model;
220
- - a new child or Team mate without an override starts with Core's parent-route snapshot and fallback behavior;
221
- - later parent changes do not retarget an existing child through the native continuation path;
222
- - the child UI shows the real model truthfully;
223
- - no plugin code claims independent child Auto classification.
129
+ **Applying a copy requires separate approval and stopped writers.** Recheck the
130
+ live source against `originalSha256`; regenerate if changed. Replace only that
131
+ log, compare `repairedSha256` and reopen with the official reader. Do not replay
132
+ business requests as a test. The utility never installs, restarts, writes the
133
+ source, clears credentials or performs automatic migration.
224
134
 
225
135
  ## Requested parent-to-child selection inheritance
226
136
 
227
- The desired behavior is for native subagents and Team mates to follow the master's **effective selection on each new child turn**, not only snapshot the route that was effective when the child was created:
228
-
229
- - An explicit child model override takes precedence over inheritance.
230
- - At child creation, an enrolled child starts from the parent's effective selection. On each later child turn, the follow-policy resolver reads its direct parent's current effective selection unless the child has an explicit override.
231
- - If the parent is fixed to a model, the next child turn follows that provider/model. If the parent is Auto, the child retains Auto intent and independently resolves a model for its own turn; it must not be pinned to the parent's concrete model for that turn.
232
- - A route is stable within a turn: changing the parent while a child turn is running does not hot-swap an in-flight request. The new parent selection applies when the child begins its next turn.
233
- - The implementation must retain provenance that distinguishes inherited Auto, inherited fixed selection, and an explicit child override across child creation, message delivery, and cold resume. A concrete model ID alone cannot prove Auto intent.
234
-
235
- ### Implementation sketch and boundary
236
-
237
- This is a requested product direction, not current behavior. A native implementation would carry an explicit inheritance mode and parent/override provenance, then resolve the parent's current effective selection at the start of each new child turn. For Auto, the child must invoke its own per-turn Auto resolution against its own messages and capabilities. Explicit child selection remains authoritative. The resolver must use the live parent's selected/requested model state, not the global default, and must fail visibly when parent evidence is missing rather than guess from a stale concrete child route. The open [Core PR #95](https://github.com/cloga/deepseek-harness/pull/95) proposes creation-time route rules for new children; its design preserves existing children on later messages and does not establish per-turn parent-following or inherited Auto intent.
238
-
239
- The plugin uses public request-selection middleware for supported native `spawn` children. The profile-wide switch explicitly authorizes overriding creation-time snapshots without inferring their original intent; legacy per-child bindings remain compatible. This is opt-in policy, not a change to native defaults. Actual request routes remain authoritative; native Team labels are not rewritten.
240
-
241
- ### October 2 investigation: routing is possible; automatic enrollment is ambiguous
242
-
243
- Tracking: [#229](https://github.com/cloga/dsh-github-copilot/issues/229).
244
- The target remains unchanged official `0.2.0-rc.2`, commit
245
- `639ed015397290b3745d163aafe02ffee4aa3f84`, not the proposed Core branch.
246
-
247
- | Exact source | Finding |
248
- | --- | --- |
249
- | [child-agent.ts](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/subagent/subagent/src/child-agent.ts) | `parentAgentOptionsForDelegation` reads the latest request header before creation options. `resolveChildAgentOptions` merges overrides and discards whether an equal route was explicit. |
250
- | [continuation.ts](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/subagent/subagent/src/continuation.ts) | Creation snapshots resolved options; cold resume reconstructs them from the descriptor. No next-turn parent-model recapture is performed here. |
251
- | [descriptor.ts](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/subagent/subagent/src/descriptor.ts) | Descriptor v3 stores resolved route/effort, not follow/override provenance, and rejects unknown fields. |
252
- | [model-selection.ts](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/core/agent/src/model-selection.ts) | Public `installModelSelection` couples scoped prompt assembly and request routing, clears inherited effort, and supports disposal. Its snapshot boundary is a step, so a follow policy must additionally freeze selection for a whole child turn. |
253
- | [subagent index.ts](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/subagent/subagent/src/index.ts) and [lifecycle.ts](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/subagent/subagent/src/lifecycle.ts) | Public start/end notifications describe published runs; they are not a before-create interceptor exposing original override intent. The activation observer is package-private. |
254
-
255
- An isolated Node 24 experiment executed the unchanged child-option resolver,
256
- descriptor functions, and public selection middleware from that commit. Each
257
- downloaded file's Git blob SHA was checked against the GitHub contents response
258
- before execution. TypeScript was stripped with Node's compiler; depth, JSON
259
- snapshot, message constructors, and the event context were synthetic dependencies.
260
- Six assertions passed:
261
-
262
- 1. Omitted overrides and an explicit provider/model equal to the parent produce identical resolved options and identical durable descriptors.
263
- 2. Changing the parent's recorded route changes a newly resolved child, not the previously captured descriptor.
264
- 3. A concrete parent request header takes precedence over Auto creation options.
265
- 4. Before the first parent request, Auto survives the creation-options fallback.
266
- 5. Adding an invented `followParent` descriptor field is rejected by the official reader.
267
- 6. Public model-selection middleware applies a fixed route, forwards virtual Auto on subsequent assembly, clears inherited effort, and removes its listeners on disposal.
268
-
269
- These are exact-function experiments, not full Core activation, real Team turns,
270
- cold-resume integration, or model transport evidence. In particular, forwarding
271
- an Auto ID does not by itself prove child-specific Auto resolution.
272
-
273
- The first result is a counterexample to automatic override detection: two
274
- different user intentions yield the same observable child state. Comparing
275
- parent/child model IDs, inspecting only `Agent.options`, or treating a missing
276
- child picker event as inheritance cannot implement the stated precedence for
277
- every existing child. Request middleware does not recover the lost information.
278
-
279
- ### One-switch policy and legacy per-child bindings
280
-
281
- The ordinary UI is now one profile-wide **Follow parent model** switch in the
282
- plugin configuration page. See [requirements, design and mockup](parent-model-follow.md).
283
- It defaults to Off and does not ask users to manage child IDs. Explicitly
284
- enabling this broad policy authorizes replacing creation-time snapshots;
285
- child-owned manual selection events still win. The per-child binding mechanism
286
- below remains for alpha.66 compatibility, not as the ordinary user workflow.
287
-
288
- **Legacy opt-in bindings; preserved independently of the broad switch.**
289
- Do not silently enroll all existing children or treat a new setting as proof of
290
- their original creation intent. `github-copilot.parentModelFollow` defaults to
291
- an empty array. The standard plugin configuration accepts explicit bindings:
292
-
293
- ```json
294
- {
295
- "parentModelFollow": [
296
- { "childSessionId": "<native-child-session-id>", "parentSessionId": "<direct-parent-session-id>" }
297
- ]
298
- }
299
- ```
137
+ The implemented opt-in [profile-wide switch](./parent-model-follow.md) follows
138
+ supported children on each new turn. Fixed parent selection is passed directly;
139
+ Auto passes the exact preference and evaluates the child's own context.
140
+ Child-owned explicit selections and admitted-turn freezing remain authoritative.
141
+ Legacy `parentModelFollow` bindings stay independent.
300
142
 
301
- These are native DSH Session IDs, not role names, model IDs, or Copilot App
302
- session handles. A binding authorizes replacement of the child's captured
303
- creation route. No binding is added by installation or discovery. Existing
304
- child-owned `model/selection` events take precedence, even for a same-model
305
- selection; enrollment does not clear them. Remove the binding to return to
306
- native routing at the next turn. Settings changes during an already captured
307
- turn do not interrupt or change its route.
308
-
309
- - A user explicitly enrolls a child Session through the native plugin configuration and its path-level settings writes, or leaves it under native selection. Bindings live only in this plugin's configuration. Do not add descriptor fields or new Session history events.
310
- - A pure Host-only projection folds existing child-owned selection events, turn starts, and native descriptor evidence, excluding inherited seed events. A later explicit child selection suspends following from its next turn, including a same-model reselection. Once present, a child-owned selection is not cleared by toggling enrollment.
311
- - Read the direct parent's pending selected intent first, then its proven effective route. Preserve the exact Auto preference. Do not borrow the global default, another Session, or a stale request header when a newer pending choice exists.
312
- - Freeze one selection before the child's first prompt assembly in a new turn. Reuse it for every subsequent step/retry/compaction attempt in that turn. Integrate it with the existing per-Agent Auto resolver so Auto evaluates the child's admitted messages and capacity requirements, not the parent's chosen model.
313
- - Reuse normal managed adapter admission for fixed-model availability and exclusions, and the existing validated candidate pool for Auto. Clear inherited reasoning effort while retaining output caps. Missing parent/selection evidence yields a named `COPILOT_PARENT_MODEL_*` diagnostic, never a guessed model or silent fallback.
314
- - Restore policy from plugin-owned settings on cold activation and inspect only public projections. Do not call public `session.selectModel` for propagation: it also writes the future global default. Do not convert historical provenance or alter native permissions.
315
- - Keep scope to verified native `spawn` children and managed Copilot parent routes. Dedicated historical role policies, fork-provider descriptors and externally managed providers are rejected when enrolled. Nested enrollment follows verified direct-parent links until an explicit selection or non-following parent supplies the intent; cycles and missing parents fail visibly.
316
- - Verify native Team model labels separately: a roster label may describe a creation snapshot rather than the next request. Do not claim accurate live UI simply because request routing changes.
317
-
318
- Release gates combine policy, Host/configuration and unchanged-Core regressions:
319
- fixed A to B, fixed to Auto and Auto to fixed, every Auto preference, independent
320
- sibling inputs, turn freezing, explicit child overrides, fork seed boundaries,
321
- strict history reading/refolding, unavailable parents, normal model exclusions,
322
- live binding changes and disposal. The native AgentLoop fixture reconstructs a
323
- child from its own strict-reader-validated history and verifies the next turn;
324
- it does not exercise disk-backed resume or the native Team orchestrator.
325
- The native creation path cannot recover original equal-route override intent.
326
- Legacy bindings authorize individual children; the new switch authorizes this
327
- tradeoff once for the profile. Neither mechanism fabricates provenance or clears
328
- child-owned selection events.
329
-
330
- Local full validation is blocked: `pnpm exec vitest --version` triggered pnpm's
331
- dependency reconciliation, which failed with HTTP 404 for
332
- `https://packagefeedproxy.microsoft.io/npm/@deepseek-ai/dsh-llm/-/dsh-llm-0.2.0-rc.2.tgz`.
333
- No registry restriction was bypassed. The isolated experiment above does not
334
- replace the complete repository and exact-Core compatibility gates.
335
-
336
- Implemented files are `src/parent-model-follow.ts`, `src/auto-model-host.ts`,
337
- `src/config.ts` and `src/preview-route.ts`. Nine dependency-free policy tests
338
- passed with `node --test tests/scripts/parent-model-follow.test.mjs`, and the
339
- policy module passed a focused TypeScript check. An actual-plugin-source VM
340
- experiment passed fixed/Auto turn freezing, config removal, explicit child
341
- override, reinstallation/refolding and no-history-write assertions with synthetic
342
- Context/LLM/token-estimator dependencies. Focused Vitest Host/config tests and
343
- the real Session projection/AgentLoop fixtures run in the required Windows/Linux
344
- CI matrix; the incomplete local dependency installation cannot run those gates.
345
- The AgentLoop fixture uses the actual TokenMeter and a synthetic public adapter,
346
- not a live model endpoint. Native Team end-to-end behavior, disk persistence,
347
- Desktop activation and transport remain separate, unclaimed evidence layers.
348
-
349
- ## Public API implementation
350
-
351
- The plugin uses only published public seams:
352
-
353
- - `PreviewAdapter.listModels()` publishes three virtual Auto picker entries alongside real account models.
354
- - `PreviewAdapter.resolveModel()` returns aggregate Auto modalities for picker admission.
355
- - `agent/pre-step` captures the admitted current-turn messages.
356
- - a prepended `agent/request` listener awaits Core's model-selection middleware, recognizes only `github-copilot-preview/auto`, resolves one real account descriptor, and returns the real model before `request/header` persistence.
357
- - the adapter refuses unresolved Auto in `prepareCall()` and `stream()` so a missing middleware path fails loudly.
358
- - a per-Agent, per-turn decision cache keeps all later steps and request-error retries on the same model.
359
- - existing descriptor leases, credential proof, account continuity, request budgets, native pi-ai transport, replay, and cancellation remain unchanged.
360
-
361
- The virtual Auto selection can remain pending while the real request header records the actual model. This is intentional: an unrelated real header must not consume the durable Auto preference. A later explicit picker selection replaces the pending Auto choice through Core's normal projection.
362
-
363
- For an otherwise unselected Session that inherits Auto from the global default, the first virtual request persists a `model/selection` Auto intent before its real request header. Core's request-header fallback would otherwise make the next turn fixed. The plugin restores the pending Auto route during subsequent prompt assembly and request resolution without changing the real header, and yields immediately to a later explicit selection. It does not turn an existing Session with a real recorded route into Auto just because the global default changed.
364
-
365
- ## Acceptance criteria
366
-
367
- The implementation is accepted only when unchanged official Core contract tests prove:
368
-
369
- 1. Auto appears only in the managed Copilot provider and explicit real/provider selections remain untouched.
370
- 2. Core's downstream model-selection result is visible to the prepended plugin listener, and the committed request header contains the resolved real model.
371
- 3. Auto intent remains durable while actual request provenance remains real.
372
- 4. one turn with multiple steps or request-error retries loads one routing decision.
373
- 5. a new user or Goal turn may make a new decision.
374
- 6. image admission and real candidate filtering agree, including the no-image-candidate failure.
375
- 7. choosing a smaller-context model can trigger the existing local pressure signal, Core compaction, and same-model retry without sending the oversized request.
376
- 8. hosted search remains independent and never receives the virtual Auto ID as a transport model.
377
- 9. no new unknown required attribution event is written; compatible historical attribution is retained, while missing decision events produce no guessed footer.
378
- 10. input fit check filters out candidates with insufficient hard input headroom before soft preference.
379
- 11. soft preferences distribute across upper/lower/center candidate bands without monopolizing one top model.
380
- 12. no Core file, dependency artifact, private registry, shared model catalog, or live history is modified.
381
-
382
- Synthetic tests prove composition and contracts only. They do not prove a live account's model availability, provider quality, pricing, OAuth readiness, Desktop activation, or real transport success.
383
-
384
- ## Deferred work
385
-
386
- - benchmark-backed quality/latency/cost ranking;
387
- - GitHub health signals or GitHub's private Auto service;
388
- - user-managed exclusions of individual account models and custom picker grouping;
389
- - cross-provider routing;
390
- - native subagent and Team Auto inheritance;
391
- - model fallback after a provider failure;
392
- - side-effect replay;
393
- - automatic changes to existing Session selections, settings, or histories.
143
+ With both policies off, ordinary native children retain Core's creation-time
144
+ route snapshot. Native resolved options/descriptor v3 do not retain whether an
145
+ equal creation route was an explicit override. Enabling the plugin policy
146
+ authorizes replacing that snapshot; it does not reconstruct original intent,
147
+ fabricate descriptor provenance or rewrite Team labels.
394
148
 
395
- ## Model exclusions and richer picker boundary
396
-
397
- **Tracking:** [#192](https://github.com/cloga/dsh-github-copilot/issues/192). **Interactive proposal:** [`output/auto-model-mockup/tiers.html`](../output/auto-model-mockup/tiers.html). This is a local, synthetic UI exercise, not a claim of current Core picker behavior. The three virtual preferences, capacity matrix, and plugin-owned model exclusions are implemented. The mockup's nested Core picker is not.
398
-
399
- The attached Copilot example uses one Auto switch with a nested Efficiency / Balance / Intelligence menu. The supported DSH model picker is owned by Core and receives a flat provider directory from `PreviewAdapter.listModels()`; the plugin's Models provider-card and bundle-config slots cannot restructure that picker. The plugin advertises three rows under **GitHub Copilot**, with the existing `auto` ID as Balance for previously selected Sessions and defaults. A nested switch like the screenshot requires a separately reviewed public Core UI seam and is not a dependency of the plugin-only preferences.
149
+ The original [investigation #229](https://github.com/cloga/dsh-github-copilot/issues/229)
150
+ and [one-switch follow-up #234](https://github.com/cloga/dsh-github-copilot/issues/234)
151
+ record the design history. Upstream native rules/settings UI is separate work,
152
+ not a dependency or claimed shipped feature of this plugin.
400
153
 
401
- Exclusions are a separate **hard filter**, not a fourth preference. All three preferences share account entitlement and turn-required verified capabilities, then remove the exact IDs stored in `github-copilot.excludedModelIds`. The mockup uses illustrative capacity scores and simulated responses, not live evaluation of model quality, cost, or latency.
402
-
403
- The model-management surface is the nested **GitHub Copilot → Manage → Model preferences** disclosure in the plugin's own settings UI, not a replacement of Core's picker. It offers local search, visible/excluded counts, **Exclude** and **Restore**, a selected-model lock reason, and retained restore rows for exact IDs temporarily absent from current account metadata. Writes are revision-checked path mutations. The plugin does not mutate pi-ai's catalog, the account grant, Core settings, or another provider's models. Its advertised directory, every Auto candidate set, aggregate Auto modalities, hosted-search route facts and managed admission remove excluded IDs. A stale picker row or direct request fails with `COPILOT_PREVIEW_MODEL_EXCLUDED`. Existing Session history is never rewritten or silently moved. The current fixed managed model cannot be excluded until another model is selected. If exclusions leave no eligible candidate, Auto fails closed with `COPILOT_AUTO_NO_ELIGIBLE_MODEL`. Account change or unavailable metadata never re-enables or guesses models.
154
+ ## Model exclusions and richer picker boundary
404
155
 
405
- The native picker still owns provider groups and text search. It remains flat: the three virtual rows are listed first and excluded Copilot models are omitted from the plugin-owned directory. Custom section headers inside a provider, nested Auto menus, hiding other providers' models, and replacing Core search/layout are **not** available through the current additive slots. Focused regressions cover directory refresh, selected-model exclusion, stale direct requests, concurrent settings conflicts, Auto/image eligibility and zero-candidate failures against unchanged pinned Core. The prototype's invented model capacity order and response remain illustrative only.
156
+ **Settings → Models → GitHub Copilot → Manage → Model preferences** offers
157
+ search, All/Enabled/Excluded filters and immediate Exclude/Restore actions.
158
+ Temporarily absent excluded IDs remain restorable. Selected models can also be
159
+ excluded; legacy `lockedModelIds` remains empty.
160
+
161
+ `setModelExcluded(modelId, excluded)` returns a narrow strict preferences result
162
+ after path-level native CAS persistence. It reads no credentials, discovers no
163
+ models and enumerates no Sessions. Unknown settings make rows read-only with
164
+ named diagnostics; status-only Retry cannot imply an empty exclusion set.
165
+ The hidden volatile Config leaf persists through native projection/restart.
166
+
167
+ Directory, Auto pools/modalities, search facts and new-turn admission remove
168
+ exact excluded IDs. An admitted Session/turn/model with the exact native request
169
+ signal may continue steps/retries; `turn/end` clears admission. New turns,
170
+ unbound calls and stale picker rows fail `COPILOT_PREVIEW_MODEL_EXCLUDED`.
171
+ Account/proof/cancellation guards remain revocable. A fixed selection is never
172
+ changed automatically; restore it or select another model before the next turn.
173
+ Zero eligible candidates fails `COPILOT_AUTO_NO_ELIGIBLE_MODEL`.
174
+
175
+ Core owns flat grouping and picker search. The old
176
+ [nested-picker prototype](../output/auto-model-mockup/tiers.html) is historical
177
+ design exploration: its capacity quality scores, nested menu and simulated
178
+ responses are not implementation or model evaluations.
179
+
180
+ ## Public seams and evidence limits
181
+
182
+ `PreviewAdapter.listModels/resolveModel`, `agent/pre-step`, public model-selection
183
+ middleware and `agent/request` compose the real route before request-header
184
+ persistence. Unresolved virtual Auto fails in adapter preparation/streaming.
185
+ Per-Agent/turn caching, native adapter leases, OAuth, replay and cancellation
186
+ keep their existing owners.
187
+
188
+ Required unchanged rc.2 source/published-artifact fixtures on Windows/Linux
189
+ cover eligibility, real headers, durable intent, multi-step/retry freezing,
190
+ images, native compaction, exclusions and gateway access. They do not establish
191
+ live model availability, quality, latency, price, account access or Desktop
192
+ activation. No Core/dependency/private-registry/shared-catalog/history patch is
193
+ permitted. Measured ranking, cross-provider Auto, failure-driven model switching,
194
+ side-effect replay and native picker redesign remain out of scope.