dsh-harness-reflex 0.1.0 → 0.3.0

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.
Files changed (124) hide show
  1. package/README.md +20 -6
  2. package/client.js +3511 -185
  3. package/dist/attribution.d.ts +266 -0
  4. package/dist/attribution.js +238 -0
  5. package/dist/attribution.js.map +1 -0
  6. package/dist/bridge.d.ts +311 -13
  7. package/dist/bridge.js +714 -42
  8. package/dist/bridge.js.map +1 -1
  9. package/dist/client-bundle.js +4 -1
  10. package/dist/client-bundle.js.map +1 -1
  11. package/dist/command.js +10 -0
  12. package/dist/command.js.map +1 -1
  13. package/dist/config.d.ts +530 -22
  14. package/dist/config.js +808 -27
  15. package/dist/config.js.map +1 -1
  16. package/dist/delegation-dispatch.d.ts +132 -0
  17. package/dist/delegation-dispatch.js +186 -0
  18. package/dist/delegation-dispatch.js.map +1 -0
  19. package/dist/delegation-health.d.ts +131 -0
  20. package/dist/delegation-health.js +97 -0
  21. package/dist/delegation-health.js.map +1 -0
  22. package/dist/delegation.d.ts +148 -0
  23. package/dist/delegation.js +186 -0
  24. package/dist/delegation.js.map +1 -0
  25. package/dist/effort-delegation.d.ts +144 -0
  26. package/dist/effort-delegation.js +280 -0
  27. package/dist/effort-delegation.js.map +1 -0
  28. package/dist/effort.d.ts +141 -0
  29. package/dist/effort.js +251 -9
  30. package/dist/effort.js.map +1 -1
  31. package/dist/host-patch.d.ts +156 -0
  32. package/dist/host-patch.js +534 -0
  33. package/dist/host-patch.js.map +1 -0
  34. package/dist/index.d.ts +12 -3
  35. package/dist/index.js +99 -7
  36. package/dist/index.js.map +1 -1
  37. package/dist/interventions.d.ts +98 -373
  38. package/dist/interventions.js +442 -1702
  39. package/dist/interventions.js.map +1 -1
  40. package/dist/panel-api.d.ts +328 -4
  41. package/dist/panel-api.js +322 -15
  42. package/dist/panel-api.js.map +1 -1
  43. package/dist/panel-mount.d.ts +81 -22
  44. package/dist/panel-mount.js +228 -7
  45. package/dist/panel-mount.js.map +1 -1
  46. package/dist/routing.d.ts +23 -18
  47. package/dist/routing.js +471 -153
  48. package/dist/routing.js.map +1 -1
  49. package/dist/session-audit.d.ts +70 -0
  50. package/dist/session-audit.js +73 -0
  51. package/dist/session-audit.js.map +1 -1
  52. package/dist/systemone-probe.d.ts +114 -0
  53. package/dist/systemone-probe.js +383 -0
  54. package/dist/systemone-probe.js.map +1 -0
  55. package/dist/testing.d.ts +212 -7
  56. package/dist/testing.js +333 -27
  57. package/dist/testing.js.map +1 -1
  58. package/dist/tools.d.ts +109 -3
  59. package/dist/tools.js +103 -4
  60. package/dist/tools.js.map +1 -1
  61. package/dist/unconfigured-backend.d.ts +72 -0
  62. package/dist/unconfigured-backend.js +94 -0
  63. package/dist/unconfigured-backend.js.map +1 -0
  64. package/dist/vendor/harness-reflex/backend/factory.d.ts +31 -1
  65. package/dist/vendor/harness-reflex/backend/factory.js +18 -3
  66. package/dist/vendor/harness-reflex/backend/factory.js.map +1 -1
  67. package/dist/vendor/harness-reflex/backend/jev.d.ts +20 -0
  68. package/dist/vendor/harness-reflex/backend/jev.js +11 -4
  69. package/dist/vendor/harness-reflex/backend/jev.js.map +1 -1
  70. package/dist/vendor/harness-reflex/backend/simple-jev.d.ts +16 -0
  71. package/dist/vendor/harness-reflex/backend/simple-jev.js +17 -6
  72. package/dist/vendor/harness-reflex/backend/simple-jev.js.map +1 -1
  73. package/dist/vendor/harness-reflex/core/closing.d.ts +90 -0
  74. package/dist/vendor/harness-reflex/core/closing.js +111 -0
  75. package/dist/vendor/harness-reflex/core/closing.js.map +1 -0
  76. package/dist/vendor/harness-reflex/core/evidence.d.ts +119 -0
  77. package/dist/vendor/harness-reflex/core/evidence.js +209 -0
  78. package/dist/vendor/harness-reflex/core/evidence.js.map +1 -0
  79. package/dist/vendor/harness-reflex/core/judge.d.ts +221 -0
  80. package/dist/vendor/harness-reflex/core/judge.js +251 -0
  81. package/dist/vendor/harness-reflex/core/judge.js.map +1 -0
  82. package/dist/vendor/harness-reflex/core/orchestrate-closing.d.ts +237 -0
  83. package/dist/vendor/harness-reflex/core/orchestrate-closing.js +250 -0
  84. package/dist/vendor/harness-reflex/core/orchestrate-closing.js.map +1 -0
  85. package/dist/vendor/harness-reflex/core/orchestrate-correction.d.ts +209 -0
  86. package/dist/vendor/harness-reflex/core/orchestrate-correction.js +141 -0
  87. package/dist/vendor/harness-reflex/core/orchestrate-correction.js.map +1 -0
  88. package/dist/vendor/harness-reflex/core/orchestrate-host.d.ts +225 -0
  89. package/dist/vendor/harness-reflex/core/orchestrate-host.js +80 -0
  90. package/dist/vendor/harness-reflex/core/orchestrate-host.js.map +1 -0
  91. package/dist/vendor/harness-reflex/core/orchestrate-stagnation.d.ts +259 -0
  92. package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js +270 -0
  93. package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js.map +1 -0
  94. package/dist/vendor/harness-reflex/core/orchestrate.d.ts +357 -0
  95. package/dist/vendor/harness-reflex/core/orchestrate.js +418 -0
  96. package/dist/vendor/harness-reflex/core/orchestrate.js.map +1 -0
  97. package/dist/vendor/harness-reflex/core/policy.d.ts +122 -0
  98. package/dist/vendor/harness-reflex/core/policy.js +102 -0
  99. package/dist/vendor/harness-reflex/core/policy.js.map +1 -0
  100. package/dist/vendor/harness-reflex/core/prune-plan.d.ts +141 -0
  101. package/dist/vendor/harness-reflex/core/prune-plan.js +390 -0
  102. package/dist/vendor/harness-reflex/core/prune-plan.js.map +1 -0
  103. package/dist/vendor/harness-reflex/core/text.d.ts +36 -0
  104. package/dist/vendor/harness-reflex/core/text.js +66 -0
  105. package/dist/vendor/harness-reflex/core/text.js.map +1 -0
  106. package/dist/vendor/harness-reflex/ports/audit.d.ts +18 -0
  107. package/dist/vendor/harness-reflex/ports/audit.js +11 -0
  108. package/dist/vendor/harness-reflex/ports/audit.js.map +1 -0
  109. package/dist/vendor/harness-reflex/ports/clock.d.ts +14 -0
  110. package/dist/vendor/harness-reflex/ports/clock.js +11 -0
  111. package/dist/vendor/harness-reflex/ports/clock.js.map +1 -0
  112. package/dist/vendor/harness-reflex/ports/decision.d.ts +75 -0
  113. package/dist/vendor/harness-reflex/ports/decision.js +2 -0
  114. package/dist/vendor/harness-reflex/ports/decision.js.map +1 -0
  115. package/dist/vendor/harness-reflex/ports/index.d.ts +14 -0
  116. package/dist/vendor/harness-reflex/ports/index.js +2 -0
  117. package/dist/vendor/harness-reflex/ports/index.js.map +1 -0
  118. package/dist/vendor/harness-reflex/ports/log.d.ts +22 -0
  119. package/dist/vendor/harness-reflex/ports/log.js +12 -0
  120. package/dist/vendor/harness-reflex/ports/log.js.map +1 -0
  121. package/dist/vendor/harness-reflex/ports/state.d.ts +46 -0
  122. package/dist/vendor/harness-reflex/ports/state.js +13 -0
  123. package/dist/vendor/harness-reflex/ports/state.js.map +1 -0
  124. package/package.json +25 -13
