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/bridge.d.ts CHANGED
@@ -1,15 +1,32 @@
1
+ import type { Agent } from '@deepseek-ai/dsh-agent';
1
2
  import { Calibrator, DecisionLedger, ReflexGateService, ReflexRouter, ReflexScreenService, StagnationDetector, ToolResultPruner, scoreStatement } from './vendor/harness-reflex/index.js';
2
3
  import type { ActionStep, BackendHealth, CandidateItem, ChoiceResponse, DecisionBackend, GateResponse, RouteResponse, ScreenResult, StagnationCheckResponse } from './vendor/harness-reflex/index.js';
3
4
  import type { ResolvedInterventionsConfig, ResolvedReflexConfig, ResolvedRoutingConfig } from './config.js';
4
5
  import { EffortInterceptor, EffortStatusFeed, type ReflexEffortStatus } from './effort.js';
6
+ import type { DelegatedEffortInheritance } from './effort-delegation.js';
7
+ import type { DelegationHealth } from './delegation-health.js';
5
8
  import type { InterventionEngine } from './interventions.js';
6
9
  import { VirtualModelRouter } from './router.js';
10
+ import { type Attribution, type CallIdentity, type CallSource } from './attribution.js';
11
+ /**
12
+ * What one dispatch observed about itself.
13
+ *
14
+ * `identity` is taken *before* the call is awaited (see {@link callIdentity}),
15
+ * so a profile switch during an in-flight call cannot restate it; `source` is
16
+ * filled once the call settles. The pair travels together into the tool payload
17
+ * and the ledger entry, which is what keeps the two surfaces agreeing.
18
+ */
19
+ interface DispatchOutcome {
20
+ readonly identity: CallIdentity;
21
+ readonly source: CallSource;
22
+ readonly detail?: string;
23
+ }
7
24
  /** Payload of the `choice` operation, mirroring the stdio MCP surface. */
8
25
  export type ReflexChoiceResult = ChoiceResponse & {
9
26
  calibratedConfidence?: number;
10
- };
27
+ } & Attribution;
11
28
  /** Payload of the `prune` operation, mirroring the stdio MCP surface. */
