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.
- package/README.md +20 -6
- package/client.js +3511 -185
- package/dist/attribution.d.ts +266 -0
- package/dist/attribution.js +238 -0
- package/dist/attribution.js.map +1 -0
- package/dist/bridge.d.ts +311 -13
- package/dist/bridge.js +714 -42
- package/dist/bridge.js.map +1 -1
- package/dist/client-bundle.js +4 -1
- package/dist/client-bundle.js.map +1 -1
- package/dist/command.js +10 -0
- package/dist/command.js.map +1 -1
- package/dist/config.d.ts +530 -22
- package/dist/config.js +808 -27
- package/dist/config.js.map +1 -1
- package/dist/delegation-dispatch.d.ts +132 -0
- package/dist/delegation-dispatch.js +186 -0
- package/dist/delegation-dispatch.js.map +1 -0
- package/dist/delegation-health.d.ts +131 -0
- package/dist/delegation-health.js +97 -0
- package/dist/delegation-health.js.map +1 -0
- package/dist/delegation.d.ts +148 -0
- package/dist/delegation.js +186 -0
- package/dist/delegation.js.map +1 -0
- package/dist/effort-delegation.d.ts +144 -0
- package/dist/effort-delegation.js +280 -0
- package/dist/effort-delegation.js.map +1 -0
- package/dist/effort.d.ts +141 -0
- package/dist/effort.js +251 -9
- package/dist/effort.js.map +1 -1
- package/dist/host-patch.d.ts +156 -0
- package/dist/host-patch.js +534 -0
- package/dist/host-patch.js.map +1 -0
- package/dist/index.d.ts +12 -3
- package/dist/index.js +99 -7
- package/dist/index.js.map +1 -1
- package/dist/interventions.d.ts +98 -373
- package/dist/interventions.js +442 -1702
- package/dist/interventions.js.map +1 -1
- package/dist/panel-api.d.ts +328 -4
- package/dist/panel-api.js +322 -15
- package/dist/panel-api.js.map +1 -1
- package/dist/panel-mount.d.ts +81 -22
- package/dist/panel-mount.js +228 -7
- package/dist/panel-mount.js.map +1 -1
- package/dist/routing.d.ts +23 -18
- package/dist/routing.js +471 -153
- package/dist/routing.js.map +1 -1
- package/dist/session-audit.d.ts +70 -0
- package/dist/session-audit.js +73 -0
- package/dist/session-audit.js.map +1 -1
- package/dist/systemone-probe.d.ts +114 -0
- package/dist/systemone-probe.js +383 -0
- package/dist/systemone-probe.js.map +1 -0
- package/dist/testing.d.ts +212 -7
- package/dist/testing.js +333 -27
- package/dist/testing.js.map +1 -1
- package/dist/tools.d.ts +109 -3
- package/dist/tools.js +103 -4
- package/dist/tools.js.map +1 -1
- package/dist/unconfigured-backend.d.ts +72 -0
- package/dist/unconfigured-backend.js +94 -0
- package/dist/unconfigured-backend.js.map +1 -0
- package/dist/vendor/harness-reflex/backend/factory.d.ts +31 -1
- package/dist/vendor/harness-reflex/backend/factory.js +18 -3
- package/dist/vendor/harness-reflex/backend/factory.js.map +1 -1
- package/dist/vendor/harness-reflex/backend/jev.d.ts +20 -0
- package/dist/vendor/harness-reflex/backend/jev.js +11 -4
- package/dist/vendor/harness-reflex/backend/jev.js.map +1 -1
- package/dist/vendor/harness-reflex/backend/simple-jev.d.ts +16 -0
- package/dist/vendor/harness-reflex/backend/simple-jev.js +17 -6
- package/dist/vendor/harness-reflex/backend/simple-jev.js.map +1 -1
- package/dist/vendor/harness-reflex/core/closing.d.ts +90 -0
- package/dist/vendor/harness-reflex/core/closing.js +111 -0
- package/dist/vendor/harness-reflex/core/closing.js.map +1 -0
- package/dist/vendor/harness-reflex/core/evidence.d.ts +119 -0
- package/dist/vendor/harness-reflex/core/evidence.js +209 -0
- package/dist/vendor/harness-reflex/core/evidence.js.map +1 -0
- package/dist/vendor/harness-reflex/core/judge.d.ts +221 -0
- package/dist/vendor/harness-reflex/core/judge.js +251 -0
- package/dist/vendor/harness-reflex/core/judge.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.d.ts +237 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.js +250 -0
- package/dist/vendor/harness-reflex/core/orchestrate-closing.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.d.ts +209 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.js +141 -0
- package/dist/vendor/harness-reflex/core/orchestrate-correction.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.d.ts +225 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.js +80 -0
- package/dist/vendor/harness-reflex/core/orchestrate-host.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.d.ts +259 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js +270 -0
- package/dist/vendor/harness-reflex/core/orchestrate-stagnation.js.map +1 -0
- package/dist/vendor/harness-reflex/core/orchestrate.d.ts +357 -0
- package/dist/vendor/harness-reflex/core/orchestrate.js +418 -0
- package/dist/vendor/harness-reflex/core/orchestrate.js.map +1 -0
- package/dist/vendor/harness-reflex/core/policy.d.ts +122 -0
- package/dist/vendor/harness-reflex/core/policy.js +102 -0
- package/dist/vendor/harness-reflex/core/policy.js.map +1 -0
- package/dist/vendor/harness-reflex/core/prune-plan.d.ts +141 -0
- package/dist/vendor/harness-reflex/core/prune-plan.js +390 -0
- package/dist/vendor/harness-reflex/core/prune-plan.js.map +1 -0
- package/dist/vendor/harness-reflex/core/text.d.ts +36 -0
- package/dist/vendor/harness-reflex/core/text.js +66 -0
- package/dist/vendor/harness-reflex/core/text.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/audit.d.ts +18 -0
- package/dist/vendor/harness-reflex/ports/audit.js +11 -0
- package/dist/vendor/harness-reflex/ports/audit.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/clock.d.ts +14 -0
- package/dist/vendor/harness-reflex/ports/clock.js +11 -0
- package/dist/vendor/harness-reflex/ports/clock.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/decision.d.ts +75 -0
- package/dist/vendor/harness-reflex/ports/decision.js +2 -0
- package/dist/vendor/harness-reflex/ports/decision.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/index.d.ts +14 -0
- package/dist/vendor/harness-reflex/ports/index.js +2 -0
- package/dist/vendor/harness-reflex/ports/index.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/log.d.ts +22 -0
- package/dist/vendor/harness-reflex/ports/log.js +12 -0
- package/dist/vendor/harness-reflex/ports/log.js.map +1 -0
- package/dist/vendor/harness-reflex/ports/state.d.ts +46 -0
- package/dist/vendor/harness-reflex/ports/state.js +13 -0
- package/dist/vendor/harness-reflex/ports/state.js.map +1 -0
- package/package.json +25 -13
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"orchestrate-correction.js","sourceRoot":"","sources":["../../../../src/vendor/harness-reflex/core/orchestrate-correction.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shared orchestration of the failure-correction decision.\n *\n * The third of the three lifts: {@link ./orchestrate} owns when a result is\n * reduced, {@link ./orchestrate-stagnation} owns when a call is refused and when\n * a step is corrected, and this one owns what happens to a result that *failed* —\n * the run is retrying an operation that keeps failing, and what the model is\n * about to read is the failure again rather than the reason it keeps failing.\n *\n * ```\n * agent/turn-stopping / tools/pre-execute (not this module)\n *\n * tools/post-execute\n * downstream first, always\n * → off / own tool / the result of a call this layer refused → hand it back\n * → [the host records the step and reports the result failed]\n * → not a failure → this decision does not apply\n * → downstream blocked the result → hand it back\n * → the cheap trigger (the trailing failing run) → not suspicious → hand it back\n * → already corrected this episode → duplicate-intervention\n * → the turn's action allowance is spent → intervention-cap\n * → buy a judgment (memo first, budgets inside)\n * → not useful → charge it, record why, hand it back\n * → latch the episode, book the action, conclude\n * → rewrite the result *only* in active mode\n * ```\n *\n * ## What is shared and what is not\n *\n * Shared here: the order above, every skip reason, the budget rules\n * (`actionWithinBudget`, `bookAction`, the judgment memo), the latch, the shape\n * of the audit detail, and the *decision* that an active mode rewrites the result.\n *\n * *Not* shared here: whether a result counts as a failure (the host's own reading\n * of `isError`, a structured exit status, or an exit marker in the text), the\n * window it is measured on and what a legitimate wait removes from it (the host\n * records steps and hands over the value — {@link progressSteps} is applied by\n * the caller, and the DSH host deliberately does *not* apply it here, because a\n * failing poll is still a failure), the wording the model reads, and the concrete\n * shape of a rewritten result.\n *\n * ## The strength of the action is the host's, the decision is not\n *\n * A correction has no single strength. The DSH engine answers with\n * `kind: 'block'` and a feedback list, which replaces the result outright; a\n * command hook answers with `additionalContext` next to the result it did not\n * touch. The shared layer therefore decides *whether* the correction applies and\n * *what it says*, and leaves *how strongly* to be expressed to {@link\n * CorrectionPort#apply}: an observation of the same decision is exactly the plan\n * that reaches the log in both modes, and installing it is the only thing the\n * mode gates.\n *\n * For the same reason this module states no permission-monotonicity rule. A\n * refusal is a permission and may not be added to anything stricter than an\n * allow — that rule lives in one place, {@link mayAddDecision}. A correction is\n * text shown to the model about a result that already happened; it grants and\n * denies nothing, so there is no decision it could weaken. The one decision it\n * must not overwrite is a result the rest of the waterfall *blocked*, and that is\n * an early return rather than a rule about kinds.\n *\n * ## Why the host supplies the window, not a store\n *\n * The same reason as the other two modules: the DSH engine keeps its window in\n * the agent's own bookkeeping and hands the shared layer a value, while a host\n * that derives it from a persisted log hands over a different value. Neither has\n * to teach the shared layer how it stores anything; the only thing the shared\n * layer mutates is the counters it is given, through {@link BudgetState}.\n *\n * @module core/orchestrate-correction\n */\nimport type { StagnationCheckResponse } from '../backend/types.js';\nimport {\n judgmentCharge,\n runJudgment,\n type JudgmentOutcome,\n type ObservedStep,\n type StagnationSuspicion,\n type VerdictMemoState\n} from './judge.js';\nimport type { HostBillingPort, HostDecisionPort, HostJudgmentPort } from './orchestrate-host.js';\nimport { actionWithinBudget, bookAction, modeOf, type PolicySnapshot } from './policy.js';\nimport { clip } from './text.js';\n\n/** The capability every decision in this module belongs to. */\nexport const CORRECTION_CAPABILITY = 'gate' as const;\n\n/** The audit action a correction is recorded under. */\nexport const CORRECTION_ACTION = 'corrective-feedback' as const;\n\n/** What one orchestrated decision turned out to be. */\nexport type CorrectionAction = 'corrected' | 'pass-through';\n\n/** The judgment cost of one decision, as the host bills it. */\nexport interface JudgedCharge {\n readonly judgments: number;\n readonly memoHits: number;\n readonly localLatencyMs: number;\n readonly remoteLatencyMs: number;\n readonly judgeTokens: number;\n}\n\n/** One planned correction, as the host records it. */\nexport interface CorrectionPlanRecord {\n readonly capability: typeof CORRECTION_CAPABILITY;\n readonly action: typeof CORRECTION_ACTION;\n readonly reason: string;\n feedback: string;\n readonly detail: Record<string, unknown>;\n}\n\n/** What one correction was built from. */\nexport interface CorrectionFeedbackFacts {\n /** Name of the call that failed. */\n readonly tool: string;\n /** The failure text the host reads off the result, for quoting. */\n readonly error: string;\n /** The cheap-path trigger. */\n readonly suspicion: StagnationSuspicion;\n /** What System 1 answered. */\n readonly verdict: StagnationCheckResponse;\n}\n\n/**\n * The counters one correction spends from and books against.\n *\n * The verdict cache is part of the budget state because a cached answer is what\n * makes a second question in the same turn free: this path shares that cache with\n * the stagnation capability, so it reads it through here rather than keeping a\n * second copy. The place in the run (`turn`, `step`) and the counters both come\n * from the judge's state, so a correction adds no field of its own to either.\n */\nexport type CorrectionState = VerdictMemoState;\n\n/**\n * Everything the shared layer cannot know by itself.\n *\n * {@link HostDecisionPort} answers the part every capability asks — policy,\n * counters, clock, switch, and the three billing channels — so this interface\n * states only what a *correction* additionally needs.\n */\nexport interface HostCorrectionPort<Result>\n extends HostDecisionPort<CorrectionState>,\n HostBillingPort<JudgedCharge, CorrectionPlanRecord>,\n HostJudgmentPort<StagnationCheckResponse> {\n /** Name of the call whose result is being decided. */\n toolName(): string;\n /** The failure text, as the model would read it. */\n error(): string;\n /**\n * The window the trigger is measured on.\n *\n * The host's, deliberately: it is the one value the three capabilities can\n * disagree about, and the disagreement is real — a failing poll is a failure\n * even though a wait is not progress.\n */\n window(): readonly ObservedStep[];\n /** The identity this decision is about. */\n signature(): string;\n /**\n * The cheap trigger over one window.\n *\n * `PolicySnapshot` carries the repetition threshold, the confidence floor and\n * the judgment budgets — the numbers the *budget* rules are stated in — but the\n * failure threshold and the window size are trigger parameters, and the host\n * owns their values.\n */\n suspicion(steps: readonly ObservedStep[]): StagnationSuspicion;\n /** Whether this identity was already corrected on this turn. */\n alreadyCorrected(): boolean;\n /** Latch this identity as corrected. */\n latchCorrected(): void;\n /** The result to hand back when nothing is done. */\n passThrough(): Result;\n /**\n * The result to hand back when the correction applies.\n *\n * How strong this is — a replacement, an added context, or nothing at all\n * because the host is only observing — is the host's to decide, and it is why\n * this is a callback rather than a kind the shared layer picks.\n */\n apply(feedback: string): Result;\n /** Word the correction handed to the model. */\n describe(facts: CorrectionFeedbackFacts): string;\n}\n\n/** The outcome of one orchestrated decision. */\nexport interface CorrectionOutcome<Result> {\n /** What the host should return to its caller. */\n readonly result: Result;\n /** What the decision was. */\n readonly action: CorrectionAction;\n /** The skip reason, when the decision refused to correct. */\n readonly skip?: string;\n}\n\n/**\n * The charge of one judgment, through the core's own billing rule.\n * @param outcome - the judgment's outcome.\n * @param started - clock reading at hook entry.\n * @param now - clock reading now.\n * @returns the charge the host records.\n */\nfunction chargeOf(outcome: JudgmentOutcome, started: number, now: number): JudgedCharge {\n return judgmentCharge(outcome, started, now);\n}\n\n/**\n * The detail every correction record carries.\n *\n * Kept identical to the correction this module replaced, so an audit trail\n * written before and after the lift reads the same: a reader comparing two\n * sessions must not be able to tell which engine produced which.\n * @param suspicion - the cheap-path trigger.\n * @param verdict - what System 1 answered.\n * @param turn - the deciding turn.\n * @param step - the deciding step.\n * @returns the audit fields.\n */\nfunction detailOf(\n suspicion: StagnationSuspicion,\n verdict: StagnationCheckResponse,\n turn: number,\n step: number\n): Record<string, unknown> {\n return {\n pattern: String(verdict.patternType ?? suspicion.pattern ?? 'unknown'),\n confidence: verdict.confidence,\n repeats: suspicion.repeats,\n turn,\n step\n };\n}\n\n/**\n * `tools/post-execute`: rewrite a result the run keeps failing to change.\n *\n * The host calls this **after** its own `next()`, and hands over what that\n * returned: a result the rest of the waterfall blocked is already unreadable, so\n * rewriting it would be inventing a surface nobody asked for.\n *\n * @param invocation - the downstream decision, the signal, and the failure facts.\n * @param port - everything that is the host's to answer.\n * @returns the result the host commits.\n */\nexport async function orchestrateCorrection<Result>(\n invocation: {\n /** Whether the result is one this layer reads as a failure. */\n readonly failed: boolean;\n /** Whether the rest of the waterfall blocked the result outright. */\n readonly blockedByDownstream: boolean;\n /** The result's abort signal, if it has one. */\n readonly signal?: AbortSignal;\n },\n port: HostCorrectionPort<Result>\n): Promise<CorrectionOutcome<Result>> {\n const passThrough = (skip?: string): CorrectionOutcome<Result> => ({\n result: port.passThrough(),\n action: 'pass-through',\n ...(skip === undefined ? {} : { skip })\n });\n\n const mode = modeOf(port.policy(), CORRECTION_CAPABILITY);\n if (mode === 'off' || !port.serves()) return passThrough();\n if (!invocation.failed) return passThrough();\n // A result the rest of the waterfall blocked never reaches the model, so there\n // is nothing here to correct. Asked first: it is the cheapest refusal and it\n // must not be able to spend a judgment.\n if (invocation.blockedByDownstream) return passThrough();\n\n const signature = port.signature();\n const suspicion = port.suspicion(port.window());\n if (!suspicion.suspicious) return passThrough();\n // The latch is asked in the same breath as the trigger, and only reports when\n // the episode was real: a correction that never happened is not a duplicate of\n // anything, and a record claiming it was would misdescribe the turn.\n if (port.alreadyCorrected()) {\n port.skip('duplicate-intervention');\n return passThrough('duplicate-intervention');\n }\n if (!actionWithinBudget(port.budget(), port.policy())) {\n port.skip('intervention-cap');\n return passThrough('intervention-cap');\n }\n\n const policy = port.policy();\n const started = port.clock().now();\n const outcome = await runJudgment({\n state: port.budget(),\n policy,\n buy: (step) => port.buy(step),\n clock: port.clock(),\n steps: port.window(),\n ...(invocation.signal === undefined ? {} : { signal: invocation.signal })\n });\n const charge = chargeOf(outcome, started, port.clock().now());\n if (!outcome.useful) {\n // A budget/abort skip keeps its own reason. The judgment really ran, so it is\n // charged rather than hidden — an abandoned paid plan is still a cost.\n port.chargeJudgment(charge);\n const skip = outcome.skip ?? 'unconfirmed';\n port.skip(skip, charge);\n return passThrough(skip);\n }\n\n const facts: CorrectionFeedbackFacts = {\n tool: port.toolName(),\n error: port.error(),\n suspicion,\n verdict: outcome.response\n };\n const plan: CorrectionPlanRecord = {\n capability: CORRECTION_CAPABILITY,\n action: CORRECTION_ACTION,\n reason: `${port.toolName()} failed ${suspicion.repeats} times; System 1 confirmed ${\n outcome.response.patternType ?? suspicion.pattern\n }`,\n feedback: port.describe(facts),\n detail: detailOf(suspicion, outcome.response, port.budget().turn, port.budget().step)\n };\n const applies = mode === 'active';\n // The latch is mode-independent on purpose. Observe has to consume the same\n // episode — one correction per failure episode, one charge against the turn's\n // cap — or its accounting would describe a run nobody could reproduce; the\n // model-visible rewrite is the only thing the mode gates.\n port.latchCorrected();\n bookAction(port.budget());\n port.conclude(plan, applies, charge);\n return applies ? { result: port.apply(plan.feedback), action: 'corrected' } : passThrough();\n}\n\n/**\n * The correction's wording, in the default form.\n *\n * Exported because a host that shows the text to the same audience may keep it\n * verbatim; a host that words it differently supplies its own through the port.\n * The two clippings are the shared part: an error is quoted at 160 characters and\n * the advice at 240, both with whitespace collapsed, so a multi-line stack can\n * never make the correction unbounded.\n * @param facts - what the correction is built from.\n * @param limits - the two budget lengths.\n * @returns the text handed to the model.\n */\nexport function describeCorrection(\n facts: CorrectionFeedbackFacts,\n limits: { readonly errorChars: number; readonly adviceChars: number; readonly totalChars: number }\n): string {\n const advice = clip((facts.verdict.recommendedIntervention ?? '').replace(/\\s+/g, ' ').trim(), limits.adviceChars);\n return clip(\n `Reflex intervention: ${facts.tool} failed ${facts.suspicion.repeats} consecutive times with ${clip(facts.error.replace(/\\s+/g, ' ').trim(), limits.errorChars)}. ` +\n `System 1 confirms ${facts.verdict.patternType ?? facts.suspicion.pattern} (confidence ${facts.verdict.confidence.toFixed(2)}). ` +\n `This result is treated as a policy failure: change the command or the code before retrying. ${advice}`,\n limits.totalChars\n );\n}\n"]}
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The decisions every orchestrated capability asks its host for.
|
|
3
|
+
*
|
|
4
|
+
* ## Why this exists
|
|
5
|
+
*
|
|
6
|
+
* Four capabilities now share one orchestration layer (prune, stagnation,
|
|
7
|
+
* correction, closing), and each of them asks its host the same handful of
|
|
8
|
+
* questions: what policy is in force, which counters may move, how one abandoned
|
|
9
|
+
* plan is recorded, how one plan is billed. Before this module, each `Host*Port`
|
|
10
|
+
* re-declared that surface in its own words. The declarations agreed, but
|
|
11
|
+
* nothing *made* them agree — a fourth capability would have been the fourth copy,
|
|
12
|
+
* and a divergence between two ports meant to be the same would have had nowhere
|
|
13
|
+
* to be caught.
|
|
14
|
+
*
|
|
15
|
+
* The shared surface is stated once, here. It is deliberately split into two
|
|
16
|
+
* interfaces rather than one, because the corpus of four ports showed the two
|
|
17
|
+
* halves have different reach:
|
|
18
|
+
*
|
|
19
|
+
* | Interface | Members | Who extends it |
|
|
20
|
+
* |---|---|---|
|
|
21
|
+
* | {@link HostDecisionPort} | `policy`, `budget`, `clock`/`now`, `serves` | **all four** |
|
|
22
|
+
* | {@link HostBillingPort} | `skip`, `chargeJudgment`, `conclude` | the three that bill the same way |
|
|
23
|
+
*
|
|
24
|
+
* ## Why the billing channels are a second interface
|
|
25
|
+
*
|
|
26
|
+
* The judgment capabilities (stagnation, correction, closing) record an abandoned
|
|
27
|
+
* plan as "reason + the judgment it cost" and bill an applied plan as "record +
|
|
28
|
+
* applied + the judgment it rode on". All three are literally the same two calls,
|
|
29
|
+
* so they share {@link HostBillingPort}.
|
|
30
|
+
*
|
|
31
|
+
* Pruning is **not** one of them, and this is the finding that stopped this batch
|
|
32
|
+
* from collapsing everything into one interface. Its two billing channels are
|
|
33
|
+
* genuinely wider:
|
|
34
|
+
*
|
|
35
|
+
* - `skip(reason, detail, judgment?)` — the `detail` is not a charge. It carries
|
|
36
|
+
* the payload diagnostics (`digest`, `floored`, `floorMissed`, the segment
|
|
37
|
+
* counts) that make *"why was nothing pruned"* answerable. Those fields are the
|
|
38
|
+
* reason the pruning audit trail exists at all.
|
|
39
|
+
* - `conclude(plan, applied, costs, judgment?, locator?)` — `costs` carries the
|
|
40
|
+
* four size columns and the retained locator, i.e. every number that makes a
|
|
41
|
+
* claimed saving *verifiable*. Collapsing it into the judgment-capability shape
|
|
42
|
+
* would silently drop them.
|
|
43
|
+
*
|
|
44
|
+
* Fitting pruning to the common shape would therefore have required either
|
|
45
|
+
* deleting audit fields or making the base `skip(reason, x?: unknown)`, which
|
|
46
|
+
* buys nothing: every caller would cast, and the one place a wrong answer is a
|
|
47
|
+
* model-visible regression would be the place the type stopped helping. Both were
|
|
48
|
+
* rejected. Pruning extends only {@link HostDecisionPort}, states its two wider
|
|
49
|
+
* channels in its own interface, and the divergence is documented there.
|
|
50
|
+
*
|
|
51
|
+
* ## The judgment is bought, not fetched
|
|
52
|
+
*
|
|
53
|
+
* A port never hands over a backend. It answers **one purchase at a time** —
|
|
54
|
+
* {@link HostJudgmentPort#buy} for the stagnation verdict (bought by both the
|
|
55
|
+
* stagnation and the correction capability, which ask the same question of the
|
|
56
|
+
* same service), `classify`/`verify` for closing's two-request judgment, and
|
|
57
|
+
* `judge(payload)` for pruning's reduction.
|
|
58
|
+
*
|
|
59
|
+
* The distinction matters because a port that exposes `backend()` forces every
|
|
60
|
+
* caller to re-implement the purchase: the memo key, the budget check, the
|
|
61
|
+
* local/remote latency split, and the billing. Those four are the shared layer's
|
|
62
|
+
* — {@link ../judge.runJudgment} and each capability's own accounting — and they
|
|
63
|
+
* are stated once. A host answers only "what did the service say, and how long
|
|
64
|
+
* did it wait".
|
|
65
|
+
*
|
|
66
|
+
* ### One buy is one request; one charge may be several buys
|
|
67
|
+
*
|
|
68
|
+
* The unit of `buy` is the *request*, not the bill. The closing check buys twice
|
|
69
|
+
* from one capability — a classification of the turn's sentences, then a
|
|
70
|
+
* verification of the claims that classification accepted — but bills them as a
|
|
71
|
+
* single {@link JudgmentCost} against the single slot the turn budget granted.
|
|
72
|
+
* That fold is the shared layer's (`orchestrateClosing`), which is exactly why
|
|
73
|
+
* the closing port must not be collapsing the two requests into one method: the
|
|
74
|
+
* latency split and the token sum belong where the charge is built. For the
|
|
75
|
+
* stagnation verdict one buy is one request and one charge.
|
|
76
|
+
*
|
|
77
|
+
* @module core/orchestrate-host
|
|
78
|
+
*/
|
|
79
|
+
import type { ActionStep } from '../backend/types.js';
|
|
80
|
+
import type { ClockPort } from '../ports/clock.js';
|
|
81
|
+
import type { BudgetState, PolicySnapshot } from './policy.js';
|
|
82
|
+
/**
|
|
83
|
+
* The charge of one judgment, as every capability bills it.
|
|
84
|
+
*
|
|
85
|
+
* Stated here rather than in one capability's module because all of them record
|
|
86
|
+
* the same five columns, and the fifth (`judgeTokens`) is the one a host that
|
|
87
|
+
* forgot it would quietly under-report.
|
|
88
|
+
*/
|
|
89
|
+
export interface JudgmentCost {
|
|
90
|
+
readonly judgments: number;
|
|
91
|
+
readonly memoHits: number;
|
|
92
|
+
readonly localLatencyMs: number;
|
|
93
|
+
readonly remoteLatencyMs: number;
|
|
94
|
+
readonly judgeTokens: number;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* One judgment request: the window, plus the question it is put to.
|
|
98
|
+
*
|
|
99
|
+
* This is the whole of what a host is asked for when a judgment is bought. It is
|
|
100
|
+
* a value rather than a port because the host's only job is "ask the service and
|
|
101
|
+
* report what it said, latency included" — the memo key, the budget check, the
|
|
102
|
+
* latency split and the charge stay with the caller that owns the counters.
|
|
103
|
+
*/
|
|
104
|
+
export interface JudgmentStep {
|
|
105
|
+
/** Why the run is judged, when the caller knows (a wait question). */
|
|
106
|
+
readonly goal: string | undefined;
|
|
107
|
+
/** The observed steps to judge, oldest first. */
|
|
108
|
+
readonly history: readonly ActionStep[];
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Where in the run one judgment is being made.
|
|
112
|
+
*
|
|
113
|
+
* This is the value the four capabilities used to each spell their own accessor
|
|
114
|
+
* for (`position()`, `location()`, `turn()`, and two bare state reads). They
|
|
115
|
+
* disagreed because a port should not answer it: every host has these two
|
|
116
|
+
* numbers, every host means the same thing by them, and a judgment is *about*
|
|
117
|
+
* one place. So the place travels with the judgment — never through the port.
|
|
118
|
+
*/
|
|
119
|
+
export interface JudgmentPosition {
|
|
120
|
+
/** The turn this judgment belongs to. */
|
|
121
|
+
turn: number;
|
|
122
|
+
/** The step this judgment belongs to. */
|
|
123
|
+
step: number;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* The counters every judgment capability keeps, positioned at where it decides.
|
|
127
|
+
*
|
|
128
|
+
* The place is part of the state for the three capabilities whose state *is* the
|
|
129
|
+
* host's running record (the same object the trigger windows are kept in): the
|
|
130
|
+
* audit detail, the retention request and the verdict memo all quote it, so one
|
|
131
|
+
* source keeps them in step. The closing check is the exception, and the
|
|
132
|
+
* exception is the finding: its turn is the boundary it was asked at, which can
|
|
133
|
+
* be a turn no step has recorded yet, so it arrives as an input of that decision
|
|
134
|
+
* instead (see `orchestrateClosing`).
|
|
135
|
+
*/
|
|
136
|
+
export interface JudgmentState extends BudgetState, JudgmentPosition {
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* What a capability that buys exactly one judgment asks its host for.
|
|
140
|
+
*
|
|
141
|
+
* The shape is one method over one value: the window and the question put to it
|
|
142
|
+
* ({@link JudgmentStep}). The host answers what the service said, latency
|
|
143
|
+
* included; the purchase around it — budget, memo, latency split, charge — is
|
|
144
|
+
* the shared layer's.
|
|
145
|
+
*
|
|
146
|
+
* A capability that buys *differently* still states its buys in this form, one
|
|
147
|
+
* member per request: closing answers `classify` and `verify`, pruning answers
|
|
148
|
+
* `judge`. The rule is that a port states the purchases it makes and never the
|
|
149
|
+
* transport behind them.
|
|
150
|
+
*
|
|
151
|
+
* @typeParam Answer - what this capability's service returns for one request.
|
|
152
|
+
*/
|
|
153
|
+
export interface HostJudgmentPort<Answer> {
|
|
154
|
+
/**
|
|
155
|
+
* Buy one judgment about one step.
|
|
156
|
+
* @param step - the window to judge and the question it is asked in.
|
|
157
|
+
* @returns the service's answer, carrying the latency the split is measured on.
|
|
158
|
+
*/
|
|
159
|
+
buy(step: JudgmentStep): Promise<Answer>;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* What every orchestrated decision asks its host, whatever it decides.
|
|
163
|
+
*
|
|
164
|
+
* These four are the ones no capability can answer alone and no capability
|
|
165
|
+
* answers differently: the policy is the host's resolved config, the counters are
|
|
166
|
+
* the host's storage, the clock is the host's wall time, and the switch is the
|
|
167
|
+
* host's.
|
|
168
|
+
*
|
|
169
|
+
* @typeParam State - the counters this decision spends from. Must extend
|
|
170
|
+
* {@link BudgetState}, because the shared budget rules mutate it through one.
|
|
171
|
+
*/
|
|
172
|
+
export interface HostDecisionPort<State extends BudgetState = BudgetState> {
|
|
173
|
+
/** The resolved policy in force right now (re-read per decision). */
|
|
174
|
+
policy(): PolicySnapshot;
|
|
175
|
+
/**
|
|
176
|
+
* The counters this decision spends from and books against.
|
|
177
|
+
*
|
|
178
|
+
* The shared layer mutates them in place through `core/policy`; a host that
|
|
179
|
+
* stores its counters elsewhere hands over the object it wants mutated and
|
|
180
|
+
* nothing else has to know where they live.
|
|
181
|
+
*/
|
|
182
|
+
budget(): State;
|
|
183
|
+
/** The clock, for the local-latency split. */
|
|
184
|
+
clock(): ClockPort;
|
|
185
|
+
/** Whether the decision applies at all (master switch on, capability not off). */
|
|
186
|
+
serves(): boolean;
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* The three accounting channels the judgment capabilities share.
|
|
190
|
+
*
|
|
191
|
+
* Extended by stagnation, correction and closing. See the module documentation
|
|
192
|
+
* for why pruning is not one of them.
|
|
193
|
+
*
|
|
194
|
+
* @typeParam Charge - the judgment charge this capability bills.
|
|
195
|
+
* @typeParam Record - the plan this capability records when it acts.
|
|
196
|
+
*/
|
|
197
|
+
export interface HostBillingPort<Charge = JudgmentCost, Record = unknown> {
|
|
198
|
+
/**
|
|
199
|
+
* Record one abandoned plan by reason.
|
|
200
|
+
*
|
|
201
|
+
* The charge is passed in because the record has to say what the refusal cost:
|
|
202
|
+
* a paid "not this" and a free "budget spent" are different answers, and a skip
|
|
203
|
+
* that reported both as free would understate the turn.
|
|
204
|
+
*/
|
|
205
|
+
skip(reason: string, charge?: Charge): void;
|
|
206
|
+
/**
|
|
207
|
+
* Bill one judgment whose plan was abandoned after it was really made.
|
|
208
|
+
*
|
|
209
|
+
* A refusal before the judgment is bought costs nothing and is never billed
|
|
210
|
+
* here. One that refused *after* it ran did spend, so hiding it would understate
|
|
211
|
+
* what the turn cost.
|
|
212
|
+
*/
|
|
213
|
+
chargeJudgment(charge: Charge): void;
|
|
214
|
+
/**
|
|
215
|
+
* Record one applied or observed plan.
|
|
216
|
+
*
|
|
217
|
+
* This is the one place a plan is billed: `plans` +1, `applied` +1 when it really
|
|
218
|
+
* took effect, and every column of the charge.
|
|
219
|
+
*
|
|
220
|
+
* @param plan - what the capability decided.
|
|
221
|
+
* @param applied - whether active mode executed it.
|
|
222
|
+
* @param charge - the judgment this decision rode on.
|
|
223
|
+
*/
|
|
224
|
+
conclude(plan: Record, applied: boolean, charge: Charge): void;
|
|
225
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The decisions every orchestrated capability asks its host for.
|
|
3
|
+
*
|
|
4
|
+
* ## Why this exists
|
|
5
|
+
*
|
|
6
|
+
* Four capabilities now share one orchestration layer (prune, stagnation,
|
|
7
|
+
* correction, closing), and each of them asks its host the same handful of
|
|
8
|
+
* questions: what policy is in force, which counters may move, how one abandoned
|
|
9
|
+
* plan is recorded, how one plan is billed. Before this module, each `Host*Port`
|
|
10
|
+
* re-declared that surface in its own words. The declarations agreed, but
|
|
11
|
+
* nothing *made* them agree — a fourth capability would have been the fourth copy,
|
|
12
|
+
* and a divergence between two ports meant to be the same would have had nowhere
|
|
13
|
+
* to be caught.
|
|
14
|
+
*
|
|
15
|
+
* The shared surface is stated once, here. It is deliberately split into two
|
|
16
|
+
* interfaces rather than one, because the corpus of four ports showed the two
|
|
17
|
+
* halves have different reach:
|
|
18
|
+
*
|
|
19
|
+
* | Interface | Members | Who extends it |
|
|
20
|
+
* |---|---|---|
|
|
21
|
+
* | {@link HostDecisionPort} | `policy`, `budget`, `clock`/`now`, `serves` | **all four** |
|
|
22
|
+
* | {@link HostBillingPort} | `skip`, `chargeJudgment`, `conclude` | the three that bill the same way |
|
|
23
|
+
*
|
|
24
|
+
* ## Why the billing channels are a second interface
|
|
25
|
+
*
|
|
26
|
+
* The judgment capabilities (stagnation, correction, closing) record an abandoned
|
|
27
|
+
* plan as "reason + the judgment it cost" and bill an applied plan as "record +
|
|
28
|
+
* applied + the judgment it rode on". All three are literally the same two calls,
|
|
29
|
+
* so they share {@link HostBillingPort}.
|
|
30
|
+
*
|
|
31
|
+
* Pruning is **not** one of them, and this is the finding that stopped this batch
|
|
32
|
+
* from collapsing everything into one interface. Its two billing channels are
|
|
33
|
+
* genuinely wider:
|
|
34
|
+
*
|
|
35
|
+
* - `skip(reason, detail, judgment?)` — the `detail` is not a charge. It carries
|
|
36
|
+
* the payload diagnostics (`digest`, `floored`, `floorMissed`, the segment
|
|
37
|
+
* counts) that make *"why was nothing pruned"* answerable. Those fields are the
|
|
38
|
+
* reason the pruning audit trail exists at all.
|
|
39
|
+
* - `conclude(plan, applied, costs, judgment?, locator?)` — `costs` carries the
|
|
40
|
+
* four size columns and the retained locator, i.e. every number that makes a
|
|
41
|
+
* claimed saving *verifiable*. Collapsing it into the judgment-capability shape
|
|
42
|
+
* would silently drop them.
|
|
43
|
+
*
|
|
44
|
+
* Fitting pruning to the common shape would therefore have required either
|
|
45
|
+
* deleting audit fields or making the base `skip(reason, x?: unknown)`, which
|
|
46
|
+
* buys nothing: every caller would cast, and the one place a wrong answer is a
|
|
47
|
+
* model-visible regression would be the place the type stopped helping. Both were
|
|
48
|
+
* rejected. Pruning extends only {@link HostDecisionPort}, states its two wider
|
|
49
|
+
* channels in its own interface, and the divergence is documented there.
|
|
50
|
+
*
|
|
51
|
+
* ## The judgment is bought, not fetched
|
|
52
|
+
*
|
|
53
|
+
* A port never hands over a backend. It answers **one purchase at a time** —
|
|
54
|
+
* {@link HostJudgmentPort#buy} for the stagnation verdict (bought by both the
|
|
55
|
+
* stagnation and the correction capability, which ask the same question of the
|
|
56
|
+
* same service), `classify`/`verify` for closing's two-request judgment, and
|
|
57
|
+
* `judge(payload)` for pruning's reduction.
|
|
58
|
+
*
|
|
59
|
+
* The distinction matters because a port that exposes `backend()` forces every
|
|
60
|
+
* caller to re-implement the purchase: the memo key, the budget check, the
|
|
61
|
+
* local/remote latency split, and the billing. Those four are the shared layer's
|
|
62
|
+
* — {@link ../judge.runJudgment} and each capability's own accounting — and they
|
|
63
|
+
* are stated once. A host answers only "what did the service say, and how long
|
|
64
|
+
* did it wait".
|
|
65
|
+
*
|
|
66
|
+
* ### One buy is one request; one charge may be several buys
|
|
67
|
+
*
|
|
68
|
+
* The unit of `buy` is the *request*, not the bill. The closing check buys twice
|
|
69
|
+
* from one capability — a classification of the turn's sentences, then a
|
|
70
|
+
* verification of the claims that classification accepted — but bills them as a
|
|
71
|
+
* single {@link JudgmentCost} against the single slot the turn budget granted.
|
|
72
|
+
* That fold is the shared layer's (`orchestrateClosing`), which is exactly why
|
|
73
|
+
* the closing port must not be collapsing the two requests into one method: the
|
|
74
|
+
* latency split and the token sum belong where the charge is built. For the
|
|
75
|
+
* stagnation verdict one buy is one request and one charge.
|
|
76
|
+
*
|
|
77
|
+
* @module core/orchestrate-host
|
|
78
|
+
*/
|
|
79
|
+
export {};
|
|
80
|
+
//# sourceMappingURL=orchestrate-host.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"orchestrate-host.js","sourceRoot":"","sources":["../../../../src/vendor/harness-reflex/core/orchestrate-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG","sourcesContent":["/**\n * The decisions every orchestrated capability asks its host for.\n *\n * ## Why this exists\n *\n * Four capabilities now share one orchestration layer (prune, stagnation,\n * correction, closing), and each of them asks its host the same handful of\n * questions: what policy is in force, which counters may move, how one abandoned\n * plan is recorded, how one plan is billed. Before this module, each `Host*Port`\n * re-declared that surface in its own words. The declarations agreed, but\n * nothing *made* them agree — a fourth capability would have been the fourth copy,\n * and a divergence between two ports meant to be the same would have had nowhere\n * to be caught.\n *\n * The shared surface is stated once, here. It is deliberately split into two\n * interfaces rather than one, because the corpus of four ports showed the two\n * halves have different reach:\n *\n * | Interface | Members | Who extends it |\n * |---|---|---|\n * | {@link HostDecisionPort} | `policy`, `budget`, `clock`/`now`, `serves` | **all four** |\n * | {@link HostBillingPort} | `skip`, `chargeJudgment`, `conclude` | the three that bill the same way |\n *\n * ## Why the billing channels are a second interface\n *\n * The judgment capabilities (stagnation, correction, closing) record an abandoned\n * plan as \"reason + the judgment it cost\" and bill an applied plan as \"record +\n * applied + the judgment it rode on\". All three are literally the same two calls,\n * so they share {@link HostBillingPort}.\n *\n * Pruning is **not** one of them, and this is the finding that stopped this batch\n * from collapsing everything into one interface. Its two billing channels are\n * genuinely wider:\n *\n * - `skip(reason, detail, judgment?)` — the `detail` is not a charge. It carries\n * the payload diagnostics (`digest`, `floored`, `floorMissed`, the segment\n * counts) that make *\"why was nothing pruned\"* answerable. Those fields are the\n * reason the pruning audit trail exists at all.\n * - `conclude(plan, applied, costs, judgment?, locator?)` — `costs` carries the\n * four size columns and the retained locator, i.e. every number that makes a\n * claimed saving *verifiable*. Collapsing it into the judgment-capability shape\n * would silently drop them.\n *\n * Fitting pruning to the common shape would therefore have required either\n * deleting audit fields or making the base `skip(reason, x?: unknown)`, which\n * buys nothing: every caller would cast, and the one place a wrong answer is a\n * model-visible regression would be the place the type stopped helping. Both were\n * rejected. Pruning extends only {@link HostDecisionPort}, states its two wider\n * channels in its own interface, and the divergence is documented there.\n *\n * ## The judgment is bought, not fetched\n *\n * A port never hands over a backend. It answers **one purchase at a time** —\n * {@link HostJudgmentPort#buy} for the stagnation verdict (bought by both the\n * stagnation and the correction capability, which ask the same question of the\n * same service), `classify`/`verify` for closing's two-request judgment, and\n * `judge(payload)` for pruning's reduction.\n *\n * The distinction matters because a port that exposes `backend()` forces every\n * caller to re-implement the purchase: the memo key, the budget check, the\n * local/remote latency split, and the billing. Those four are the shared layer's\n * — {@link ../judge.runJudgment} and each capability's own accounting — and they\n * are stated once. A host answers only \"what did the service say, and how long\n * did it wait\".\n *\n * ### One buy is one request; one charge may be several buys\n *\n * The unit of `buy` is the *request*, not the bill. The closing check buys twice\n * from one capability — a classification of the turn's sentences, then a\n * verification of the claims that classification accepted — but bills them as a\n * single {@link JudgmentCost} against the single slot the turn budget granted.\n * That fold is the shared layer's (`orchestrateClosing`), which is exactly why\n * the closing port must not be collapsing the two requests into one method: the\n * latency split and the token sum belong where the charge is built. For the\n * stagnation verdict one buy is one request and one charge.\n *\n * @module core/orchestrate-host\n */\n\nimport type { ActionStep, StagnationCheckResponse } from '../backend/types.js';\nimport type { ClockPort } from '../ports/clock.js';\nimport type { BudgetState, PolicySnapshot } from './policy.js';\n\n/**\n * The charge of one judgment, as every capability bills it.\n *\n * Stated here rather than in one capability's module because all of them record\n * the same five columns, and the fifth (`judgeTokens`) is the one a host that\n * forgot it would quietly under-report.\n */\nexport interface JudgmentCost {\n readonly judgments: number;\n readonly memoHits: number;\n readonly localLatencyMs: number;\n readonly remoteLatencyMs: number;\n readonly judgeTokens: number;\n}\n\n/**\n * One judgment request: the window, plus the question it is put to.\n *\n * This is the whole of what a host is asked for when a judgment is bought. It is\n * a value rather than a port because the host's only job is \"ask the service and\n * report what it said, latency included\" — the memo key, the budget check, the\n * latency split and the charge stay with the caller that owns the counters.\n */\nexport interface JudgmentStep {\n /** Why the run is judged, when the caller knows (a wait question). */\n readonly goal: string | undefined;\n /** The observed steps to judge, oldest first. */\n readonly history: readonly ActionStep[];\n}\n\n/**\n * Where in the run one judgment is being made.\n *\n * This is the value the four capabilities used to each spell their own accessor\n * for (`position()`, `location()`, `turn()`, and two bare state reads). They\n * disagreed because a port should not answer it: every host has these two\n * numbers, every host means the same thing by them, and a judgment is *about*\n * one place. So the place travels with the judgment — never through the port.\n */\nexport interface JudgmentPosition {\n /** The turn this judgment belongs to. */\n turn: number;\n /** The step this judgment belongs to. */\n step: number;\n}\n\n/**\n * The counters every judgment capability keeps, positioned at where it decides.\n *\n * The place is part of the state for the three capabilities whose state *is* the\n * host's running record (the same object the trigger windows are kept in): the\n * audit detail, the retention request and the verdict memo all quote it, so one\n * source keeps them in step. The closing check is the exception, and the\n * exception is the finding: its turn is the boundary it was asked at, which can\n * be a turn no step has recorded yet, so it arrives as an input of that decision\n * instead (see `orchestrateClosing`).\n */\nexport interface JudgmentState extends BudgetState, JudgmentPosition {}\n\n/**\n * What a capability that buys exactly one judgment asks its host for.\n *\n * The shape is one method over one value: the window and the question put to it\n * ({@link JudgmentStep}). The host answers what the service said, latency\n * included; the purchase around it — budget, memo, latency split, charge — is\n * the shared layer's.\n *\n * A capability that buys *differently* still states its buys in this form, one\n * member per request: closing answers `classify` and `verify`, pruning answers\n * `judge`. The rule is that a port states the purchases it makes and never the\n * transport behind them.\n *\n * @typeParam Answer - what this capability's service returns for one request.\n */\nexport interface HostJudgmentPort<Answer> {\n /**\n * Buy one judgment about one step.\n * @param step - the window to judge and the question it is asked in.\n * @returns the service's answer, carrying the latency the split is measured on.\n */\n buy(step: JudgmentStep): Promise<Answer>;\n}\n\n/**\n * What every orchestrated decision asks its host, whatever it decides.\n *\n * These four are the ones no capability can answer alone and no capability\n * answers differently: the policy is the host's resolved config, the counters are\n * the host's storage, the clock is the host's wall time, and the switch is the\n * host's.\n *\n * @typeParam State - the counters this decision spends from. Must extend\n * {@link BudgetState}, because the shared budget rules mutate it through one.\n */\nexport interface HostDecisionPort<State extends BudgetState = BudgetState> {\n /** The resolved policy in force right now (re-read per decision). */\n policy(): PolicySnapshot;\n /**\n * The counters this decision spends from and books against.\n *\n * The shared layer mutates them in place through `core/policy`; a host that\n * stores its counters elsewhere hands over the object it wants mutated and\n * nothing else has to know where they live.\n */\n budget(): State;\n /** The clock, for the local-latency split. */\n clock(): ClockPort;\n /** Whether the decision applies at all (master switch on, capability not off). */\n serves(): boolean;\n}\n\n/**\n * The three accounting channels the judgment capabilities share.\n *\n * Extended by stagnation, correction and closing. See the module documentation\n * for why pruning is not one of them.\n *\n * @typeParam Charge - the judgment charge this capability bills.\n * @typeParam Record - the plan this capability records when it acts.\n */\nexport interface HostBillingPort<Charge = JudgmentCost, Record = unknown> {\n /**\n * Record one abandoned plan by reason.\n *\n * The charge is passed in because the record has to say what the refusal cost:\n * a paid \"not this\" and a free \"budget spent\" are different answers, and a skip\n * that reported both as free would understate the turn.\n */\n skip(reason: string, charge?: Charge): void;\n /**\n * Bill one judgment whose plan was abandoned after it was really made.\n *\n * A refusal before the judgment is bought costs nothing and is never billed\n * here. One that refused *after* it ran did spend, so hiding it would understate\n * what the turn cost.\n */\n chargeJudgment(charge: Charge): void;\n /**\n * Record one applied or observed plan.\n *\n * This is the one place a plan is billed: `plans` +1, `applied` +1 when it really\n * took effect, and every column of the charge.\n *\n * @param plan - what the capability decided.\n * @param applied - whether active mode executed it.\n * @param charge - the judgment this decision rode on.\n */\n conclude(plan: Record, applied: boolean, charge: Charge): void;\n}\n"]}
|
|
@@ -0,0 +1,259 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The shared orchestration of the stagnation decision.
|
|
3
|
+
*
|
|
4
|
+
* Like {@link ./orchestrate}, this module owns *when and in what order* a
|
|
5
|
+
* decision is made, and none of the host facts the decision is made of. It was
|
|
6
|
+
* lifted in behaviour from the DSH engine's `toolCall` and `preStep` branches so
|
|
7
|
+
* that a second host can reuse them, and each of the two hooks is a function over
|
|
8
|
+
* a port:
|
|
9
|
+
*
|
|
10
|
+
* ```
|
|
11
|
+
* tools/pre-execute
|
|
12
|
+
* downstream first, always
|
|
13
|
+
* → off / own tool / aborted → hand the downstream decision back
|
|
14
|
+
* → [the window: recorded steps + this call, waits removed]
|
|
15
|
+
* → a wait shape already classified this turn → wait-query, nothing asked
|
|
16
|
+
* → the cheap trigger (repetition / failing retry / oscillation)
|
|
17
|
+
* → a handle-shaped repetition promoted to a wait question
|
|
18
|
+
* → not suspicious, or already refused → hand it back
|
|
19
|
+
* → already intervened on this episode → duplicate-intervention
|
|
20
|
+
* → the turn's action allowance is spent → intervention-cap
|
|
21
|
+
* → buy a judgment (memo first, budgets inside)
|
|
22
|
+
* → not useful → charge it, record why, hand it back
|
|
23
|
+
* → latch the refusal, latch the episode, book the action, conclude
|
|
24
|
+
* → deny *only* when the downstream decision was an allow
|
|
25
|
+
*
|
|
26
|
+
* agent/pre-step
|
|
27
|
+
* downstream first, always
|
|
28
|
+
* → off / aborted / not `enter` → hand the downstream decision back
|
|
29
|
+
* → nothing observed → nothing to correct
|
|
30
|
+
* → the last observation was a wait → wait-query / wait-query-unjudged
|
|
31
|
+
* → already intervened / no allowance → duplicate-intervention / cap
|
|
32
|
+
* → the cheap trigger over the progress-only window
|
|
33
|
+
* → buy a judgment → not useful → charge it, record why, hand it back
|
|
34
|
+
* → latch the correction, book the action, conclude
|
|
35
|
+
* → append the correction to the admitted messages (active only)
|
|
36
|
+
* ```
|
|
37
|
+
*
|
|
38
|
+
* ## What is shared and what is not
|
|
39
|
+
*
|
|
40
|
+
* Shared here: both orders, every skip reason, the budget rules
|
|
41
|
+
* (`actionWithinBudget`, `bookAction`, the judgment memo), the latch semantics,
|
|
42
|
+
* the shape of the audit detail, and the rule that decides whether a refusal may
|
|
43
|
+
* be *added* at all.
|
|
44
|
+
*
|
|
45
|
+
* *Not* shared here: the window itself (the host records steps and hands over an
|
|
46
|
+
* array), the call identity a repetition is measured on (the host's signature
|
|
47
|
+
* algorithm), what counts as a legitimate wait (the host's tool list and argument
|
|
48
|
+
* shape), how a correction is attached to a step or a refusal delivered (the
|
|
49
|
+
* host's message and decision types), and the operator-facing wording of either.
|
|
50
|
+
*
|
|
51
|
+
* ## Why the host supplies the window, not a store
|
|
52
|
+
*
|
|
53
|
+
* The DSH engine keeps its window in the agent's own bookkeeping and hands the
|
|
54
|
+
* shared layer a value; a host that derives the window from a persisted log would
|
|
55
|
+
* hand over a different value. Both are legal, and neither has to teach the
|
|
56
|
+
* shared layer how it stores anything. The only thing the shared layer mutates is
|
|
57
|
+
* the counters it is given, through {@link BudgetState}.
|
|
58
|
+
*
|
|
59
|
+
* ## The safety property this module states
|
|
60
|
+
*
|
|
61
|
+
* A refusal may only ever be *added on top of an allow* — {@link mayAddDecision},
|
|
62
|
+
* one place, one rule. A host that returned something stricter is never
|
|
63
|
+
* overwritten, because the harness would otherwise be able to turn a host's
|
|
64
|
+
* conservative decision into a weaker one.
|
|
65
|
+
*
|
|
66
|
+
* @module core/orchestrate-stagnation
|
|
67
|
+
*/
|
|
68
|
+
import type { StagnationCheckResponse } from '../backend/types.js';
|
|
69
|
+
import type { HostBillingPort, HostDecisionPort, HostJudgmentPort } from './orchestrate-host.js';
|
|
70
|
+
import { type ObservedStep, type StagnationSuspicion, type VerdictMemoState } from './judge.js';
|
|
71
|
+
/** The capability every decision in this module belongs to. */
|
|
72
|
+
export declare const STAGNATION_CAPABILITY: "stagnation";
|
|
73
|
+
/** What one orchestrated decision turned out to be. */
|
|
74
|
+
export type StagnationAction = 'allow' | 'deny' | 'pass-through';
|
|
75
|
+
/**
|
|
76
|
+
* The window a stagnation trigger and its judgment are measured on.
|
|
77
|
+
*
|
|
78
|
+
* A wait query is not progress the run can be repeating: an identically repeated
|
|
79
|
+
* status/result query of the same background job is the sanctioned way to wait,
|
|
80
|
+
* so those steps are dropped before the repetition, failure and oscillation
|
|
81
|
+
* triggers read the window. Genuine calls on either side of a wait stay adjacent
|
|
82
|
+
* instead of being separated by it, which keeps a real loop visible while a run
|
|
83
|
+
* is waiting.
|
|
84
|
+
* @param steps - observed steps, oldest first.
|
|
85
|
+
* @returns the steps that count as progress.
|
|
86
|
+
*/
|
|
87
|
+
export declare function progressSteps(steps: readonly ObservedStep[]): readonly ObservedStep[];
|
|
88
|
+
/**
|
|
89
|
+
* Whether an action may be added on top of the decision the rest of the
|
|
90
|
+
* waterfall already made.
|
|
91
|
+
*
|
|
92
|
+
* This is the permission-monotonicity rule, in one place: a `deny` may be added
|
|
93
|
+
* only to an `allow`. An approval in flight, a denial carrying its own structured
|
|
94
|
+
* error identity, or a cancellation is information the Host attached, and
|
|
95
|
+
* overwriting any of it would drop that information or relax the decision.
|
|
96
|
+
* @param downstreamKind - the kind of the downstream decision.
|
|
97
|
+
* @returns whether the shared layer may add a refusal.
|
|
98
|
+
*/
|
|
99
|
+
export declare function mayAddDecision(downstreamKind: string): boolean;
|
|
100
|
+
/**
|
|
101
|
+
* The trigger for a repetition of a *wait-shaped* call.
|
|
102
|
+
*
|
|
103
|
+
* The host's tool list only decides that this repetition is worth asking about;
|
|
104
|
+
* it does not pass or refuse anything by itself.
|
|
105
|
+
* @param shape - the wait shape the host recognised.
|
|
106
|
+
* @param repeats - how many times the identity already occurred.
|
|
107
|
+
* @returns the promoted trigger.
|
|
108
|
+
*/
|
|
109
|
+
export declare function waitTrigger(shape: string, repeats: number): StagnationSuspicion;
|
|
110
|
+
/** The judgment cost of one decision, as the host bills it. */
|
|
111
|
+
export interface JudgedCharge {
|
|
112
|
+
readonly judgments: number;
|
|
113
|
+
readonly memoHits: number;
|
|
114
|
+
readonly localLatencyMs: number;
|
|
115
|
+
readonly remoteLatencyMs: number;
|
|
116
|
+
readonly judgeTokens: number;
|
|
117
|
+
}
|
|
118
|
+
/** One planned stagnation decision, as the host records it. */
|
|
119
|
+
export interface StagnationPlanRecord {
|
|
120
|
+
readonly capability: typeof STAGNATION_CAPABILITY;
|
|
121
|
+
readonly action: 'deny-call' | 'corrective-context';
|
|
122
|
+
readonly reason: string;
|
|
123
|
+
feedback: string;
|
|
124
|
+
readonly detail: Record<string, unknown>;
|
|
125
|
+
}
|
|
126
|
+
/** What one refusal or correction was built from. */
|
|
127
|
+
export interface StagnationFeedbackFacts {
|
|
128
|
+
readonly tool: string;
|
|
129
|
+
readonly suspicion: StagnationSuspicion;
|
|
130
|
+
readonly verdict: StagnationCheckResponse;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* The counters one decision spends from and books against.
|
|
134
|
+
*
|
|
135
|
+
* The verdict cache is part of the budget state because a cached answer is what
|
|
136
|
+
* makes a second question in the same turn free: the shared layer reads it
|
|
137
|
+
* through here rather than keeping a second copy.
|
|
138
|
+
*/
|
|
139
|
+
export interface StagnationState extends VerdictMemoState {
|
|
140
|
+
verdictTurn: number;
|
|
141
|
+
verdictKey: string;
|
|
142
|
+
verdict?: StagnationCheckResponse;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Everything the shared layer cannot know by itself.
|
|
146
|
+
*
|
|
147
|
+
* {@link HostDecisionPort} answers the part every capability asks — policy,
|
|
148
|
+
* counters, clock, switch, and the three billing channels — so this interface
|
|
149
|
+
* states only what a *refusal or correction* additionally needs.
|
|
150
|
+
*/
|
|
151
|
+
export interface HostStagnationPort<Decision, Corrected> extends HostDecisionPort<StagnationState>, HostBillingPort<JudgedCharge, StagnationPlanRecord>, HostJudgmentPort<StagnationCheckResponse> {
|
|
152
|
+
/** Name of the call being decided, for the record and the wording. */
|
|
153
|
+
toolName(): string;
|
|
154
|
+
/** The recorded window, oldest first, *without* the call about to run. */
|
|
155
|
+
window(): readonly ObservedStep[];
|
|
156
|
+
/** The step the call about to run would append, without committing it. */
|
|
157
|
+
pendingStep(): ObservedStep;
|
|
158
|
+
/** The identity this decision is about. */
|
|
159
|
+
signature(): string;
|
|
160
|
+
/**
|
|
161
|
+
* The cheap trigger over one window.
|
|
162
|
+
*
|
|
163
|
+
* `PolicySnapshot` carries the repetition threshold and the confidence floor —
|
|
164
|
+
* the two numbers the *budget* rules are stated in — but the failure threshold
|
|
165
|
+
* and the window size are trigger parameters, and the host owns their values.
|
|
166
|
+
* Keeping them here is what keeps one policy type for every capability.
|
|
167
|
+
*/
|
|
168
|
+
suspicion(steps: readonly ObservedStep[]): StagnationSuspicion;
|
|
169
|
+
/** The progress-only window a pre-step corrects against. */
|
|
170
|
+
progressWindow(): readonly ObservedStep[];
|
|
171
|
+
/** Whether this identity was already intervened on this turn. */
|
|
172
|
+
alreadyIntervened(): boolean;
|
|
173
|
+
/** Whether this identity was already refused this turn. */
|
|
174
|
+
alreadyDenied(): boolean;
|
|
175
|
+
/**
|
|
176
|
+
* Whether the signature of a step was already classified as a wait.
|
|
177
|
+
*
|
|
178
|
+
* The pre-step hook needs it to tell "a poll the run already had answered" from
|
|
179
|
+
* "a poll this turn never judged" — two different skip reasons, and the second
|
|
180
|
+
* one is not a stagnation episode at all.
|
|
181
|
+
*/
|
|
182
|
+
wasClassifiedAsWait(signature: string): boolean;
|
|
183
|
+
/** Latch this identity as refused. */
|
|
184
|
+
latchDenied(): void;
|
|
185
|
+
/** Latch this identity as an episode already acted on. */
|
|
186
|
+
latchIntervened(): void;
|
|
187
|
+
/** The decision to hand back when nothing is done. */
|
|
188
|
+
passThrough(): Decision;
|
|
189
|
+
/** Build the refusal, once the decision is to apply one. */
|
|
190
|
+
deny(feedback: string): Decision;
|
|
191
|
+
/** Append the correction to the admitted messages, once the decision is to apply one. */
|
|
192
|
+
correct(feedback: string): Corrected;
|
|
193
|
+
/** Word the refusal handed to the model. */
|
|
194
|
+
denyFeedback(facts: StagnationFeedbackFacts): string;
|
|
195
|
+
/** Word the corrective context attached to a step. */
|
|
196
|
+
contextFeedback(facts: StagnationFeedbackFacts): string;
|
|
197
|
+
}
|
|
198
|
+
/** The outcome of one orchestrated decision. */
|
|
199
|
+
export interface StagnationOutcome<Decision> {
|
|
200
|
+
/** What the host should return to its caller. */
|
|
201
|
+
readonly result: Decision;
|
|
202
|
+
/** What the decision was. */
|
|
203
|
+
readonly action: StagnationAction;
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* `tools/pre-execute`: refuse a call the run is repeating.
|
|
207
|
+
*
|
|
208
|
+
* The host calls this **after** its own `next()`, and hands over what that
|
|
209
|
+
* returned: the downstream decision is the first fact the decision is about, and
|
|
210
|
+
* a refusal may only ever be added to an allow.
|
|
211
|
+
*
|
|
212
|
+
* @param invocation - the downstream decision, the signal, and the window facts.
|
|
213
|
+
* @param port - everything that is the host's to answer.
|
|
214
|
+
* @returns the decision the Host dispatches on.
|
|
215
|
+
*/
|
|
216
|
+
export declare function orchestrateStagnationPre<Decision, Corrected>(invocation: {
|
|
217
|
+
/** Kind of the decision the rest of the waterfall made. */
|
|
218
|
+
readonly downstreamKind: string;
|
|
219
|
+
/** The call's abort signal, if it has one. */
|
|
220
|
+
readonly signal?: AbortSignal;
|
|
221
|
+
/**
|
|
222
|
+
* The window the judgment is about, when a wait question needs one.
|
|
223
|
+
*
|
|
224
|
+
* Defaults to the progress-only window. A host that annotates its polls
|
|
225
|
+
* supplies the annotated list here, because *how* a poll is labelled is the
|
|
226
|
+
* host's business and the shared layer only asks the question.
|
|
227
|
+
*/
|
|
228
|
+
judgeSteps?: () => readonly ObservedStep[];
|
|
229
|
+
/** The question a promoted wait asks, or nothing for an ordinary repetition. */
|
|
230
|
+
waitQuestion?: () => string | undefined;
|
|
231
|
+
/** Whether this wait shape was already classified this turn. */
|
|
232
|
+
waitClassified?: () => boolean;
|
|
233
|
+
/** Latch the wait shape as classified. */
|
|
234
|
+
latchWait?: () => void;
|
|
235
|
+
/** The wait handle shape, so the trigger can name it. */
|
|
236
|
+
waitShape?: () => {
|
|
237
|
+
readonly shape: string;
|
|
238
|
+
readonly repeats: number;
|
|
239
|
+
} | undefined;
|
|
240
|
+
/** Record that this call was refused, so its result is not judged as evidence. */
|
|
241
|
+
noteRefused?: () => void;
|
|
242
|
+
}, port: HostStagnationPort<Decision, Corrected>): Promise<StagnationOutcome<Decision>>;
|
|
243
|
+
/**
|
|
244
|
+
* `agent/pre-step`: attach the correction to the step after a loop repeated
|
|
245
|
+
* itself.
|
|
246
|
+
*
|
|
247
|
+
* The host calls this **after** its own `next()`. A step the rest of the
|
|
248
|
+
* waterfall rejected, or a step whose turn is being cancelled, is not corrected.
|
|
249
|
+
*
|
|
250
|
+
* @param invocation - the downstream decision and the signal.
|
|
251
|
+
* @param port - everything that is the host's to answer.
|
|
252
|
+
* @returns the decision the loop enters with.
|
|
253
|
+
*/
|
|
254
|
+
export declare function orchestrateStagnationStep<Decision, Corrected>(invocation: {
|
|
255
|
+
/** Kind of the decision the rest of the waterfall made. */
|
|
256
|
+
readonly downstreamKind: string;
|
|
257
|
+
/** The step's abort signal, if it has one. */
|
|
258
|
+
readonly signal?: AbortSignal;
|
|
259
|
+
}, port: HostStagnationPort<Decision, Corrected>): Promise<StagnationOutcome<Decision | Corrected>>;
|