package/dist/config.d.ts CHANGED
@@ -40,31 +40,199 @@ export interface ReflexRoutingConfig {
40
40
  maxTaskChars?: number;
41
41
  }
42
42
  /**
43
- * Authored connection settings of the System One decision backend.
43
+ * One named System One connection profile.
44
44
  *
45
- * The Settings panel edits this block, so it is deliberately secret-free: the
46
- * API key never enters the settings document. `apiKeyEnv` names the environment
47
- * variable that holds the key, which keeps the credential in the deployment's
48
- * own environment (and out of every `settings.describe` answer, whose redaction
49
- * only covers schema-declared secret slots).
45
+ * A profile **is** the connection (g-066): there is no block of last resort
46
+ * beside it, so every field the runtime needs is either stated here or read out
47
+ * of the environment by the backend. The panel lists profiles, picks one as
48
+ * active, and tests each connection without ever receiving the key: `apiKey` is
49
+ * a schema-declared `role('secret')` slot, so DSH's structural redaction removes
50
+ * it from every wire-boundary value and reports its *presence* through a
51
+ * sidecar instead.
50
52
  *
51
- * Every field is optional and *overrides* the environment for this plugin
52
- * instance only. An omitted field keeps the environment/environment-default
53
- * behaviour of the backend implementation, so an existing env-configured
54
- * deployment is unaffected by adding the block.
53
+ * Legality: a profile name is a key of `systemOne.profiles`, so it may not be
54
+ * empty, may not contain `.` (the settings-route path separator), and may not
55
+ * collide after case folding — the panel shows these names as identifiers.
55
56
  */