12
- export interface ReflexPruneResult {
29
+ export interface ReflexPruneResult extends Attribution {
13
30
  tokensSaved: number;
14
31
  reductionPercentage: string;
15
32
  shadow: boolean;
@@ -28,6 +45,136 @@ export interface ReflexLedgerResult {
28
45
  */
29
46
  systemOneHealth?: BackendHealth;
30
47
  }
48
+ /**
49
+ * The slice of {@link DecisionLedger} a decision service uses.
50
+ *
51
+ * Declared structurally so this decorator never pretends to be the ledger: the
52
+ * services only ever call `record`, and the runtime keeps the real ledger for
53
+ * every other read.
54
+ */
55
+ type LedgerSink = Pick<DecisionLedger, 'record'>;
56
+ /**
57
+ * One already-attributed call, for callers that drive a decision service
58
+ * themselves instead of going through {@link ReflexRuntime.choice} and friends.
59
+ *
60
+ * `ledger` is the call's private buffer; `settle` appends it once the source is
61
+ * known and returns the attribution to put on the caller's own payload.
62
+ */
63
+ export interface CallRing {
64
+ /** The ledger ring this call's service entries are buffered in. */
65
+ readonly ledger: LedgerSink;
66
+ /**
67
+ * Close the ring: append its entries with the final source.
68
+ * @param outcome - the settled source.
69
+ * @returns the attribution for the caller's payload.
70
+ */
71
+ settle(outcome: {
72
+ source: CallSource;
73
+ detail?: string;
74
+ }): Attribution;
75
+ }
76
+ /**
77
+ * The attributed, append-only ledger sink every decision service writes through.
78
+ *
79
+ * ## Why a decorator rather than fields on the entry (g-068)
80
+ *
81
+ * `ReflexGateService`, `ReflexRouter`, `ToolResultPruner` and the rest write
82
+ * their *own* ledger entry while they run, and that entry is the one a reader
83
+ * sees. `DecisionLedger` is shared with the root stdio MCP package, whose
84
+ * contract g-068 must not touch, so this layer keeps the provenance inside the
85
+ * entry's existing open `details` bag instead of adding fields to it.
86
+ *
87
+ * ## Per-call isolation (the att-001 review's BLOCK-1)
88
+ *
89
+ * The first attempt kept **one** "current stamp" field and cleared it in a
90
+ * `finally`. Two overlapping calls then destroyed each other's attribution: the
91
+ * fast call's clear wiped the slow call's stamp, the slow call's service entry
92
+ * was written unattributed, and its payload still said `local-fallback`. The
93
+ * ledger and the payload disagreed about the same call, which is the exact
94
+ * falsehood this goal exists to remove. There is no single shared field any
95
+ * more: {@link open} returns a *token*, a service's entry is held in a buffer
96
+ * **owned by that token**, and nothing a concurrent call does can reach it.
97
+ *
98
+ * ## Written once, finished, never rewritten (BLOCK-2)
99
+ *
100
+ * A service writes its entry *before* the answer settles, when `source` is still
101
+ * unknown. Stamp-then-rewrite-the-last-JSONL-line was the first attempt's answer
102
+ * to that, and it was wrong twice over: it rewrote a line that might belong to
103
+ * another call, and rewriting a whole file is an append-only violation that can
104
+ * truncate a sink another writer is appending to. Here the service's entry is
105
+ * **buffered** on its token; when the call settles, {@link finish} appends that
106
+ * one entry exactly once — identity *and* source together, already final. An
107
+ * unregistered token (a call that threw before settling) falls back to the
108
+ * buffered group in {@link flush}, so no entry is ever lost. The JSONL file is
109
+ * therefore only ever appended to: no line is rewritten and no line is moved.
110
+ *
111
+ * ## Why attribution can honestly be `unknown`
112
+ *
113
+ * A call whose outcome cannot be proven must say so rather than claim `remote`.
114
+ * Two paths reach that state and both end up here: a backend that exposes no
115
+ * failure record at all (the vLLM logits backend) and a call whose service entry
116
+ * was written after the call had already settled ({@link AttributedLedger.report}
117
+ * explains how). See {@link classifyEvidence}.
118
+ */
119
+ export declare class AttributedLedger {
120
+ #private;
121
+ private readonly target;
122
+ /**
123
+ * @param target - the activation's real ledger sink.
124
+ */
125
+ constructor(target: LedgerSink);
126
+ /**
127
+ * Open one call's ledger context.
128
+ * @param identity - the identity taken at dispatch, before the call is awaited.
129
+ * @returns the token to settle the call with, and the sink its services write through.
130
+ */
131
+ open(identity: CallIdentity): {
132
+ token: number;
133
+ ledger: LedgerSink;
134
+ };
135
+ /**
136
+ * The sink a service writes through when no call is in force.
137
+ *
138
+ * A service driven directly — the automatic-intervention engine, a
139
+ * programmatic caller, a test — has no dispatch context to attribute it to.
140
+ * Its entry is appended **immediately** (dropping it would lose an audited
141
+ * judgment) with the source the service itself reported when it reported one
142
+ * (a `systemOneSource`-style field on the entry), and `unknown` otherwise. It is
143
+ * never left to read as a remote success.
144
+ * @param token - the identity-less call id, for logging only.
145
+ * @returns the unattributed sink.
146
+ */
147
+ unattributedSink(): LedgerSink;
148
+ /**
149
+ * Append what one call held, once, with the final source.
150
+ *
151
+ * The source is written into `details` here — the last moment it is knowable
152
+ * and the only moment anything is persisted — so no line is ever rewritten.
153
+ * @param token - the call's token.
154
+ * @param outcome - the settled outcome, source included.
155
+ * @returns how many entries this call appended.
156
+ */
157
+ finish(token: number, outcome: DispatchOutcome): number;
158
+ /**
159
+ * Append what one call held, with a source that could not be verified.
160
+ * @param token - the call's token.
161
+ * @returns how many entries this call appended.
162
+ */
163
+ finishUnknown(token: number): number;
164
+ /**
165
+ * Append entries that were written while no call was open.
166
+ *
167
+ * They cannot be attributed to a call, so they are marked `unknown` rather
168
+ * than left to read as a remote success.
169
+ * @returns whether any entry was appended.
170
+ */
171
+ flush(): boolean;
172
+ /**
173
+ * Take, once, whether a settled call could not be tied to its own entry.
174
+ * @returns `true` when the last settlement landed late.
175
+ */
176
+ takeLateCall(): boolean;
177
+ }
31
178
  /**
32
179
  * In-process System One runtime shared by every reflex tool of one plugin
33
180
  * activation.
@@ -55,6 +202,44 @@ export declare class ReflexRuntime {
55
202
  readonly effort: EffortInterceptor;
56
203
  /** Status-bar surface of the adaptive effort decisions of this activation. */
57
204
  readonly effortStatusFeed: EffortStatusFeed;
205
+ /**
206
+ * Per-call sinks handed to the shared decision services.
207
+ *
208
+ * The decision services are long-lived and write their own ledger entry, but
209
+ * the call they are serving is per-dispatch. Each dispatch runs its services
210
+ * inside its own {@link #callScope}, so the sink below resolves to *that*
211
+ * call's buffer. This is why no shared "current stamp" field exists: a
212
+ * concurrent call cannot see, let alone clear, another call's context.
213
+ */
214
+ readonly tracking: {
215
+ gate: LedgerSink;
216
+ prune: LedgerSink;
217
+ stagnation: LedgerSink;
218
+ route: LedgerSink;
219
+ screen: LedgerSink;
220
+ };
221
+ /**
222
+ * Hand a decision service an already-attributed payload.
223
+ *
224
+ * The automatic intervention layer ({@link InterventionEngine}) drives the
225
+ * same services directly at Host hook points, so those calls never reach
226
+ * {@link #dispatch}. They still spend a System One judgment, and the goal
227
+ * requires every such call to be attributed — an entry the ledger cannot name
228
+ * is exactly the opacity g-068 removes.
229
+ *
230
+ * The returned ring is the call's own ledger token: the caller wraps the
231
+ * service call in {@link runInCall}, then reports the outcome through
232
+ * `settle` when the answer arrives, which is when the source first exists.
233
+ * @returns the ring for the call about to be made.
234
+ */
235
+ openCall(): CallRing;
236
+ /**
237
+ * Run one call inside its own ledger ring.
238
+ * @param ring - the ring from {@link openCall}.
239
+ * @param run - the work to run with that ring in force.
240
+ * @returns whatever `run` returns.
241
+ */
242
+ runInCall<T>(ring: CallRing, run: () => Promise<T>): Promise<T>;
58
243
  /**
59
244
  * @param config - resolved plugin configuration.
60
245
  * @param dependencies - test seams for the ledger, backend, and routing clock,
@@ -90,11 +275,42 @@ export declare class ReflexRuntime {
90
275
  * @returns a copy of the counters.
91
276
  */
92
277
  systemOneHealth(): BackendHealth | undefined;
278
+ /**
279
+ * The connection identity a call dispatched *now* would carry.
280
+ *
281
+ * Public so the panel and a test can ask the same question the dispatch path
282
+ * asks, without going through a call. It reads the live resolved connection
283
+ * block, never the activation-time snapshot, so a config-only commit is
284
+ * reflected immediately (and a profile switch cannot lag one call behind).
285
+ * @returns the identity to snapshot into the next call.
286
+ */
287
+ currentCallIdentity(): CallIdentity;
288
+ /**
289
+ * Run one outbound decision inside a full attributed call.
290
+ *
291
+ * The seam the automatic-intervention engine uses: it opens a ring, runs the
292
+ * service inside it, classifies the outcome from the same evidence the tools
293
+ * use, settles the ring (append-only, once) and hands back both the value and
294
+ * the attribution so the caller can put it on its own payload.
295
+ * @param run - the decision to make.
296
+ * @param options - how to read the outcome.
297
+ * @returns the value and its attribution.
298
+ */
299
+ attribute<T>(run: () => Promise<T>, options: {
300
+ answered(value: T): boolean;
301
+ localFallback?: (value: T) => boolean;
302
+ }): Promise<{
303
+ result: T;
304
+ attribution: Attribution;
305
+ }>;
93
306
  /**
94
307
  * Multi-class choice, with the deployment's calibration curve applied to the
95
308
  * winning confidence when one is loaded.
96
309
  * @param request - question, options, and optional context.
97
- * @returns the choice response plus the calibrated confidence, when available.
310
+ * @returns the choice response plus the calibrated confidence and the
311
+ * attribution (connection, requested model, source), when available.
312
+ * @throws Error when the connection produced no answer: a choice tool must not
313
+ * invent a distribution, and the ledger still records the rejected attempt.
98
314
  */
99
315
  choice(request: {
100
316
  question: string;
@@ -104,23 +320,23 @@ export declare class ReflexRuntime {
104
320
  /**
105
321
  * Continuous 0.0 – 1.0 scoring projected from one choice call.
106
322
  * @param request - statement, rubric, and optional context.
107
- * @returns the score response recorded in the ledger.
323
+ * @returns the score response, recorded in the ledger with its attribution.
108
324
  */
109
325
  score(request: {
110
326
  statement: string;
111
327
  criteria?: string;
112
328
  context?: string;
113
- }): Promise<Awaited<ReturnType<typeof scoreStatement>>>;
329
+ }): Promise<Awaited<ReturnType<typeof scoreStatement>> & Attribution>;
114
330
  /**
115
331
  * Rank candidate skills/tools against a goal.
116
332
  * @param request - goal, candidates, and how many to return.
117
- * @returns the ranked candidates.
333
+ * @returns the ranked candidates with their attribution.
118
334
  */
119
335
  route(request: {
120
336
  goal: string;
121
337
  candidates: CandidateItem[];
122
338
  topK?: number;
123
- }): Promise<RouteResponse>;
339
+ }): Promise<RouteResponse & Attribution>;
124
340
  /**
125
341
  * Screen untrusted content for prompt injection and instruction hijacking.
126
342
  * @param request - content, its source, and whether to force deep screening.
@@ -130,11 +346,16 @@ export declare class ReflexRuntime {
130
346
  content: string;
131
347
  source?: 'tool_output' | 'web_page' | 'user_input' | 'file_content';
132
348
  strict?: boolean;
133
- }): Promise<ScreenResult>;
349
+ }): Promise<ScreenResult & Attribution>;
134
350
  /**
135
351
  * Fail-closed verification of assertions against evidence.
352
+ *
353
+ * A remote rejection is *not* rethrown: the gate's contract is a verdict, and
354
+ * every assertion escalates. What changes is the honesty of that verdict —
355
+ * the attribution says `rejected` and carries the reason, so a local
356
+ * fail-closed escalation can no longer be read as a System One judgement.
136
357
  * @param request - assertions, evidence, and optional strictness.
137
- * @returns one outcome per assertion plus the overall verdict.
358
+ * @returns one outcome per assertion plus the overall verdict and attribution.
138
359
  */
139
360
  gate(request: {
140
361
  assertions: Array<{
@@ -143,7 +364,7 @@ export declare class ReflexRuntime {
143
364
  }>;
144
365
  evidence: string;
145
366
  strictness?: 'high' | 'normal' | 'lenient';
146
- }): Promise<GateResponse>;
367
+ }): Promise<GateResponse & Attribution>;
147
368
  /**
148
369
  * Prune bulky output, preserving the lines the intent depends on.
149
370
  *
@@ -157,7 +378,7 @@ export declare class ReflexRuntime {
157
378
  rawOutput: string;
158
379
  intent?: string;
159
380
  shadowMode?: boolean;
160
- }): Promise<ReflexPruneResult>;
381
+ }): Promise<ReflexPruneResult & Attribution>;
161
382
  /**
162
383
  * Record one action and check whether the run is stagnating.
163
384
  *
@@ -258,6 +479,47 @@ export declare class ReflexRuntime {
258
479
  * @param registrationEvents - reads how many provider registrations happened.
259
480
  */
