dsh-model-think-level 2.4.0 → 2.5.1

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.
@@ -171,6 +171,31 @@ export declare const DEFAULT_EFFORT_FIELD = "defaultEffort";
171
171
  export declare const CAMOUFLAGE_PATH = "/dsh-model-think-level/camouflage";
172
172
  /** File name of the camouflage document inside the plugin's home dir. */
173
173
  export declare const CAMOUFLAGE_FILE = "camouflage.json";
174
+ /**
175
+ * Same-origin host route owning the Responses history-compatibility document:
176
+ * `GET` answers which routes recover a topic whose upstream history was minted
177
+ * under another backend resource, `POST` saves one route's switch.
178
+ * Backing file: `<DSH_HOME>/dsh-model-think-level/topic-recovery.json` (see
179
+ * {@link HISTORY_COMPAT_FILE}).
180
+ *
181
+ * Plugin-owned for the same reason the camouflage document is: the official
182
+ * add-provider card writes the WHOLE profile at `providers.<route>`, so a field
183
+ * its schema does not know is dropped by the first save.
184
+ */
185
+ export declare const HISTORY_COMPAT_PATH = "/dsh-model-think-level/history-compat";
186
+ /**
187
+ * File name of the history-compatibility document inside the plugin home dir.
188
+ *
189
+ * Deliberately not `history-compat.json`: the sync layer treats any segment
190
+ * matching `history` as session history and refuses to carry it, so the name
191
+ * itself would keep these switches from ever leaving this computer.
192
+ */
193
+ export declare const HISTORY_COMPAT_FILE = "topic-recovery.json";
194
+ /**
195
+ * The name this document shipped under before it was syncable. Still read (and
196
+ * migrated on first read) so a switch saved by an earlier build is not lost.
197
+ */
198
+ export declare const HISTORY_COMPAT_LEGACY_FILE = "history-compat.json";
174
199
  /**
175
200
  * Same-origin host route owning the image-generation config surface: `GET`
176
201
  * answers the derived image-model list merged with the stored overrides,
@@ -45,6 +45,14 @@ export interface HeaderOverride {
45
45
  * own document, not in the profile, so it survives an official card save.
46
46
  */
47
47
  camouflage?: CamouflagePreset;
48
+ /**
49
+ * Whether this route may recover a Responses topic whose upstream items were
50
+ * minted under a different backend resource (see `history-compat.ts`). Absent
51
+ * means off: a route only pays for the check once the user turned it on for
52
+ * that route. Stored in the plugin's own document, so it survives an official
53
+ * card save.
54
+ */
55
+ historyCompat?: boolean;
48
56
  }
49
57
  /** Backwards-compatible name retained for callers that only knew the UA seam. */
50
58
  export type UserAgentOverride = HeaderOverride;
