pi-braid 0.0.0-stage → 0.40.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/AGENTS.md +195 -0
- package/CONTRIBUTING.md +302 -0
- package/LICENSE +21 -0
- package/README.md +260 -2
- package/TOOLS.md +147 -0
- package/dist/extensions/cognitive/mars-reflector/index.d.ts +82 -0
- package/dist/extensions/cognitive/mars-reflector/index.js +327 -0
- package/dist/extensions/cognitive/metacognition/handlers/claim-verification.d.ts +23 -0
- package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +233 -0
- package/dist/extensions/cognitive/metacognition/handlers/finalize.d.ts +27 -0
- package/dist/extensions/cognitive/metacognition/handlers/finalize.js +557 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +19 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +291 -0
- package/dist/extensions/cognitive/metacognition/handlers/scoring.d.ts +28 -0
- package/dist/extensions/cognitive/metacognition/handlers/scoring.js +173 -0
- package/dist/extensions/cognitive/metacognition/handlers/think-budget.d.ts +85 -0
- package/dist/extensions/cognitive/metacognition/handlers/think-budget.js +164 -0
- package/dist/extensions/cognitive/metacognition/handlers/think.d.ts +27 -0
- package/dist/extensions/cognitive/metacognition/handlers/think.js +374 -0
- package/dist/extensions/cognitive/metacognition/handlers/verify.d.ts +53 -0
- package/dist/extensions/cognitive/metacognition/handlers/verify.js +321 -0
- package/dist/extensions/cognitive/metacognition/index.d.ts +10 -0
- package/dist/extensions/cognitive/metacognition/index.js +90 -0
- package/dist/extensions/cognitive/reasoning/index.d.ts +43 -0
- package/dist/extensions/cognitive/reasoning/index.js +99 -0
- package/dist/extensions/cognitive/sycophancy-detector/index.d.ts +16 -0
- package/dist/extensions/cognitive/sycophancy-detector/index.js +203 -0
- package/dist/extensions/cognitive/topic-drift/index.d.ts +51 -0
- package/dist/extensions/cognitive/topic-drift/index.js +346 -0
- package/dist/extensions/cognitive/turn-outcome/index.d.ts +35 -0
- package/dist/extensions/cognitive/turn-outcome/index.js +163 -0
- package/dist/extensions/context-management/index.d.ts +77 -0
- package/dist/extensions/context-management/index.js +339 -0
- package/dist/extensions/core/agent-environment/index.d.ts +30 -0
- package/dist/extensions/core/agent-environment/index.js +89 -0
- package/dist/extensions/core/polyfill/index.d.ts +28 -0
- package/dist/extensions/core/polyfill/index.js +474 -0
- package/dist/extensions/core/prompt-builder/awareness-whisper.d.ts +74 -0
- package/dist/extensions/core/prompt-builder/awareness-whisper.js +116 -0
- package/dist/extensions/core/prompt-builder/context-section.d.ts +41 -0
- package/dist/extensions/core/prompt-builder/context-section.js +101 -0
- package/dist/extensions/core/prompt-builder/custom-sections.d.ts +21 -0
- package/dist/extensions/core/prompt-builder/custom-sections.js +11 -0
- package/dist/extensions/core/prompt-builder/external-tool-guidelines.d.ts +23 -0
- package/dist/extensions/core/prompt-builder/external-tool-guidelines.js +37 -0
- package/dist/extensions/core/prompt-builder/identity.d.ts +33 -0
- package/dist/extensions/core/prompt-builder/identity.js +77 -0
- package/dist/extensions/core/prompt-builder/index.d.ts +33 -0
- package/dist/extensions/core/prompt-builder/index.js +496 -0
- package/dist/extensions/core/prompt-builder/inspect.d.ts +58 -0
- package/dist/extensions/core/prompt-builder/inspect.js +182 -0
- package/dist/extensions/core/prompt-builder/instance-composition.d.ts +101 -0
- package/dist/extensions/core/prompt-builder/instance-composition.js +416 -0
- package/dist/extensions/core/prompt-builder/memory-section.d.ts +20 -0
- package/dist/extensions/core/prompt-builder/memory-section.js +60 -0
- package/dist/extensions/core/prompt-builder/pi-reference-section.d.ts +17 -0
- package/dist/extensions/core/prompt-builder/pi-reference-section.js +11 -0
- package/dist/extensions/core/prompt-builder/project-docs-section.d.ts +42 -0
- package/dist/extensions/core/prompt-builder/project-docs-section.js +72 -0
- package/dist/extensions/core/prompt-builder/section-parity.d.ts +36 -0
- package/dist/extensions/core/prompt-builder/section-parity.js +66 -0
- package/dist/extensions/core/prompt-builder/section-publish.d.ts +30 -0
- package/dist/extensions/core/prompt-builder/section-publish.js +16 -0
- package/dist/extensions/core/prompt-builder/section.d.ts +75 -0
- package/dist/extensions/core/prompt-builder/section.js +127 -0
- package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +18 -0
- package/dist/extensions/core/prompt-builder/surface-discipline-section.js +20 -0
- package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +27 -0
- package/dist/extensions/core/prompt-builder/system-info-tool.js +67 -0
- package/dist/extensions/core/prompt-builder/tool-description-trim.d.ts +56 -0
- package/dist/extensions/core/prompt-builder/tool-description-trim.js +129 -0
- package/dist/extensions/core/prompt-builder/tool-guidelines.d.ts +80 -0
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +179 -0
- package/dist/extensions/core/prompt-builder/tool-pipelines.d.ts +50 -0
- package/dist/extensions/core/prompt-builder/tool-pipelines.js +69 -0
- package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +44 -0
- package/dist/extensions/core/prompt-builder/top-level-extensions.js +300 -0
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +333 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +817 -0
- package/dist/extensions/core/skills-tool/index.d.ts +56 -0
- package/dist/extensions/core/skills-tool/index.js +200 -0
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +50 -0
- package/dist/extensions/core/skills-tool/loading-guidance.js +87 -0
- package/dist/extensions/core/skills-tool/session-records.d.ts +114 -0
- package/dist/extensions/core/skills-tool/session-records.js +268 -0
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +48 -0
- package/dist/extensions/core/skills-tool/skill-triggers.js +113 -0
- package/dist/extensions/enforcement/detection/malformed.d.ts +9 -0
- package/dist/extensions/enforcement/detection/malformed.js +30 -0
- package/dist/extensions/enforcement/detection/verification.d.ts +10 -0
- package/dist/extensions/enforcement/detection/verification.js +34 -0
- package/dist/extensions/enforcement/enforcement-types.d.ts +33 -0
- package/dist/extensions/enforcement/enforcement-types.js +24 -0
- package/dist/extensions/enforcement/handler-registry.d.ts +12 -0
- package/dist/extensions/enforcement/handler-registry.js +196 -0
- package/dist/extensions/enforcement/handlers/analysis/bpe-handler.d.ts +10 -0
- package/dist/extensions/enforcement/handlers/analysis/bpe-handler.js +37 -0
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +60 -0
- package/dist/extensions/enforcement/handlers/analysis/drift-handler.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/analysis/drift-handler.js +75 -0
- package/dist/extensions/enforcement/handlers/analysis/feedback-handler.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/analysis/feedback-handler.js +19 -0
- package/dist/extensions/enforcement/handlers/analysis/mars-handler.d.ts +14 -0
- package/dist/extensions/enforcement/handlers/analysis/mars-handler.js +99 -0
- package/dist/extensions/enforcement/handlers/analysis/reflection-handler.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/analysis/reflection-handler.js +16 -0
- package/dist/extensions/enforcement/handlers/blocking.d.ts +16 -0
- package/dist/extensions/enforcement/handlers/blocking.js +33 -0
- package/dist/extensions/enforcement/handlers/message-analysis.d.ts +25 -0
- package/dist/extensions/enforcement/handlers/message-analysis.js +70 -0
- package/dist/extensions/enforcement/handlers/orphan-chains.d.ts +14 -0
- package/dist/extensions/enforcement/handlers/orphan-chains.js +44 -0
- package/dist/extensions/enforcement/handlers/over-correction-gate.d.ts +73 -0
- package/dist/extensions/enforcement/handlers/over-correction-gate.js +565 -0
- package/dist/extensions/enforcement/handlers/probe-handler.d.ts +31 -0
- package/dist/extensions/enforcement/handlers/probe-handler.js +111 -0
- package/dist/extensions/enforcement/handlers/register-adherence-meter.d.ts +52 -0
- package/dist/extensions/enforcement/handlers/register-adherence-meter.js +158 -0
- package/dist/extensions/enforcement/handlers/register-agent-end-api-error.d.ts +3 -0
- package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +69 -0
- package/dist/extensions/enforcement/handlers/register-input-handler.d.ts +10 -0
- package/dist/extensions/enforcement/handlers/register-input-handler.js +35 -0
- package/dist/extensions/enforcement/handlers/register-message-end.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/register-message-end.js +388 -0
- package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.d.ts +25 -0
- package/dist/extensions/enforcement/handlers/register-post-cycle-hygiene.js +143 -0
- package/dist/extensions/enforcement/handlers/register-session-compact.d.ts +50 -0
- package/dist/extensions/enforcement/handlers/register-session-compact.js +207 -0
- package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.d.ts +21 -0
- package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +116 -0
- package/dist/extensions/enforcement/handlers/register-session-shutdown.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/register-session-shutdown.js +38 -0
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +34 -0
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +240 -0
- package/dist/extensions/enforcement/handlers/register-session-start.d.ts +16 -0
- package/dist/extensions/enforcement/handlers/register-session-start.js +198 -0
- package/dist/extensions/enforcement/handlers/register-tool-call.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/register-tool-call.js +132 -0
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +18 -0
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +56 -0
- package/dist/extensions/enforcement/handlers/register-tool-result.d.ts +6 -0
- package/dist/extensions/enforcement/handlers/register-tool-result.js +91 -0
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +35 -0
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +385 -0
- package/dist/extensions/enforcement/handlers/routing-handler.d.ts +42 -0
- package/dist/extensions/enforcement/handlers/routing-handler.js +135 -0
- package/dist/extensions/enforcement/handlers/tool-tracker.d.ts +9 -0
- package/dist/extensions/enforcement/handlers/tool-tracker.js +122 -0
- package/dist/extensions/enforcement/handlers/turn-analysis.d.ts +41 -0
- package/dist/extensions/enforcement/handlers/turn-analysis.js +109 -0
- package/dist/extensions/enforcement/handlers/turn-end-handler.d.ts +9 -0
- package/dist/extensions/enforcement/handlers/turn-end-handler.js +451 -0
- package/dist/extensions/enforcement/index.d.ts +15 -0
- package/dist/extensions/enforcement/index.js +22 -0
- package/dist/extensions/enforcement/judge-utils.d.ts +73 -0
- package/dist/extensions/enforcement/judge-utils.js +83 -0
- package/dist/extensions/enforcement/nudge-manager.d.ts +106 -0
- package/dist/extensions/enforcement/nudge-manager.js +203 -0
- package/dist/extensions/enforcement/self-state-claims.d.ts +79 -0
- package/dist/extensions/enforcement/self-state-claims.js +167 -0
- package/dist/extensions/enforcement/session-health.d.ts +107 -0
- package/dist/extensions/enforcement/session-health.js +251 -0
- package/dist/extensions/enforcement/signals.d.ts +54 -0
- package/dist/extensions/enforcement/signals.js +47 -0
- package/dist/extensions/enforcement/similarity.d.ts +16 -0
- package/dist/extensions/enforcement/similarity.js +64 -0
- package/dist/extensions/enforcement/state.d.ts +40 -0
- package/dist/extensions/enforcement/state.js +74 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +88 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.js +119 -0
- package/dist/extensions/enforcement/substate/error-tracking-state.d.ts +20 -0
- package/dist/extensions/enforcement/substate/error-tracking-state.js +37 -0
- package/dist/extensions/enforcement/substate/memory-hygiene-state.d.ts +24 -0
- package/dist/extensions/enforcement/substate/memory-hygiene-state.js +37 -0
- package/dist/extensions/enforcement/substate/session-state.d.ts +34 -0
- package/dist/extensions/enforcement/substate/session-state.js +45 -0
- package/dist/extensions/enforcement/substate/thought-chain-state.d.ts +23 -0
- package/dist/extensions/enforcement/substate/thought-chain-state.js +43 -0
- package/dist/extensions/enforcement/substate/tool-tracking-state.d.ts +71 -0
- package/dist/extensions/enforcement/substate/tool-tracking-state.js +99 -0
- package/dist/extensions/enforcement/substate/verification-judge-state.d.ts +17 -0
- package/dist/extensions/enforcement/substate/verification-judge-state.js +39 -0
- package/dist/extensions/enforcement/task-evidence.d.ts +108 -0
- package/dist/extensions/enforcement/task-evidence.js +335 -0
- package/dist/extensions/enforcement/types.d.ts +35 -0
- package/dist/extensions/enforcement/types.js +5 -0
- package/dist/extensions/enforcement/validation.d.ts +12 -0
- package/dist/extensions/enforcement/validation.js +151 -0
- package/dist/extensions/enforcement/verification-judge.d.ts +110 -0
- package/dist/extensions/enforcement/verification-judge.js +214 -0
- package/dist/extensions/enforcement/whisper.d.ts +46 -0
- package/dist/extensions/enforcement/whisper.js +104 -0
- package/dist/extensions/heartbeat/analytics/ab-variant.d.ts +19 -0
- package/dist/extensions/heartbeat/analytics/ab-variant.js +86 -0
- package/dist/extensions/heartbeat/analytics/core.d.ts +12 -0
- package/dist/extensions/heartbeat/analytics/core.js +201 -0
- package/dist/extensions/heartbeat/analytics/format.d.ts +7 -0
- package/dist/extensions/heartbeat/analytics/format.js +111 -0
- package/dist/extensions/heartbeat/analytics/index.d.ts +14 -0
- package/dist/extensions/heartbeat/analytics/index.js +352 -0
- package/dist/extensions/heartbeat/analytics/shared.d.ts +85 -0
- package/dist/extensions/heartbeat/analytics/shared.js +69 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +31 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +881 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.d.ts +10 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/meta-learning.js +49 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.d.ts +17 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.js +161 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.d.ts +13 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/budget.js +101 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.d.ts +10 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.js +221 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.d.ts +9 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/evolver.js +65 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.d.ts +8 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/measurement.js +32 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.d.ts +9 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/recaller.js +75 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.d.ts +9 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.js +98 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +14 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +149 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/state.d.ts +22 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/state.js +82 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/types.d.ts +124 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/types.js +7 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +52 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +83 -0
- package/dist/extensions/manifest.d.ts +32 -0
- package/dist/extensions/manifest.js +251 -0
- package/dist/extensions/memory/context-lifecycle/helpers.d.ts +55 -0
- package/dist/extensions/memory/context-lifecycle/helpers.js +142 -0
- package/dist/extensions/memory/context-lifecycle/index.d.ts +17 -0
- package/dist/extensions/memory/context-lifecycle/index.js +977 -0
- package/dist/extensions/memory/context-lifecycle/policy-engine.d.ts +50 -0
- package/dist/extensions/memory/context-lifecycle/policy-engine.js +196 -0
- package/dist/extensions/memory/context-lifecycle/signal-detector.d.ts +28 -0
- package/dist/extensions/memory/context-lifecycle/signal-detector.js +224 -0
- package/dist/extensions/memory/context-lifecycle/state.d.ts +98 -0
- package/dist/extensions/memory/context-lifecycle/state.js +90 -0
- package/dist/extensions/memory/context-lifecycle/types.d.ts +132 -0
- package/dist/extensions/memory/context-lifecycle/types.js +273 -0
- package/dist/extensions/memory/context-manager/analysis.d.ts +47 -0
- package/dist/extensions/memory/context-manager/analysis.js +264 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-chunked.d.ts +159 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-chunked.js +658 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-retry.d.ts +29 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +410 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-trace.d.ts +74 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-trace.js +180 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.d.ts +69 -0
- package/dist/extensions/memory/context-manager/handlers/compaction-watchdog.js +297 -0
- package/dist/extensions/memory/context-manager/handlers/compaction.d.ts +37 -0
- package/dist/extensions/memory/context-manager/handlers/compaction.js +2150 -0
- package/dist/extensions/memory/context-manager/handlers/context-emergency.d.ts +124 -0
- package/dist/extensions/memory/context-manager/handlers/context-emergency.js +364 -0
- package/dist/extensions/memory/context-manager/handlers/events.d.ts +5 -0
- package/dist/extensions/memory/context-manager/handlers/events.js +314 -0
- package/dist/extensions/memory/context-manager/handlers/navigation.d.ts +5 -0
- package/dist/extensions/memory/context-manager/handlers/navigation.js +86 -0
- package/dist/extensions/memory/context-manager/handlers/offload.d.ts +94 -0
- package/dist/extensions/memory/context-manager/handlers/offload.js +248 -0
- package/dist/extensions/memory/context-manager/handlers/rotation.d.ts +6 -0
- package/dist/extensions/memory/context-manager/handlers/rotation.js +304 -0
- package/dist/extensions/memory/context-manager/handlers/shared.d.ts +410 -0
- package/dist/extensions/memory/context-manager/handlers/shared.js +579 -0
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +55 -0
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +190 -0
- package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.d.ts +21 -0
- package/dist/extensions/memory/context-manager/handlers/toolresult-capture-cap.js +155 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +90 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +1156 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.d.ts +16 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +276 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.d.ts +19 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +378 -0
- package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.d.ts +13 -0
- package/dist/extensions/memory/context-manager/handlers/tools/offload-recover.js +181 -0
- package/dist/extensions/memory/context-manager/index.d.ts +3 -0
- package/dist/extensions/memory/context-manager/index.js +88 -0
- package/dist/extensions/memory/context-manager/pruning.d.ts +47 -0
- package/dist/extensions/memory/context-manager/pruning.js +406 -0
- package/dist/extensions/memory/context-manager/semantic-compress.d.ts +71 -0
- package/dist/extensions/memory/context-manager/semantic-compress.js +279 -0
- package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.d.ts +20 -0
- package/dist/extensions/memory/memory-agent-bridge/conflict-qa-tool.js +71 -0
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +30 -0
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +231 -0
- package/dist/extensions/memory/memory-agent-bridge/index.d.ts +28 -0
- package/dist/extensions/memory/memory-agent-bridge/index.js +124 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.d.ts +21 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +194 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-tool.d.ts +22 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +548 -0
- package/dist/extensions/memory/scratchpad/format.d.ts +19 -0
- package/dist/extensions/memory/scratchpad/format.js +135 -0
- package/dist/extensions/memory/scratchpad/handlers.d.ts +53 -0
- package/dist/extensions/memory/scratchpad/handlers.js +469 -0
- package/dist/extensions/memory/scratchpad/index.d.ts +17 -0
- package/dist/extensions/memory/scratchpad/index.js +168 -0
- package/dist/extensions/memory/scratchpad/persistence.d.ts +46 -0
- package/dist/extensions/memory/scratchpad/persistence.js +343 -0
- package/dist/extensions/memory/scratchpad/types.d.ts +124 -0
- package/dist/extensions/memory/scratchpad/types.js +8 -0
- package/dist/extensions/memory/scratchpad/utils.d.ts +76 -0
- package/dist/extensions/memory/scratchpad/utils.js +236 -0
- package/dist/extensions/memory/session-recall/analyze.d.ts +58 -0
- package/dist/extensions/memory/session-recall/analyze.js +478 -0
- package/dist/extensions/memory/session-recall/context-aggregate.d.ts +117 -0
- package/dist/extensions/memory/session-recall/context-aggregate.js +315 -0
- package/dist/extensions/memory/session-recall/index.d.ts +29 -0
- package/dist/extensions/memory/session-recall/index.js +820 -0
- package/dist/extensions/memory/session-recall/query.d.ts +15 -0
- package/dist/extensions/memory/session-recall/query.js +38 -0
- package/dist/extensions/memory/session-recall/rank.d.ts +71 -0
- package/dist/extensions/memory/session-recall/rank.js +85 -0
- package/dist/extensions/memory/session-recall/search.d.ts +159 -0
- package/dist/extensions/memory/session-recall/search.js +682 -0
- package/dist/extensions/memory/session-recall/stats.d.ts +34 -0
- package/dist/extensions/memory/session-recall/stats.js +67 -0
- package/dist/extensions/memory/session-recall/text-utils.d.ts +82 -0
- package/dist/extensions/memory/session-recall/text-utils.js +184 -0
- package/dist/extensions/memory/three-memory-stores/episodes-disk.d.ts +43 -0
- package/dist/extensions/memory/three-memory-stores/episodes-disk.js +125 -0
- package/dist/extensions/memory/three-memory-stores/episodes.d.ts +46 -0
- package/dist/extensions/memory/three-memory-stores/episodes.js +299 -0
- package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.d.ts +25 -0
- package/dist/extensions/memory/three-memory-stores/handlers/whisper-recall.js +112 -0
- package/dist/extensions/memory/three-memory-stores/heuristics.d.ts +19 -0
- package/dist/extensions/memory/three-memory-stores/heuristics.js +89 -0
- package/dist/extensions/memory/three-memory-stores/index.d.ts +34 -0
- package/dist/extensions/memory/three-memory-stores/index.js +436 -0
- package/dist/extensions/memory/three-memory-stores/tool-reliability.d.ts +11 -0
- package/dist/extensions/memory/three-memory-stores/tool-reliability.js +38 -0
- package/dist/extensions/memory/three-memory-stores/types.d.ts +69 -0
- package/dist/extensions/memory/three-memory-stores/types.js +2 -0
- package/dist/extensions/memory/workspace-snapshot/index.d.ts +19 -0
- package/dist/extensions/memory/workspace-snapshot/index.js +363 -0
- package/dist/extensions/orchestrator/index.d.ts +19 -0
- package/dist/extensions/orchestrator/index.js +796 -0
- package/dist/extensions/scheduling/timer/fire-timing.d.ts +25 -0
- package/dist/extensions/scheduling/timer/fire-timing.js +28 -0
- package/dist/extensions/scheduling/timer/index.d.ts +102 -0
- package/dist/extensions/scheduling/timer/index.js +1143 -0
- package/dist/extensions/scheduling/timer/poller.d.ts +52 -0
- package/dist/extensions/scheduling/timer/poller.js +135 -0
- package/dist/extensions/scheduling/timer/recovery.d.ts +145 -0
- package/dist/extensions/scheduling/timer/recovery.js +445 -0
- package/dist/extensions/scheduling/timer/store-file.d.ts +38 -0
- package/dist/extensions/scheduling/timer/store-file.js +59 -0
- package/dist/extensions/scheduling/timer/timer-manager.d.ts +21 -0
- package/dist/extensions/scheduling/timer/timer-manager.js +143 -0
- package/dist/extensions/scheduling/timer/wake-retry.d.ts +455 -0
- package/dist/extensions/scheduling/timer/wake-retry.js +872 -0
- package/dist/extensions/self/auto-recovery/index.d.ts +20 -0
- package/dist/extensions/self/auto-recovery/index.js +89 -0
- package/dist/extensions/self/error-tracking/index.d.ts +3 -0
- package/dist/extensions/self/error-tracking/index.js +244 -0
- package/dist/extensions/self/health-maintenance/format.d.ts +3 -0
- package/dist/extensions/self/health-maintenance/format.js +60 -0
- package/dist/extensions/self/health-maintenance/handlers/session-health-tool.d.ts +23 -0
- package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +158 -0
- package/dist/extensions/self/health-maintenance/helpers.d.ts +25 -0
- package/dist/extensions/self/health-maintenance/helpers.js +67 -0
- package/dist/extensions/self/health-maintenance/index.d.ts +6 -0
- package/dist/extensions/self/health-maintenance/index.js +238 -0
- package/dist/extensions/self/health-maintenance/types.d.ts +14 -0
- package/dist/extensions/self/health-maintenance/types.js +2 -0
- package/dist/extensions/self/latent-activator/index.d.ts +12 -0
- package/dist/extensions/self/latent-activator/index.js +173 -0
- package/dist/extensions/self/latent-activator/mixes.d.ts +9 -0
- package/dist/extensions/self/latent-activator/mixes.js +20 -0
- package/dist/extensions/self/latent-activator/signals.d.ts +17 -0
- package/dist/extensions/self/latent-activator/signals.js +228 -0
- package/dist/extensions/self/latent-activator/state.d.ts +43 -0
- package/dist/extensions/self/latent-activator/state.js +59 -0
- package/dist/extensions/self/latent-activator/types.d.ts +8 -0
- package/dist/extensions/self/latent-activator/types.js +8 -0
- package/dist/extensions/self/watchdog/config.d.ts +4 -0
- package/dist/extensions/self/watchdog/config.js +79 -0
- package/dist/extensions/self/watchdog/engine.d.ts +256 -0
- package/dist/extensions/self/watchdog/engine.js +935 -0
- package/dist/extensions/self/watchdog/index.d.ts +23 -0
- package/dist/extensions/self/watchdog/index.js +485 -0
- package/dist/index.d.ts +25 -0
- package/dist/index.js +81 -0
- package/dist/lib/ai/consolidated-claim-critic.d.ts +84 -0
- package/dist/lib/ai/consolidated-claim-critic.js +191 -0
- package/dist/lib/ai/cost-report.d.ts +83 -0
- package/dist/lib/ai/cost-report.js +116 -0
- package/dist/lib/ai/critic-cache.d.ts +57 -0
- package/dist/lib/ai/critic-cache.js +100 -0
- package/dist/lib/ai/critic-fallbacks.d.ts +37 -0
- package/dist/lib/ai/critic-fallbacks.js +75 -0
- package/dist/lib/ai/critic-gate.d.ts +75 -0
- package/dist/lib/ai/critic-gate.js +81 -0
- package/dist/lib/ai/critic-helpers.d.ts +26 -0
- package/dist/lib/ai/critic-helpers.js +131 -0
- package/dist/lib/ai/critic-registry.d.ts +417 -0
- package/dist/lib/ai/critic-registry.js +639 -0
- package/dist/lib/ai/critic-stats.d.ts +78 -0
- package/dist/lib/ai/critic-stats.js +90 -0
- package/dist/lib/ai/judge-budget.d.ts +138 -0
- package/dist/lib/ai/judge-budget.js +143 -0
- package/dist/lib/ai/language-hint.d.ts +21 -0
- package/dist/lib/ai/language-hint.js +58 -0
- package/dist/lib/ai/llm-call.d.ts +141 -0
- package/dist/lib/ai/llm-call.js +745 -0
- package/dist/lib/ai/model-resolver.d.ts +90 -0
- package/dist/lib/ai/model-resolver.js +185 -0
- package/dist/lib/ai/models-init.d.ts +46 -0
- package/dist/lib/ai/models-init.js +65 -0
- package/dist/lib/ai/payload-hygiene.d.ts +74 -0
- package/dist/lib/ai/payload-hygiene.js +240 -0
- package/dist/lib/ai/post-loop-classify.d.ts +128 -0
- package/dist/lib/ai/post-loop-classify.js +87 -0
- package/dist/lib/ai/text-classifier.d.ts +142 -0
- package/dist/lib/ai/text-classifier.js +548 -0
- package/dist/lib/cognitive/hints.d.ts +33 -0
- package/dist/lib/cognitive/hints.js +223 -0
- package/dist/lib/cognitive/openspec.d.ts +29 -0
- package/dist/lib/cognitive/openspec.js +108 -0
- package/dist/lib/config/braid-paths.d.ts +188 -0
- package/dist/lib/config/braid-paths.js +340 -0
- package/dist/lib/config/braid-settings.d.ts +489 -0
- package/dist/lib/config/braid-settings.js +938 -0
- package/dist/lib/config/per-tool-settings.d.ts +95 -0
- package/dist/lib/config/per-tool-settings.js +161 -0
- package/dist/lib/config/session-profiles.d.ts +68 -0
- package/dist/lib/config/session-profiles.js +143 -0
- package/dist/lib/constants/injection-details.d.ts +30 -0
- package/dist/lib/constants/injection-details.js +30 -0
- package/dist/lib/constants/session-thresholds.d.ts +42 -0
- package/dist/lib/constants/session-thresholds.js +54 -0
- package/dist/lib/constants/tool-constants.d.ts +11 -0
- package/dist/lib/constants/tool-constants.js +12 -0
- package/dist/lib/core/event-names.d.ts +23 -0
- package/dist/lib/core/event-names.js +26 -0
- package/dist/lib/core/logger.d.ts +102 -0
- package/dist/lib/core/logger.js +274 -0
- package/dist/lib/detection/compression-strategy.d.ts +38 -0
- package/dist/lib/detection/compression-strategy.js +147 -0
- package/dist/lib/detection/consolidated-topic-critic.d.ts +51 -0
- package/dist/lib/detection/consolidated-topic-critic.js +132 -0
- package/dist/lib/detection/context-density.d.ts +70 -0
- package/dist/lib/detection/context-density.js +193 -0
- package/dist/lib/detection/context-thresholds.d.ts +88 -0
- package/dist/lib/detection/context-thresholds.js +107 -0
- package/dist/lib/detection/context-tiers.d.ts +80 -0
- package/dist/lib/detection/context-tiers.js +144 -0
- package/dist/lib/detection/context-usage.d.ts +75 -0
- package/dist/lib/detection/context-usage.js +209 -0
- package/dist/lib/detection/degradation-detector.d.ts +74 -0
- package/dist/lib/detection/degradation-detector.js +454 -0
- package/dist/lib/detection/test-burst.d.ts +77 -0
- package/dist/lib/detection/test-burst.js +126 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +125 -0
- package/dist/lib/detection/tool-loop-detector.js +302 -0
- package/dist/lib/detection/topic-drift-detector.d.ts +80 -0
- package/dist/lib/detection/topic-drift-detector.js +252 -0
- package/dist/lib/enforcement/adherence-meter.d.ts +240 -0
- package/dist/lib/enforcement/adherence-meter.js +420 -0
- package/dist/lib/enforcement/turn-dedup.d.ts +106 -0
- package/dist/lib/enforcement/turn-dedup.js +195 -0
- package/dist/lib/errors/llm-error.d.ts +79 -0
- package/dist/lib/errors/llm-error.js +241 -0
- package/dist/lib/events/consolidation-channel.d.ts +109 -0
- package/dist/lib/events/consolidation-channel.js +374 -0
- package/dist/lib/events/consolidation-scoring.d.ts +59 -0
- package/dist/lib/events/consolidation-scoring.js +95 -0
- package/dist/lib/events/event-bus.d.ts +123 -0
- package/dist/lib/events/event-bus.js +108 -0
- package/dist/lib/events/event-types.d.ts +39 -0
- package/dist/lib/events/event-types.js +30 -0
- package/dist/lib/events/timer-bus.d.ts +21 -0
- package/dist/lib/events/timer-bus.js +41 -0
- package/dist/lib/events/timer-types.d.ts +64 -0
- package/dist/lib/events/timer-types.js +8 -0
- package/dist/lib/events/turn-end-coordinator.d.ts +52 -0
- package/dist/lib/events/turn-end-coordinator.js +89 -0
- package/dist/lib/harness/failure-trace-collector.d.ts +31 -0
- package/dist/lib/harness/failure-trace-collector.js +114 -0
- package/dist/lib/harness/index.d.ts +20 -0
- package/dist/lib/harness/index.js +21 -0
- package/dist/lib/harness/types.d.ts +85 -0
- package/dist/lib/harness/types.js +20 -0
- package/dist/lib/harness/weakness-miner.d.ts +29 -0
- package/dist/lib/harness/weakness-miner.js +165 -0
- package/dist/lib/memory/constants.d.ts +11 -0
- package/dist/lib/memory/constants.js +29 -0
- package/dist/lib/memory/index.d.ts +147 -0
- package/dist/lib/memory/index.js +564 -0
- package/dist/lib/memory/lifecycle.d.ts +50 -0
- package/dist/lib/memory/lifecycle.js +139 -0
- package/dist/lib/memory/past-insights.d.ts +35 -0
- package/dist/lib/memory/past-insights.js +189 -0
- package/dist/lib/memory/storage.d.ts +38 -0
- package/dist/lib/memory/storage.js +167 -0
- package/dist/lib/memory/store-lock.d.ts +23 -0
- package/dist/lib/memory/store-lock.js +69 -0
- package/dist/lib/memory/store-merge.d.ts +38 -0
- package/dist/lib/memory/store-merge.js +73 -0
- package/dist/lib/memory/types.d.ts +65 -0
- package/dist/lib/memory/types.js +5 -0
- package/dist/lib/memory/utils.d.ts +35 -0
- package/dist/lib/memory/utils.js +156 -0
- package/dist/lib/memory/write-log.d.ts +85 -0
- package/dist/lib/memory/write-log.js +124 -0
- package/dist/lib/memory/write-quality.d.ts +197 -0
- package/dist/lib/memory/write-quality.js +314 -0
- package/dist/lib/orchestrator/branch.d.ts +63 -0
- package/dist/lib/orchestrator/branch.js +192 -0
- package/dist/lib/orchestrator/index.d.ts +14 -0
- package/dist/lib/orchestrator/index.js +11 -0
- package/dist/lib/orchestrator/locks.d.ts +46 -0
- package/dist/lib/orchestrator/locks.js +122 -0
- package/dist/lib/orchestrator/slop-scanner.d.ts +31 -0
- package/dist/lib/orchestrator/slop-scanner.js +207 -0
- package/dist/lib/orchestrator/workers.d.ts +453 -0
- package/dist/lib/orchestrator/workers.js +1001 -0
- package/dist/lib/public.d.ts +18 -0
- package/dist/lib/public.js +23 -0
- package/dist/lib/reasoning/advice-tracker.d.ts +51 -0
- package/dist/lib/reasoning/advice-tracker.js +177 -0
- package/dist/lib/reasoning/belief-policy-engine.d.ts +48 -0
- package/dist/lib/reasoning/belief-policy-engine.js +268 -0
- package/dist/lib/reasoning/belief-types.d.ts +32 -0
- package/dist/lib/reasoning/belief-types.js +8 -0
- package/dist/lib/reasoning/classifier-offline.d.ts +72 -0
- package/dist/lib/reasoning/classifier-offline.js +75 -0
- package/dist/lib/reasoning/dreamer.d.ts +37 -0
- package/dist/lib/reasoning/dreamer.js +169 -0
- package/dist/lib/reasoning/nudge-analytics.d.ts +18 -0
- package/dist/lib/reasoning/nudge-analytics.js +62 -0
- package/dist/lib/reasoning/policy-rules.d.ts +18 -0
- package/dist/lib/reasoning/policy-rules.js +153 -0
- package/dist/lib/reasoning/reasoning-metrics.d.ts +42 -0
- package/dist/lib/reasoning/reasoning-metrics.js +174 -0
- package/dist/lib/reasoning/reasoning-summary.d.ts +34 -0
- package/dist/lib/reasoning/reasoning-summary.js +122 -0
- package/dist/lib/reasoning/tool-usage-analyzer.d.ts +50 -0
- package/dist/lib/reasoning/tool-usage-analyzer.js +188 -0
- package/dist/lib/state/async-storage.d.ts +52 -0
- package/dist/lib/state/async-storage.js +171 -0
- package/dist/lib/state/extension-state.d.ts +184 -0
- package/dist/lib/state/extension-state.js +373 -0
- package/dist/lib/state/global-state.d.ts +358 -0
- package/dist/lib/state/global-state.js +741 -0
- package/dist/lib/state/metacognitive-state.d.ts +21 -0
- package/dist/lib/state/metacognitive-state.js +50 -0
- package/dist/lib/state/session-manager.d.ts +32 -0
- package/dist/lib/state/session-manager.js +11 -0
- package/dist/lib/state/session-start-queue.d.ts +42 -0
- package/dist/lib/state/session-start-queue.js +105 -0
- package/dist/lib/state/state-checkpoint.d.ts +72 -0
- package/dist/lib/state/state-checkpoint.js +252 -0
- package/dist/lib/state/telegram-poller-liveness.d.ts +54 -0
- package/dist/lib/state/telegram-poller-liveness.js +67 -0
- package/dist/lib/state/tool-provenance.d.ts +22 -0
- package/dist/lib/state/tool-provenance.js +25 -0
- package/dist/lib/state/workspace-snapshot.d.ts +111 -0
- package/dist/lib/state/workspace-snapshot.js +372 -0
- package/dist/lib/store/belief-store.d.ts +112 -0
- package/dist/lib/store/belief-store.js +252 -0
- package/dist/lib/store/bidirectional-verifier.d.ts +87 -0
- package/dist/lib/store/bidirectional-verifier.js +242 -0
- package/dist/lib/store/claim-tracker.d.ts +66 -0
- package/dist/lib/store/claim-tracker.js +276 -0
- package/dist/lib/store/conflict-qa.d.ts +96 -0
- package/dist/lib/store/conflict-qa.js +283 -0
- package/dist/lib/store/evidence-pool.d.ts +185 -0
- package/dist/lib/store/evidence-pool.js +598 -0
- package/dist/lib/telemetry/context-heartbeat.d.ts +122 -0
- package/dist/lib/telemetry/context-heartbeat.js +449 -0
- package/dist/lib/telemetry/drift-signals.d.ts +46 -0
- package/dist/lib/telemetry/drift-signals.js +75 -0
- package/dist/lib/telemetry/rss-telemetry.d.ts +41 -0
- package/dist/lib/telemetry/rss-telemetry.js +53 -0
- package/dist/lib/types/episode-types.d.ts +31 -0
- package/dist/lib/types/episode-types.js +9 -0
- package/dist/lib/types/standard-result.d.ts +32 -0
- package/dist/lib/types/standard-result.js +22 -0
- package/dist/lib/utils/async-fs.d.ts +17 -0
- package/dist/lib/utils/async-fs.js +22 -0
- package/dist/lib/utils/bounded.d.ts +38 -0
- package/dist/lib/utils/bounded.js +59 -0
- package/dist/lib/utils/dedup.d.ts +40 -0
- package/dist/lib/utils/dedup.js +43 -0
- package/dist/lib/utils/error-guard.d.ts +15 -0
- package/dist/lib/utils/error-guard.js +22 -0
- package/dist/lib/utils/extension-utils.d.ts +36 -0
- package/dist/lib/utils/extension-utils.js +65 -0
- package/dist/lib/utils/extract-json.d.ts +23 -0
- package/dist/lib/utils/extract-json.js +90 -0
- package/dist/lib/utils/file-mutation-queue.d.ts +33 -0
- package/dist/lib/utils/file-mutation-queue.js +150 -0
- package/dist/lib/utils/filter-safe-to-remove.d.ts +26 -0
- package/dist/lib/utils/filter-safe-to-remove.js +256 -0
- package/dist/lib/utils/format-tool-result.d.ts +47 -0
- package/dist/lib/utils/format-tool-result.js +88 -0
- package/dist/lib/utils/id.d.ts +44 -0
- package/dist/lib/utils/id.js +59 -0
- package/dist/lib/utils/injection-tracker.d.ts +317 -0
- package/dist/lib/utils/injection-tracker.js +840 -0
- package/dist/lib/utils/local-time.d.ts +57 -0
- package/dist/lib/utils/local-time.js +181 -0
- package/dist/lib/utils/memory-fence.d.ts +55 -0
- package/dist/lib/utils/memory-fence.js +66 -0
- package/dist/lib/utils/sop-extractor.d.ts +75 -0
- package/dist/lib/utils/sop-extractor.js +259 -0
- package/dist/lib/utils/sop-suggestion.d.ts +34 -0
- package/dist/lib/utils/sop-suggestion.js +336 -0
- package/dist/lib/utils/wake-gate.d.ts +151 -0
- package/dist/lib/utils/wake-gate.js +265 -0
- package/dist/lib/utils/whisper-format.d.ts +95 -0
- package/dist/lib/utils/whisper-format.js +115 -0
- package/dist/lib/verification/coordination-checker.d.ts +72 -0
- package/dist/lib/verification/coordination-checker.js +126 -0
- package/dist/loader/api.d.ts +19 -0
- package/dist/loader/api.js +114 -0
- package/dist/loader/loader.d.ts +85 -0
- package/dist/loader/loader.js +534 -0
- package/docs/BEGINNERS.md +144 -0
- package/docs/COMPACTION-LOSS-INVESTIGATION.md +179 -0
- package/docs/CONTEXT-MAP.md +220 -0
- package/docs/CONTEXT-POLICY.md +86 -0
- package/docs/HISTORY.md +110 -0
- package/docs/LOCAL_DEV.md +246 -0
- package/docs/ROADMAP.md +107 -0
- package/docs/SETUP.md +459 -0
- package/package.json +97 -4
- package/skills/agent-testing/SKILL.md +214 -0
- package/skills/braid-reference/SKILL.md +88 -0
- package/skills/code-refactoring/SKILL.md +211 -0
- package/skills/code-search/SKILL.md +14 -0
- package/skills/documentation/SKILL.md +89 -0
- package/skills/dox/AGENTS.md.template +83 -0
- package/skills/dox/SKILL.md +86 -0
- package/skills/healthcheck/SKILL.md +65 -0
- package/skills/herdr-topology/SKILL.md +269 -0
- package/skills/meta-cognition/SKILL.md +24 -0
- package/skills/meta-improvement/SKILL.md +180 -0
- package/skills/misdirection-audit/SKILL.md +66 -0
- package/skills/pi-reference/SKILL.md +104 -0
- package/skills/placement-discipline/SKILL.md +69 -0
- package/skills/probe-evaluation/SKILL.md +85 -0
- package/skills/release-pipeline/SKILL.md +191 -0
- package/skills/research/SKILL.md +166 -0
- package/skills/skill-usage/SKILL.md +81 -0
- package/skills/software-engineer/SKILL.md +83 -0
- package/skills/subagent-orchestration/SKILL.md +454 -0
- package/skills/subagent-orchestration/scripts/workers.mjs +283 -0
- package/skills/subagent-verification/SKILL.md +127 -0
- package/skills/tone-quality/SKILL.md +176 -0
- package/skills/voice-replies/SKILL.md +125 -0
- package/src/AGENTS.md +111 -0
- package/src/extensions/cognitive/AGENTS.md +29 -0
- package/src/extensions/cognitive/mars-reflector/index.ts +415 -0
- package/src/extensions/cognitive/metacognition/handlers/AGENTS.md +30 -0
- package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +295 -0
- package/src/extensions/cognitive/metacognition/handlers/finalize.ts +648 -0
- package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +368 -0
- package/src/extensions/cognitive/metacognition/handlers/scoring.ts +242 -0
- package/src/extensions/cognitive/metacognition/handlers/think-budget.ts +199 -0
- package/src/extensions/cognitive/metacognition/handlers/think.ts +489 -0
- package/src/extensions/cognitive/metacognition/handlers/verify.ts +440 -0
- package/src/extensions/cognitive/metacognition/index.ts +109 -0
- package/src/extensions/cognitive/reasoning/index.ts +168 -0
- package/src/extensions/cognitive/sycophancy-detector/index.ts +286 -0
- package/src/extensions/cognitive/topic-drift/index.ts +429 -0
- package/src/extensions/cognitive/turn-outcome/index.ts +209 -0
- package/src/extensions/context-management/README.md +102 -0
- package/src/extensions/context-management/index.ts +383 -0
- package/src/extensions/core/AGENTS.md +34 -0
- package/src/extensions/core/agent-environment/index.ts +135 -0
- package/src/extensions/core/polyfill/index.ts +617 -0
- package/src/extensions/core/prompt-builder/AGENTS.md +151 -0
- package/src/extensions/core/prompt-builder/awareness-whisper.ts +162 -0
- package/src/extensions/core/prompt-builder/context-section.ts +120 -0
- package/src/extensions/core/prompt-builder/custom-sections.ts +27 -0
- package/src/extensions/core/prompt-builder/external-tool-guidelines.ts +41 -0
- package/src/extensions/core/prompt-builder/identity.ts +98 -0
- package/src/extensions/core/prompt-builder/index.ts +602 -0
- package/src/extensions/core/prompt-builder/inspect.ts +227 -0
- package/src/extensions/core/prompt-builder/instance-composition.ts +515 -0
- package/src/extensions/core/prompt-builder/memory-section.ts +76 -0
- package/src/extensions/core/prompt-builder/pi-reference-section.ts +26 -0
- package/src/extensions/core/prompt-builder/project-docs-section.ts +105 -0
- package/src/extensions/core/prompt-builder/section-parity.ts +108 -0
- package/src/extensions/core/prompt-builder/section-publish.ts +43 -0
- package/src/extensions/core/prompt-builder/section.ts +150 -0
- package/src/extensions/core/prompt-builder/surface-discipline-section.ts +21 -0
- package/src/extensions/core/prompt-builder/system-info-tool.ts +87 -0
- package/src/extensions/core/prompt-builder/tool-description-trim.ts +127 -0
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +226 -0
- package/src/extensions/core/prompt-builder/tool-pipelines.ts +78 -0
- package/src/extensions/core/prompt-builder/top-level-extensions.ts +338 -0
- package/src/extensions/core/skills-tool/auto-inject.ts +1004 -0
- package/src/extensions/core/skills-tool/index.ts +240 -0
- package/src/extensions/core/skills-tool/loading-guidance.ts +89 -0
- package/src/extensions/core/skills-tool/session-records.ts +328 -0
- package/src/extensions/core/skills-tool/skill-triggers.ts +119 -0
- package/src/extensions/enforcement/AGENTS.md +69 -0
- package/src/extensions/enforcement/detection/malformed.ts +42 -0
- package/src/extensions/enforcement/detection/verification.ts +52 -0
- package/src/extensions/enforcement/enforcement-types.ts +42 -0
- package/src/extensions/enforcement/handler-registry.ts +225 -0
- package/src/extensions/enforcement/handlers/AGENTS.md +68 -0
- package/src/extensions/enforcement/handlers/analysis/AGENTS.md +40 -0
- package/src/extensions/enforcement/handlers/analysis/bpe-handler.ts +53 -0
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +73 -0
- package/src/extensions/enforcement/handlers/analysis/drift-handler.ts +100 -0
- package/src/extensions/enforcement/handlers/analysis/feedback-handler.ts +22 -0
- package/src/extensions/enforcement/handlers/analysis/mars-handler.ts +121 -0
- package/src/extensions/enforcement/handlers/analysis/reflection-handler.ts +22 -0
- package/src/extensions/enforcement/handlers/blocking.ts +50 -0
- package/src/extensions/enforcement/handlers/message-analysis.ts +95 -0
- package/src/extensions/enforcement/handlers/orphan-chains.ts +53 -0
- package/src/extensions/enforcement/handlers/over-correction-gate.ts +634 -0
- package/src/extensions/enforcement/handlers/probe-handler.ts +133 -0
- package/src/extensions/enforcement/handlers/register-adherence-meter.ts +216 -0
- package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +82 -0
- package/src/extensions/enforcement/handlers/register-input-handler.ts +36 -0
- package/src/extensions/enforcement/handlers/register-message-end.ts +477 -0
- package/src/extensions/enforcement/handlers/register-post-cycle-hygiene.ts +166 -0
- package/src/extensions/enforcement/handlers/register-session-compact.ts +248 -0
- package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +138 -0
- package/src/extensions/enforcement/handlers/register-session-shutdown.ts +46 -0
- package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +270 -0
- package/src/extensions/enforcement/handlers/register-session-start.ts +240 -0
- package/src/extensions/enforcement/handlers/register-tool-call.ts +160 -0
- package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +73 -0
- package/src/extensions/enforcement/handlers/register-tool-result.ts +108 -0
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +456 -0
- package/src/extensions/enforcement/handlers/routing-handler.ts +191 -0
- package/src/extensions/enforcement/handlers/tool-tracker.ts +145 -0
- package/src/extensions/enforcement/handlers/turn-analysis.ts +156 -0
- package/src/extensions/enforcement/handlers/turn-end-handler.ts +538 -0
- package/src/extensions/enforcement/index.ts +28 -0
- package/src/extensions/enforcement/judge-utils.ts +106 -0
- package/src/extensions/enforcement/nudge-manager.ts +298 -0
- package/src/extensions/enforcement/self-state-claims.ts +204 -0
- package/src/extensions/enforcement/session-health.ts +317 -0
- package/src/extensions/enforcement/signals.ts +88 -0
- package/src/extensions/enforcement/similarity.ts +76 -0
- package/src/extensions/enforcement/state.ts +115 -0
- package/src/extensions/enforcement/substate/context-hygiene-state.ts +212 -0
- package/src/extensions/enforcement/substate/error-tracking-state.ts +50 -0
- package/src/extensions/enforcement/substate/memory-hygiene-state.ts +54 -0
- package/src/extensions/enforcement/substate/session-state.ts +79 -0
- package/src/extensions/enforcement/substate/thought-chain-state.ts +62 -0
- package/src/extensions/enforcement/substate/tool-tracking-state.ts +166 -0
- package/src/extensions/enforcement/substate/verification-judge-state.ts +52 -0
- package/src/extensions/enforcement/task-evidence.ts +436 -0
- package/src/extensions/enforcement/types.ts +38 -0
- package/src/extensions/enforcement/validation.ts +194 -0
- package/src/extensions/enforcement/verification-judge.ts +317 -0
- package/src/extensions/enforcement/whisper.ts +120 -0
- package/src/extensions/heartbeat/AGENTS.md +47 -0
- package/src/extensions/heartbeat/analytics/AGENTS.md +57 -0
- package/src/extensions/heartbeat/analytics/ab-variant.ts +106 -0
- package/src/extensions/heartbeat/analytics/core.ts +222 -0
- package/src/extensions/heartbeat/analytics/format.ts +144 -0
- package/src/extensions/heartbeat/analytics/index.ts +373 -0
- package/src/extensions/heartbeat/analytics/shared.ts +149 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +84 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +1095 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/meta-learning.ts +75 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/modules/behavioral-drift.ts +200 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/modules/budget.ts +113 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/modules/context-hygiene.ts +288 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/modules/evolver.ts +88 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/modules/measurement.ts +47 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/modules/recaller.ts +99 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/modules/reflection-consolidator.ts +114 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +193 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/state.ts +88 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/types.ts +128 -0
- package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +98 -0
- package/src/extensions/manifest.ts +293 -0
- package/src/extensions/memory/AGENTS.md +93 -0
- package/src/extensions/memory/context-lifecycle/AGENTS.md +62 -0
- package/src/extensions/memory/context-lifecycle/helpers.ts +167 -0
- package/src/extensions/memory/context-lifecycle/index.ts +1232 -0
- package/src/extensions/memory/context-lifecycle/policy-engine.ts +287 -0
- package/src/extensions/memory/context-lifecycle/signal-detector.ts +293 -0
- package/src/extensions/memory/context-lifecycle/state.ts +165 -0
- package/src/extensions/memory/context-lifecycle/types.ts +441 -0
- package/src/extensions/memory/context-manager/analysis.ts +344 -0
- package/src/extensions/memory/context-manager/handlers/AGENTS.md +37 -0
- package/src/extensions/memory/context-manager/handlers/compaction-chunked.ts +800 -0
- package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +556 -0
- package/src/extensions/memory/context-manager/handlers/compaction-trace.ts +243 -0
- package/src/extensions/memory/context-manager/handlers/compaction-watchdog.ts +366 -0
- package/src/extensions/memory/context-manager/handlers/compaction.ts +2552 -0
- package/src/extensions/memory/context-manager/handlers/context-emergency.ts +470 -0
- package/src/extensions/memory/context-manager/handlers/events.ts +430 -0
- package/src/extensions/memory/context-manager/handlers/navigation.ts +94 -0
- package/src/extensions/memory/context-manager/handlers/offload.ts +330 -0
- package/src/extensions/memory/context-manager/handlers/rotation.ts +363 -0
- package/src/extensions/memory/context-manager/handlers/shared.ts +961 -0
- package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +219 -0
- package/src/extensions/memory/context-manager/handlers/toolresult-capture-cap.ts +176 -0
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +1333 -0
- package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +343 -0
- package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +423 -0
- package/src/extensions/memory/context-manager/handlers/tools/offload-recover.ts +234 -0
- package/src/extensions/memory/context-manager/index.ts +111 -0
- package/src/extensions/memory/context-manager/pruning.ts +479 -0
- package/src/extensions/memory/context-manager/semantic-compress.ts +321 -0
- package/src/extensions/memory/memory-agent-bridge/AGENTS.md +62 -0
- package/src/extensions/memory/memory-agent-bridge/conflict-qa-tool.ts +106 -0
- package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +283 -0
- package/src/extensions/memory/memory-agent-bridge/index.ts +163 -0
- package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +284 -0
- package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +746 -0
- package/src/extensions/memory/scratchpad/AGENTS.md +148 -0
- package/src/extensions/memory/scratchpad/format.ts +161 -0
- package/src/extensions/memory/scratchpad/handlers.ts +601 -0
- package/src/extensions/memory/scratchpad/index.ts +230 -0
- package/src/extensions/memory/scratchpad/persistence.ts +374 -0
- package/src/extensions/memory/scratchpad/types.ts +149 -0
- package/src/extensions/memory/scratchpad/utils.ts +268 -0
- package/src/extensions/memory/session-recall/AGENTS.md +104 -0
- package/src/extensions/memory/session-recall/analyze.ts +605 -0
- package/src/extensions/memory/session-recall/context-aggregate.ts +381 -0
- package/src/extensions/memory/session-recall/index.ts +956 -0
- package/src/extensions/memory/session-recall/query.ts +44 -0
- package/src/extensions/memory/session-recall/rank.ts +121 -0
- package/src/extensions/memory/session-recall/search.ts +801 -0
- package/src/extensions/memory/session-recall/stats.ts +93 -0
- package/src/extensions/memory/session-recall/text-utils.ts +209 -0
- package/src/extensions/memory/three-memory-stores/AGENTS.md +66 -0
- package/src/extensions/memory/three-memory-stores/episodes-disk.ts +138 -0
- package/src/extensions/memory/three-memory-stores/episodes.ts +371 -0
- package/src/extensions/memory/three-memory-stores/handlers/whisper-recall.ts +132 -0
- package/src/extensions/memory/three-memory-stores/heuristics.ts +109 -0
- package/src/extensions/memory/three-memory-stores/index.ts +549 -0
- package/src/extensions/memory/three-memory-stores/tool-reliability.ts +58 -0
- package/src/extensions/memory/three-memory-stores/types.ts +74 -0
- package/src/extensions/memory/workspace-snapshot/AGENTS.md +19 -0
- package/src/extensions/memory/workspace-snapshot/index.ts +455 -0
- package/src/extensions/orchestrator/index.ts +1141 -0
- package/src/extensions/scheduling/AGENTS.md +26 -0
- package/src/extensions/scheduling/timer/AGENTS.md +259 -0
- package/src/extensions/scheduling/timer/fire-timing.ts +46 -0
- package/src/extensions/scheduling/timer/index.ts +1331 -0
- package/src/extensions/scheduling/timer/poller.ts +138 -0
- package/src/extensions/scheduling/timer/recovery.ts +462 -0
- package/src/extensions/scheduling/timer/store-file.ts +59 -0
- package/src/extensions/scheduling/timer/timer-manager.ts +161 -0
- package/src/extensions/scheduling/timer/wake-retry.ts +1057 -0
- package/src/extensions/self/AGENTS.md +30 -0
- package/src/extensions/self/auto-recovery/index.ts +112 -0
- package/src/extensions/self/error-tracking/AGENTS.md +38 -0
- package/src/extensions/self/error-tracking/index.ts +299 -0
- package/src/extensions/self/health-maintenance/AGENTS.md +42 -0
- package/src/extensions/self/health-maintenance/format.ts +87 -0
- package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +182 -0
- package/src/extensions/self/health-maintenance/helpers.ts +78 -0
- package/src/extensions/self/health-maintenance/index.ts +308 -0
- package/src/extensions/self/health-maintenance/types.ts +14 -0
- package/src/extensions/self/latent-activator/AGENTS.md +64 -0
- package/src/extensions/self/latent-activator/index.ts +206 -0
- package/src/extensions/self/latent-activator/mixes.ts +22 -0
- package/src/extensions/self/latent-activator/signals.ts +237 -0
- package/src/extensions/self/latent-activator/state.ts +79 -0
- package/src/extensions/self/latent-activator/types.ts +47 -0
- package/src/extensions/self/watchdog/AGENTS.md +27 -0
- package/src/extensions/self/watchdog/config.ts +73 -0
- package/src/extensions/self/watchdog/engine.ts +1246 -0
- package/src/extensions/self/watchdog/index.ts +577 -0
- package/src/index.ts +93 -0
- package/src/lib/AGENTS.md +39 -0
- package/src/lib/ai/AGENTS.md +37 -0
- package/src/lib/ai/consolidated-claim-critic.ts +287 -0
- package/src/lib/ai/cost-report.ts +206 -0
- package/src/lib/ai/critic-cache.ts +122 -0
- package/src/lib/ai/critic-fallbacks.ts +74 -0
- package/src/lib/ai/critic-gate.ts +135 -0
- package/src/lib/ai/critic-helpers.ts +135 -0
- package/src/lib/ai/critic-registry.ts +754 -0
- package/src/lib/ai/critic-stats.ts +158 -0
- package/src/lib/ai/judge-budget.ts +241 -0
- package/src/lib/ai/language-hint.ts +70 -0
- package/src/lib/ai/llm-call.ts +975 -0
- package/src/lib/ai/model-resolver.ts +224 -0
- package/src/lib/ai/models-init.ts +68 -0
- package/src/lib/ai/payload-hygiene.ts +265 -0
- package/src/lib/ai/post-loop-classify.ts +185 -0
- package/src/lib/ai/text-classifier.ts +746 -0
- package/src/lib/cognitive/AGENTS.md +40 -0
- package/src/lib/cognitive/hints.ts +254 -0
- package/src/lib/cognitive/openspec.ts +124 -0
- package/src/lib/config/AGENTS.md +17 -0
- package/src/lib/config/braid-paths.ts +401 -0
- package/src/lib/config/braid-settings.ts +1442 -0
- package/src/lib/config/per-tool-settings.ts +197 -0
- package/src/lib/config/session-profiles.ts +165 -0
- package/src/lib/constants/AGENTS.md +15 -0
- package/src/lib/constants/injection-details.ts +32 -0
- package/src/lib/constants/session-thresholds.ts +64 -0
- package/src/lib/constants/tool-constants.ts +16 -0
- package/src/lib/core/AGENTS.md +23 -0
- package/src/lib/core/event-names.ts +31 -0
- package/src/lib/core/logger.ts +334 -0
- package/src/lib/detection/AGENTS.md +21 -0
- package/src/lib/detection/compression-strategy.ts +183 -0
- package/src/lib/detection/consolidated-topic-critic.ts +188 -0
- package/src/lib/detection/context-density.ts +237 -0
- package/src/lib/detection/context-thresholds.ts +132 -0
- package/src/lib/detection/context-tiers.ts +201 -0
- package/src/lib/detection/context-usage.ts +270 -0
- package/src/lib/detection/degradation-detector.ts +583 -0
- package/src/lib/detection/test-burst.ts +170 -0
- package/src/lib/detection/tool-loop-detector.ts +364 -0
- package/src/lib/detection/topic-drift-detector.ts +323 -0
- package/src/lib/enforcement/AGENTS.md +20 -0
- package/src/lib/enforcement/adherence-meter.ts +578 -0
- package/src/lib/enforcement/turn-dedup.ts +246 -0
- package/src/lib/errors/llm-error.ts +288 -0
- package/src/lib/events/AGENTS.md +23 -0
- package/src/lib/events/consolidation-channel.ts +493 -0
- package/src/lib/events/consolidation-scoring.ts +112 -0
- package/src/lib/events/event-bus.ts +213 -0
- package/src/lib/events/event-types.ts +53 -0
- package/src/lib/events/timer-bus.ts +53 -0
- package/src/lib/events/timer-types.ts +64 -0
- package/src/lib/events/turn-end-coordinator.ts +108 -0
- package/src/lib/harness/AGENTS.md +20 -0
- package/src/lib/harness/failure-trace-collector.ts +157 -0
- package/src/lib/harness/index.ts +41 -0
- package/src/lib/harness/types.ts +122 -0
- package/src/lib/harness/weakness-miner.ts +209 -0
- package/src/lib/memory/AGENTS.md +36 -0
- package/src/lib/memory/constants.ts +34 -0
- package/src/lib/memory/index.ts +705 -0
- package/src/lib/memory/lifecycle.ts +159 -0
- package/src/lib/memory/past-insights.ts +221 -0
- package/src/lib/memory/storage.ts +187 -0
- package/src/lib/memory/store-lock.ts +70 -0
- package/src/lib/memory/store-merge.ts +100 -0
- package/src/lib/memory/types.ts +82 -0
- package/src/lib/memory/utils.ts +173 -0
- package/src/lib/memory/write-log.ts +174 -0
- package/src/lib/memory/write-quality.ts +383 -0
- package/src/lib/orchestrator/branch.ts +193 -0
- package/src/lib/orchestrator/index.ts +78 -0
- package/src/lib/orchestrator/locks.ts +160 -0
- package/src/lib/orchestrator/slop-scanner.ts +258 -0
- package/src/lib/orchestrator/workers.ts +1382 -0
- package/src/lib/public.ts +43 -0
- package/src/lib/reasoning/AGENTS.md +25 -0
- package/src/lib/reasoning/advice-tracker.ts +244 -0
- package/src/lib/reasoning/belief-policy-engine.ts +342 -0
- package/src/lib/reasoning/belief-types.ts +45 -0
- package/src/lib/reasoning/classifier-offline.ts +111 -0
- package/src/lib/reasoning/dreamer.ts +215 -0
- package/src/lib/reasoning/nudge-analytics.ts +85 -0
- package/src/lib/reasoning/policy-rules.ts +172 -0
- package/src/lib/reasoning/reasoning-metrics.ts +202 -0
- package/src/lib/reasoning/reasoning-summary.ts +154 -0
- package/src/lib/reasoning/tool-usage-analyzer.ts +248 -0
- package/src/lib/state/AGENTS.md +192 -0
- package/src/lib/state/async-storage.ts +189 -0
- package/src/lib/state/extension-state.ts +419 -0
- package/src/lib/state/global-state.ts +1046 -0
- package/src/lib/state/metacognitive-state.ts +65 -0
- package/src/lib/state/session-manager.ts +43 -0
- package/src/lib/state/session-start-queue.ts +135 -0
- package/src/lib/state/state-checkpoint.ts +352 -0
- package/src/lib/state/telegram-poller-liveness.ts +75 -0
- package/src/lib/state/tool-provenance.ts +26 -0
- package/src/lib/state/workspace-snapshot.ts +466 -0
- package/src/lib/store/AGENTS.md +24 -0
- package/src/lib/store/belief-store.ts +325 -0
- package/src/lib/store/bidirectional-verifier.ts +316 -0
- package/src/lib/store/claim-tracker.ts +382 -0
- package/src/lib/store/conflict-qa.ts +385 -0
- package/src/lib/store/evidence-pool.ts +779 -0
- package/src/lib/telemetry/AGENTS.md +28 -0
- package/src/lib/telemetry/context-heartbeat.ts +555 -0
- package/src/lib/telemetry/drift-signals.ts +105 -0
- package/src/lib/telemetry/rss-telemetry.ts +57 -0
- package/src/lib/types/AGENTS.md +21 -0
- package/src/lib/types/episode-types.ts +31 -0
- package/src/lib/types/standard-result.ts +40 -0
- package/src/lib/utils/AGENTS.md +30 -0
- package/src/lib/utils/async-fs.ts +23 -0
- package/src/lib/utils/bounded.ts +58 -0
- package/src/lib/utils/dedup.ts +44 -0
- package/src/lib/utils/error-guard.ts +27 -0
- package/src/lib/utils/extension-utils.ts +72 -0
- package/src/lib/utils/extract-json.ts +89 -0
- package/src/lib/utils/file-mutation-queue.ts +172 -0
- package/src/lib/utils/filter-safe-to-remove.ts +301 -0
- package/src/lib/utils/format-tool-result.ts +109 -0
- package/src/lib/utils/id.ts +64 -0
- package/src/lib/utils/injection-tracker.ts +1014 -0
- package/src/lib/utils/local-time.ts +196 -0
- package/src/lib/utils/memory-fence.ts +70 -0
- package/src/lib/utils/sop-extractor.ts +329 -0
- package/src/lib/utils/sop-suggestion.ts +426 -0
- package/src/lib/utils/wake-gate.ts +318 -0
- package/src/lib/utils/whisper-format.ts +120 -0
- package/src/lib/verification/coordination-checker.ts +183 -0
- package/src/loader/AGENTS.md +32 -0
- package/src/loader/api.ts +138 -0
- package/src/loader/loader.ts +600 -0
- package/src/types/extension-context.d.ts +85 -0
|
@@ -0,0 +1,1382 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Worker registry for multi-agent orchestration.
|
|
3
|
+
*
|
|
4
|
+
* Admission, lifecycle, and result-location records for agent workers.
|
|
5
|
+
* The parent registers a worker before spawning it, updates the handle as
|
|
6
|
+
* pane/session facts arrive, and closes the entry with an outcome and gate
|
|
7
|
+
* evidence. `checkWorker` computes a verdict from evidence (output file,
|
|
8
|
+
* session growth, branch commits, result schema) — never from the worker's
|
|
9
|
+
* own claim alone.
|
|
10
|
+
*
|
|
11
|
+
* Registry file location: ~/.pi/agent/braid/projects/<sanitized-cwd>/workers.json
|
|
12
|
+
* (per-CWD, beside locks.json, shared across all agents on the same project).
|
|
13
|
+
*
|
|
14
|
+
* A terminal completion is also judged for effect evidence — a deliverable
|
|
15
|
+
* written during the run, a branch advance or recorded merge, or a gate that
|
|
16
|
+
* exited 0. A completed close with none of the three is flagged, not refused:
|
|
17
|
+
* the flag travels on the close result and the check verdict.
|
|
18
|
+
*
|
|
19
|
+
* Writes are atomic (temp file + rename) with mode 0600. Reads tolerate a
|
|
20
|
+
* missing or corrupt file by returning an empty registry, like locks.ts.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
import {
|
|
24
|
+
chmodSync,
|
|
25
|
+
existsSync,
|
|
26
|
+
mkdirSync,
|
|
27
|
+
readFileSync,
|
|
28
|
+
readdirSync,
|
|
29
|
+
renameSync,
|
|
30
|
+
rmSync,
|
|
31
|
+
statSync,
|
|
32
|
+
writeFileSync,
|
|
33
|
+
} from "node:fs";
|
|
34
|
+
import { execFileSync } from "node:child_process";
|
|
35
|
+
import { dirname, join } from "node:path";
|
|
36
|
+
import { getWorkersFilePath, projectsDir } from "../config/braid-paths.js";
|
|
37
|
+
import { getAllLocks, releaseLock } from "./locks.js";
|
|
38
|
+
|
|
39
|
+
// ── Types ──────────────────────────────────────────────────────────────────
|
|
40
|
+
|
|
41
|
+
export type WorkerStatus =
|
|
42
|
+
| "admitted"
|
|
43
|
+
| "working"
|
|
44
|
+
| "merged"
|
|
45
|
+
| "completed"
|
|
46
|
+
| "error"
|
|
47
|
+
| "stalled"
|
|
48
|
+
| "false-done"
|
|
49
|
+
| "closed";
|
|
50
|
+
|
|
51
|
+
/** Terminal outcomes accepted by closeWorker. */
|
|
52
|
+
export type WorkerOutcome = "completed" | "error" | "stalled" | "false-done" | "closed";
|
|
53
|
+
|
|
54
|
+
export interface WorkerGate {
|
|
55
|
+
cmd: string;
|
|
56
|
+
exit: number;
|
|
57
|
+
at: string;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** One duplicate admission a live entry turned away, and the request it refused. */
|
|
61
|
+
export interface WorkerAdmissionRefusal {
|
|
62
|
+
/** The request id whose admission this entry refused. */
|
|
63
|
+
requestId: string;
|
|
64
|
+
/** When the refusal was recorded. */
|
|
65
|
+
at: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Checkpoint fields a caller supplies. The registry stamps `at`, so a writer
|
|
70
|
+
* cannot backdate a resume point.
|
|
71
|
+
*/
|
|
72
|
+
export interface WorkerCheckpointInput {
|
|
73
|
+
/** Lifecycle phase the worker is in (e.g. "impl", "gates"). */
|
|
74
|
+
phase: string;
|
|
75
|
+
/** Last completed step within that phase (e.g. "commit", "typecheck"). */
|
|
76
|
+
step: string;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export interface WorkerCheckpoint extends WorkerCheckpointInput {
|
|
80
|
+
/** When the checkpoint was written. */
|
|
81
|
+
at: string;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export interface WorkerEntry {
|
|
85
|
+
workerId: string;
|
|
86
|
+
spec: string;
|
|
87
|
+
status: WorkerStatus;
|
|
88
|
+
cwd: string;
|
|
89
|
+
pane: string | null;
|
|
90
|
+
workspace: string | null;
|
|
91
|
+
workerSession: string | null;
|
|
92
|
+
outputFile: string | null;
|
|
93
|
+
branch: string | null;
|
|
94
|
+
files: string[];
|
|
95
|
+
spawnedAt: string;
|
|
96
|
+
lastSeenAt: string | null;
|
|
97
|
+
resultAt: string | null;
|
|
98
|
+
/** Base tip this worker's work merges into; null until a merge lands. */
|
|
99
|
+
mergeSha: string | null;
|
|
100
|
+
/** When that merge landed. */
|
|
101
|
+
mergedAt: string | null;
|
|
102
|
+
closedAt: string | null;
|
|
103
|
+
gates: WorkerGate[];
|
|
104
|
+
/**
|
|
105
|
+
* Duplicate admissions this row turned away while it was live: each records
|
|
106
|
+
* the request id that was refused and when. Summed for the fleet's refusal
|
|
107
|
+
* count, so the number is registry fact rather than an inference.
|
|
108
|
+
*/
|
|
109
|
+
admissionRefusals: WorkerAdmissionRefusal[];
|
|
110
|
+
/**
|
|
111
|
+
* Exactly-once identity of the unit of work this entry admits, keyed by
|
|
112
|
+
* `(workerId, step)` — see deriveRequestId. Null on a row admitted before
|
|
113
|
+
* request ids existed, and no request ever matches such a row.
|
|
114
|
+
*/
|
|
115
|
+
requestId: string | null;
|
|
116
|
+
/**
|
|
117
|
+
* Where the work stood when the entry was last written: the phase and the
|
|
118
|
+
* last step completed in it. Null when the worker never recorded one, which
|
|
119
|
+
* leaves the row with no resume point.
|
|
120
|
+
*/
|
|
121
|
+
checkpoint: WorkerCheckpoint | null;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
export interface WorkerRegistry {
|
|
125
|
+
version: number;
|
|
126
|
+
workers: Record<string, WorkerEntry>;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
export interface RegisterWorkerInput {
|
|
130
|
+
workerId: string;
|
|
131
|
+
spec: string;
|
|
132
|
+
cwd: string;
|
|
133
|
+
files?: string[];
|
|
134
|
+
branch?: string;
|
|
135
|
+
outputFile?: string;
|
|
136
|
+
/**
|
|
137
|
+
* Worker handle, when the caller already has it at admission time. Absent
|
|
138
|
+
* stays null: a handle is never invented, and a pane is a place to look, not
|
|
139
|
+
* evidence that anything runs there.
|
|
140
|
+
*/
|
|
141
|
+
pane?: string;
|
|
142
|
+
/** Path to the worker's session .jsonl; the only liveness evidence the
|
|
143
|
+
* registry holds, read as file mtime by evaluateWorker. */
|
|
144
|
+
workerSession?: string;
|
|
145
|
+
/**
|
|
146
|
+
* Exactly-once request id for this submission. Defaults to the derived
|
|
147
|
+
* `(workerId, step)` key for step 1, so a retried admission of the same work
|
|
148
|
+
* resolves to the same request and reuses the entry it already admitted.
|
|
149
|
+
*/
|
|
150
|
+
requestId?: string;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
export interface RegisterWorkerResult {
|
|
154
|
+
ok: boolean;
|
|
155
|
+
entry?: WorkerEntry;
|
|
156
|
+
reason?: string;
|
|
157
|
+
/** True when a live entry already admitted this request and was reused. */
|
|
158
|
+
reused?: boolean;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
export interface UpdateWorkerPatch {
|
|
162
|
+
pane?: string;
|
|
163
|
+
workspace?: string;
|
|
164
|
+
workerSession?: string;
|
|
165
|
+
outputFile?: string;
|
|
166
|
+
branch?: string;
|
|
167
|
+
files?: string[];
|
|
168
|
+
status?: WorkerStatus;
|
|
169
|
+
/** Resume point to record; stamped with the write time. */
|
|
170
|
+
checkpoint?: WorkerCheckpointInput;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export interface WorkerCheckOptions {
|
|
174
|
+
/** herdr lifecycle state (idle|working|blocked|done|unknown), passed by the parent. */
|
|
175
|
+
liveStatus?: string;
|
|
176
|
+
/** Git repo root used for the branch-ahead count. */
|
|
177
|
+
cwd?: string;
|
|
178
|
+
/**
|
|
179
|
+
* Branch recorded on this worker's lock rows. Used only when the entry has
|
|
180
|
+
* no branch of its own (`entry.branch ?? fallbackBranch`); when omitted,
|
|
181
|
+
* checkWorker reads the project lock table itself.
|
|
182
|
+
*/
|
|
183
|
+
fallbackBranch?: string;
|
|
184
|
+
/** Clock override for tests; defaults to Date.now(). */
|
|
185
|
+
now?: number;
|
|
186
|
+
/** Frozen-session threshold in seconds; defaults to 600. */
|
|
187
|
+
stalledAfterSec?: number;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
export interface WorkerCheckResult {
|
|
191
|
+
workerId: string;
|
|
192
|
+
status: WorkerVerdictStatus;
|
|
193
|
+
reason: string;
|
|
194
|
+
outputFile: string | null;
|
|
195
|
+
outputExists: boolean;
|
|
196
|
+
outputAgeSec: number | null;
|
|
197
|
+
sessionGrowthAgeSec: number | null;
|
|
198
|
+
branchAhead: number | null;
|
|
199
|
+
schemaValid: boolean;
|
|
200
|
+
/**
|
|
201
|
+
* How many assistant messages back from the newest the result block was
|
|
202
|
+
* found (0 = the last assistant message), or null when none was valid
|
|
203
|
+
* within the scan window. Lets a parent tell a terminal block from a
|
|
204
|
+
* near-terminal one.
|
|
205
|
+
*/
|
|
206
|
+
resultSchemaMessageOffset: number | null;
|
|
207
|
+
/** Request id the entry was admitted under, when it recorded one. */
|
|
208
|
+
requestId: string | null;
|
|
209
|
+
/** Resume point the entry carries, when it has one. */
|
|
210
|
+
checkpoint: WorkerCheckpoint | null;
|
|
211
|
+
gateSummary: string;
|
|
212
|
+
/**
|
|
213
|
+
* Effect evidence for a terminal completion, or null when the row is not
|
|
214
|
+
* one (unclosed, or closed with a non-completed outcome). `none` true is
|
|
215
|
+
* the no-effect-evidence flag: the close recorded a completion while the
|
|
216
|
+
* row shows none of the three evidence kinds.
|
|
217
|
+
*/
|
|
218
|
+
effectEvidence: WorkerEffectEvidence | null;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* A status the registry reports. `resumable` is derived, never stored: it says
|
|
223
|
+
* the entry is mid-flight with a checkpoint to resume from, which is a
|
|
224
|
+
* statement about evidence rather than a lifecycle state a caller sets. No
|
|
225
|
+
* stored row carries it, so the on-disk status set is unchanged.
|
|
226
|
+
*/
|
|
227
|
+
export type WorkerVerdictStatus = WorkerStatus | "resumable";
|
|
228
|
+
|
|
229
|
+
// ── Constants ──────────────────────────────────────────────────────────────
|
|
230
|
+
|
|
231
|
+
export const WORKER_REGISTRY_VERSION = 1;
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* Spec names a worker result may declare: the accepted set, and the one source
|
|
235
|
+
* the tool schema renders from. `project` is in the set; the tool prose listed
|
|
236
|
+
* only four before it rendered from here, which is the drift this list ends.
|
|
237
|
+
*/
|
|
238
|
+
export const WORKER_SPECS: readonly string[] = ["research", "impl", "verify", "audit", "project"];
|
|
239
|
+
|
|
240
|
+
export const WORKER_STATUSES: readonly WorkerStatus[] = [
|
|
241
|
+
"admitted",
|
|
242
|
+
"working",
|
|
243
|
+
"merged",
|
|
244
|
+
"completed",
|
|
245
|
+
"error",
|
|
246
|
+
"stalled",
|
|
247
|
+
"false-done",
|
|
248
|
+
"closed",
|
|
249
|
+
];
|
|
250
|
+
|
|
251
|
+
export const WORKER_OUTCOMES: readonly WorkerOutcome[] = [
|
|
252
|
+
"completed",
|
|
253
|
+
"error",
|
|
254
|
+
"stalled",
|
|
255
|
+
"false-done",
|
|
256
|
+
"closed",
|
|
257
|
+
];
|
|
258
|
+
|
|
259
|
+
/** Statuses check-worker may report: the stored statuses plus `resumable`. */
|
|
260
|
+
export const WORKER_VERDICT_STATUSES: readonly WorkerVerdictStatus[] = [
|
|
261
|
+
...WORKER_STATUSES,
|
|
262
|
+
"resumable",
|
|
263
|
+
];
|
|
264
|
+
|
|
265
|
+
/** Statuses a worker's result schema may self-report. */
|
|
266
|
+
export const RESULT_SCHEMA_STATUSES: readonly string[] = [
|
|
267
|
+
"completed",
|
|
268
|
+
"partial",
|
|
269
|
+
"blocked",
|
|
270
|
+
"error",
|
|
271
|
+
];
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* The four roles a worker lifecycle's values can play. They are distinct
|
|
275
|
+
* vocabularies that share words: `completed` is a stored status, a close
|
|
276
|
+
* outcome, a computed verdict and a result attestation, so a bare value
|
|
277
|
+
* means nothing until the layer names which one it is.
|
|
278
|
+
*/
|
|
279
|
+
export type WorkerStatusLayerRole =
|
|
280
|
+
| "stored status"
|
|
281
|
+
| "close outcome"
|
|
282
|
+
| "computed verdict"
|
|
283
|
+
| "result attestation";
|
|
284
|
+
|
|
285
|
+
/** One vocabulary in the status-layer table: its role, writer, and values. */
|
|
286
|
+
export interface WorkerStatusLayer {
|
|
287
|
+
/** The role the values play; the four layers are never interchangeable. */
|
|
288
|
+
role: WorkerStatusLayerRole;
|
|
289
|
+
/** Who writes values in this layer. */
|
|
290
|
+
owner: string;
|
|
291
|
+
/** Accepted values, in reporting order. */
|
|
292
|
+
values: readonly string[];
|
|
293
|
+
/** What one value in this layer states, as a clause the tool schema reuses. */
|
|
294
|
+
states: string;
|
|
295
|
+
}
|
|
296
|
+
|
|
297
|
+
/**
|
|
298
|
+
* The four vocabularies a worker lifecycle speaks in, each with its values and
|
|
299
|
+
* its writer. Readers (the tool schema, the tests, the report) render from this
|
|
300
|
+
* table rather than restating the values, so a value added here reaches every
|
|
301
|
+
* reader at once.
|
|
302
|
+
*/
|
|
303
|
+
export const WORKER_STATUS_LAYERS: readonly WorkerStatusLayer[] = [
|
|
304
|
+
{
|
|
305
|
+
role: "stored status",
|
|
306
|
+
owner: "registry row (spawn admission, update-worker, close and merge writes)",
|
|
307
|
+
values: WORKER_STATUSES,
|
|
308
|
+
states: "the lifecycle state the registry row carries",
|
|
309
|
+
},
|
|
310
|
+
{
|
|
311
|
+
role: "close outcome",
|
|
312
|
+
owner: "close-worker call",
|
|
313
|
+
values: WORKER_OUTCOMES,
|
|
314
|
+
states: "the terminal outcome a close records",
|
|
315
|
+
},
|
|
316
|
+
{
|
|
317
|
+
role: "computed verdict",
|
|
318
|
+
owner: "check-worker",
|
|
319
|
+
values: WORKER_VERDICT_STATUSES,
|
|
320
|
+
states: "what check-worker derives from evidence, resumable never stored",
|
|
321
|
+
},
|
|
322
|
+
{
|
|
323
|
+
role: "result attestation",
|
|
324
|
+
owner: "worker's own result block",
|
|
325
|
+
values: RESULT_SCHEMA_STATUSES,
|
|
326
|
+
states: "what the worker's result block claims about its own result",
|
|
327
|
+
},
|
|
328
|
+
];
|
|
329
|
+
|
|
330
|
+
const DEFAULT_STALLED_AFTER_SEC = 600;
|
|
331
|
+
|
|
332
|
+
/**
|
|
333
|
+
* How many assistant messages back from the newest a result block may sit.
|
|
334
|
+
* A worker that emits its validated block and then one closing prose line is
|
|
335
|
+
* still terminal; a parent must be able to tell that block from a progress
|
|
336
|
+
* note, so the offset is recorded in the verdict.
|
|
337
|
+
*/
|
|
338
|
+
const RESULT_SCHEMA_MAX_MESSAGES_BACK = 3;
|
|
339
|
+
|
|
340
|
+
// ── Status parsing ─────────────────────────────────────────────────────────
|
|
341
|
+
|
|
342
|
+
export function parseWorkerStatus(raw: string): WorkerStatus {
|
|
343
|
+
const value = raw.trim() as WorkerStatus;
|
|
344
|
+
if (!WORKER_STATUSES.includes(value)) {
|
|
345
|
+
throw new Error(
|
|
346
|
+
`Unknown worker status "${raw}". Expected one of: ${WORKER_STATUSES.join(", ")}`,
|
|
347
|
+
);
|
|
348
|
+
}
|
|
349
|
+
return value;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
export function parseWorkerOutcome(raw: string): WorkerOutcome {
|
|
353
|
+
const value = raw.trim() as WorkerOutcome;
|
|
354
|
+
if (!WORKER_OUTCOMES.includes(value)) {
|
|
355
|
+
throw new Error(
|
|
356
|
+
`Unknown worker outcome "${raw}". Expected one of: ${WORKER_OUTCOMES.join(", ")}`,
|
|
357
|
+
);
|
|
358
|
+
}
|
|
359
|
+
return value;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
// ── Registry I/O ───────────────────────────────────────────────────────────
|
|
363
|
+
|
|
364
|
+
function emptyRegistry(): WorkerRegistry {
|
|
365
|
+
return { version: WORKER_REGISTRY_VERSION, workers: {} };
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* Fill in what a row written before these fields existed lacks. The read path
|
|
370
|
+
* writes nothing back: an entry with no request id or checkpoint reports null
|
|
371
|
+
* for both and keeps every other fact it has, so reading a legacy registry
|
|
372
|
+
* migrates nothing.
|
|
373
|
+
*/
|
|
374
|
+
function normalizeEntry(raw: WorkerEntry): WorkerEntry {
|
|
375
|
+
const requestId =
|
|
376
|
+
typeof raw.requestId === "string" && raw.requestId.length > 0 ? raw.requestId : null;
|
|
377
|
+
return {
|
|
378
|
+
...raw,
|
|
379
|
+
requestId,
|
|
380
|
+
checkpoint: isCheckpoint(raw.checkpoint) ? raw.checkpoint : null,
|
|
381
|
+
admissionRefusals: Array.isArray(raw.admissionRefusals) ? raw.admissionRefusals : [],
|
|
382
|
+
};
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
function isCheckpoint(raw: unknown): raw is WorkerCheckpoint {
|
|
386
|
+
if (!raw || typeof raw !== "object") return false;
|
|
387
|
+
const value = raw as { phase?: unknown; step?: unknown; at?: unknown };
|
|
388
|
+
return (
|
|
389
|
+
typeof value.phase === "string" &&
|
|
390
|
+
value.phase.length > 0 &&
|
|
391
|
+
typeof value.step === "string" &&
|
|
392
|
+
value.step.length > 0 &&
|
|
393
|
+
typeof value.at === "string"
|
|
394
|
+
);
|
|
395
|
+
}
|
|
396
|
+
|
|
397
|
+
function loadRegistryFile(file: string): WorkerRegistry {
|
|
398
|
+
try {
|
|
399
|
+
if (!existsSync(file)) return emptyRegistry();
|
|
400
|
+
const raw = readFileSync(file, "utf-8").trim();
|
|
401
|
+
if (!raw) return emptyRegistry();
|
|
402
|
+
const parsed = JSON.parse(raw) as WorkerRegistry;
|
|
403
|
+
if (
|
|
404
|
+
!parsed ||
|
|
405
|
+
typeof parsed !== "object" ||
|
|
406
|
+
!parsed.workers ||
|
|
407
|
+
typeof parsed.workers !== "object"
|
|
408
|
+
) {
|
|
409
|
+
return emptyRegistry();
|
|
410
|
+
}
|
|
411
|
+
const workers: Record<string, WorkerEntry> = {};
|
|
412
|
+
for (const [id, entry] of Object.entries(parsed.workers)) {
|
|
413
|
+
if (entry && typeof entry === "object") workers[id] = normalizeEntry(entry);
|
|
414
|
+
}
|
|
415
|
+
return {
|
|
416
|
+
version: typeof parsed.version === "number" ? parsed.version : WORKER_REGISTRY_VERSION,
|
|
417
|
+
workers,
|
|
418
|
+
};
|
|
419
|
+
} catch {
|
|
420
|
+
return emptyRegistry();
|
|
421
|
+
}
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
/** Read the registry for a project cwd (defaults to process.cwd()). */
|
|
425
|
+
export function readWorkers(cwd?: string): WorkerRegistry {
|
|
426
|
+
return loadRegistryFile(getWorkersFilePath(cwd ?? process.cwd()));
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
/**
|
|
430
|
+
* Persist the registry atomically: temp file in the same directory, then
|
|
431
|
+
* rename. Writes fail loudly (unlike lock writes) — a registry that
|
|
432
|
+
* silently drops admissions is worse than a visible error.
|
|
433
|
+
*/
|
|
434
|
+
export function writeWorkers(registry: WorkerRegistry, cwd?: string): void {
|
|
435
|
+
const file = getWorkersFilePath(cwd ?? process.cwd());
|
|
436
|
+
mkdirSync(dirname(file), { recursive: true });
|
|
437
|
+
const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
|
|
438
|
+
try {
|
|
439
|
+
writeFileSync(tmp, JSON.stringify(registry, null, 2), { encoding: "utf-8", mode: 0o600 });
|
|
440
|
+
chmodSync(tmp, 0o600);
|
|
441
|
+
renameSync(tmp, file);
|
|
442
|
+
} finally {
|
|
443
|
+
if (existsSync(tmp)) rmSync(tmp, { force: true });
|
|
444
|
+
}
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
// ── Worker lookup ──────────────────────────────────────────────────────────
|
|
448
|
+
|
|
449
|
+
/**
|
|
450
|
+
* Locate a worker entry. With an explicit cwd the lookup is scoped to that
|
|
451
|
+
* project. Without one, the process cwd is tried first, then every project
|
|
452
|
+
* registry under ~/.pi/agent/braid/projects — the parent often runs in its
|
|
453
|
+
* own workspace while the worker's registry lives under the target repo.
|
|
454
|
+
* Returns the registry plus the key used for writes (the entry's own cwd).
|
|
455
|
+
*/
|
|
456
|
+
function locateWorker(
|
|
457
|
+
workerId: string,
|
|
458
|
+
cwd?: string,
|
|
459
|
+
): { registry: WorkerRegistry; key: string } | null {
|
|
460
|
+
const key = cwd ?? process.cwd();
|
|
461
|
+
const registry = readWorkers(key);
|
|
462
|
+
if (registry.workers[workerId]) return { registry, key };
|
|
463
|
+
|
|
464
|
+
// A miss in the caller's own project is not proof the worker is unknown. A
|
|
465
|
+
// project can be named differently by different callers while being one
|
|
466
|
+
// directory, and an id-addressed action (check/update/close) that answered
|
|
467
|
+
// "unknown" for a live row would leave it stranded. Walk every project
|
|
468
|
+
// registry first; the caller's own key still wins when it has the row.
|
|
469
|
+
const projectsRoot = projectsDir();
|
|
470
|
+
try {
|
|
471
|
+
for (const dirent of readdirSync(projectsRoot, { withFileTypes: true })) {
|
|
472
|
+
if (!dirent.isDirectory()) continue;
|
|
473
|
+
const other = loadRegistryFile(join(projectsRoot, dirent.name, "workers.json"));
|
|
474
|
+
const entry = other.workers[workerId];
|
|
475
|
+
if (entry) return { registry: other, key: entry.cwd };
|
|
476
|
+
}
|
|
477
|
+
} catch {
|
|
478
|
+
/* no projects dir yet */
|
|
479
|
+
}
|
|
480
|
+
return null;
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
// ── Request identity ───────────────────────────────────────────────────────
|
|
484
|
+
|
|
485
|
+
/**
|
|
486
|
+
* The exactly-once identity of a unit of work: `(workerId, step)`. The step is
|
|
487
|
+
* the submission attempt — 1 for the first — so a caller that retries the same
|
|
488
|
+
* submission composes the same id and is recognized, while work admitted under
|
|
489
|
+
* a later step gets its own id. Admission records the id on the entry, and a
|
|
490
|
+
* submission whose id matches a live entry reuses that entry rather than
|
|
491
|
+
* admitting a second one.
|
|
492
|
+
*/
|
|
493
|
+
export function deriveRequestId(workerId: string, step = 1): string {
|
|
494
|
+
return `${workerId}:${step}`;
|
|
495
|
+
}
|
|
496
|
+
|
|
497
|
+
/** The request id an admission carries: the caller's, or the derived key. */
|
|
498
|
+
export function resolveRequestId(workerId: string, requestId?: string): string {
|
|
499
|
+
const explicit = requestId?.trim();
|
|
500
|
+
return explicit ? explicit : deriveRequestId(workerId);
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
/**
|
|
504
|
+
* True when this entry admits the same request. A row with no recorded id
|
|
505
|
+
* predates request identity, so nothing matches it: a legacy live entry keeps
|
|
506
|
+
* refusing re-admission instead of being adopted silently by a new request.
|
|
507
|
+
*/
|
|
508
|
+
function isSameRequest(entry: WorkerEntry, requestId: string): boolean {
|
|
509
|
+
return typeof entry.requestId === "string" && entry.requestId === requestId;
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
/** What a request states about the work, against what the entry recorded. */
|
|
513
|
+
function requestDifferences(
|
|
514
|
+
entry: WorkerEntry,
|
|
515
|
+
request: { spec?: string; files?: string[] },
|
|
516
|
+
): string[] {
|
|
517
|
+
const differences: string[] = [];
|
|
518
|
+
if (request.spec !== undefined && request.spec !== entry.spec) {
|
|
519
|
+
differences.push(`spec "${entry.spec}" vs "${request.spec}"`);
|
|
520
|
+
}
|
|
521
|
+
if (request.files !== undefined) {
|
|
522
|
+
const recorded = [...entry.files].sort();
|
|
523
|
+
const requested = [...request.files].sort();
|
|
524
|
+
const same =
|
|
525
|
+
recorded.length === requested.length && recorded.every((file, i) => file === requested[i]);
|
|
526
|
+
if (!same) {
|
|
527
|
+
differences.push(`files [${recorded.join(", ")}] vs [${requested.join(", ")}]`);
|
|
528
|
+
}
|
|
529
|
+
}
|
|
530
|
+
return differences;
|
|
531
|
+
}
|
|
532
|
+
|
|
533
|
+
export interface WorkerAdmissionDecision {
|
|
534
|
+
action: "admit" | "reuse" | "refuse";
|
|
535
|
+
entry?: WorkerEntry;
|
|
536
|
+
reason?: string;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
/**
|
|
540
|
+
* What admitting `requestId` does to the live entry that may hold this worker.
|
|
541
|
+
* Reuse only when the ids match *and* the request describes the same work: a
|
|
542
|
+
* second live row for one worker is the duplicate this identity prevents, and
|
|
543
|
+
* the same id carrying a different payload is a contradiction, not a retry. A
|
|
544
|
+
* closed entry is no obstacle — retries past a close are countable.
|
|
545
|
+
*/
|
|
546
|
+
export function decideAdmission(
|
|
547
|
+
existing: WorkerEntry | undefined,
|
|
548
|
+
requestId: string,
|
|
549
|
+
request: { spec?: string; files?: string[] },
|
|
550
|
+
): WorkerAdmissionDecision {
|
|
551
|
+
if (!existing || existing.closedAt) return { action: "admit" };
|
|
552
|
+
if (!isSameRequest(existing, requestId)) {
|
|
553
|
+
return {
|
|
554
|
+
action: "refuse",
|
|
555
|
+
entry: existing,
|
|
556
|
+
reason:
|
|
557
|
+
`worker ${existing.workerId} is live (status ${existing.status}, ` +
|
|
558
|
+
`${existing.requestId ? `requestId ${existing.requestId}` : "no requestId recorded"}); ` +
|
|
559
|
+
`requestId ${requestId} is a different request — close the live entry to admit it`,
|
|
560
|
+
};
|
|
561
|
+
}
|
|
562
|
+
const differences = requestDifferences(existing, request);
|
|
563
|
+
if (differences.length > 0) {
|
|
564
|
+
return {
|
|
565
|
+
action: "refuse",
|
|
566
|
+
entry: existing,
|
|
567
|
+
reason:
|
|
568
|
+
`requestId ${requestId} is already admitted and describes different work ` +
|
|
569
|
+
`(${differences.join("; ")}) — a retry carries the same payload; close the live ` +
|
|
570
|
+
`entry before admitting changed work`,
|
|
571
|
+
};
|
|
572
|
+
}
|
|
573
|
+
return { action: "reuse", entry: existing };
|
|
574
|
+
}
|
|
575
|
+
|
|
576
|
+
/** Append a refusal to the live entry it was made against; no I/O. */
|
|
577
|
+
function appendAdmissionRefusal(entry: WorkerEntry, requestId: string): void {
|
|
578
|
+
const refusals = Array.isArray(entry.admissionRefusals) ? entry.admissionRefusals : [];
|
|
579
|
+
refusals.push({ requestId, at: new Date().toISOString() });
|
|
580
|
+
entry.admissionRefusals = refusals;
|
|
581
|
+
}
|
|
582
|
+
|
|
583
|
+
/**
|
|
584
|
+
* Persist a refused admission against the live worker that refused it. A
|
|
585
|
+
* refusal leaves the row's lifecycle untouched — no status, no handle, no
|
|
586
|
+
* lastSeenAt — and records only the request id and the time, so the count of
|
|
587
|
+
* turned-away duplicates is readable from the registry instead of inferred.
|
|
588
|
+
* Returns false when the worker is unknown or already closed: a closed row
|
|
589
|
+
* refuses nothing.
|
|
590
|
+
*/
|
|
591
|
+
export function recordAdmissionRefusal(workerId: string, requestId: string, cwd?: string): boolean {
|
|
592
|
+
const located = locateWorker(workerId, cwd);
|
|
593
|
+
if (!located) return false;
|
|
594
|
+
const entry = located.registry.workers[workerId];
|
|
595
|
+
if (entry.closedAt) return false;
|
|
596
|
+
appendAdmissionRefusal(entry, requestId);
|
|
597
|
+
writeWorkers(located.registry, located.key);
|
|
598
|
+
return true;
|
|
599
|
+
}
|
|
600
|
+
|
|
601
|
+
// ── CRUD ───────────────────────────────────────────────────────────────────
|
|
602
|
+
|
|
603
|
+
/**
|
|
604
|
+
* Admit a worker. Refuses when a live (not closed) entry exists for the
|
|
605
|
+
* same workerId; a closed entry is rolled over (retries are countable).
|
|
606
|
+
*/
|
|
607
|
+
export function registerWorker(input: RegisterWorkerInput, cwd?: string): RegisterWorkerResult {
|
|
608
|
+
if (!input.workerId) throw new Error("workerId is required");
|
|
609
|
+
if (!input.spec) throw new Error("spec is required");
|
|
610
|
+
if (!input.cwd) throw new Error("cwd is required");
|
|
611
|
+
|
|
612
|
+
const key = cwd ?? input.cwd;
|
|
613
|
+
const registry = readWorkers(key);
|
|
614
|
+
const existing = registry.workers[input.workerId];
|
|
615
|
+
const requestId = resolveRequestId(input.workerId, input.requestId);
|
|
616
|
+
const decision = decideAdmission(existing, requestId, { spec: input.spec, files: input.files });
|
|
617
|
+
if (decision.action === "reuse") {
|
|
618
|
+
return { ok: true, entry: decision.entry, reused: true };
|
|
619
|
+
}
|
|
620
|
+
if (decision.action === "refuse") {
|
|
621
|
+
// Record the refusal on the live entry so the fleet's refusal count is a
|
|
622
|
+
// registry fact; a refusal changes no lifecycle field.
|
|
623
|
+
if (existing && !existing.closedAt) {
|
|
624
|
+
appendAdmissionRefusal(existing, requestId);
|
|
625
|
+
writeWorkers(registry, key);
|
|
626
|
+
}
|
|
627
|
+
return { ok: false, reason: decision.reason, entry: decision.entry };
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
const nowIso = new Date().toISOString();
|
|
631
|
+
const entry: WorkerEntry = {
|
|
632
|
+
workerId: input.workerId,
|
|
633
|
+
spec: input.spec,
|
|
634
|
+
status: "admitted",
|
|
635
|
+
cwd: input.cwd,
|
|
636
|
+
pane: input.pane ?? null,
|
|
637
|
+
workspace: null,
|
|
638
|
+
workerSession: input.workerSession ?? null,
|
|
639
|
+
outputFile: input.outputFile ?? null,
|
|
640
|
+
branch: input.branch ?? null,
|
|
641
|
+
files: input.files ?? [],
|
|
642
|
+
spawnedAt: nowIso,
|
|
643
|
+
lastSeenAt: nowIso,
|
|
644
|
+
resultAt: null,
|
|
645
|
+
mergeSha: null,
|
|
646
|
+
mergedAt: null,
|
|
647
|
+
closedAt: null,
|
|
648
|
+
gates: [],
|
|
649
|
+
admissionRefusals: [],
|
|
650
|
+
requestId,
|
|
651
|
+
checkpoint: null,
|
|
652
|
+
};
|
|
653
|
+
registry.workers[input.workerId] = entry;
|
|
654
|
+
writeWorkers(registry, key);
|
|
655
|
+
return { ok: true, entry };
|
|
656
|
+
}
|
|
657
|
+
|
|
658
|
+
/** Stamp a caller's checkpoint with the write time; reject an empty phase/step. */
|
|
659
|
+
function stampCheckpoint(input: WorkerCheckpointInput): WorkerCheckpoint {
|
|
660
|
+
const phase = input.phase?.trim();
|
|
661
|
+
const step = input.step?.trim();
|
|
662
|
+
if (!phase) throw new Error("checkpoint.phase is required");
|
|
663
|
+
if (!step) throw new Error("checkpoint.step is required");
|
|
664
|
+
return { phase, step, at: new Date().toISOString() };
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
/** Merge handle fields into an entry; refreshes lastSeenAt. Null when unknown. */
|
|
668
|
+
export function updateWorker(
|
|
669
|
+
workerId: string,
|
|
670
|
+
patch: UpdateWorkerPatch,
|
|
671
|
+
cwd?: string,
|
|
672
|
+
): WorkerEntry | null {
|
|
673
|
+
const located = locateWorker(workerId, cwd);
|
|
674
|
+
if (!located) return null;
|
|
675
|
+
const entry = located.registry.workers[workerId];
|
|
676
|
+
|
|
677
|
+
if (patch.pane !== undefined) entry.pane = patch.pane;
|
|
678
|
+
if (patch.workspace !== undefined) entry.workspace = patch.workspace;
|
|
679
|
+
if (patch.workerSession !== undefined) entry.workerSession = patch.workerSession;
|
|
680
|
+
if (patch.outputFile !== undefined) entry.outputFile = patch.outputFile;
|
|
681
|
+
if (patch.branch !== undefined) entry.branch = patch.branch;
|
|
682
|
+
if (patch.files !== undefined) entry.files = patch.files;
|
|
683
|
+
if (patch.status !== undefined) entry.status = parseWorkerStatus(patch.status);
|
|
684
|
+
if (patch.checkpoint !== undefined) entry.checkpoint = stampCheckpoint(patch.checkpoint);
|
|
685
|
+
entry.lastSeenAt = new Date().toISOString();
|
|
686
|
+
|
|
687
|
+
writeWorkers(located.registry, located.key);
|
|
688
|
+
return entry;
|
|
689
|
+
}
|
|
690
|
+
|
|
691
|
+
/**
|
|
692
|
+
* Record that this worker's work was merged into a base branch.
|
|
693
|
+
*
|
|
694
|
+
* The write goes to the row's own project key rather than to the caller's
|
|
695
|
+
* cwd, so the mark cannot land beside the row instead of on it. Returns null
|
|
696
|
+
* when the worker has no row at all: a merge records what admission already
|
|
697
|
+
* established and never invents an entry, because `spec` and `outputFile` are
|
|
698
|
+
* facts only admission knows.
|
|
699
|
+
*/
|
|
700
|
+
export function recordWorkerMerge(
|
|
701
|
+
workerId: string,
|
|
702
|
+
info: { mergeSha: string; cwd?: string },
|
|
703
|
+
): WorkerEntry | null {
|
|
704
|
+
const located = locateWorker(workerId, info.cwd);
|
|
705
|
+
if (!located) return null;
|
|
706
|
+
const entry = located.registry.workers[workerId];
|
|
707
|
+
|
|
708
|
+
const nowIso = new Date().toISOString();
|
|
709
|
+
// A closed row keeps its terminal status: the merge is recorded on it, but
|
|
710
|
+
// the outcome of the close stands.
|
|
711
|
+
if (!entry.closedAt) entry.status = "merged";
|
|
712
|
+
entry.mergeSha = info.mergeSha;
|
|
713
|
+
entry.mergedAt = nowIso;
|
|
714
|
+
entry.lastSeenAt = nowIso;
|
|
715
|
+
if (!entry.resultAt) entry.resultAt = nowIso;
|
|
716
|
+
|
|
717
|
+
writeWorkers(located.registry, located.key);
|
|
718
|
+
return entry;
|
|
719
|
+
}
|
|
720
|
+
|
|
721
|
+
/**
|
|
722
|
+
* Refuse close-time gate evidence that cannot describe a real run: a
|
|
723
|
+
* completed close with nothing recorded, a non-array value, or an entry whose
|
|
724
|
+
* `cmd` is not a non-empty string or whose `exit` is not a number. Throws on
|
|
725
|
+
* the first violation, before the caller writes anything.
|
|
726
|
+
*/
|
|
727
|
+
function assertGateEvidence(
|
|
728
|
+
workerId: string,
|
|
729
|
+
outcome: WorkerOutcome,
|
|
730
|
+
gates: Array<{ cmd: string; exit: number }> | undefined,
|
|
731
|
+
): void {
|
|
732
|
+
if (gates !== undefined && !Array.isArray(gates)) {
|
|
733
|
+
throw new Error(
|
|
734
|
+
`closeWorker: gates must be an array of { cmd, exit } entries (worker ${workerId})`,
|
|
735
|
+
);
|
|
736
|
+
}
|
|
737
|
+
if (outcome === "completed" && (!gates || gates.length === 0)) {
|
|
738
|
+
throw new Error(
|
|
739
|
+
`closeWorker: a completed close requires non-empty gate evidence (worker ${workerId})`,
|
|
740
|
+
);
|
|
741
|
+
}
|
|
742
|
+
if (!gates) return;
|
|
743
|
+
for (let i = 0; i < gates.length; i++) {
|
|
744
|
+
const gate: unknown = gates[i];
|
|
745
|
+
if (!gate || typeof gate !== "object" || Array.isArray(gate)) {
|
|
746
|
+
throw new Error(
|
|
747
|
+
`closeWorker: gates[${i}] must be an object carrying cmd and exit (worker ${workerId})`,
|
|
748
|
+
);
|
|
749
|
+
}
|
|
750
|
+
const { cmd, exit } = gate as { cmd?: unknown; exit?: unknown };
|
|
751
|
+
if (typeof cmd !== "string" || cmd.trim() === "") {
|
|
752
|
+
throw new Error(
|
|
753
|
+
`closeWorker: gates[${i}].cmd must be a non-empty string (worker ${workerId})`,
|
|
754
|
+
);
|
|
755
|
+
}
|
|
756
|
+
if (typeof exit !== "number" || !Number.isFinite(exit)) {
|
|
757
|
+
throw new Error(`closeWorker: gates[${i}].exit must be a number (worker ${workerId})`);
|
|
758
|
+
}
|
|
759
|
+
}
|
|
760
|
+
}
|
|
761
|
+
|
|
762
|
+
/**
|
|
763
|
+
* Close an entry with a terminal outcome and optional gate evidence.
|
|
764
|
+
* Already-closed entries are left untouched (first close wins); the checks
|
|
765
|
+
* below run only on a close that would actually stamp the row, so a retried
|
|
766
|
+
* close stays a silent no-op and an unknown worker still returns null.
|
|
767
|
+
*
|
|
768
|
+
* A completed close carries evidence: the reporter contract requires a
|
|
769
|
+
* non-empty `gate_evidence` block, and a probe measured this path storing a
|
|
770
|
+
* bare `completed` with no gates at all. That contradiction is refused now,
|
|
771
|
+
* and each provided gate is shape-checked (non-empty `cmd`, numeric `exit`)
|
|
772
|
+
* before any write — a violation leaves the row and the lock table untouched.
|
|
773
|
+
*
|
|
774
|
+
* Releases the worker's file locks: close is terminal, and a lock that
|
|
775
|
+
* survives it blocks the next spawn on the same files. The release runs with
|
|
776
|
+
* the entry's own project key so the lock table read is the same one
|
|
777
|
+
* `acquireLock` wrote; `release-locks` stays the explicit override.
|
|
778
|
+
*/
|
|
779
|
+
export function closeWorker(
|
|
780
|
+
workerId: string,
|
|
781
|
+
outcome: WorkerOutcome,
|
|
782
|
+
gates?: Array<{ cmd: string; exit: number }>,
|
|
783
|
+
cwd?: string,
|
|
784
|
+
): WorkerEntry | null {
|
|
785
|
+
const parsed = parseWorkerOutcome(outcome);
|
|
786
|
+
const located = locateWorker(workerId, cwd);
|
|
787
|
+
if (!located) return null;
|
|
788
|
+
const entry = located.registry.workers[workerId];
|
|
789
|
+
if (entry.closedAt) return entry;
|
|
790
|
+
|
|
791
|
+
assertGateEvidence(workerId, parsed, gates);
|
|
792
|
+
|
|
793
|
+
releaseLock(workerId, located.key);
|
|
794
|
+
|
|
795
|
+
const nowIso = new Date().toISOString();
|
|
796
|
+
entry.status = parsed;
|
|
797
|
+
entry.closedAt = nowIso;
|
|
798
|
+
entry.lastSeenAt = nowIso;
|
|
799
|
+
if (parsed === "completed" && !entry.resultAt) entry.resultAt = nowIso;
|
|
800
|
+
if (gates && gates.length > 0) {
|
|
801
|
+
for (const gate of gates) {
|
|
802
|
+
entry.gates.push({ cmd: gate.cmd, exit: gate.exit, at: nowIso });
|
|
803
|
+
}
|
|
804
|
+
}
|
|
805
|
+
|
|
806
|
+
writeWorkers(located.registry, located.key);
|
|
807
|
+
return entry;
|
|
808
|
+
}
|
|
809
|
+
|
|
810
|
+
// ── Result schema ──────────────────────────────────────────────────────────
|
|
811
|
+
|
|
812
|
+
function tryParseObject(raw: string): Record<string, unknown> | null {
|
|
813
|
+
try {
|
|
814
|
+
const parsed = JSON.parse(raw);
|
|
815
|
+
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
|
|
816
|
+
return parsed as Record<string, unknown>;
|
|
817
|
+
}
|
|
818
|
+
return null;
|
|
819
|
+
} catch {
|
|
820
|
+
return null;
|
|
821
|
+
}
|
|
822
|
+
}
|
|
823
|
+
|
|
824
|
+
function isResultSchema(obj: Record<string, unknown>): boolean {
|
|
825
|
+
return (
|
|
826
|
+
typeof obj.worker === "string" &&
|
|
827
|
+
obj.worker.length > 0 &&
|
|
828
|
+
typeof obj.spec === "string" &&
|
|
829
|
+
obj.spec.length > 0 &&
|
|
830
|
+
typeof obj.status === "string" &&
|
|
831
|
+
RESULT_SCHEMA_STATUSES.includes(obj.status) &&
|
|
832
|
+
typeof obj.output_file === "string" &&
|
|
833
|
+
obj.output_file.length > 0
|
|
834
|
+
);
|
|
835
|
+
}
|
|
836
|
+
|
|
837
|
+
/**
|
|
838
|
+
* Pull the newest valid result block out of one assistant message, or null.
|
|
839
|
+
* Fenced ```json blocks are tried newest-first, then a bare JSON body.
|
|
840
|
+
*/
|
|
841
|
+
function extractResultBlock(content: unknown): Record<string, unknown> | null {
|
|
842
|
+
const texts: string[] = [];
|
|
843
|
+
if (Array.isArray(content)) {
|
|
844
|
+
for (const part of content) {
|
|
845
|
+
if (part && typeof part === "object" && (part as { type?: unknown }).type === "text") {
|
|
846
|
+
const text = (part as { text?: unknown }).text;
|
|
847
|
+
if (typeof text === "string") texts.push(text);
|
|
848
|
+
}
|
|
849
|
+
}
|
|
850
|
+
} else if (typeof content === "string") {
|
|
851
|
+
texts.push(content);
|
|
852
|
+
}
|
|
853
|
+
const joined = texts.join("\n");
|
|
854
|
+
|
|
855
|
+
const blocks = [...joined.matchAll(/```json[ \t]*\r?\n([\s\S]*?)```/gi)].map((m) => m[1]);
|
|
856
|
+
for (let b = blocks.length - 1; b >= 0; b--) {
|
|
857
|
+
const parsed = tryParseObject(blocks[b]);
|
|
858
|
+
if (parsed && isResultSchema(parsed)) return parsed;
|
|
859
|
+
}
|
|
860
|
+
const bare = tryParseObject(joined.trim());
|
|
861
|
+
if (bare && isResultSchema(bare)) return bare;
|
|
862
|
+
return null;
|
|
863
|
+
}
|
|
864
|
+
|
|
865
|
+
/** A located result block plus where it sat in the assistant-message tail. */
|
|
866
|
+
export interface ResultSchemaLocation {
|
|
867
|
+
schema: Record<string, unknown>;
|
|
868
|
+
/** Assistant messages back from the newest (0 = the last assistant message). */
|
|
869
|
+
messageOffset: number;
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
/**
|
|
873
|
+
* Locate the worker's result-schema block in the session file.
|
|
874
|
+
*
|
|
875
|
+
* Scans the last assistant message first. A worker that emits its validated
|
|
876
|
+
* block and then one closing prose line still produced a terminal result, so
|
|
877
|
+
* when that message yields no block the scan continues through at most
|
|
878
|
+
* `maxMessagesBack` assistant messages and takes the most recent valid one.
|
|
879
|
+
* The offset is returned so a caller can distinguish a terminal block (0) from
|
|
880
|
+
* a near-terminal one. No valid block within the window is still a failure.
|
|
881
|
+
*/
|
|
882
|
+
export function locateResultSchema(
|
|
883
|
+
sessionPath: string | null,
|
|
884
|
+
maxMessagesBack = RESULT_SCHEMA_MAX_MESSAGES_BACK,
|
|
885
|
+
): ResultSchemaLocation | null {
|
|
886
|
+
if (!sessionPath || !existsSync(sessionPath)) return null;
|
|
887
|
+
try {
|
|
888
|
+
const lines = readFileSync(sessionPath, "utf-8").split("\n");
|
|
889
|
+
let seen = 0;
|
|
890
|
+
for (let i = lines.length - 1; i >= 0 && seen < maxMessagesBack; i--) {
|
|
891
|
+
const line = lines[i].trim();
|
|
892
|
+
if (!line) continue;
|
|
893
|
+
let record: Record<string, unknown>;
|
|
894
|
+
try {
|
|
895
|
+
record = JSON.parse(line) as Record<string, unknown>;
|
|
896
|
+
} catch {
|
|
897
|
+
continue;
|
|
898
|
+
}
|
|
899
|
+
const message = record.message as { role?: string; content?: unknown } | undefined;
|
|
900
|
+
if (record.type !== "message" || message?.role !== "assistant") continue;
|
|
901
|
+
|
|
902
|
+
const offset = seen;
|
|
903
|
+
seen++;
|
|
904
|
+
const parsed = extractResultBlock(message.content);
|
|
905
|
+
if (parsed) return { schema: parsed, messageOffset: offset };
|
|
906
|
+
}
|
|
907
|
+
return null;
|
|
908
|
+
} catch {
|
|
909
|
+
return null;
|
|
910
|
+
}
|
|
911
|
+
}
|
|
912
|
+
|
|
913
|
+
/** True when the session carries a valid result block within the scan window. */
|
|
914
|
+
export function validateResultSchema(sessionPath: string | null): boolean {
|
|
915
|
+
return locateResultSchema(sessionPath) !== null;
|
|
916
|
+
}
|
|
917
|
+
|
|
918
|
+
// ── Effect evidence ────────────────────────────────────────────────────────
|
|
919
|
+
|
|
920
|
+
/**
|
|
921
|
+
* The phrase a terminal completion without effect evidence is flagged with,
|
|
922
|
+
* in the close-worker result and in check-worker's verdict output. One
|
|
923
|
+
* declared source: the renderers and the tests read it from here, so the
|
|
924
|
+
* phrase cannot drift between the two surfaces.
|
|
925
|
+
*/
|
|
926
|
+
export const WORKER_EFFECT_EVIDENCE_FLAG = "no effect evidence";
|
|
927
|
+
|
|
928
|
+
/**
|
|
929
|
+
* The three kinds of effect evidence a terminal completion is judged by. A
|
|
930
|
+
* completion that produced none of them — no deliverable written during the
|
|
931
|
+
* run, no commit landed, no gate reproduced — is the claims-without-artifacts
|
|
932
|
+
* class the flag names.
|
|
933
|
+
*/
|
|
934
|
+
export interface WorkerEffectEvidence {
|
|
935
|
+
/** The deliverable exists and its mtime is not before the worker spawned. */
|
|
936
|
+
outputWritten: boolean;
|
|
937
|
+
/** The worker's branch is ahead of its base, or a merge sha is recorded. */
|
|
938
|
+
branchAdvanced: boolean;
|
|
939
|
+
/** At least one recorded gate exited 0. */
|
|
940
|
+
gatePassed: boolean;
|
|
941
|
+
/** True when none of the three kinds holds. */
|
|
942
|
+
none: boolean;
|
|
943
|
+
}
|
|
944
|
+
|
|
945
|
+
/** The facts effect evidence needs that the registry row alone cannot supply. */
|
|
946
|
+
export interface WorkerEffectFacts {
|
|
947
|
+
/** The output file's mtime in ms, or null when it does not exist. */
|
|
948
|
+
outputMtimeMs: number | null;
|
|
949
|
+
/** Commits on the worker's branch beyond its base, or null when uncountable. */
|
|
950
|
+
branchAhead: number | null;
|
|
951
|
+
}
|
|
952
|
+
|
|
953
|
+
/**
|
|
954
|
+
* Judge a terminal completion's effect evidence. Pure over the entry and the
|
|
955
|
+
* gathered facts: the deliverable was written during the run (mtime not
|
|
956
|
+
* before spawnedAt), the branch advanced (ahead >= 1) or a merge sha stands
|
|
957
|
+
* in for it, or a recorded gate exited 0. Any one kind is evidence; none is
|
|
958
|
+
* the flag.
|
|
959
|
+
*/
|
|
960
|
+
export function workerEffectEvidence(
|
|
961
|
+
entry: Pick<WorkerEntry, "spawnedAt" | "mergeSha" | "gates">,
|
|
962
|
+
facts: WorkerEffectFacts,
|
|
963
|
+
): WorkerEffectEvidence {
|
|
964
|
+
const spawnedAt = Date.parse(entry.spawnedAt);
|
|
965
|
+
const outputWritten =
|
|
966
|
+
facts.outputMtimeMs !== null && Number.isFinite(spawnedAt)
|
|
967
|
+
? facts.outputMtimeMs >= spawnedAt
|
|
968
|
+
: false;
|
|
969
|
+
const branchAdvanced =
|
|
970
|
+
(typeof facts.branchAhead === "number" && facts.branchAhead >= 1) || Boolean(entry.mergeSha);
|
|
971
|
+
const gatePassed = Array.isArray(entry.gates)
|
|
972
|
+
? entry.gates.some(
|
|
973
|
+
(gate) =>
|
|
974
|
+
gate !== null &&
|
|
975
|
+
typeof gate === "object" &&
|
|
976
|
+
typeof gate.exit === "number" &&
|
|
977
|
+
Number.isFinite(gate.exit) &&
|
|
978
|
+
gate.exit === 0,
|
|
979
|
+
)
|
|
980
|
+
: false;
|
|
981
|
+
return {
|
|
982
|
+
outputWritten,
|
|
983
|
+
branchAdvanced,
|
|
984
|
+
gatePassed,
|
|
985
|
+
none: !outputWritten && !branchAdvanced && !gatePassed,
|
|
986
|
+
};
|
|
987
|
+
}
|
|
988
|
+
|
|
989
|
+
/**
|
|
990
|
+
* Gather the facts effect evidence needs and judge the entry: one stat for
|
|
991
|
+
* the deliverable's mtime, one git rev-list for the branch count. The branch
|
|
992
|
+
* is the entry's own — the worker's lock rows are released before a close is
|
|
993
|
+
* judged, and a merge sha stands in for an advanced branch once the work
|
|
994
|
+
* landed.
|
|
995
|
+
*/
|
|
996
|
+
export function workerEffectEvidenceForEntry(
|
|
997
|
+
entry: WorkerEntry,
|
|
998
|
+
opts: { cwd?: string } = {},
|
|
999
|
+
): WorkerEffectEvidence {
|
|
1000
|
+
return workerEffectEvidence(entry, {
|
|
1001
|
+
outputMtimeMs: fileMtimeMs(entry.outputFile),
|
|
1002
|
+
branchAhead: countBranchAhead(entry.branch, opts.cwd),
|
|
1003
|
+
});
|
|
1004
|
+
}
|
|
1005
|
+
|
|
1006
|
+
// ── Verdict computation ────────────────────────────────────────────────────
|
|
1007
|
+
|
|
1008
|
+
function fileAgeSec(file: string | null, now: number): number | null {
|
|
1009
|
+
if (!file) return null;
|
|
1010
|
+
try {
|
|
1011
|
+
return Math.max(0, Math.round((now - statSync(file).mtimeMs) / 1000));
|
|
1012
|
+
} catch {
|
|
1013
|
+
return null;
|
|
1014
|
+
}
|
|
1015
|
+
}
|
|
1016
|
+
|
|
1017
|
+
/** The file's mtime in ms, or null when it does not exist. */
|
|
1018
|
+
function fileMtimeMs(file: string | null): number | null {
|
|
1019
|
+
if (!file) return null;
|
|
1020
|
+
try {
|
|
1021
|
+
return statSync(file).mtimeMs;
|
|
1022
|
+
} catch {
|
|
1023
|
+
return null;
|
|
1024
|
+
}
|
|
1025
|
+
}
|
|
1026
|
+
|
|
1027
|
+
function countBranchAhead(branch: string | null, cwd?: string): number | null {
|
|
1028
|
+
if (!branch || !cwd) return null;
|
|
1029
|
+
try {
|
|
1030
|
+
const out = execFileSync("git", ["rev-list", "--count", `HEAD..${branch}`], {
|
|
1031
|
+
cwd,
|
|
1032
|
+
encoding: "utf-8",
|
|
1033
|
+
stdio: ["ignore", "pipe", "ignore"],
|
|
1034
|
+
});
|
|
1035
|
+
const count = Number.parseInt(out.trim(), 10);
|
|
1036
|
+
return Number.isFinite(count) ? count : null;
|
|
1037
|
+
} catch {
|
|
1038
|
+
return null;
|
|
1039
|
+
}
|
|
1040
|
+
}
|
|
1041
|
+
|
|
1042
|
+
function summarizeGates(gates: WorkerGate[]): string {
|
|
1043
|
+
if (!gates || gates.length === 0) return "no gates recorded";
|
|
1044
|
+
const failed = gates.filter((gate) => gate.exit !== 0);
|
|
1045
|
+
if (failed.length === 0) return `${gates.length}/${gates.length} passed`;
|
|
1046
|
+
return `${gates.length - failed.length}/${gates.length} passed; failing: ${failed
|
|
1047
|
+
.map((gate) => gate.cmd)
|
|
1048
|
+
.join(", ")}`;
|
|
1049
|
+
}
|
|
1050
|
+
|
|
1051
|
+
function normalizeLiveStatus(raw?: string): "working" | "blocked" | "done" | "idle" | null {
|
|
1052
|
+
if (!raw) return null;
|
|
1053
|
+
const value = raw.trim().toLowerCase();
|
|
1054
|
+
if (value === "working" || value === "blocked" || value === "done" || value === "idle") {
|
|
1055
|
+
return value;
|
|
1056
|
+
}
|
|
1057
|
+
return null;
|
|
1058
|
+
}
|
|
1059
|
+
|
|
1060
|
+
/**
|
|
1061
|
+
* Compute the verdict for a worker entry. `completed` requires the output
|
|
1062
|
+
* file to exist and the result schema to parse (impl spec also requires at
|
|
1063
|
+
* least one commit on the worker branch); a live "done"/"idle" status with
|
|
1064
|
+
* missing evidence is encoded as `false-done`, never `completed`.
|
|
1065
|
+
*
|
|
1066
|
+
* The branch-ahead count uses `entry.branch`, falling back to the branch on
|
|
1067
|
+
* this worker's lock rows (`opts.fallbackBranch`) when the entry has none, so
|
|
1068
|
+
* an entry with a stale null branch does not hide a branch that carries the
|
|
1069
|
+
* worker's commit.
|
|
1070
|
+
*
|
|
1071
|
+
* Liveness, when the parent passes no live state, comes from the recorded
|
|
1072
|
+
* session file's mtime: written within the stall window reads as `working`,
|
|
1073
|
+
* frozen without an output reads as `stalled`, and no recorded session leaves
|
|
1074
|
+
* an admitted row as `admitted`. The pane is never read as liveness.
|
|
1075
|
+
*
|
|
1076
|
+
* A checkpoint changes only the two verdicts that would otherwise leave the
|
|
1077
|
+
* parent guessing: a frozen session, or no session evidence at all, reads as
|
|
1078
|
+
* `resumable` — never as a stale `working` — and the verdict carries the
|
|
1079
|
+
* phase, the last completed step, and the request id to resume under. A
|
|
1080
|
+
* recorded stall or false-done mark and a live status the parent passed stay
|
|
1081
|
+
* as they are: those are decisions and direct observations, not inferences a
|
|
1082
|
+
* checkpoint may override. Evidence of completion still wins over the resume
|
|
1083
|
+
* point.
|
|
1084
|
+
*
|
|
1085
|
+
* A row closed as `completed` also carries its effect evidence: whether the
|
|
1086
|
+
* deliverable was written during the run (mtime not before spawnedAt),
|
|
1087
|
+
* whether the branch advanced or a merge sha is recorded, and whether any
|
|
1088
|
+
* recorded gate exited 0. None of the three is the no-effect-evidence flag;
|
|
1089
|
+
* the flag is a field on the verdict, never a different status, and a row
|
|
1090
|
+
* that is not a terminal completion carries null.
|
|
1091
|
+
*/
|
|
1092
|
+
export function evaluateWorker(
|
|
1093
|
+
entry: WorkerEntry,
|
|
1094
|
+
opts: WorkerCheckOptions = {},
|
|
1095
|
+
): WorkerCheckResult {
|
|
1096
|
+
const now = opts.now ?? Date.now();
|
|
1097
|
+
const stalledAfterSec = opts.stalledAfterSec ?? DEFAULT_STALLED_AFTER_SEC;
|
|
1098
|
+
|
|
1099
|
+
const outputExists =
|
|
1100
|
+
typeof entry.outputFile === "string" &&
|
|
1101
|
+
entry.outputFile.length > 0 &&
|
|
1102
|
+
existsSync(entry.outputFile);
|
|
1103
|
+
const outputAgeSec = outputExists ? fileAgeSec(entry.outputFile, now) : null;
|
|
1104
|
+
const sessionGrowthAgeSec = fileAgeSec(entry.workerSession, now);
|
|
1105
|
+
const locatedResult = locateResultSchema(entry.workerSession);
|
|
1106
|
+
const schemaValid = locatedResult !== null;
|
|
1107
|
+
const resultSchemaMessageOffset = locatedResult?.messageOffset ?? null;
|
|
1108
|
+
const effectiveBranch = entry.branch ?? opts.fallbackBranch ?? null;
|
|
1109
|
+
const branchAhead = countBranchAhead(effectiveBranch, opts.cwd);
|
|
1110
|
+
const gateSummary = summarizeGates(entry.gates);
|
|
1111
|
+
const effectEvidence =
|
|
1112
|
+
entry.closedAt && entry.status === "completed"
|
|
1113
|
+
? workerEffectEvidence(entry, {
|
|
1114
|
+
outputMtimeMs: fileMtimeMs(entry.outputFile),
|
|
1115
|
+
branchAhead,
|
|
1116
|
+
})
|
|
1117
|
+
: null;
|
|
1118
|
+
// The stall window is read once: a session written inside it is liveness a
|
|
1119
|
+
// checkpoint must not outrank, and it is the only case where a checkpoint
|
|
1120
|
+
// changes the verdict.
|
|
1121
|
+
const frozen = sessionGrowthAgeSec !== null && sessionGrowthAgeSec > stalledAfterSec;
|
|
1122
|
+
const requestId = entry.requestId ?? null;
|
|
1123
|
+
const checkpoint = entry.checkpoint ?? null;
|
|
1124
|
+
|
|
1125
|
+
const base = {
|
|
1126
|
+
workerId: entry.workerId,
|
|
1127
|
+
outputFile: entry.outputFile,
|
|
1128
|
+
outputExists,
|
|
1129
|
+
outputAgeSec,
|
|
1130
|
+
sessionGrowthAgeSec,
|
|
1131
|
+
branchAhead,
|
|
1132
|
+
schemaValid,
|
|
1133
|
+
resultSchemaMessageOffset,
|
|
1134
|
+
requestId,
|
|
1135
|
+
checkpoint,
|
|
1136
|
+
gateSummary,
|
|
1137
|
+
effectEvidence,
|
|
1138
|
+
};
|
|
1139
|
+
|
|
1140
|
+
const blockers: string[] = [];
|
|
1141
|
+
if (!outputExists) blockers.push("output file missing");
|
|
1142
|
+
if (!schemaValid) blockers.push("result schema missing");
|
|
1143
|
+
if (entry.spec === "impl" && !(typeof branchAhead === "number" && branchAhead > 0)) {
|
|
1144
|
+
blockers.push("no commit on worker branch");
|
|
1145
|
+
}
|
|
1146
|
+
const commitNote = entry.spec === "impl" ? " + commit present" : "";
|
|
1147
|
+
|
|
1148
|
+
if (entry.closedAt) {
|
|
1149
|
+
return {
|
|
1150
|
+
...base,
|
|
1151
|
+
status: "closed",
|
|
1152
|
+
reason: `closed ${entry.closedAt} with outcome ${entry.status}`,
|
|
1153
|
+
};
|
|
1154
|
+
}
|
|
1155
|
+
if (entry.status === "error") {
|
|
1156
|
+
return { ...base, status: "error", reason: "registry marked error" };
|
|
1157
|
+
}
|
|
1158
|
+
|
|
1159
|
+
const live = normalizeLiveStatus(opts.liveStatus);
|
|
1160
|
+
if (live === "working") {
|
|
1161
|
+
return { ...base, status: "working", reason: "live status working" };
|
|
1162
|
+
}
|
|
1163
|
+
if (live === "blocked") {
|
|
1164
|
+
return { ...base, status: "stalled", reason: "live status blocked" };
|
|
1165
|
+
}
|
|
1166
|
+
if (live === "done" || live === "idle") {
|
|
1167
|
+
if (blockers.length === 0) {
|
|
1168
|
+
return {
|
|
1169
|
+
...base,
|
|
1170
|
+
status: "completed",
|
|
1171
|
+
reason: `live status ${live}; output + schema verified${commitNote}`,
|
|
1172
|
+
};
|
|
1173
|
+
}
|
|
1174
|
+
return {
|
|
1175
|
+
...base,
|
|
1176
|
+
status: "false-done",
|
|
1177
|
+
reason: `live status ${live} but ${blockers.join("; ")}`,
|
|
1178
|
+
};
|
|
1179
|
+
}
|
|
1180
|
+
|
|
1181
|
+
// No usable live status: evidence wins over registry declarations.
|
|
1182
|
+
if (blockers.length === 0) {
|
|
1183
|
+
return { ...base, status: "completed", reason: `output + schema verified${commitNote}` };
|
|
1184
|
+
}
|
|
1185
|
+
if (entry.status === "stalled") {
|
|
1186
|
+
return {
|
|
1187
|
+
...base,
|
|
1188
|
+
status: "stalled",
|
|
1189
|
+
reason: `registry marked stalled; ${blockers.join("; ")}`,
|
|
1190
|
+
};
|
|
1191
|
+
}
|
|
1192
|
+
if (entry.status === "false-done") {
|
|
1193
|
+
return {
|
|
1194
|
+
...base,
|
|
1195
|
+
status: "false-done",
|
|
1196
|
+
reason: `registry marked false-done; ${blockers.join("; ")}`,
|
|
1197
|
+
};
|
|
1198
|
+
}
|
|
1199
|
+
if (entry.status === "merged") {
|
|
1200
|
+
// The work landed, so the row is not "in flight": an unclosed merged row
|
|
1201
|
+
// reports what is still missing from its record instead.
|
|
1202
|
+
return {
|
|
1203
|
+
...base,
|
|
1204
|
+
status: "merged",
|
|
1205
|
+
reason: `merged at ${entry.mergedAt ?? "unknown"} but ${blockers.join("; ")}`,
|
|
1206
|
+
};
|
|
1207
|
+
}
|
|
1208
|
+
// A frozen session is where a crash leaves a row. With a checkpoint on disk
|
|
1209
|
+
// the resume point survives the crash, so the row reads as resumable rather
|
|
1210
|
+
// than stalled: where the work stopped is on record, not guessed.
|
|
1211
|
+
if (frozen) {
|
|
1212
|
+
if (checkpoint) {
|
|
1213
|
+
return {
|
|
1214
|
+
...base,
|
|
1215
|
+
status: "resumable",
|
|
1216
|
+
reason:
|
|
1217
|
+
`no live status; session frozen for ${sessionGrowthAgeSec}s` +
|
|
1218
|
+
`${outputExists ? "" : " with no output"}; resume from checkpoint ` +
|
|
1219
|
+
`${checkpoint.phase}/${checkpoint.step} (${checkpoint.at})` +
|
|
1220
|
+
`${requestId ? ` under requestId ${requestId}` : ""}`,
|
|
1221
|
+
};
|
|
1222
|
+
}
|
|
1223
|
+
if (!outputExists) {
|
|
1224
|
+
return {
|
|
1225
|
+
...base,
|
|
1226
|
+
status: "stalled",
|
|
1227
|
+
reason: `worker session frozen for ${sessionGrowthAgeSec}s with no output`,
|
|
1228
|
+
};
|
|
1229
|
+
}
|
|
1230
|
+
}
|
|
1231
|
+
// A recorded session file that is still being written is the one liveness
|
|
1232
|
+
// signal the registry owns: the parent does not have to hand a live state to
|
|
1233
|
+
// check-worker before an admitted row reads as more than "not yet observed".
|
|
1234
|
+
// The pane is deliberately not consulted: it is a place to look, not proof
|
|
1235
|
+
// that a process runs there, and the tool never queries herdr itself.
|
|
1236
|
+
if (sessionGrowthAgeSec !== null) {
|
|
1237
|
+
return {
|
|
1238
|
+
...base,
|
|
1239
|
+
status: "working",
|
|
1240
|
+
reason: `session file active ${sessionGrowthAgeSec}s ago${entry.pane ? ` (pane ${entry.pane})` : ""}`,
|
|
1241
|
+
};
|
|
1242
|
+
}
|
|
1243
|
+
// No session handle, or the recorded one is gone: there is no liveness
|
|
1244
|
+
// evidence at all. A checkpoint still says where the work stopped, so the
|
|
1245
|
+
// row reads as resumable; without one it is only "not yet observed".
|
|
1246
|
+
if (checkpoint) {
|
|
1247
|
+
return {
|
|
1248
|
+
...base,
|
|
1249
|
+
status: "resumable",
|
|
1250
|
+
reason:
|
|
1251
|
+
`no live status and ${
|
|
1252
|
+
entry.workerSession
|
|
1253
|
+
? `recorded session ${entry.workerSession} is gone`
|
|
1254
|
+
: "no session handle recorded (register-worker/update-worker `workerSession`)"
|
|
1255
|
+
}; resume from checkpoint ${checkpoint.phase}/${checkpoint.step} (${checkpoint.at})` +
|
|
1256
|
+
`${requestId ? ` under requestId ${requestId}` : ""}`,
|
|
1257
|
+
};
|
|
1258
|
+
}
|
|
1259
|
+
if (entry.status === "admitted") {
|
|
1260
|
+
return {
|
|
1261
|
+
...base,
|
|
1262
|
+
status: "admitted",
|
|
1263
|
+
reason:
|
|
1264
|
+
"no live status and no session handle recorded (register-worker/update-worker `workerSession`); not yet observed running",
|
|
1265
|
+
};
|
|
1266
|
+
}
|
|
1267
|
+
return { ...base, status: "working", reason: "no live status; in flight" };
|
|
1268
|
+
}
|
|
1269
|
+
|
|
1270
|
+
/**
|
|
1271
|
+
* The branch recorded on this worker's lock rows in the given project, or
|
|
1272
|
+
* undefined. Used as the branch fallback when the registry entry has none:
|
|
1273
|
+
* every lock row carries the branch `acquireLock` was given.
|
|
1274
|
+
*/
|
|
1275
|
+
function lockBranchFor(workerId: string, projectCwd: string): string | undefined {
|
|
1276
|
+
for (const lock of Object.values(getAllLocks(projectCwd))) {
|
|
1277
|
+
if (lock.workerId === workerId) return lock.branch;
|
|
1278
|
+
}
|
|
1279
|
+
return undefined;
|
|
1280
|
+
}
|
|
1281
|
+
|
|
1282
|
+
/**
|
|
1283
|
+
* Read the registry and compute the verdict; null when the worker is unknown.
|
|
1284
|
+
* Resolves the branch fallback from the lock table at the entry's own project
|
|
1285
|
+
* key, so a worker located across registries still reads its own locks.
|
|
1286
|
+
*/
|
|
1287
|
+
export function checkWorker(
|
|
1288
|
+
workerId: string,
|
|
1289
|
+
opts: WorkerCheckOptions = {},
|
|
1290
|
+
): WorkerCheckResult | null {
|
|
1291
|
+
const located = locateWorker(workerId, opts.cwd);
|
|
1292
|
+
if (!located) return null;
|
|
1293
|
+
const fallbackBranch = opts.fallbackBranch ?? lockBranchFor(workerId, located.key);
|
|
1294
|
+
return evaluateWorker(located.registry.workers[workerId], { ...opts, fallbackBranch });
|
|
1295
|
+
}
|
|
1296
|
+
|
|
1297
|
+
// ── Fleet statistics ───────────────────────────────────────────────────────
|
|
1298
|
+
|
|
1299
|
+
/** Spawn→result latency over the entries that recorded a result time. */
|
|
1300
|
+
export interface WorkerLatencySummary {
|
|
1301
|
+
/** How many entries contributed a delta; the sample the median is over. */
|
|
1302
|
+
sample: number;
|
|
1303
|
+
/** Median delta in milliseconds, or null when the sample is empty. */
|
|
1304
|
+
medianMs: number | null;
|
|
1305
|
+
minMs: number | null;
|
|
1306
|
+
maxMs: number | null;
|
|
1307
|
+
}
|
|
1308
|
+
|
|
1309
|
+
/** A registry's fleet numbers: what a seat needs to judge its own health. */
|
|
1310
|
+
export interface WorkerStats {
|
|
1311
|
+
/** Every row in the registry. */
|
|
1312
|
+
total: number;
|
|
1313
|
+
/** Rows with no close time — still in flight, or never closed. */
|
|
1314
|
+
live: number;
|
|
1315
|
+
/** Rows with a close time; the denominator of the completion rate. */
|
|
1316
|
+
closed: number;
|
|
1317
|
+
/** Closed rows whose terminal status is `completed`. */
|
|
1318
|
+
completed: number;
|
|
1319
|
+
/** completed / closed, or null when nothing is closed — no rate to state. */
|
|
1320
|
+
completionRate: number | null;
|
|
1321
|
+
/** Spawn→result latency; the sample is stated, never implied by a number. */
|
|
1322
|
+
latency: WorkerLatencySummary;
|
|
1323
|
+
/** Duplicate admissions refused across all rows, summed from their records. */
|
|
1324
|
+
admissionRefusals: number;
|
|
1325
|
+
}
|
|
1326
|
+
|
|
1327
|
+
/** Median of a non-empty list; the mean of the middle pair on an even count. */
|
|
1328
|
+
function median(values: number[]): number | null {
|
|
1329
|
+
if (values.length === 0) return null;
|
|
1330
|
+
const sorted = [...values].sort((a, b) => a - b);
|
|
1331
|
+
const mid = Math.floor(sorted.length / 2);
|
|
1332
|
+
return sorted.length % 2 === 0 ? Math.round((sorted[mid - 1] + sorted[mid]) / 2) : sorted[mid];
|
|
1333
|
+
}
|
|
1334
|
+
|
|
1335
|
+
/**
|
|
1336
|
+
* The spawn→result delta an entry recorded, or null when it has none. A row
|
|
1337
|
+
* with no result time — a worker still in flight, or one that closed without a
|
|
1338
|
+
* result — contributes nothing: it must not enter the median. A malformed or
|
|
1339
|
+
* backwards pair is no delta either.
|
|
1340
|
+
*/
|
|
1341
|
+
function resultLatencyMs(entry: WorkerEntry): number | null {
|
|
1342
|
+
if (!entry.spawnedAt || !entry.resultAt) return null;
|
|
1343
|
+
const spawned = Date.parse(entry.spawnedAt);
|
|
1344
|
+
const result = Date.parse(entry.resultAt);
|
|
1345
|
+
if (!Number.isFinite(spawned) || !Number.isFinite(result)) return null;
|
|
1346
|
+
const delta = result - spawned;
|
|
1347
|
+
return delta >= 0 ? delta : null;
|
|
1348
|
+
}
|
|
1349
|
+
|
|
1350
|
+
/**
|
|
1351
|
+
* Compute a registry's fleet statistics. Pure over the registry value: no
|
|
1352
|
+
* clock, no disk, no verdicts. The latency sample is the entries that recorded
|
|
1353
|
+
* a result time, so an in-flight row is excluded rather than counted at its
|
|
1354
|
+
* close; the completion rate is over closed rows. Every number states its own
|
|
1355
|
+
* denominator, so a small sample reads as small.
|
|
1356
|
+
*/
|
|
1357
|
+
export function computeWorkerStats(registry: WorkerRegistry): WorkerStats {
|
|
1358
|
+
const entries = Object.values(registry.workers);
|
|
1359
|
+
const closed = entries.filter((entry) => Boolean(entry.closedAt));
|
|
1360
|
+
const completed = closed.filter((entry) => entry.status === "completed").length;
|
|
1361
|
+
const latencies: number[] = [];
|
|
1362
|
+
let admissionRefusals = 0;
|
|
1363
|
+
for (const entry of entries) {
|
|
1364
|
+
const delta = resultLatencyMs(entry);
|
|
1365
|
+
if (delta !== null) latencies.push(delta);
|
|
1366
|
+
if (Array.isArray(entry.admissionRefusals)) admissionRefusals += entry.admissionRefusals.length;
|
|
1367
|
+
}
|
|
1368
|
+
return {
|
|
1369
|
+
total: entries.length,
|
|
1370
|
+
live: entries.length - closed.length,
|
|
1371
|
+
closed: closed.length,
|
|
1372
|
+
completed,
|
|
1373
|
+
completionRate: closed.length === 0 ? null : completed / closed.length,
|
|
1374
|
+
latency: {
|
|
1375
|
+
sample: latencies.length,
|
|
1376
|
+
medianMs: median(latencies),
|
|
1377
|
+
minMs: latencies.length === 0 ? null : Math.min(...latencies),
|
|
1378
|
+
maxMs: latencies.length === 0 ? null : Math.max(...latencies),
|
|
1379
|
+
},
|
|
1380
|
+
admissionRefusals,
|
|
1381
|
+
};
|
|
1382
|
+
}
|