56
- export interface ReflexSystemOneConfig {
57
+ export interface ReflexSystemOneProfile {
57
58
  /** Base URL of the Jev gateway or the OpenAI-compatible logits endpoint. */
58
59
  baseUrl?: string;
59
- /** Model id the backend asks for. */
60
+ /**
61
+ * The one legacy model id (pre-g-066 shape).
62
+ *
63
+ * A connection that authors this and nothing else keeps working untouched:
64
+ * {@link resolveSystemOneProfiles} treats it as a one-entry
65
+ * {@link modelIds} list. Authors spelling both is refused rather than guessed
66
+ * at, because the two say different things about which models exist.
67
+ */
60
68
  model?: string;
61
69
  /**
62
- * Name of the environment variable holding the API key (`SYSTEM_ONE_API_KEY`
63
- * by default). Never the key itself.
70
+ * Every model id this connection may ask for (g-066).
71
+ *
72
+ * A list, not a single id, because one gateway serves several models behind
73
+ * one URL and key. {@link selectedModel} is the one the *runtime* and the
74
+ * *probe* use — the two read the same field, so testing a connection tests
75
+ * what the next decision actually sends.
76
+ */
77
+ modelIds?: string[];
78
+ /**
79
+ * Which of {@link modelIds} is in force.
80
+ *
81
+ * Absent means "the first one", which is what a one-model connection always
82
+ * resolves to. A name outside the list is *reported*
83
+ * ({@link ResolvedSystemOneConfig.activeProfileModelMissing}) and resolves to
84
+ * nothing instead of silently running a model nobody selected: quietly
85
+ * picking the first entry is exactly the "switched behind my back" behaviour
86
+ * this goal removes.
87
+ */
88
+ selectedModel?: string;
89
+ /**
90
+ * The API key itself.
91
+ *
92
+ * Write-only: schemastery declares it `role('secret')`, so it never crosses a
93
+ * wire boundary and no response can echo it. Absent means "no key stated by
94
+ * this profile" — the resolution chain then falls through to `apiKeyEnv`.
95
+ */
96
+ apiKey?: string;
97
+ /**
98
+ * Name of the environment variable holding the API key. Never the key itself.
99
+ *
100
+ * Kept beside {@link apiKey} on purpose: a profile may name an environment
101
+ * variable instead of carrying a secret.
64
102
  */
65
103
  apiKeyEnv?: string;
66
104
  /** Per-request timeout in milliseconds. */
67
105
  timeoutMs?: number;
106
+ /** Backend override for this profile (`auto`/`mock`/`jev`/`vllm`). */
107
+ backend?: string;
108
+ }
109
+ /** Row name of the factory connection, as the panel shows it. */
110
+ export declare const FACTORY_PROFILE_NAME = "JEV official";
111
+ /** The environment variable the factory connection locks onto — never another. */
112
+ export declare const FACTORY_PROFILE_API_KEY_ENV = "JEV_API_KEY";
113
+ /**
114
+ * The factory connection (g-067): the project's own Jev gateway, switched on.
115
+ *
116
+ * A deployment whose settings document declares **no** `systemOne` block is a
117
+ * **fresh document**, and it should not open on "no connection, nothing works":
118
+ * the plugin ships with one working remote connection already named, already
119
+ * active, pointing at the official endpoint and model, and locked onto
120
+ * {@link FACTORY_PROFILE_API_KEY_ENV}.
121
+ *
122
+ * It is deliberately a normal profile — an entry of `systemOne.profiles` with
123
+ * nothing special about it — and it is supplied by the **schema default**
124
+ * (`Config.systemOne`), which schemastery applies only to an *absent* key. That
125
+ * single rule is the whole distinction between "fresh" and "the owner said
126
+ * something":
127
+ *
128
+ * - **deactivate** — the page writes `systemOne.active: ''`; the section is
129
+ * stated, resolves as `no-active-profile`, and **no** factory row is filled
130
+ * back in (the row stays listed, switched off);
131
+ * - **delete** — the page unsets the row *and* states the empty activation, so
132
+ * the section is `{profiles: {}, active: ''}` → `no-profiles`, and nothing is
133
+ * filled back in;
134
+ * - **rename / replace** — any authored `systemOne` block wins outright; the
135
+ * factory row is only ever materialized into a document that has none.
136
+ *
137
+ * The one write that would blur the line is a cleared path whose parent is then
138
+ * rebuilt from nothing (`{}`, which schemastery does not default): that is why
139
+ * the page never unsets `systemOne.active` or the last profile row on its own —
140
+ * it states an explicit empty activation instead.
141
+ *
142
+ * The lock matters as much as the row. `apiKeyEnv` **names** the variable, and
143
+ * naming locks (g-059): with no `JEV_API_KEY` exported the connection reports
144
+ * "named but empty" and sends no key — it never reaches for
145
+ * `SYSTEM_ONE_API_KEY`, `VLLM_API_KEY` or `OPENAI_API_KEY` behind the owner's
146
+ * back. Only the variable *name* is ever authored; the secret itself is never
147
+ * written into a settings document by this row.
148
+ *
149
+ * ## The implementation is bound, not left to `auto` (g-067 att-002)
150
+ *
151
+ * The row pins `backend: 'jev'` rather than inheriting the top-level selector.
152
+ * An independent review blocked the first attempt for exactly this: with no
153
+ * `backend` on the row, a fresh deployment (top-level `backend: 'auto'`) had its
154
+ * implementation chosen from the *environment* on every build — `auto` delegates
155
+ * to the vendored factory, which reads `SYSTEM_ONE_BACKEND`/`REFLEX_BACKEND` and
156
+ * `VLLM_BASE_URL`/`OPENAI_BASE_URL`. Exporting two variables therefore took the
157
+ * already-resolved `JEV_API_KEY` and sent it as `Authorization` to a vLLM
158
+ * endpoint nobody configured, while the panel's connection test — which treats
159
+ * `auto` as Jev — still probed the official URL and reported green.
160
+ *
161
+ * So the factory row states all three of the facts a connection has: where
162
+ * (official URL), what model, and **which implementation speaks it**. The
163
+ * implementation is no longer something the environment can change underneath a
164
+ * connection the plugin shipped. This is a row-level binding, which is the
165
+ * documented precedence for every profile — not a top-level override: an
166
+ * authored row, and a deployment's own `backend` selector for authored rows,
167
+ * are untouched.
168
+ *
169
+ * An **explicit** top-level `mock` still answers in-process: a mock never opens
170
+ * a socket, so it cannot send the key anywhere, and `createBackend` honours it
171
+ * before any transport is built (see its mock branch). What the binding removes
172
+ * is the *implicit* `auto` route, which is the one the environment decided.
173
+ */
174
+ export declare const FACTORY_SYSTEMONE_PROFILE: Readonly<{
175
+ baseUrl: "https://api.typesafe.ai/v1/systemone";
176
+ model: "jev-latest";
177
+ apiKeyEnv: "JEV_API_KEY";
178
+ backend: "jev";
179
+ }>;
180
+ /**
181
+ * Authored connection settings of the System One decision backend.
182
+ *
183
+ * **Only named profiles connect** (g-066). The flat `baseUrl` / `model` /
184
+ * `apiKeyEnv` / `timeoutMs` fields this block used to carry beside
185
+ * `profiles` are gone, together with the "profile over flat over environment"
186
+ * merge they made possible: with no valid active profile the plugin is
187
+ * *unconfigured* and sends no external request at all. Silently running some
188
+ * other block — or picking whatever environment variable happened to be
189
+ * exported — is the behaviour the goal removes.
190
+ *
191
+ * The fields are deliberately **not declared on the schema** any more, for two
192
+ * reasons:
193
+ *
194
+ * 1. Schemastery drops what an object does not declare, so a settings document
195
+ * that still carries them (written by an earlier release) keeps them on disk
196
+ * untouched instead of having them rewritten under the page's feet. g-066
197
+ * converts nothing: migration is the owner's decision, not a side effect of
198
+ * opening a panel.
199
+ * 2. A deployment authored in `cordis.patch.yml` with the old flat shape still
200
+ * hands those keys to {@link resolveSystemOneConfig} — read below under
201
+ * `legacy*` — and they can *only* describe a connection that this plugin
202
+ * would previously have used implicitly. Reading them is what turns "your
203
+ * working deployment now fails closed with no explanation" into a precise
204
+ * message telling the owner to name a profile.
205
+ *
206
+ * An omitted profile field keeps the environment/default behaviour of the
207
+ * backend implementation.
208
+ */
209
+ export interface ReflexSystemOneConfig {
210
+ /** Named connection profiles, keyed by the name the panel shows. */
211
+ profiles?: Record<string, ReflexSystemOneProfile>;
212
+ /**
213
+ * Name of the profile in force.
214
+ *
215
+ * A name that matches no authored profile is *not* silently ignored: the
216
+ * resolution reports `activeProfileMissing` and resolves **nothing**, which
217
+ * the panel shows as a warning and the runtime treats as unconfigured.
218
+ * Failing the whole activation was the alternative and was rejected: a single
219
+ * mistyped name would take every reflex tool down, and the tools still have
220
+ * their deterministic local fallbacks.
221
+ */
222
+ active?: string;
223
+ /**
224
+ * Pre-g-066 flat connection fields, read for the *diagnosis* only.
225
+ *
226
+ * Never used to connect: see {@link ReflexSystemOneConfig}. Kept out of the
227
+ * authoring schema; listed here so the resolution can name them.
228
+ */
229
+ baseUrl?: string;
230
+ /** Pre-g-066 flat model id; diagnosis only. */
231
+ model?: string;
232
+ /** Pre-g-066 flat key-variable name; diagnosis only. */
233
+ apiKeyEnv?: string;
234
+ /** Pre-g-066 flat timeout; diagnosis only. */
235
+ timeoutMs?: number;
68
236
  }
69
237
  /**
70
238
  * The three-state vocabulary every automatic capability shares.
@@ -236,6 +404,26 @@ export interface ReflexToolsConfig {
236
404
  */
237
405
  enabled?: Partial<Record<ReflexToolSuffix, boolean>>;
238
406
  }