@@ -114,8 +122,10 @@ export declare function declaredUserAgent(profile: Record<string, unknown> | und
114
122
  * Optional: a deployment with no camouflage file builds exactly the index it
115
123
  * built before, and a route named here that the settings no longer carry is
116
124
  * simply never matched.
125
+ * @param historyCompat - route → whether that route recovers foreign Responses
126
+ * history, from the plugin's own document. Optional for the same reason.
117
127
  */
118
- export declare function buildHeaderIndex(providers: Record<string, Record<string, unknown>>, camouflages?: Readonly<Record<string, CamouflagePreset | undefined>>): HeaderIndex;
128
+ export declare function buildHeaderIndex(providers: Record<string, Record<string, unknown>>, camouflages?: Readonly<Record<string, CamouflagePreset | undefined>>, historyCompat?: Readonly<Record<string, boolean>>): HeaderIndex;
119
129
  /** Original public name retained while callers migrate to the generic index. */
120
130
  export declare function buildUserAgentIndex(providers: Record<string, Record<string, unknown>>): UserAgentIndex;
121
131
  /** The pathname of a request URL, normalized the way {@link pathPrefixOf} is. */
@@ -0,0 +1,55 @@
1
+ /**
2
+ * The history-compatibility document: which provider routes may recover a
3
+ * Responses topic whose upstream history was minted under another backend
4
+ * resource.
5
+ *
6
+ * It lives in the plugin's own home directory rather than in the pi-ai profile
7
+ * for the same reason the camouflage document does: the official add-provider
8
+ * card writes the WHOLE profile at `providers.<route>`, so a field the official
9
+ * schema does not know would be dropped by the first save.
10
+ *
11
+ * Only "on" is ever stored. A route that is off carries no entry, so deleting
12
+ * and re-creating a provider cannot inherit a stale switch — and the file says
13
+ * exactly which routes are covered instead of listing the whole catalogue.
14
+ *
15
+ * The document holds no secrets: route names and one boolean. It is parsed
16
+ * leniently (an unreadable file means "nothing enabled") and written
17
+ * atomically, like the camouflage document.
18
+ *
19
+ * @module dsh-model-think-level/history-compat-store
20
+ */
21
+ /** The whole stored document. */
22
+ export interface HistoryCompatDocument {
23
+ /** Schema version; a future shape can migrate by reading this. */
24
+ readonly version: 1;
25
+ /** Route → enabled. An absent route is off. */
26
+ readonly providers: Readonly<Record<string, true>>;
27
+ }
28
+ /** A fresh, empty document. */
29
+ export declare function emptyHistoryCompat(): HistoryCompatDocument;
30
+ /** Absolute path of the document beside the camouflage and key documents. */
31
+ export declare function historyCompatFilePath(home?: string): string;
32
+ /**
33
+ * Parse an already-decoded document. Never throws and never trusts the input:
34
+ * an entry whose value is not `true` is dropped, so a file written by a newer
35
+ * build costs only the settings this build cannot express.
36
+ * @param raw - the decoded JSON value (or anything else).
37
+ */
38
+ export declare function parseHistoryCompat(raw: unknown): HistoryCompatDocument;
39
+ /** Read the document. Never throws; an absent file means "nothing enabled". */
40
+ export declare function readHistoryCompat(file?: string): HistoryCompatDocument;
41
+ /** Write the document at one path, atomically. */
42
+ export declare function writeHistoryCompat(document: HistoryCompatDocument, file?: string): void;
43
+ /**
44
+ * Turn one route's switch on or off.
45
+ *
46
+ * `false` removes the entry rather than storing "off": the document then says
47
+ * exactly which routes are covered.
48
+ * @param route - the provider route key.
49
+ * @param enabled - whether this route may recover foreign history.
50
+ * @param file - document path (tests pass a temp file).
51
+ * @returns the document as it now stands on disk.
52
+ */
53
+ export declare function setRouteHistoryCompat(route: string, enabled: boolean, file?: string): HistoryCompatDocument;
54
+ /** One route's stored switch, never resolving through Object.prototype. */
55
+ export declare function historyCompatOf(document: HistoryCompatDocument, route: string): boolean;
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Responses history compatibility: replaying a topic whose upstream items were
3
+ * created under a different backend resource.
4
+ *
5
+ * A relay that fans one route out over several upstream accounts mints item IDs
6
+ * and encrypted reasoning under whichever account answered. A conversation that
7
+ * starts on account A and is continued on account B is then refused with
8
+ * `The requested item was created under a different Azure OpenAI resource. Use
9
+ * the same resource that created the item to access it.` — a refusal about the
10
+ * HISTORY, not about the key, the model or the prompt. Re-sending the identical
11
+ * request fails forever, and rotating keys only multiplies failing attempts:
12
+ * every key reaches the same relay, and the relay's own pool decides which
13
+ * resource sees the request.
14
+ *
15
+ * Two facts make this module structural rather than a fetch-layer patch:
16
+ *
17
+ * 1. The refusal arrives in more than one shape. A relay may answer `400` with
18
+ * the sentence in its body, or — much more often with streamed Responses —
19
+ * answer `200` and emit `response.failed` INSIDE the SSE stream. Both carry
20
+ * the same sentence, so the recovery must be driven by what the sentence
21
+ * says, not by which HTTP door it came through.
22
+ * 2. The history the provider replays is assembled from the pi-ai message
23
+ * context, not from a JSON body this module could safely rewrite. Thinking
24
+ * blocks persist a serialized reasoning item in `thinkingSignature`, text
25
+ * blocks persist `{id, phase}` in `textSignature`, and tool calls persist
26
+ * `callId|itemId` in `id`. Degrading those fields is therefore a context
27
+ * transformation; the same conversation keeps working on the next turn
28
+ * because only the copy sent upstream is changed.
29
+ *
30
+ * The stages are the ones the relay world settled on, escalated only as far as
31
+ * the provider demands:
32
+ *
33
+ * 1. `portable_ids` — drop the foreign item handle from every replayable block:
34
+ * the `id` inside a reasoning signature, the whole `textSignature`, and the
35
+ * `itemId` half of a tool call's `callId|itemId`. The server then treats the
36
+ * item as new instead of resolving a foreign handle. A text signature cannot
37
+ * keep its `phase` once the id is gone: pi-ai only reads `{v:1, id, phase?}`,
38
+ * and a signature without a string `id` is sent verbatim as the item id.
39
+ * 2. `drop_reasoning` — additionally stop replaying historical reasoning items
40
+ * altogether (the `thinkingSignature` is removed; the visible thinking text
41
+ * stays in the local history untouched). Reasoning is the other thing bound
42
+ * to the minting resource.
43
+ *
44
+ * What is deliberately NOT touched: `call_id` (it pairs a call with its output;
45
+ * breaking the pair corrupts the turn), the thinking text itself, and any part
46
+ * of the caller's stored conversation — cleanup rewrites the OUTGOING copy
47
+ * only.
48
+ *
49
+ * @module dsh-model-think-level/history-compat
50
+ */
51
+ /** Upper bound on an error body this module is willing to read, in bytes. */
52
+ export declare const HISTORY_INSPECT_LIMIT = 65536;
53
+ /** How long an error body may take before inspection is abandoned. */
54
+ export declare const HISTORY_INSPECT_TIMEOUT_MS = 2000;
55
+ /**
56
+ * Whether a provider message is the resource-mismatch refusal.
57
+ * @param text - the error body or stream error message, decoded.
58
+ * @returns whether the history (not the request shape) is what failed.
59
+ */
60
+ export declare function isHistoryStateMismatch(text: string): boolean;
61
+ /** One recovery step. `drop_reasoning` also applies `portable_ids`. */
62
+ export declare const HISTORY_STAGES: readonly ["portable_ids", "drop_reasoning"];
63
+ /** One recovery step. `drop_reasoning` also applies `portable_ids`. */
64
+ export type HistoryStage = (typeof HISTORY_STAGES)[number];
65
+ /**
66
+ * Rewrite the OUTGOING message context for one recovery stage.
67
+ *
68
+ * The returned context shares every untouched message with the input; only the
69
+ * assistant messages that carry a foreign handle are copied. The caller's own
70
+ * context is never mutated, which is what lets the next turn replay the topic
71
+ * exactly as it was stored.
72
+ *
73
+ * @param context - the pi-ai request context (`{ systemPrompt, messages, tools }`).
74
+ * @param stage - how far the recovery may go.
75
+ * @returns a degraded copy, or undefined when this stage changes nothing.
76
+ */
77
+ export declare function degradeForHistory(context: unknown, stage: HistoryStage): Record<string, unknown> | undefined;
78
+ /**
79
+ * Whether a response is one this module should read at all.
80
+ *
81
+ * Two doors carry the refusal: `400` (the request-shaped answer) and `5xx` (a
82
+ * relay that wraps the upstream rejection as its own failure). Auth, quota and
83
+ * not-found answers are never this case, and reading them would only delay the
84
+ * ordinary error path.
85
+ */
86
+ export declare function isHistoryRefusalCandidate(response: Response): boolean;
87
+ /**
88
+ * Re-encode a foreign-history refusal as a JSON provider error.
89
+ *
90
+ * The fetch seam cannot recover the history itself (it only holds bytes), but
91
+ * it is the only layer that sees a non-2xx body before the provider SDK turns
92
+ * it into an opaque message. Wrapping the refusal sentence in a JSON error body
93
+ * keeps the HTTP status intact and guarantees the sentence survives into the
94
+ * stream error, where the request seam recognises it and replays a degraded
95
+ * history.
96
+ *
97
+ * @param response - the provider's error response.
98
+ * @returns the replacement response, or undefined when this is not the refusal.
99
+ */
100
+ export declare function reencodeHistoryRefusal(response: Response): Promise<Response | undefined>;