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/CHANGELOG.md +20 -0
- package/README.md +103 -23
- package/USER_GUIDE.md +121 -43
- package/dist/adapters/agy.js +1 -1
- package/dist/adapters/agy.js.map +1 -1
- package/dist/adapters/codex.d.ts +133 -4
- package/dist/adapters/codex.js +325 -2
- package/dist/adapters/codex.js.map +1 -1
- package/dist/backend/defaults.d.ts +31 -0
- package/dist/backend/defaults.js +32 -0
- package/dist/backend/defaults.js.map +1 -0
- package/dist/backend/jev.js +6 -5
- package/dist/backend/jev.js.map +1 -1
- package/dist/backend/mock.d.ts +12 -1
- package/dist/backend/mock.js +34 -0
- package/dist/backend/mock.js.map +1 -1
- package/dist/backend/simple-jev.js +5 -4
- package/dist/backend/simple-jev.js.map +1 -1
- package/dist/backend/types.d.ts +34 -0
- package/dist/backend/types.js.map +1 -1
- package/dist/cli/index.js +5 -3
- package/dist/cli/index.js.map +1 -1
- package/dist/core/closing.d.ts +90 -0
- package/dist/core/closing.js +111 -0
- package/dist/core/closing.js.map +1 -0
- package/dist/core/evidence.d.ts +119 -0
- package/dist/core/evidence.js +209 -0
- package/dist/core/evidence.js.map +1 -0
- package/dist/core/judge.d.ts +221 -0
- package/dist/core/judge.js +251 -0
- package/dist/core/judge.js.map +1 -0
- package/dist/core/orchestrate-closing.d.ts +237 -0
- package/dist/core/orchestrate-closing.js +250 -0
- package/dist/core/orchestrate-closing.js.map +1 -0
- package/dist/core/orchestrate-correction.d.ts +209 -0
- package/dist/core/orchestrate-correction.js +141 -0
- package/dist/core/orchestrate-correction.js.map +1 -0
- package/dist/core/orchestrate-host.d.ts +225 -0
- package/dist/core/orchestrate-host.js +80 -0
- package/dist/core/orchestrate-host.js.map +1 -0
- package/dist/core/orchestrate-stagnation.d.ts +259 -0
- package/dist/core/orchestrate-stagnation.js +270 -0
- package/dist/core/orchestrate-stagnation.js.map +1 -0
- package/dist/core/orchestrate.d.ts +357 -0
- package/dist/core/orchestrate.js +418 -0
- package/dist/core/orchestrate.js.map +1 -0
- package/dist/core/policy.d.ts +122 -0
- package/dist/core/policy.js +102 -0
- package/dist/core/policy.js.map +1 -0
- package/dist/core/prune-plan.d.ts +141 -0
- package/dist/core/prune-plan.js +390 -0
- package/dist/core/prune-plan.js.map +1 -0
- package/dist/core/score.d.ts +2 -2
- package/dist/core/score.js.map +1 -1
- package/dist/core/text.d.ts +36 -0
- package/dist/core/text.js +66 -0
- package/dist/core/text.js.map +1 -0
- package/dist/hook/cli.d.ts +9 -0
- package/dist/hook/cli.js +52 -0
- package/dist/hook/cli.js.map +1 -0
- package/dist/hook/contract.d.ts +125 -0
- package/dist/hook/contract.js +159 -0
- package/dist/hook/contract.js.map +1 -0
- package/dist/hook/decision.d.ts +97 -0
- package/dist/hook/decision.js +955 -0
- package/dist/hook/decision.js.map +1 -0
- package/dist/hook/memory-store.d.ts +81 -0
- package/dist/hook/memory-store.js +157 -0
- package/dist/hook/memory-store.js.map +1 -0
- package/dist/hook/payload.d.ts +55 -0
- package/dist/hook/payload.js +129 -0
- package/dist/hook/payload.js.map +1 -0
- package/dist/hook/run.d.ts +48 -0
- package/dist/hook/run.js +218 -0
- package/dist/hook/run.js.map +1 -0
- package/dist/hook/store-port.d.ts +72 -0
- package/dist/hook/store-port.js +2 -0
- package/dist/hook/store-port.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/ports/audit.d.ts +18 -0
- package/dist/ports/audit.js +11 -0
- package/dist/ports/audit.js.map +1 -0
- package/dist/ports/clock.d.ts +14 -0
- package/dist/ports/clock.js +11 -0
- package/dist/ports/clock.js.map +1 -0
- package/dist/ports/decision.d.ts +75 -0
- package/dist/ports/decision.js +2 -0
- package/dist/ports/decision.js.map +1 -0
- package/dist/ports/index.d.ts +14 -0
- package/dist/ports/index.js +2 -0
- package/dist/ports/index.js.map +1 -0
- package/dist/ports/log.d.ts +22 -0
- package/dist/ports/log.js +12 -0
- package/dist/ports/log.js.map +1 -0
- package/dist/ports/state.d.ts +46 -0
- package/dist/ports/state.js +13 -0
- package/dist/ports/state.js.map +1 -0
- package/dist/state/clock.d.ts +40 -0
- package/dist/state/clock.js +43 -0
- package/dist/state/clock.js.map +1 -0
- package/dist/state/file-store.d.ts +340 -0
- package/dist/state/file-store.js +849 -0
- package/dist/state/file-store.js.map +1 -0
- package/dist/state/paths.d.ts +41 -0
- package/dist/state/paths.js +73 -0
- package/dist/state/paths.js.map +1 -0
- package/docs/USER_GUIDE.en.md +79 -36
- package/docs/claude-code.md +281 -0
- package/docs/design/v0.2.0-harness-plugins.md +381 -0
- package/docs/design/v0.3.0-orchestration-unification.md +580 -0
- package/docs/dsh-plugin.md +54 -54
- package/docs/release-checklist-v0.1.0.md +32 -21
- package/docs/release-handbook-porting-notes.md +11 -11
- package/docs/release-handbook.md +55 -30
- package/docs/release-notes-v0.1.0.md +27 -14
- package/docs/release-notes-v0.3.0.md +152 -0
- package/docs/research/claude-code-harness.md +607 -0
- package/docs/research/pi-harness.md +621 -0
- package/package.json +16 -7
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"orchestrate-stagnation.js","sourceRoot":"","sources":["../../src/core/orchestrate-stagnation.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The shared orchestration of the stagnation decision.\n *\n * Like {@link ./orchestrate}, this module owns *when and in what order* a\n * decision is made, and none of the host facts the decision is made of. It was\n * lifted in behaviour from the DSH engine's `toolCall` and `preStep` branches so\n * that a second host can reuse them, and each of the two hooks is a function over\n * a port:\n *\n * ```\n * tools/pre-execute\n * downstream first, always\n * → off / own tool / aborted → hand the downstream decision back\n * → [the window: recorded steps + this call, waits removed]\n * → a wait shape already classified this turn → wait-query, nothing asked\n * → the cheap trigger (repetition / failing retry / oscillation)\n * → a handle-shaped repetition promoted to a wait question\n * → not suspicious, or already refused → hand it back\n * → already intervened on 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 refusal, latch the episode, book the action, conclude\n * → deny *only* when the downstream decision was an allow\n *\n * agent/pre-step\n * downstream first, always\n * → off / aborted / not `enter` → hand the downstream decision back\n * → nothing observed → nothing to correct\n * → the last observation was a wait → wait-query / wait-query-unjudged\n * → already intervened / no allowance → duplicate-intervention / cap\n * → the cheap trigger over the progress-only window\n * → buy a judgment → not useful → charge it, record why, hand it back\n * → latch the correction, book the action, conclude\n * → append the correction to the admitted messages (active only)\n * ```\n *\n * ## What is shared and what is not\n *\n * Shared here: both orders, every skip reason, the budget rules\n * (`actionWithinBudget`, `bookAction`, the judgment memo), the latch semantics,\n * the shape of the audit detail, and the rule that decides whether a refusal may\n * be *added* at all.\n *\n * *Not* shared here: the window itself (the host records steps and hands over an\n * array), the call identity a repetition is measured on (the host's signature\n * algorithm), what counts as a legitimate wait (the host's tool list and argument\n * shape), how a correction is attached to a step or a refusal delivered (the\n * host's message and decision types), and the operator-facing wording of either.\n *\n * ## Why the host supplies the window, not a store\n *\n * The DSH engine keeps its window in the agent's own bookkeeping and hands the\n * shared layer a value; a host that derives the window from a persisted log would\n * hand over a different value. Both are legal, and neither has to teach the\n * shared layer how it stores anything. The only thing the shared layer mutates is\n * the counters it is given, through {@link BudgetState}.\n *\n * ## The safety property this module states\n *\n * A refusal may only ever be *added on top of an allow* — {@link mayAddDecision},\n * one place, one rule. A host that returned something stricter is never\n * overwritten, because the harness would otherwise be able to turn a host's\n * conservative decision into a weaker one.\n *\n * @module core/orchestrate-stagnation\n */\nimport type { StagnationCheckResponse } from '../backend/types.js';\nimport type { HostBillingPort, HostDecisionPort, HostJudgmentPort, JudgmentState } from './orchestrate-host.js';\nimport {\n judgmentCharge,\n runJudgment,\n type JudgmentOutcome,\n type ObservedStep,\n type StagnationSuspicion,\n type VerdictMemoState\n} from './judge.js';\nimport { actionWithinBudget, bookAction, modeOf, type PolicySnapshot } from './policy.js';\n\n/** The capability every decision in this module belongs to. */\nexport const STAGNATION_CAPABILITY = 'stagnation' as const;\n\n/** What one orchestrated decision turned out to be. */\nexport type StagnationAction = 'allow' | 'deny' | 'pass-through';\n\n/**\n * The window a stagnation trigger and its judgment are measured on.\n *\n * A wait query is not progress the run can be repeating: an identically repeated\n * status/result query of the same background job is the sanctioned way to wait,\n * so those steps are dropped before the repetition, failure and oscillation\n * triggers read the window. Genuine calls on either side of a wait stay adjacent\n * instead of being separated by it, which keeps a real loop visible while a run\n * is waiting.\n * @param steps - observed steps, oldest first.\n * @returns the steps that count as progress.\n */\nexport function progressSteps(steps: readonly ObservedStep[]): readonly ObservedStep[] {\n return steps.some((step) => step.wait === true) ? steps.filter((step) => step.wait !== true) : steps;\n}\n\n/**\n * Whether an action may be added on top of the decision the rest of the\n * waterfall already made.\n *\n * This is the permission-monotonicity rule, in one place: a `deny` may be added\n * only to an `allow`. An approval in flight, a denial carrying its own structured\n * error identity, or a cancellation is information the Host attached, and\n * overwriting any of it would drop that information or relax the decision.\n * @param downstreamKind - the kind of the downstream decision.\n * @returns whether the shared layer may add a refusal.\n */\nexport function mayAddDecision(downstreamKind: string): boolean {\n return downstreamKind === 'allow';\n}\n\n/**\n * The trigger for a repetition of a *wait-shaped* call.\n *\n * The host's tool list only decides that this repetition is worth asking about;\n * it does not pass or refuse anything by itself.\n * @param shape - the wait shape the host recognised.\n * @param repeats - how many times the identity already occurred.\n * @returns the promoted trigger.\n */\nexport function waitTrigger(shape: string, repeats: number): StagnationSuspicion {\n return {\n suspicious: true,\n pattern: 'repetition',\n note: `wait-suspect ${shape} repeated ${repeats}x`,\n repeats\n };\n}\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 stagnation decision, as the host records it. */\nexport interface StagnationPlanRecord {\n readonly capability: typeof STAGNATION_CAPABILITY;\n readonly action: 'deny-call' | 'corrective-context';\n readonly reason: string;\n feedback: string;\n readonly detail: Record<string, unknown>;\n}\n\n/** What one refusal or correction was built from. */\nexport interface StagnationFeedbackFacts {\n readonly tool: string;\n readonly suspicion: StagnationSuspicion;\n readonly verdict: StagnationCheckResponse;\n}\n\n/**\n * The counters one decision 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: the shared layer reads it\n * through here rather than keeping a second copy.\n */\nexport interface StagnationState extends VerdictMemoState {\n verdictTurn: number;\n verdictKey: string;\n verdict?: StagnationCheckResponse;\n}\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 *refusal or correction* additionally needs.\n */\nexport interface HostStagnationPort<Decision, Corrected>\n extends HostDecisionPort<StagnationState>,\n HostBillingPort<JudgedCharge, StagnationPlanRecord>,\n HostJudgmentPort<StagnationCheckResponse> {\n /** Name of the call being decided, for the record and the wording. */\n toolName(): string;\n /** The recorded window, oldest first, *without* the call about to run. */\n window(): readonly ObservedStep[];\n /** The step the call about to run would append, without committing it. */\n pendingStep(): 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 and the confidence floor —\n * the two numbers the *budget* rules are stated in — but the failure threshold\n * and the window size are trigger parameters, and the host owns their values.\n * Keeping them here is what keeps one policy type for every capability.\n */\n suspicion(steps: readonly ObservedStep[]): StagnationSuspicion;\n /** The progress-only window a pre-step corrects against. */\n progressWindow(): readonly ObservedStep[];\n /** Whether this identity was already intervened on this turn. */\n alreadyIntervened(): boolean;\n /** Whether this identity was already refused this turn. */\n alreadyDenied(): boolean;\n /**\n * Whether the signature of a step was already classified as a wait.\n *\n * The pre-step hook needs it to tell \"a poll the run already had answered\" from\n * \"a poll this turn never judged\" — two different skip reasons, and the second\n * one is not a stagnation episode at all.\n */\n wasClassifiedAsWait(signature: string): boolean;\n /** Latch this identity as refused. */\n latchDenied(): void;\n /** Latch this identity as an episode already acted on. */\n latchIntervened(): void;\n /** The decision to hand back when nothing is done. */\n passThrough(): Decision;\n /** Build the refusal, once the decision is to apply one. */\n deny(feedback: string): Decision;\n /** Append the correction to the admitted messages, once the decision is to apply one. */\n correct(feedback: string): Corrected;\n /** Word the refusal handed to the model. */\n denyFeedback(facts: StagnationFeedbackFacts): string;\n /** Word the corrective context attached to a step. */\n contextFeedback(facts: StagnationFeedbackFacts): string;\n}\n\n/** The outcome of one orchestrated decision. */\nexport interface StagnationOutcome<Decision> {\n /** What the host should return to its caller. */\n readonly result: Decision;\n /** What the decision was. */\n readonly action: StagnationAction;\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 stagnation record carries.\n * @param suspicion - the cheap-path trigger.\n * @param verdict - what System 1 answered.\n * @param state - the deciding state, for turn and step.\n * @param step - the step the decision belongs to.\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/pre-execute`: refuse a call the run is repeating.\n *\n * The host calls this **after** its own `next()`, and hands over what that\n * returned: the downstream decision is the first fact the decision is about, and\n * a refusal may only ever be added to an allow.\n *\n * @param invocation - the downstream decision, the signal, and the window facts.\n * @param port - everything that is the host's to answer.\n * @returns the decision the Host dispatches on.\n */\nexport async function orchestrateStagnationPre<Decision, Corrected>(\n invocation: {\n /** Kind of the decision the rest of the waterfall made. */\n readonly downstreamKind: string;\n /** The call's abort signal, if it has one. */\n readonly signal?: AbortSignal;\n /**\n * The window the judgment is about, when a wait question needs one.\n *\n * Defaults to the progress-only window. A host that annotates its polls\n * supplies the annotated list here, because *how* a poll is labelled is the\n * host's business and the shared layer only asks the question.\n */\n judgeSteps?: () => readonly ObservedStep[];\n /** The question a promoted wait asks, or nothing for an ordinary repetition. */\n waitQuestion?: () => string | undefined;\n /** Whether this wait shape was already classified this turn. */\n waitClassified?: () => boolean;\n /** Latch the wait shape as classified. */\n latchWait?: () => void;\n /** The wait handle shape, so the trigger can name it. */\n waitShape?: () => { readonly shape: string; readonly repeats: number } | undefined;\n /** Record that this call was refused, so its result is not judged as evidence. */\n noteRefused?: () => void;\n },\n port: HostStagnationPort<Decision, Corrected>\n): Promise<StagnationOutcome<Decision>> {\n const { signal } = invocation;\n const passThrough = (): StagnationOutcome<Decision> => ({ result: port.passThrough(), action: 'pass-through' });\n const mode = modeOf(port.policy(), STAGNATION_CAPABILITY);\n if (mode === 'off' || !port.serves()) return passThrough();\n if (signal?.aborted === true) return passThrough();\n\n const policy = port.policy();\n const pending = port.pendingStep();\n // The call about to run is part of its own window: three identical calls are a\n // repetition at the moment the third one is proposed, and the judgment has to\n // see all three.\n const allWindow = [...port.window(), pending];\n const window = progressSteps(allWindow);\n const signalValue = invocation.waitShape?.();\n\n // A wait-suspect call this turn already classified is answered by that verdict\n // rather than re-asked; anything else is only worth a question when it actually\n // repeats (the same threshold as any other repetition).\n if (signalValue !== undefined && invocation.waitClassified?.() === true) {\n port.skip('wait-query');\n return passThrough();\n }\n\n let suspicion = port.suspicion(window);\n let waitSuspected = false;\n if (signalValue !== undefined && signalValue.repeats >= policy.repeatThreshold) {\n suspicion = waitTrigger(signalValue.shape, signalValue.repeats);\n waitSuspected = true;\n }\n if (!suspicion.suspicious || port.alreadyDenied()) return passThrough();\n if (port.alreadyIntervened()) {\n port.skip('duplicate-intervention');\n return passThrough();\n }\n if (!actionWithinBudget(port.budget(), policy)) {\n port.skip('intervention-cap');\n return passThrough();\n }\n\n // A wait question is judged on the polls themselves (each labelled with its\n // place in the series, so the backend can read a wait rather than an exact\n // repeat); every other question keeps the progress-only window.\n const steps = waitSuspected ? (invocation.judgeSteps?.() ?? window) : window;\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,\n ...(waitSuspected ? { goal: invocation.waitQuestion?.() } : {}),\n ...(signal === undefined ? {} : { signal })\n });\n const charge = chargeOf(outcome, started, port.clock().now());\n // Denial is latched per signature whether or not it was applied: in observe\n // mode the refusal is what would have happened, and the latch is what keeps the\n // next identical attempt from being judged again in the same turn.\n port.latchDenied();\n\n if (!outcome.useful) {\n if (waitSuspected) invocation.latchWait?.();\n // A budget/abort skip keeps its own reason; only a real \"not stuck\" answer to\n // a wait question is recorded as the wait outcome.\n port.chargeJudgment(charge);\n port.skip(outcome.skip ?? (waitSuspected ? 'wait-query' : 'unconfirmed'), charge);\n return passThrough();\n }\n\n const facts: StagnationFeedbackFacts = {\n tool: port.toolName(),\n suspicion,\n verdict: outcome.response\n };\n const plan: StagnationPlanRecord = {\n capability: STAGNATION_CAPABILITY,\n action: 'deny-call',\n reason: `System 1 confirmed ${outcome.response.patternType ?? suspicion.pattern} stagnation before ${port.toolName()}`,\n feedback: port.denyFeedback(facts),\n detail: detailOf(suspicion, outcome.response, port.budget().turn, port.budget().step)\n };\n const applies = mode === 'active' && mayAddDecision(invocation.downstreamKind);\n if (mode === 'active' && !applies) port.skip('downstream-decided');\n invocation.noteRefused?.();\n // The episode and the action are latched in both modes: observe has to plan\n // exactly what active would do — one refusal per episode, subject to the same\n // turn cap — or its column would over-count the very thing it is measuring.\n port.latchIntervened();\n bookAction(port.budget());\n port.conclude(plan, applies, charge);\n return applies\n ? { result: port.deny(plan.feedback), action: 'deny' }\n : passThrough();\n}\n\n/**\n * `agent/pre-step`: attach the correction to the step after a loop repeated\n * itself.\n *\n * The host calls this **after** its own `next()`. A step the rest of the\n * waterfall rejected, or a step whose turn is being cancelled, is not corrected.\n *\n * @param invocation - the downstream decision and the signal.\n * @param port - everything that is the host's to answer.\n * @returns the decision the loop enters with.\n */\nexport async function orchestrateStagnationStep<Decision, Corrected>(\n invocation: {\n /** Kind of the decision the rest of the waterfall made. */\n readonly downstreamKind: string;\n /** The step's abort signal, if it has one. */\n readonly signal?: AbortSignal;\n },\n port: HostStagnationPort<Decision, Corrected>\n): Promise<StagnationOutcome<Decision | Corrected>> {\n const passThrough = (): StagnationOutcome<Decision | Corrected> => ({\n result: port.passThrough() as Decision | Corrected,\n action: 'pass-through'\n });\n const mode = modeOf(port.policy(), STAGNATION_CAPABILITY);\n if (mode === 'off' || !port.serves()) return passThrough();\n if (invocation.signal?.aborted === true || invocation.downstreamKind !== 'enter') return passThrough();\n\n // The last observation is read from the *raw* window, before waits are dropped:\n // a wait is exactly what this branch is about, so a window that had already\n // filtered it out could never recognize one. Everything after this reads the\n // progress-only window.\n const recorded = port.window();\n const last = recorded[recorded.length - 1];\n if (last === undefined) return passThrough();\n // A poll that already passed the semantic wait judgment has nothing to correct\n // here: the run asked about a background job again, it did not repeat its work.\n // A poll this turn never judged was not a repetition, so it is not an episode.\n if (last.wait === true) {\n port.skip(port.wasClassifiedAsWait(last.signature) ? 'wait-query' : 'wait-query-unjudged');\n return passThrough();\n }\n const window = port.progressWindow();\n if (port.alreadyIntervened()) {\n port.skip('duplicate-intervention');\n return passThrough();\n }\n const policy = port.policy();\n if (!actionWithinBudget(port.budget(), policy)) {\n port.skip('intervention-cap');\n return passThrough();\n }\n\n const suspicion = port.suspicion(window);\n if (!suspicion.suspicious) return passThrough();\n\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: window,\n ...(invocation.signal === undefined ? {} : { signal: invocation.signal })\n });\n const charge = chargeOf(outcome, started, port.clock().now());\n if (!outcome.useful) {\n port.chargeJudgment(charge);\n port.skip(outcome.skip ?? 'unconfirmed', charge);\n return passThrough();\n }\n\n const facts: StagnationFeedbackFacts = {\n tool: port.toolName(),\n suspicion,\n verdict: outcome.response\n };\n const plan: StagnationPlanRecord = {\n capability: STAGNATION_CAPABILITY,\n action: 'corrective-context',\n reason: `System 1 confirmed ${outcome.response.patternType ?? suspicion.pattern} stagnation before step ${port.budget().step}`,\n feedback: port.contextFeedback(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 intervention per detected loop, one charge against the turn's\n // cap — or its accounting would describe a run nobody could reproduce;\n // installing the message is the only thing the mode gates.\n port.latchIntervened();\n bookAction(port.budget());\n port.conclude(plan, applies, charge);\n return applies\n ? { result: port.correct(plan.feedback), action: 'allow' }\n : passThrough();\n}\n"]}
|
|
@@ -0,0 +1,357 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The shared orchestration of one judged reduction.
|
|
3
|
+
*
|
|
4
|
+
* This module owns *when and in what order* a pruning decision is made; it does
|
|
5
|
+
* not own any of the host facts that decision is made of. It was lifted verbatim
|
|
6
|
+
* in behaviour from the DSH engine's private prune branch so that a second host
|
|
7
|
+
* can reuse it, and it is written as a pure function over a port so that the
|
|
8
|
+
* order — which is a safety property, not a style — is stated in exactly one
|
|
9
|
+
* place:
|
|
10
|
+
*
|
|
11
|
+
* ```
|
|
12
|
+
* refuse off / downstream-blocked / value-shaped
|
|
13
|
+
* → refuse payloads that are not line-oriented output
|
|
14
|
+
* → refuse payloads too large to retain
|
|
15
|
+
* → refuse when no retention sink exists
|
|
16
|
+
* → refuse when the turn's action allowance is spent
|
|
17
|
+
* → buy a judgment (memo first), refuse when the judgment budget is spent
|
|
18
|
+
* → compose the floored candidate, refuse when it is not smaller
|
|
19
|
+
* → [observe: record the plan and stop]
|
|
20
|
+
* → retain the original, refuse when no verifiable copy exists
|
|
21
|
+
* → compose against the real locator, refuse when the result is not smaller
|
|
22
|
+
* → ask the host to install it, refuse when there is no text block
|
|
23
|
+
* → only now record the saving
|
|
24
|
+
* ```
|
|
25
|
+
*
|
|
26
|
+
* Every "refuse" returns the downstream decision untouched and reports why. A
|
|
27
|
+
* reduction that cannot be verified can therefore never be reported as applied.
|
|
28
|
+
*
|
|
29
|
+
* ## What is shared and what is not
|
|
30
|
+
*
|
|
31
|
+
* Shared here: the order above, every skip reason, the budget rules (which
|
|
32
|
+
* counter moves when), the size arithmetic, the memo semantics, and the shape of
|
|
33
|
+
* the audit detail. *Not* shared here: how a candidate is obtained (the host's
|
|
34
|
+
* judge), how an original is retained (the host's sink, whose locator differs per
|
|
35
|
+
* host), how text is installed into a host content type, and how the operator-
|
|
36
|
+
* facing note is worded (that is a product decision per host).
|
|
37
|
+
*
|
|
38
|
+
* ## Why the port rather than callback arguments
|
|
39
|
+
*
|
|
40
|
+
* The DSH engine and the Claude hook disagree about nearly every *fact* and
|
|
41
|
+
* about none of the *rules*. A port keeps the rules in one file and lets each
|
|
42
|
+
* host answer only the questions it alone can answer. `HostPrunePort` is
|
|
43
|
+
* deliberately total: there is no optional method, so a host that cannot retain
|
|
44
|
+
* an original says so once, up front, instead of the shared layer guessing from
|
|
45
|
+
* an absent callback.
|
|
46
|
+
*
|
|
47
|
+
* @module core/orchestrate
|
|
48
|
+
*/
|
|
49
|
+
import type { HostDecisionPort, JudgmentState } from './orchestrate-host.js';
|
|
50
|
+
import { type TextBlockLike } from './text.js';
|
|
51
|
+
/** Line breaks a payload needs before it is treated as line-oriented output. */
|
|
52
|
+
export declare const PRUNE_MIN_LINES = 4;
|
|
53
|
+
/**
|
|
54
|
+
* Largest payload the shared layer is willing to see copied into a host log.
|
|
55
|
+
*
|
|
56
|
+
* Retention is what makes a reduction safe, so this is a *precondition* of
|
|
57
|
+
* pruning rather than a fallback: above it the decision reports
|
|
58
|
+
* `retention-too-large` and leaves the result untouched, so an oversized payload
|
|
59
|
+
* can never be reported as saved on the strength of a copy that was never kept.
|
|
60
|
+
*/
|
|
61
|
+
export declare const MAX_RETAINED_CHARS = 100000;
|
|
62
|
+
/** Characters of a reduction's explanatory note. */
|
|
63
|
+
export declare const PRUNE_FEEDBACK_CHARS = 600;
|
|
64
|
+
/** The floor options a reduction is composed with. */
|
|
65
|
+
export interface PruneFloorSettings {
|
|
66
|
+
/** Lowest share of the original a reduction may keep. */
|
|
67
|
+
readonly floorRatio: number;
|
|
68
|
+
/** Default split of the context budget, taken from the head. */
|
|
69
|
+
readonly headChars: number;
|
|
70
|
+
/** Default split of the context budget, taken from the tail. */
|
|
71
|
+
readonly tailChars: number;
|
|
72
|
+
}
|
|
73
|
+
/** The payload half of a prune decision's audit fields. */
|
|
74
|
+
export type PrunePayloadDetail = {
|
|
75
|
+
/** Payload identity, absent for an empty payload. */
|
|
76
|
+
readonly digest?: string;
|
|
77
|
+
/** Size of the payload the decision is about. */
|
|
78
|
+
readonly originalChars?: number;
|
|
79
|
+
};
|
|
80
|
+
/**
|
|
81
|
+
* The payload half of a prune decision's audit fields.
|
|
82
|
+
*
|
|
83
|
+
* Taken before the service is asked, so a branch that refuses the payload early
|
|
84
|
+
* still names the payload it refused.
|
|
85
|
+
* @param text - the effective text the decision is about.
|
|
86
|
+
* @returns the digest and size, or nothing for an empty payload.
|
|
87
|
+
*/
|
|
88
|
+
export declare function prunePayloadDetail(text: string): PrunePayloadDetail;
|
|
89
|
+
/** What the judged candidate reports about its own path. */
|
|
90
|
+
export interface PruneDiagnostics {
|
|
91
|
+
readonly judgePath?: 'segmented' | 'local' | 'fallback';
|
|
92
|
+
readonly judgedSegments?: number;
|
|
93
|
+
readonly unjudgedSegments?: number;
|
|
94
|
+
readonly keptSegments?: number;
|
|
95
|
+
readonly aggressiveChars?: number;
|
|
96
|
+
readonly balancedChars?: number;
|
|
97
|
+
readonly conservativeChars?: number;
|
|
98
|
+
readonly scoredSegments?: number;
|
|
99
|
+
readonly autoKeptSegments?: number;
|
|
100
|
+
readonly unparsedScoreAnswers?: number;
|
|
101
|
+
readonly fallbackReason?: string;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* The judgment half of a prune decision's audit fields.
|
|
105
|
+
*
|
|
106
|
+
* A pure pass-through of what the prune service computed, plus the two sizes
|
|
107
|
+
* every record quotes.
|
|
108
|
+
* @param response - the service's answer.
|
|
109
|
+
* @param originalTokens - tokens of the raw payload.
|
|
110
|
+
* @param candidateTokens - tokens of the composed candidate.
|
|
111
|
+
* @returns the diagnostics plus sizes.
|
|
112
|
+
*/
|
|
113
|
+
export declare function pruneDiagnosticsOf(response: PruneDiagnostics, originalTokens: number, candidateTokens: number): PruneDiagnostics & {
|
|
114
|
+
readonly originalTokens: number;
|
|
115
|
+
readonly candidateTokens: number;
|
|
116
|
+
};
|
|
117
|
+
/** One remembered reduction of one payload. */
|
|
118
|
+
export interface PruneMemoEntry {
|
|
119
|
+
/** The real reduction, absent until a mode computed it. */
|
|
120
|
+
readonly text?: string;
|
|
121
|
+
readonly originalChars: number;
|
|
122
|
+
readonly prunedChars: number;
|
|
123
|
+
readonly tokensSaved: number;
|
|
124
|
+
/** Whether the reduction was floored, so a memo hit reports the same plan. */
|
|
125
|
+
readonly floored: boolean;
|
|
126
|
+
/** Whether the reduction missed the floor's promised share, replayed on a hit. */
|
|
127
|
+
readonly floorMissed?: boolean;
|
|
128
|
+
/** Whether that miss installed without its locator marker, replayed on a hit. */
|
|
129
|
+
readonly markerOmitted?: boolean;
|
|
130
|
+
/** Locator of the retained original, once a retention for this payload succeeded. */
|
|
131
|
+
readonly locator?: string;
|
|
132
|
+
/** Diagnostics of the judgment that composed this form, replayed on a hit. */
|
|
133
|
+
readonly diagnostics?: PruneDiagnostics;
|
|
134
|
+
}
|
|
135
|
+
/** What the shared layer asks a host to retain before it replaces a payload. */
|
|
136
|
+
export interface PruneRetentionRequest {
|
|
137
|
+
/** Payload identity: `digestOf(text)`. */
|
|
138
|
+
readonly digest: string;
|
|
139
|
+
/** Identity of the call whose result is about to shrink. */
|
|
140
|
+
readonly callId: string;
|
|
141
|
+
/** Name of that call. */
|
|
142
|
+
readonly tool: string;
|
|
143
|
+
/** Turn and step of the replacement. */
|
|
144
|
+
readonly turn: number;
|
|
145
|
+
readonly step: number;
|
|
146
|
+
/** The replaced payload, verbatim. */
|
|
147
|
+
readonly text: string;
|
|
148
|
+
}
|
|
149
|
+
/** The controlled copy one retention produced. */
|
|
150
|
+
export interface PruneRetention {
|
|
151
|
+
/** Locator the replacement publishes. */
|
|
152
|
+
readonly locator: string;
|
|
153
|
+
/** Committed log position, when the sink can report one. */
|
|
154
|
+
readonly seq?: number;
|
|
155
|
+
}
|
|
156
|
+
/** The counters one reduction spends from, and where it is deciding. */
|
|
157
|
+
export type PruneState = JudgmentState;
|
|
158
|
+
/** A judged candidate, as the shared layer needs it. */
|
|
159
|
+
export interface PruneCandidate {
|
|
160
|
+
/** The candidate text the floor composes from. */
|
|
161
|
+
readonly processedOutput: string;
|
|
162
|
+
/** Reduction share the service reported, recorded as the plan's confidence. */
|
|
163
|
+
readonly reductionPercentage: number;
|
|
164
|
+
/** Whether the service withheld the text (measured but not returned). */
|
|
165
|
+
readonly shadow?: boolean;
|
|
166
|
+
/** Service latency, used to split local from remote time. */
|
|
167
|
+
readonly latencyMs: number;
|
|
168
|
+
/** Path diagnostics, recorded only. */
|
|
169
|
+
readonly diagnostics?: PruneDiagnostics;
|
|
170
|
+
}
|
|
171
|
+
/** The judgment cost of one decision. */
|
|
172
|
+
export interface PruneJudgmentCharge {
|
|
173
|
+
readonly judgments: number;
|
|
174
|
+
readonly memoHits: number;
|
|
175
|
+
readonly localLatencyMs: number;
|
|
176
|
+
readonly remoteLatencyMs: number;
|
|
177
|
+
readonly judgeTokens: number;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Everything the pruning decision cannot know by itself.
|
|
181
|
+
*
|
|
182
|
+
* {@link HostDecisionPort} answers the part every capability asks — policy,
|
|
183
|
+
* counters, billing channels — but this port departs from the base in two ways,
|
|
184
|
+
* and both are deliberate rather than pending:
|
|
185
|
+
*
|
|
186
|
+
* 1. **`skip` and `conclude` are wider here.** A pruning skip carries the
|
|
187
|
+
* payload diagnostics (`digest`, `floored`, the segment counts) that make
|
|
188
|
+
* "why was nothing pruned" answerable, and a pruning `conclude` carries the
|
|
189
|
+
* four size columns and the retained locator that make a saving verifiable.
|
|
190
|
+
* Narrowing either to the base signature would drop a field the audit trail
|
|
191
|
+
* is defined by, so this port overrides them with the wider shape.
|
|
192
|
+
* 2. **`now()` replaces `clock()`.** The pruning decision only ever needs one
|
|
193
|
+
* number, taken at hook entry; handing it a port for one reading would be a
|
|
194
|
+
* ceremony. The signature is structurally compatible with `ClockPort`, so a
|
|
195
|
+
* host can satisfy either reading from the same source.
|
|
196
|
+
*
|
|
197
|
+
* The rest — `serves()`, `budget()`, `chargeJudgment()` — keeps the base
|
|
198
|
+
* contract: `serves()` is answered from the effective mode, which this port
|
|
199
|
+
* already exposes as `mode()`.
|
|
200
|
+
*/
|
|
201
|
+
export interface HostPrunePort<Result> extends HostDecisionPort<PruneState> {
|
|
202
|
+
/** The effective mode of the `prune` capability. */
|
|
203
|
+
mode(): 'off' | 'observe' | 'active';
|
|
204
|
+
/** Whether the decision applies at all: the mode is not `off`. */
|
|
205
|
+
serves(): boolean;
|
|
206
|
+
/** Latest clock reading. Structurally the same reading `ClockPort` gives. */
|
|
207
|
+
now(): number;
|
|
208
|
+
/** Character count above which a payload is a pruning candidate. */
|
|
209
|
+
threshold(): number;
|
|
210
|
+
/** Floor settings in force. */
|
|
211
|
+
floor(): PruneFloorSettings;
|
|
212
|
+
/** The memo namespace of this agent's session. */
|
|
213
|
+
memoKey(): string;
|
|
214
|
+
/** One memoized reduction, refreshed on hit; `undefined` when not remembered. */
|
|
215
|
+
memoGet(key: string): PruneMemoEntry | undefined;
|
|
216
|
+
/** Remember one reduction. */
|
|
217
|
+
memoSet(key: string, entry: PruneMemoEntry): void;
|
|
218
|
+
/**
|
|
219
|
+
* The locator this host's sink *will* give a payload.
|
|
220
|
+
*
|
|
221
|
+
* The prediction exists so both modes account for the same form: the floor
|
|
222
|
+
* composes against a locator, and if the sink then names the copy differently
|
|
223
|
+
* the text has to be rebuilt and the plan no longer describes what is
|
|
224
|
+
* installed. Only the host knows its own naming scheme — DSH prefixes the
|
|
225
|
+
* plugin record type, the Claude store hashes into a path — so this is a host
|
|
226
|
+
* fact, not a shared rule.
|
|
227
|
+
*/
|
|
228
|
+
locatorOf(digest: string): string;
|
|
229
|
+
/** Ask the pruning service for a candidate. */
|
|
230
|
+
judge(text: string): Promise<PruneCandidate>;
|
|
231
|
+
/**
|
|
232
|
+
* Retain one original and prove the copy landed.
|
|
233
|
+
*
|
|
234
|
+
* Returns the locator of a *verifiable* copy, or `undefined` when nothing
|
|
235
|
+
* verifiable was written. A host without a sink returns a function that always
|
|
236
|
+
* answers `undefined`; the shared layer then reports `retention-unavailable`
|
|
237
|
+
* before it spends anything.
|
|
238
|
+
*/
|
|
239
|
+
retain(request: PruneRetentionRequest, session: unknown): PruneRetention | undefined;
|
|
240
|
+
/** Whether this host has a retention sink at all. */
|
|
241
|
+
hasRetention(): boolean;
|
|
242
|
+
/** The session a retention request belongs to, for a session-scoped sink. */
|
|
243
|
+
session(): unknown;
|
|
244
|
+
/**
|
|
245
|
+
* Install `text` into the host's effective content.
|
|
246
|
+
*
|
|
247
|
+
* @returns the replacement the host commits, or `undefined` when there is no
|
|
248
|
+
* text block to replace.
|
|
249
|
+
*/
|
|
250
|
+
install(text: string): Result | undefined;
|
|
251
|
+
/** Whether the effective content carries a text block at all. */
|
|
252
|
+
hasTextBlock(): boolean;
|
|
253
|
+
/** Word the operator-facing note of one reduction. */
|
|
254
|
+
describe(facts: PruneFeedbackFacts): string;
|
|
255
|
+
/**
|
|
256
|
+
* Count one abandoned plan by reason, with the diagnostic detail it carried.
|
|
257
|
+
*
|
|
258
|
+
* An abandoned plan that got far enough to have a candidate is charged by the
|
|
259
|
+
* host here (its judgment really ran); one refused before that is not charged
|
|
260
|
+
* at all, because nothing was bought.
|
|
261
|
+
*/
|
|
262
|
+
skip(reason: string, detail: Record<string, unknown>, judgment?: PruneJudgmentCharge): void;
|
|
263
|
+
/**
|
|
264
|
+
* Bill a judgment whose plan was abandoned after it was really made.
|
|
265
|
+
*
|
|
266
|
+
* A refusal before the service runs costs nothing and is never billed here. A
|
|
267
|
+
* refusal *after* it did spend the judgment, so hiding it would understate what
|
|
268
|
+
* the turn cost. `originalTokens` is the size the abandoned branch had already
|
|
269
|
+
* measured, or zero when it had measured nothing.
|
|
270
|
+
*/
|
|
271
|
+
chargeJudgment(judgment: PruneJudgmentCharge, originalTokens?: number): void;
|
|
272
|
+
/**
|
|
273
|
+
* Record one applied or observed plan, with the sizes it accounts for.
|
|
274
|
+
*
|
|
275
|
+
* This is the one place a plan is billed: `plans` +1, `applied` +1 when it
|
|
276
|
+
* really took effect, and every size column from `costs`.
|
|
277
|
+
*/
|
|
278
|
+
conclude(record: PrunePlanRecord, applied: boolean, costs: {
|
|
279
|
+
readonly originalTokens: number;
|
|
280
|
+
readonly candidateTokens: number;
|
|
281
|
+
readonly potentialSavedTokens: number;
|
|
282
|
+
readonly actualSavedTokens?: number;
|
|
283
|
+
}, judgment: PruneJudgmentCharge | undefined, originalLocator?: string): void;
|
|
284
|
+
/** Count one retained copy, once per payload per activation. */
|
|
285
|
+
noteRetained(locator: string): void;
|
|
286
|
+
/** The decision this reduction passes through when it does nothing. */
|
|
287
|
+
passThrough(): Result;
|
|
288
|
+
}
|
|
289
|
+
/** What one reduction installed, for the note. */
|
|
290
|
+
export interface PruneFeedbackFacts {
|
|
291
|
+
readonly tool: string;
|
|
292
|
+
readonly originalTokens: number;
|
|
293
|
+
readonly candidateTokens: number;
|
|
294
|
+
readonly floored: boolean;
|
|
295
|
+
readonly floorMissed: boolean;
|
|
296
|
+
readonly markerOmitted: boolean;
|
|
297
|
+
readonly locator: string;
|
|
298
|
+
readonly keptSegments?: number;
|
|
299
|
+
readonly judgedSegments?: number;
|
|
300
|
+
}
|
|
301
|
+
/** One planned reduction, as the host records it. */
|
|
302
|
+
export interface PrunePlanRecord {
|
|
303
|
+
readonly capability: 'prune';
|
|
304
|
+
readonly action: 'prune-result';
|
|
305
|
+
readonly reason: string;
|
|
306
|
+
feedback: string;
|
|
307
|
+
readonly detail: Record<string, unknown>;
|
|
308
|
+
}
|
|
309
|
+
/** The outcome of one orchestrated decision. */
|
|
310
|
+
export interface PruneOutcome<Result> {
|
|
311
|
+
/** What the host should return to its caller. */
|
|
312
|
+
readonly result: Result;
|
|
313
|
+
/** Whether a reduction was really installed. */
|
|
314
|
+
readonly applied: boolean;
|
|
315
|
+
/** The skip reason, when the decision refused to reduce. */
|
|
316
|
+
readonly skip?: string;
|
|
317
|
+
}
|
|
318
|
+
/**
|
|
319
|
+
* Run the one pruning decision.
|
|
320
|
+
*
|
|
321
|
+
* @param invocation - the call whose result is being considered, and the
|
|
322
|
+
* effective text of that result.
|
|
323
|
+
* @param port - everything that is the host's to answer.
|
|
324
|
+
* @returns the decision the host commits.
|
|
325
|
+
*/
|
|
326
|
+
export declare function orchestratePrune<Result>(invocation: {
|
|
327
|
+
readonly callId: string;
|
|
328
|
+
readonly tool: string;
|
|
329
|
+
/** The effective text of the result (downstream first). */
|
|
330
|
+
readonly text: string;
|
|
331
|
+
/** Whether the rest of the waterfall blocked the result outright. */
|
|
332
|
+
readonly blockedByDownstream: boolean;
|
|
333
|
+
/** Whether a value-shaped accept replaced the payload wholesale. */
|
|
334
|
+
readonly valueShapedAccept: boolean;
|
|
335
|
+
/** Clock reading at hook entry. */
|
|
336
|
+
readonly started: number;
|
|
337
|
+
}, port: HostPrunePort<Result>): Promise<PruneOutcome<Result>>;
|
|
338
|
+
/**
|
|
339
|
+
* Percentage of a payload a reduction kept.
|
|
340
|
+
* @param originalChars - size of the raw payload.
|
|
341
|
+
* @param prunedChars - size of the reduction.
|
|
342
|
+
* @returns the kept share, rounded to one decimal.
|
|
343
|
+
*/
|
|
344
|
+
export declare function reductionPercentageOf(originalChars: number, prunedChars: number): number;
|
|
345
|
+
/**
|
|
346
|
+
* The note of one reduction, in the default wording.
|
|
347
|
+
*
|
|
348
|
+
* It is meant for an operator, never for the model: a prune is supposed to remove
|
|
349
|
+
* context, so sending an explanation of the removal would work against the thing
|
|
350
|
+
* it accounts for. A host that shows it to a *person* may keep this wording
|
|
351
|
+
* verbatim; that is why it lives here next to the facts it is built from.
|
|
352
|
+
* @param facts - what the reduction did.
|
|
353
|
+
* @returns the note, bounded.
|
|
354
|
+
*/
|
|
355
|
+
export declare function describeReduction(facts: PruneFeedbackFacts): string;
|
|
356
|
+
/** Re-exported so a host can name the same content shape the core reads. */
|
|
357
|
+
export type { TextBlockLike };
|