407
+ /**
408
+ * Authored switch of the *host capability* the delegation tool needs.
409
+ *
410
+ * Deliberately not part of {@link ReflexToolsConfig}: `tools.enabled.<suffix>`
411
+ * decides whether this plugin registers a tool it can serve on its own, while
412
+ * this flag decides whether the Host is asked to publish the model-selection
413
+ * surface `reflex_delegate` needs. Ticking it is a consent to edit the host
414
+ * profile patch (`tool-subagent.config.modelSelection: true`) — a file this
415
+ * plugin otherwise never touches, and whose change only applies after a DSH
416
+ * restart.
417
+ */
418
+ export interface ReflexDelegationConfig {
419
+ /**
420
+ * Whether the delegation capability is asked for. Default `false`: the tool
421
+ * does not work until the Host's `tool-subagent` publishes `reasoning_effort`,
422
+ * so the switch starts off rather than advertising a tool that cannot carry a
423
+ * level. `true` means "I want it, and I agree to the host switch it needs".
424
+ */
425
+ enabled?: boolean;
426
+ }
239
427
  /** Deployment configuration for the reflex tool bundle. */
240
428
  export interface ReflexConfig {
241
429
  /**
@@ -264,6 +452,8 @@ export interface ReflexConfig {
264
452
  effort?: ReflexEffortConfig;
265
453
  /** Per-tool switches of the eight reflex tools. */
266
454
  tools?: ReflexToolsConfig;
455
+ /** The host capability `reflex_delegate` depends on. */
456
+ delegation?: ReflexDelegationConfig;
267
457
  /** Automatic interventions on the Host's tool and agent lifecycle hooks. */
268
458
  interventions?: ReflexInterventionsConfig;
269
459
  }