260
481
  attachRouting(reconfigure?: (routing: ResolvedRoutingConfig) => void, registrationEvents?: () => number): void;
482
+ /**
483
+ * Attach the live delegation-capability read of this activation.
484
+ *
485
+ * Set by the plugin lifecycle right after the tool surface, so the panel can
486
+ * explain what the Host actually publishes instead of silently omitting it.
487
+ * The runtime does not own the registry: it only reports what the Host says.
488
+ * @param read - returns the current reading.
489
+ * @param refresh - re-checks the registry and reconciles the tool surface.
490
+ */
491
+ attachDelegationHealth(read?: () => DelegationHealth, refresh?: () => void): void;
492
+ /**
493
+ * Attach the hook that records the agent scope the capability is read in.
494
+ *
495
+ * `dsh-tools` is scoped, and a preset-hosted delegation tool is invisible from
496
+ * the global view. The lifecycle owns the reading, so it also owns the scope:
497
+ * this only lets a caller that *does* have an `Agent` (the panel poll, a
498
+ * session-aware caller) tell it which scope to read as. Never decides
499
+ * registration — that is configuration's job.
500
+ * @param note - receives the scope to read the delegation capability in.
501
+ */
502
+ attachDelegationScope(note?: (agent: Agent) => void): void;
503
+ /**
504
+ * Record the scope future delegation reads should use.
505
+ * @param agent - the calling agent, or a preset to read as.
506
+ */
507
+ noteDelegationScope(agent: Agent): void;
508
+ /** Re-check the Host delegation capability in the recorded scope. */
509
+ checkDelegationHealth(): DelegationHealth | undefined;
510
+ /** The current delegation-capability reading, when the lifecycle attached one. */
511
+ get delegationHealth(): DelegationHealth | undefined;
512
+ /**
513
+ * Attach the delegated-agent effort inheritance of this activation.
514
+ * @param inheritance - the installed listener, or undefined to detach.
515
+ */
516
+ attachEffortInheritance(inheritance: DelegatedEffortInheritance | undefined): void;
517
+ /**
518
+ * How many delegated selections this activation rewrote to a concrete level.
519
+ *
520
+ * Monotonic: it counts the marker replacements, not the steps that used them.
521
+ */
522
+ get effortInheritanceRewrites(): number;
261
523
  /** Provider registrations this activation made (monotonic; diagnostics). */
262
524
  get routingRegistrationEvents(): number;
263
525
  /** Backend rebuilds this activation performed (0 when a seam supplied one). */
@@ -333,13 +595,48 @@ export declare class ReflexRuntime {
333
595
  /**
334
596
  * Build the backend a plugin activation should use.
335
597
  *
598
+ * ## Nothing connects without an active profile (g-066)
599
+ *
600
+ * The connection fields come from the active profile only, so when
601
+ * {@link ResolvedSystemOneConfig.unconfigured} is set there is nothing to build
602
+ * and this function **refuses**. Building a backend anyway is exactly the old
603
+ * fallback: with no profile resolved, the vendored factory would choose `jev`
604
+ * because `JEV_API_KEY` happens to be exported, and the plugin would make a
605
+ * request nobody configured. Returning the mock backend instead was the other
606
+ * candidate and was rejected as well: "unconfigured" must not look like "answered
607
+ * locally with heuristics" in the ledger or the panel.
608
+ *
609
+ * The replacement is {@link UnconfiguredBackend}: the same deterministic local
610
+ * heuristics, under a name that says what is wrong, plus a health record that
611
+ * reports the missing connection instead of staying silent. `backend` may still
612
+ * be `mock` **explicitly**, which is a deployment choosing the in-process
613
+ * implementation on purpose — the two must remain distinguishable.
614
+ *
336
615
  * The connection block of the resolved config overrides the environment for
337
616
  * this plugin instance only: the backend implementations already fall back to
338
617
  * the environment for every omitted option, so an explicitly configured
339
618
  * deployment and an env-configured one behave the same when the block is empty.
619
+ *
620
+ * The key is the exception worth naming: it is resolved **here**, through
621
+ * {@link resolveApiKeyWithSource}, and handed to the backend explicitly. The
622
+ * backends keep their own environment reads for the fields they own (base URL,
623
+ * model), but a key that only arrived through their fallback would be invisible
624
+ * to {@link resolveApiKeyWithSource} — and therefore to the panel, which is how
625
+ * "the panel says the env var is empty while the backend works" was possible.
626
+ * One chain, one answer for both.
627
+ *
628
+ * Every construction here also passes `apiKeyResolved: true` (g-059). That flag
629
+ * makes "the chain resolved no key" *final*: without it both backends would
630
+ * re-read `SYSTEM_ONE_API_KEY` / `JEV_API_KEY` (and the logits backend would
631
+ * invent `dummy`) whenever the key was omitted, so a block naming an empty
632
+ * variable would show as missing on the panel while its requests still
633
+ * authenticated — the divergence this file exists to close, pointing the other
634
+ * way. The flag defaults to `false` in the vendored backends, so every other
635
+ * construction (tests, probes, a bare import) keeps the historical chain.
340
636
  * @param config - resolved plugin configuration.
341
- * @param env - environment the API-key indirection reads; defaults to `process.env`.
342
- * @returns the forced backend, or one chosen from the environment for `auto`.
637
+ * @param env - environment the API-key chain reads; defaults to `process.env`.
638
+ * @returns the forced backend, the local-only one when nothing is configured, or
639
+ * one chosen from the environment for `auto`.
343
640
  */
344
641
  export declare function createBackend(config: ResolvedReflexConfig, env?: Record<string, string | undefined>): DecisionBackend;
345
642
  /**
@@ -355,3 +652,4 @@ export declare function createReflexRuntime(config: ResolvedReflexConfig, depend
355
652
  configSource?: unknown;
356
653
  warn?: (message: string) => void;
357
654
  }): ReflexRuntime;
655
+ export {};