@@ -279,14 +469,93 @@ export interface ResolvedRoutingConfig {
279
469
  export interface ResolvedSystemOneConfig {
280
470
  /** Selected implementation; `auto` keeps the environment heuristics. */
281
471
  backend: 'auto' | 'mock' | 'jev' | 'vllm';
282
- /** Base URL override, absent when the environment decides. */
472
+ /**
473
+ * Base URL of the connection in force, absent when nothing selected one.
474
+ *
475
+ * Since g-066 this is *the active profile's* address (or, for a profile that
476
+ * states none, nothing at all — the backend then reads the environment). It
477
+ * is never inherited from a block beside the profile, because no such block
478
+ * exists any more.
479
+ */
283
480
  baseUrl?: string;
284
- /** Model id override, absent when the environment decides. */
481
+ /** Model id the runtime asks for: the active profile's selected model. */
285
482
  model?: string;
286
483
  /** Environment variable that holds the API key; never the key itself. */
287
484
  apiKeyEnv?: string;
288
485
  /** Per-request timeout override in milliseconds. */
289
486
  timeoutMs?: number;
487
+ /**
488
+ * The API key of the *resolved* profile, when the chain found one.
489
+ *
490
+ * Never serialized to a panel or route: {@link ResolvedSystemOneConfig} is only
491
+ * handed to {@link createBackend} and to the connection probe.
492
+ */
493
+ apiKey?: string;
494
+ /** Active profile name as authored, when one was. */
495
+ active?: string;
496
+ /**
497
+ * Every profile, normalized, in authored order. Keys are the panel's row ids.
498
+ *
499
+ * Absent when the document authors no `profiles` at all.
500
+ */
501
+ profiles?: Record<string, ResolvedSystemOneProfile>;
502
+ /**
503
+ * The authored `active` name matched no profile.
504
+ *
505
+ * The panel shows this as a warning and the runtime is **unconfigured**: it
506
+ * makes no connection of its own accord. Nothing is resolved from anywhere
507
+ * else, so a typo cannot silently run a connection the user did not select.
508
+ */
509
+ activeProfileMissing?: boolean;
510
+ /**
511
+ * Why nothing can be connected, when nothing can (g-066).
512
+ *
513
+ * - `no-active-profile`: profiles exist but none is activated;
514
+ * - `no-profiles`: the document authors no profile at all;
515
+ * - `active-profile-missing`: `active` names no authored profile;
516
+ * - `legacy-config-required`: the document carries only the pre-g-066 flat
517
+ * fields, which no longer connect anything;
518
+ * - `model-selection-unusable`: the active profile resolved, but the model its
519
+ * configuration puts in force cannot be sent (owner-authored refusal);
520
+ * - `model-selection-invalid`: the active profile's *selected* model is not in
521
+ * its list, so nothing runs (see {@link activeProfileModelMissing}).
522
+ *
523
+ * Absent exactly when an active profile resolved **and** its model is
524
+ * sendable. The panel renders it as the "unconfigured" state and the backend
525
+ * refuses to build, so an unusable model never becomes a request to some other
526
+ * model (g-066 att-002).
527
+ */
528
+ unconfigured?: 'no-active-profile' | 'no-profiles' | 'active-profile-missing' | 'legacy-config-required' | 'model-selection-unusable' | 'model-selection-invalid';
529
+ /**
530
+ * The active profile names a `selectedModel` that is not in its `modelIds`.
531
+ *
532
+ * Reported, and the resolved {@link model} is left absent rather than falling
533
+ * back to the first id: a connection whose *selected* model does not exist is
534
+ * a broken selection, not an invitation to run a different model. Since
535
+ * g-066 att-002 it is also *final*: {@link unconfigured} is set with
536
+ * `model-selection-invalid` and {@link createBackend} builds no transport, so
537
+ * the backend's own `|| DEFAULT_MODEL` fallback can never turn "nothing was
538
+ * selected" into a request for a model nobody picked.
539
+ */
540
+ activeProfileModelMissing?: boolean;
541
+ }
542
+ /** One profile after defaults and validation. */
543
+ export interface ResolvedSystemOneProfile {
544
+ baseUrl?: string;
545
+ /**
546
+ * Every model id the connection offers, in authored order.
547
+ *
548
+ * Derived from `modelIds`, or from a legacy single `model` as a one-entry
549
+ * list — so every connection has the same shape downstream.
550
+ */
551
+ modelIds?: string[];
552
+ /** The model in force for this connection (see {@link ReflexSystemOneProfile.selectedModel}). */
553
+ selectedModel?: string;
554
+ /** The key this profile carries. Write-only; see {@link ReflexSystemOneProfile}. */
555
+ apiKey?: string;
556
+ apiKeyEnv?: string;
557
+ timeoutMs?: number;
558
+ backend?: 'auto' | 'mock' | 'jev' | 'vllm';
290
559
  }
291
560
  /** Effort configuration after defaults and validation have been applied. */
292
561
  export interface ResolvedEffortConfig {
@@ -307,6 +576,14 @@ export interface ResolvedToolsConfig {
307
576
  /** Suffix → whether the tool is registered. Every suffix has an entry. */
308
577
  enabled: Record<ReflexToolSuffix, boolean>;
309
578
  }
579
+ /** Delegation switch after defaults have been applied. */
580
+ export interface ResolvedDelegationConfig {
581
+ /**
582
+ * Whether the user has consented to the host `modelSelection` switch this
583
+ * activation's `reflex_delegate` needs. Default `false`.
584
+ */
585
+ enabled: boolean;
586
+ }
310
587
  /** Configuration after defaults and validation have been applied. */
311
588
  export interface ResolvedReflexConfig {
312
589
  backend: 'auto' | 'mock' | 'jev' | 'vllm';
@@ -318,6 +595,7 @@ export interface ResolvedReflexConfig {
318
595
  routing: ResolvedRoutingConfig;
319
596
  effort: ResolvedEffortConfig;
320
597
  tools: ResolvedToolsConfig;
598
+ delegation: ResolvedDelegationConfig;
321
599
  interventions: ResolvedInterventionsConfig;
322
600
  }
323
601
  /**
@@ -363,23 +641,240 @@ export declare function resolveInterventionSetting(value: string | undefined, al
363
641
  export declare function resolveInterventionsConfig(authored: ReflexInterventionsConfig | undefined, pruneThreshold?: number): ResolvedInterventionsConfig;
364
642
  /**
365
643
  * Validate the System One connection block and fill in every default.
366
- * @param backend - the top-level backend selector.
644
+ *
645
+ * ## The resolution rule (g-066: one connection, the active profile)
646
+ *
647
+ * **Only the active profile connects.** Every connection field — `baseUrl`,
648
+ * `model`, `apiKey`, `apiKeyEnv`, `timeoutMs`, `backend` — comes from the
649
+ * profile `active` names, or stays `undefined` and is then decided by the
650
+ * backend's own environment read and documented default.
651
+ *
652
+ * There is no block of last resort. A document with no valid active profile
653
+ * resolves to {@link ResolvedSystemOneConfig.unconfigured} with **no** connection
654
+ * fields at all, so nothing downstream can invent one:
655
+ *
656
+ * | document | `unconfigured` |
657
+ * | ----------------------------------------- | ------------------------- |
658
+ * | no profiles at all | `no-profiles` |
659
+ * | profiles, none activated | `no-active-profile` |
660
+ * | `active` naming a profile that is not there | `active-profile-missing` |
661
+ * | only the pre-g-066 flat fields | `legacy-config-required` |
662
+ *
663
+ * The pre-g-066 merge ("active profile over flat block over environment") was
664
+ * removed because the *fallback* was the bug: a mistyped or missing activation
665
+ * ran a connection the user never selected. The legacy fields are still *read*,
666
+ * but only to name the problem in `legacy-config-required` — converting them into
667
+ * a profile would be a silent configuration change (and, for `apiKeyEnv`, a
668
+ * silent choice between a literal key and a variable), so this function never
669
+ * does it.
670
+ *
671
+ * `apiKey` and `apiKeyEnv` stay independent, so a profile may carry a literal key
672
+ * while naming no variable, or name a variable and carry no key;
673
+ * {@link resolveApiKeyWithSource} decides which the transport presents.
674
+ *
675
+ * @param backend - the top-level backend selector (the fallback implementation
676
+ * choice for a profile that states none).
367
677
  * @param authored - the authored `systemOne` block.
368
678
  * @returns the resolved connection settings.
369
679
  * @throws Error when a field is present but unusable.
370
680
  */
371
681
  export declare function resolveSystemOneConfig(backend: 'auto' | 'mock' | 'jev' | 'vllm' | undefined, authored: ReflexSystemOneConfig | undefined): ResolvedSystemOneConfig;
682
+ /**
683
+ * The environment variables the key chain falls back to, in order.
684
+ *
685
+ * This list is the *whole* fallback, exported so callers that want to name the
686
+ * candidates (the panel's "nothing configured" copy) read it from here instead of
687
+ * restating it. Changing the order here changes it for the backend, the panel,
688
+ * and the connection probe at once — which is the point.
689
+ */
690
+ export declare const API_KEY_ENV_FALLBACKS: readonly ["SYSTEM_ONE_API_KEY", "JEV_API_KEY", "VLLM_API_KEY", "OPENAI_API_KEY"];
691
+ /**
692
+ * The outcome of resolving one connection's key.
693
+ *
694
+ * A discriminated union rather than `{ key } | undefined` (g-059): "the block
695
+ * named a variable and that variable is empty" is a *different fact* from "the
696
+ * block named nothing and nothing was exported", and the panel has to say which.
697
+ * Collapsing both into `undefined` is exactly what let the two be conflated.
698
+ *
699
+ * - `{ key }` — a key was found; {@link source} says where.
700
+ * - `{ missing: 'named', variable }` — the block **named** `variable` and it holds
701
+ * nothing. Naming is a lock: no fallback variable was consulted, and none may be.
702
+ * - `undefined` — the block named nothing and no fallback variable holds a key.
703
+ */
704
+ export type ApiKeyResolution = ResolvedApiKey | ApiKeyNotFound;
705
+ /** Where a resolved key came from. */
706
+ export interface ResolvedApiKey {
707
+ /** The key itself. Stays in the host process; no projection serializes it. */
708
+ key: string;
709
+ /**
710
+ * `profile` for a literal key from the settings document; `env` for the
711
+ * variable the block named; `fallback` for a {@link API_KEY_ENV_FALLBACKS}
712
+ * variable reached because the block named none. `fallback` is a separate tag
713
+ * so the panel can print "(回退)" — a deployment that *meant* to name a
714
+ * variable can then see that it in fact named nothing.
715
+ */
716
+ source: 'profile' | 'env' | 'fallback';
717
+ /** The variable that supplied the key when {@link source} is `env` or `fallback`. */
718
+ variable?: string;
719
+ }
720
+ /** The variable the block named holds nothing, and the lookup stopped there. */
721
+ export interface ApiKeyNotFound {
722
+ /** Why nothing resolved. */
723
+ missing: 'named';
724
+ /** The variable the block named — the empty one, never a fallback. */
725
+ variable: string;
726
+ }
727
+ /**
728
+ * Resolve the API key for a connection, and say where it came from.
729
+ *
730
+ * This is the **single source of truth** for the key chain. The backend
731
+ * constructors, the panel's readiness projection, and the `/systemone/test`
732
+ * probe all call it, so the panel can never again report a different reality
733
+ * from the one the runtime acts on.
734
+ *
735
+ * The chain, in order:
736
+ *
737
+ * 1. **`config.apiKey`** — a literal key from the settings document, where it is
738
+ * a declared `role('secret')` slot. It outranks every variable and makes
739
+ * `apiKeyEnv` irrelevant: a deployment that stores the secret outright has no
740
+ * use for a variable *name*.
741
+ * 2. **`config.apiKeyEnv`** — the variable the connection *names*. **Naming
742
+ * locks**: this is the only variable consulted, and if it is empty the result
743
+ * is {@link ApiKeyNotFound} — never a fallback to step 3. The settings
744
+ * document carries only the name, so a panel write cannot leak the value.
745
+ * 3. **{@link API_KEY_ENV_FALLBACKS}** — only when step 2 named nothing:
746
+ * `SYSTEM_ONE_API_KEY`, `JEV_API_KEY`, `VLLM_API_KEY`, `OPENAI_API_KEY`,
747
+ * first non-empty wins.
748
+ *
749
+ * Step 2 no longer falls through to step 3 (g-059). The earlier choice — "naming
750
+ * a variable is not a request to lock onto it" — was reversed by the owner: a
751
+ * deployment that names `SYSTEM_ONE_API_KEY` while only `JEV_API_KEY` is
752
+ * exported must read as *missing*, not silently work from a variable nobody
753
+ * named. Locking is now implied by naming, so an empty value cannot be mistaken
754
+ * for "nobody named anything".
755
+ *
756
+ * An empty string counts as absent at every step, so an exported-but-empty
757
+ * variable is never a credential.
758
+ *
759
+ * A **blank** `apiKeyEnv` (spaces only) is not a naming:
760
+ * {@link resolveSystemOneConfig} trims it away before this function sees it, so
761
+ * a stray space in the name field keeps the historical fallback instead of
762
+ * locking onto a variable whose name is a space.
763
+ *
764
+ * @param config - resolved System One connection settings (a profile's, or the flat block's).
765
+ * @param env - environment to read; defaults to `process.env`.
766
+ * @returns the key and its provenance; the locked-but-empty fact; or `undefined`
767
+ * when nothing was named and nothing was exported.
768
+ */
769
+ export declare function resolveApiKeyWithSource(config: Pick<ResolvedSystemOneConfig, 'apiKeyEnv' | 'apiKey'>, env?: Record<string, string | undefined>): ApiKeyResolution | undefined;
770
+ /**
771
+ * The key a resolution carries, or `undefined` for both kinds of absence.
772
+ *
773
+ * The one place the union is flattened: a transport only needs to know *whether*
774
+ * there is a key, never *why* there is none. Panel copy must not use this —
775
+ * telling "named but empty" from "nothing configured" is the point of the union.
776
+ * @param resolution - a {@link resolveApiKeyWithSource} result.
777
+ * @returns the key, when one resolved.
778
+ */
779
+ export declare function resolvedKeyOf(resolution: ApiKeyResolution | undefined): string | undefined;
372
780
  /**
373
781
  * Read the API key a resolved connection block points at.
374
782
  *
375
- * The indirection is the point: the settings document carries the variable's
376
- * *name*, so a panel write can never leak the credential into a file the Host
377
- * then renders back to every client.
783
+ * A thin wrapper over {@link resolveApiKeyWithSource}: callers that need only the
784
+ * value use this one, and callers that must report *where* it came from use that
785
+ * one. Deliberately kept as the only spelling of the chain — a second
786
+ * implementation here is exactly the drift (`panel says empty, backend works`)
787
+ * this pair exists to prevent.
788
+ *
378
789
  * @param config - resolved System One connection settings.
379
790
  * @param env - environment to read; defaults to `process.env`.
380
- * @returns the key, or `undefined` when the variable is unset or empty.
791
+ * @returns the key, or `undefined` when no source holds one.
381
792
  */
382
- export declare function resolveApiKey(config: Pick<ResolvedSystemOneConfig, 'apiKeyEnv'>, env?: Record<string, string | undefined>): string | undefined;
793
+ export declare function resolveApiKey(config: Pick<ResolvedSystemOneConfig, 'apiKeyEnv' | 'apiKey'>, env?: Record<string, string | undefined>): string | undefined;
794
+ /** The connection facts one probe target carries (never a value it can echo). */
795
+ export interface ConnectionTarget {
796
+ /** Profile name this target was projected from. */
797
+ name: string;
798
+ /** Backend that would serve this target. */
799
+ backend: 'auto' | 'mock' | 'jev' | 'vllm';
800
+ baseUrl?: string;
801
+ model?: string;
802
+ apiKeyEnv?: string;
803
+ /** The key to present. Stays in this process; never serialized. */
804
+ apiKey?: string;
805
+ timeoutMs?: number;
806
+ /**
807
+ * This connection's model cannot be sent (g-066 att-002): its `selectedModel`
808
+ * is not in its list, or no implementation could be sure which model to ask
809
+ * for when it names none. A probe reports this instead of guessing a model.
810
+ */
811
+ modelUnusable?: boolean;
812
+ }
813
+ /**
814
+ * Project one profile's connection facts for the connection test.
815
+ *
816
+ * The probe must send exactly the request the runtime would send, so both read
817
+ * the *same* profile fields: base URL, the **selected** model
818
+ * ({@link modelForProfile}), the key and its variable, the timeout, and the
819
+ * backend. Since g-066 there is nothing to merge — a profile that states no
820
+ * `baseUrl` inherits from **nobody**, and the backend's own environment read is
821
+ * the only thing left below it, exactly as for the runtime.
822
+ *
823
+ * The model is derived rather than read from {@link ConnectionTarget.model}, so a
824
+ * probe can never test a model the runtime does not run: one `selectedModel`
825
+ * outside `modelIds` makes both of them **absent** (and the panel says why,
826
+ * while {@link resolveSystemOneConfig} refuses to connect at all). A profile that
827
+ * lists no model is the one case where the answer is the implementation default
828
+ * — the same {@link plannedModel} the resolved connection uses, so the two can
829
+ * never disagree about which model a connection asks for.
830
+ *
831
+ * `modelUnusable` is the probe's whole answer for a connection whose model
832
+ * cannot be sent: it must not guess one instead.
833
+ *
834
+ * @param flat - the resolved block, supplying the backend fallback only.
835
+ * @param name - profile name (the probe's label).
836
+ * @param profile - the profile to project.
837
+ * @returns the target's connection facts.
838
+ */
839
+ export declare function connectionTarget(flat: Pick<ResolvedSystemOneConfig, 'backend'>, name: string, profile: ResolvedSystemOneProfile): ConnectionTarget;
840
+ /** The transport a connection resolves to: the three the plugin can build. */
841
+ export type ConnectionImplementation = 'mock' | 'jev' | 'vllm';
842
+ /**
843
+ * The implementation a connection's backend selector really builds (g-067 att-002).
844
+ *
845
+ * The one place `auto` is turned into a concrete transport, asked by both ends
846
+ * of the same connection: {@link createBackend} builds from it, and the
847
+ * connection test probes with it. Any second derivation is a divergence waiting
848
+ * to happen — and one already happened: the probe hard-coded `auto → jev` while
849
+ * `auto` in the runtime delegated to the vendored factory, which reads the
850
+ * environment. Under `SYSTEM_ONE_BACKEND=vllm` the test button probed the
851
+ * official Jev URL and reported green while the runtime dialled a vLLM endpoint
852
+ * with the same key.
853
+ *
854
+ * `auto` is modelled exactly as far as it is deterministic: the vendored
855
+ * factory's own precedence, read from the environment —
856
+ *
857
+ * 1. an explicit `SYSTEM_ONE_BACKEND` / `REFLEX_BACKEND` selects that provider
858
+ * (`jev`, or `vllm`/`simple-jev`/`logits` as the logits backend);
859
+ * 2. with no selector, a Jev credential (`SYSTEM_ONE_API_KEY` / `JEV_API_KEY`)
860
+ * selects Jev, then a vLLM endpoint selects the logits backend;
861
+ * 3. anything else is the in-process mock.
862
+ *
863
+ * Note what this function does **not** do: it does not make `auto` safe. It
864
+ * makes the two halves honest about the same answer. A connection that must not
865
+ * follow the environment pins its own `backend` instead — which is what the
866
+ * factory row does ({@link FACTORY_SYSTEMONE_PROFILE}).
867
+ *
868
+ * The one deviation from the factory is deliberate: with a selector naming a
869
+ * provider, the factory's "any other name falls through to the mock" is kept,
870
+ * because that is what the runtime really builds — guessing Jev there would
871
+ * reintroduce the false green from the other side.
872
+ *
873
+ * @param selector - the connection's effective backend selector.
874
+ * @param env - the environment the `auto` factory would read.
875
+ * @returns the transport that would be built.
876
+ */
877
+ export declare function connectionImplementation(selector: string, env?: Record<string, string | undefined>): ConnectionImplementation;
383
878
  /**
384
879
  * Read a resolved config value out of its volatile marker.
385
880
  */
@@ -427,6 +922,19 @@ export declare function resolveConfig(config?: ReflexConfig): ResolvedReflexConf
427
922
  * @throws Error when the block, a key, or a value cannot be honoured.
428
923
  */
429
924
  export declare function resolveToolsConfig(authored: ReflexToolsConfig | undefined): ResolvedToolsConfig;
925
+ /**
926
+ * Validate the delegation block and fill in its default.
927
+ *
928
+ * The default is `false` and it is load-bearing: with the switch on, the tool
929
+ * is offered; with it off, `reflex_delegate` is not registered at all, because a
930
+ * wrapper whose level cannot be delivered would be a capability that only looks
931
+ * like one. A non-boolean is refused rather than coerced, for the same reason
932
+ * every other block refuses one.
933
+ * @param authored - the authored `delegation` block.
934
+ * @returns the resolved switch.
935
+ * @throws Error when the value is present but not a boolean.
936
+ */
937
+ export declare function resolveDelegationConfig(authored: ReflexDelegationConfig | undefined): ResolvedDelegationConfig;
430
938
  /**
431
939
  * Validate one authored `reasoningEffort` value.
432
940
  *