@sema-agent/core 7.59.0 → 7.61.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1169 -0
- package/README.md +2 -2
- package/dist/agents/agent-definition.d.ts +7 -0
- package/dist/agents/agent-definition.js +12 -0
- package/dist/agents/agent-transcript-tool.d.ts +4 -3
- package/dist/agents/agent-transcript-tool.js +4 -2
- package/dist/agents/cascade.d.ts +61 -10
- package/dist/agents/cascade.js +60 -20
- package/dist/agents/child-model-seat.js +6 -3
- package/dist/agents/composition-allowance.d.ts +53 -0
- package/dist/agents/composition-allowance.js +49 -0
- package/dist/agents/composition-placement.d.ts +29 -0
- package/dist/agents/composition-placement.js +24 -0
- package/dist/agents/cumulative-stats.d.ts +4 -0
- package/dist/agents/cumulative-stats.js +3 -1
- package/dist/agents/inherited-tool-pool.d.ts +28 -1
- package/dist/agents/inherited-tool-pool.js +22 -0
- package/dist/agents/list-agents-tool.d.ts +1 -1
- package/dist/agents/peer-notice-route.d.ts +1 -1
- package/dist/agents/peer-notice-route.js +4 -3
- package/dist/agents/peer-notices.d.ts +4 -4
- package/dist/agents/peer-notices.js +8 -4
- package/dist/agents/peer-session-drain.d.ts +8 -1
- package/dist/agents/peer-session-drain.js +36 -7
- package/dist/agents/repair-loop.js +16 -6
- package/dist/agents/retain-ledger.d.ts +11 -1
- package/dist/agents/retain-ledger.js +16 -3
- package/dist/agents/roster-store.d.ts +2 -2
- package/dist/agents/roster-store.js +8 -3
- package/dist/agents/send-message-tool.d.ts +14 -27
- package/dist/agents/send-message-tool.js +47 -54
- package/dist/agents/subagent-completion-gate.d.ts +35 -0
- package/dist/agents/subagent-completion-gate.js +62 -0
- package/dist/agents/subagent-steps.d.ts +7 -6
- package/dist/agents/subagent.d.ts +52 -28
- package/dist/agents/subagent.js +276 -246
- package/dist/agents/suspend-guard.d.ts +9 -0
- package/dist/agents/suspend-guard.js +4 -0
- package/dist/agents/tool-filter.d.ts +1 -3
- package/dist/agents/tool-filter.js +4 -12
- package/dist/agents/verify.d.ts +41 -14
- package/dist/agents/verify.js +37 -27
- package/dist/bench/metrics.d.ts +3 -5
- package/dist/bench/metrics.js +0 -1
- package/dist/brain/anthropic.js +1 -0
- package/dist/brain/degrading.js +3 -1
- package/dist/brain/errors.d.ts +7 -1
- package/dist/brain/errors.js +6 -0
- package/dist/brain/failover.js +2 -1
- package/dist/brain/open-responses.js +1 -0
- package/dist/brain/openai.js +1 -0
- package/dist/brain/provider-dialect.d.ts +10 -0
- package/dist/brain/provider-dialect.js +13 -2
- package/dist/brain/route-adjudicator.js +3 -1
- package/dist/brain/status-sink.d.ts +7 -1
- package/dist/brain/status-sink.js +6 -0
- package/dist/brain/stream-engine.d.ts +3 -0
- package/dist/brain/stream-engine.js +4 -0
- package/dist/brain/timeout.d.ts +3 -1
- package/dist/brain/timeout.js +18 -5
- package/dist/core/a2a.d.ts +15 -5
- package/dist/core/a2a.js +34 -19
- package/dist/core/agent-definition.d.ts +20 -0
- package/dist/core/agent-state.d.ts +1 -1
- package/dist/core/allow-entry.d.ts +61 -23
- package/dist/core/allow-entry.js +134 -39
- package/dist/core/artifact-host.d.ts +0 -2
- package/dist/core/artifact-host.js +0 -1
- package/dist/core/ask-origin.d.ts +79 -0
- package/dist/core/ask-origin.js +76 -0
- package/dist/core/ask-question.d.ts +19 -13
- package/dist/core/ask-question.js +8 -2
- package/dist/core/auto-compaction.d.ts +2 -0
- package/dist/core/auto-compaction.js +2 -1
- package/dist/core/auto-mode-defaults.d.ts +8 -0
- package/dist/core/auto-mode-defaults.js +1 -0
- package/dist/core/auto-mode-rebuild.d.ts +2 -1
- package/dist/core/auto-mode.d.ts +39 -4
- package/dist/core/auto-mode.js +66 -17
- package/dist/core/background-agent-store.d.ts +17 -6
- package/dist/core/background-agent-store.js +15 -13
- package/dist/core/background-shell.d.ts +12 -1
- package/dist/core/background-shell.js +12 -0
- package/dist/core/checkpoint-requirements.d.ts +24 -3
- package/dist/core/checkpoint-requirements.js +9 -1
- package/dist/core/checkpoint-store.d.ts +86 -32
- package/dist/core/checkpoint-store.js +10 -5
- package/dist/core/child-clamp-seats.d.ts +3 -2
- package/dist/core/child-clamp-seats.js +4 -3
- package/dist/core/closest-name.d.ts +13 -0
- package/dist/core/closest-name.js +35 -0
- package/dist/core/compliance.d.ts +1 -1
- package/dist/core/context-settings.js +3 -5
- package/dist/core/credential-echo.d.ts +52 -0
- package/dist/core/credential-echo.js +65 -0
- package/dist/core/credential-vocabulary.d.ts +13 -3
- package/dist/core/credential-vocabulary.js +12 -4
- package/dist/core/cross-boundary-taint.d.ts +5 -6
- package/dist/core/decision-receipt.d.ts +14 -1
- package/dist/core/decision-receipt.js +6 -3
- package/dist/core/delegation-frames.d.ts +13 -9
- package/dist/core/effective-path-target.js +2 -3
- package/dist/core/engine-attestation.d.ts +11 -1
- package/dist/core/engine-attestation.js +2 -0
- package/dist/core/engine-notice.d.ts +106 -32
- package/dist/core/file-history-retention.d.ts +8 -0
- package/dist/core/file-history-retention.js +14 -11
- package/dist/core/file-history-store.d.ts +31 -1
- package/dist/core/file-history-store.js +31 -2
- package/dist/core/frame-settlement.d.ts +15 -0
- package/dist/core/frame-settlement.js +10 -1
- package/dist/core/fs-write-gate-policy.d.ts +3 -3
- package/dist/core/fs-write-gate-policy.js +8 -7
- package/dist/core/gate-fold.js +9 -6
- package/dist/core/gate-lanes.js +46 -12
- package/dist/core/gate-outcome.d.ts +40 -1
- package/dist/core/gate-outcome.js +10 -0
- package/dist/core/git-worktree-env.d.ts +7 -3
- package/dist/core/git-worktree-env.js +16 -13
- package/dist/core/governance-codes.d.ts +19 -3
- package/dist/core/governance-codes.js +27 -3
- package/dist/core/hands-band-screen.js +0 -1
- package/dist/core/hands-band.d.ts +0 -3
- package/dist/core/hooks.d.ts +51 -60
- package/dist/core/hooks.js +131 -78
- package/dist/core/host-floor.js +3 -5
- package/dist/core/image-admission.d.ts +145 -52
- package/dist/core/image-admission.js +202 -47
- package/dist/core/image-downsample.d.ts +36 -69
- package/dist/core/image-downsample.js +111 -73
- package/dist/core/input-author.d.ts +36 -0
- package/dist/core/input-author.js +39 -0
- package/dist/core/integer-option.d.ts +21 -0
- package/dist/core/integer-option.js +13 -0
- package/dist/core/leg-identity.d.ts +62 -0
- package/dist/core/leg-identity.js +18 -0
- package/dist/core/locked-config.d.ts +55 -3
- package/dist/core/locked-config.js +84 -51
- package/dist/core/lsp.d.ts +5 -3
- package/dist/core/lsp.js +3 -2
- package/dist/core/mailbox-store.d.ts +85 -10
- package/dist/core/mailbox-store.js +31 -10
- package/dist/core/mcp-call-meta.d.ts +2 -2
- package/dist/core/mcp-call-meta.js +9 -10
- package/dist/core/mcp-connection-pool.d.ts +6 -20
- package/dist/core/mcp-connection-pool.js +10 -28
- package/dist/core/mcp-failure.d.ts +83 -16
- package/dist/core/mcp-failure.js +67 -30
- package/dist/core/mcp-host-seat.d.ts +131 -0
- package/dist/core/mcp-host-seat.js +305 -0
- package/dist/core/mcp-probe.d.ts +7 -2
- package/dist/core/mcp-probe.js +9 -4
- package/dist/core/mcp-server-link.d.ts +18 -6
- package/dist/core/mcp-server-link.js +19 -4
- package/dist/core/mcp-server-spec.d.ts +39 -9
- package/dist/core/mcp-server-spec.js +55 -21
- package/dist/core/mcp-session-end.d.ts +1 -2
- package/dist/core/mcp-session-end.js +1 -1
- package/dist/core/mcp.d.ts +23 -55
- package/dist/core/mcp.js +172 -156
- package/dist/core/media-byte-cap.d.ts +21 -46
- package/dist/core/media-byte-cap.js +55 -55
- package/dist/core/member-group.d.ts +7 -0
- package/dist/core/member-group.js +35 -0
- package/dist/core/memory-admission.d.ts +23 -6
- package/dist/core/memory-admission.js +19 -9
- package/dist/core/memory-engine/consolidation.d.ts +1 -1
- package/dist/core/memory-engine/consolidation.js +7 -1
- package/dist/core/memory-engine/content-origin.d.ts +13 -0
- package/dist/core/memory-engine/content-origin.js +21 -3
- package/dist/core/memory-engine/dual-root.d.ts +31 -0
- package/dist/core/memory-engine/dual-root.js +59 -11
- package/dist/core/memory-engine/engine.js +27 -24
- package/dist/core/memory-engine/file-backend.d.ts +13 -0
- package/dist/core/memory-engine/file-backend.js +35 -15
- package/dist/core/memory-engine/index.d.ts +2 -1
- package/dist/core/memory-engine/index.js +2 -1
- package/dist/core/memory-engine/layout.d.ts +3 -0
- package/dist/core/memory-engine/layout.js +13 -3
- package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
- package/dist/core/memory-engine/memory-deployment.js +182 -0
- package/dist/core/memory-engine/scope-contract.d.ts +13 -3
- package/dist/core/memory-engine/scope-contract.js +2 -2
- package/dist/core/memory-engine/sync-client.d.ts +68 -13
- package/dist/core/memory-engine/sync-client.js +147 -18
- package/dist/core/memory-engine/sync-report.d.ts +106 -0
- package/dist/core/memory-engine/sync-report.js +119 -0
- package/dist/core/memory-engine/sync.d.ts +13 -3
- package/dist/core/mode-policy.d.ts +15 -7
- package/dist/core/mode-policy.js +18 -6
- package/dist/core/model-receipt.d.ts +39 -0
- package/dist/core/model-receipt.js +139 -0
- package/dist/core/mods/agent-stations.d.ts +100 -0
- package/dist/core/mods/agent-stations.js +154 -0
- package/dist/core/mods/dollar.d.ts +62 -0
- package/dist/core/mods/extension-call.d.ts +15 -1
- package/dist/core/mods/extension-call.js +7 -2
- package/dist/core/mods/kernel/dispatch.d.ts +9 -4
- package/dist/core/mods/kernel/dispatch.js +8 -8
- package/dist/core/mods/kernel/events.d.ts +13 -4
- package/dist/core/mods/kernel/events.js +14 -10
- package/dist/core/mods/kernel/receive.d.ts +5 -0
- package/dist/core/mods/kernel/receive.js +10 -0
- package/dist/core/mods/kernel/registration.d.ts +3 -0
- package/dist/core/mods/kernel/registration.js +5 -0
- package/dist/core/mods/kernel/site-rules.d.ts +6 -3
- package/dist/core/mods/kernel/site-rules.js +10 -2
- package/dist/core/mods/lifecycle-stations.d.ts +41 -0
- package/dist/core/mods/lifecycle-stations.js +35 -0
- package/dist/core/mods/session-append.d.ts +115 -0
- package/dist/core/mods/session-append.js +311 -0
- package/dist/core/mods/session-compact.d.ts +48 -0
- package/dist/core/mods/session-compact.js +194 -0
- package/dist/core/mods/session-receive.d.ts +93 -0
- package/dist/core/mods/session-receive.js +141 -0
- package/dist/core/mods/session-send.d.ts +72 -0
- package/dist/core/mods/session-send.js +88 -0
- package/dist/core/mods/stations.d.ts +89 -75
- package/dist/core/mods/stations.js +57 -53
- package/dist/core/mods/tool-call.d.ts +12 -4
- package/dist/core/mods/tool-call.js +32 -16
- package/dist/core/mounted-mcp.d.ts +5 -0
- package/dist/core/mounted-mcp.js +2 -2
- package/dist/core/namespaced-rule-name.d.ts +7 -1
- package/dist/core/namespaced-rule-name.js +13 -2
- package/dist/core/oracle-isolation.js +1 -1
- package/dist/core/output-style.js +3 -4
- package/dist/core/own-property-receipt.d.ts +62 -0
- package/dist/core/own-property-receipt.js +43 -0
- package/dist/core/park-selfcheck.js +12 -10
- package/dist/core/path-identity.d.ts +11 -0
- package/dist/core/path-identity.js +4 -0
- package/dist/core/path-rule-binding.d.ts +3 -1
- package/dist/core/path-rule-binding.js +3 -1
- package/dist/core/peer-seat.d.ts +66 -11
- package/dist/core/peer-seat.js +199 -42
- package/dist/core/permission-rule-consent.d.ts +21 -26
- package/dist/core/permission-rule-consent.js +22 -3
- package/dist/core/permission-rule-model.d.ts +38 -13
- package/dist/core/permission-rule-model.js +54 -16
- package/dist/core/permission-rule-org.d.ts +1 -1
- package/dist/core/permission-rule-provider.js +4 -1
- package/dist/core/permission-rules.d.ts +4 -0
- package/dist/core/permission-rules.js +11 -16
- package/dist/core/protocol-http-auth.d.ts +14 -2
- package/dist/core/protocol-http-auth.js +16 -7
- package/dist/core/read-face-seats.d.ts +7 -5
- package/dist/core/read-face-seats.js +4 -1
- package/dist/core/redaction-marks.d.ts +4 -3
- package/dist/core/redaction-marks.js +2 -2
- package/dist/core/remote-env.d.ts +218 -122
- package/dist/core/remote-env.js +133 -14
- package/dist/core/retention-policy.d.ts +24 -23
- package/dist/core/retention-policy.js +36 -2
- package/dist/core/retention.d.ts +4 -1
- package/dist/core/retention.js +37 -12
- package/dist/core/retired-keys.d.ts +8 -3
- package/dist/core/retired-keys.js +4 -1
- package/dist/core/rewrite-rejudge.d.ts +12 -5
- package/dist/core/rewrite-rejudge.js +9 -5
- package/dist/core/roles.d.ts +37 -3
- package/dist/core/roles.js +126 -78
- package/dist/core/row-admission.d.ts +10 -0
- package/dist/core/row-admission.js +5 -0
- package/dist/core/rule-owner.d.ts +3 -0
- package/dist/core/runner/advisor-instructions.d.ts +2 -1
- package/dist/core/runner/advisor-instructions.js +2 -1
- package/dist/core/runner/announce-once-ledger.d.ts +4 -4
- package/dist/core/runner/assemble-result.d.ts +13 -8
- package/dist/core/runner/assemble-result.js +12 -8
- package/dist/core/runner/call-hook-stations.d.ts +17 -10
- package/dist/core/runner/call-hook-stations.js +21 -10
- package/dist/core/runner/caller-roster.d.ts +12 -9
- package/dist/core/runner/caller-roster.js +5 -2
- package/dist/core/runner/checkpoint-scope.d.ts +16 -1
- package/dist/core/runner/checkpoint-scope.js +21 -0
- package/dist/core/runner/child-tree.d.ts +7 -8
- package/dist/core/runner/child-tree.js +6 -6
- package/dist/core/runner/classifier-ladder.d.ts +10 -2
- package/dist/core/runner/classifier-ladder.js +39 -8
- package/dist/core/runner/compact-session.js +14 -2
- package/dist/core/runner/compaction-call-options.d.ts +1 -1
- package/dist/core/runner/compaction-restate.d.ts +2 -2
- package/dist/core/runner/compaction-restate.js +4 -3
- package/dist/core/runner/construction-doors.d.ts +2 -2
- package/dist/core/runner/construction-doors.js +7 -2
- package/dist/core/runner/contracts.d.ts +158 -65
- package/dist/core/runner/cross-boundary-lane.d.ts +4 -6
- package/dist/core/runner/cross-boundary-lane.js +11 -2
- package/dist/core/runner/decide-continuation.d.ts +4 -2
- package/dist/core/runner/decide-continuation.js +7 -4
- package/dist/core/runner/denial-limit-arms.d.ts +15 -21
- package/dist/core/runner/denial-limit-arms.js +17 -10
- package/dist/core/runner/env-capability-census.d.ts +15 -20
- package/dist/core/runner/env-capability-census.js +25 -34
- package/dist/core/runner/expire-settle.d.ts +44 -0
- package/dist/core/runner/expire-settle.js +55 -0
- package/dist/core/runner/file-history-request.d.ts +2 -2
- package/dist/core/runner/file-history-request.js +0 -8
- package/dist/core/runner/gate-exit.d.ts +75 -7
- package/dist/core/runner/gate-exit.js +20 -1
- package/dist/core/runner/git-status-frame.d.ts +5 -2
- package/dist/core/runner/git-status-frame.js +4 -4
- package/dist/core/runner/halt-attribution.d.ts +2 -1
- package/dist/core/runner/halt-attribution.js +2 -1
- package/dist/core/runner/image.d.ts +7 -2
- package/dist/core/runner/image.js +14 -8
- package/dist/core/runner/inline-image.d.ts +10 -8
- package/dist/core/runner/inline-image.js +11 -9
- package/dist/core/runner/local-claims.d.ts +17 -0
- package/dist/core/runner/local-claims.js +18 -0
- package/dist/core/runner/media-removed-seat.d.ts +46 -0
- package/dist/core/runner/media-removed-seat.js +88 -0
- package/dist/core/runner/memory-consolidation-driver.js +4 -4
- package/dist/core/runner/park-commit.d.ts +2 -2
- package/dist/core/runner/permission-rule-lanes.d.ts +5 -1
- package/dist/core/runner/permission-rule-lanes.js +29 -10
- package/dist/core/runner/person-path-rows.js +1 -1
- package/dist/core/runner/placement-fence.d.ts +26 -0
- package/dist/core/runner/placement-fence.js +38 -0
- package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
- package/dist/core/runner/prepare-ask-lane.js +4 -4
- package/dist/core/runner/prepare-boundary-parks.d.ts +6 -3
- package/dist/core/runner/prepare-boundary-parks.js +4 -4
- package/dist/core/runner/prepare-caps-and-workflow.d.ts +6 -0
- package/dist/core/runner/prepare-caps-and-workflow.js +5 -3
- package/dist/core/runner/prepare-config-doors.d.ts +6 -1
- package/dist/core/runner/prepare-config-doors.js +30 -26
- package/dist/core/runner/prepare-context-lane.d.ts +6 -2
- package/dist/core/runner/prepare-context-lane.js +13 -13
- package/dist/core/runner/prepare-delegation-surface.d.ts +13 -11
- package/dist/core/runner/prepare-delegation-surface.js +7 -8
- package/dist/core/runner/prepare-execution-env.d.ts +5 -2
- package/dist/core/runner/prepare-execution-env.js +7 -4
- package/dist/core/runner/prepare-file-history.d.ts +10 -12
- package/dist/core/runner/prepare-file-history.js +3 -12
- package/dist/core/runner/prepare-gate-stations.d.ts +23 -17
- package/dist/core/runner/prepare-gate-stations.js +10 -7
- package/dist/core/runner/prepare-hands-readface.d.ts +8 -6
- package/dist/core/runner/prepare-hands-readface.js +19 -11
- package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
- package/dist/core/runner/prepare-inherited-gate.js +12 -5
- package/dist/core/runner/prepare-lsp.d.ts +3 -0
- package/dist/core/runner/prepare-lsp.js +2 -2
- package/dist/core/runner/prepare-memory-engine-session.js +1 -1
- package/dist/core/runner/prepare-memory.d.ts +2 -2
- package/dist/core/runner/prepare-memory.js +2 -2
- package/dist/core/runner/prepare-park-ask.d.ts +8 -7
- package/dist/core/runner/prepare-park-ask.js +6 -12
- package/dist/core/runner/prepare-policy-chain.d.ts +15 -25
- package/dist/core/runner/prepare-policy-chain.js +131 -128
- package/dist/core/runner/prepare-project-context.d.ts +2 -2
- package/dist/core/runner/prepare-project-context.js +8 -5
- package/dist/core/runner/prepare-prompt-inputs.d.ts +4 -0
- package/dist/core/runner/prepare-prompt-inputs.js +4 -2
- package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
- package/dist/core/runner/prepare-protocol-tools.js +9 -2
- package/dist/core/runner/prepare-question-face.d.ts +6 -4
- package/dist/core/runner/prepare-question-face.js +2 -2
- package/dist/core/runner/prepare-run-refs.d.ts +3 -0
- package/dist/core/runner/prepare-run-refs.js +2 -2
- package/dist/core/runner/prepare-suspend-saga.d.ts +11 -9
- package/dist/core/runner/prepare-suspend-saga.js +21 -13
- package/dist/core/runner/prepare-task.d.ts +1 -1
- package/dist/core/runner/prepare-task.js +84 -42
- package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
- package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
- package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
- package/dist/core/runner/prepare-turn-wiring.js +7 -2
- package/dist/core/runner/prepare-wiring-manifest.d.ts +7 -3
- package/dist/core/runner/prepare-wiring-manifest.js +34 -19
- package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
- package/dist/core/runner/prepare-workspace-restore.js +12 -8
- package/dist/core/runner/read-root-grant.d.ts +1 -1
- package/dist/core/runner/read-root-grant.js +2 -1
- package/dist/core/runner/resume-admission.d.ts +5 -3
- package/dist/core/runner/resume-admission.js +17 -3
- package/dist/core/runner/resume-apply.js +3 -1
- package/dist/core/runner/resume-checkpoint-screen.js +4 -4
- package/dist/core/runner/resume-claim.d.ts +8 -3
- package/dist/core/runner/resume-claim.js +28 -12
- package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
- package/dist/core/runner/resume-internals-and-config.js +10 -1
- package/dist/core/runner/resume-preflight.d.ts +3 -2
- package/dist/core/runner/resume-preflight.js +13 -26
- package/dist/core/runner/retired-runner-deps.js +6 -1
- package/dist/core/runner/run-attachment-seats.js +3 -3
- package/dist/core/runner/run-brain-sinks.js +1 -0
- package/dist/core/runner/run-git-lane.d.ts +3 -1
- package/dist/core/runner/run-git-lane.js +3 -2
- package/dist/core/runner/run-harness-handlers.d.ts +3 -1
- package/dist/core/runner/run-harness-handlers.js +5 -3
- package/dist/core/runner/run-identity-wiring.d.ts +2 -2
- package/dist/core/runner/run-identity-wiring.js +15 -6
- package/dist/core/runner/run-leg.d.ts +3 -3
- package/dist/core/runner/run-leg.js +65 -56
- package/dist/core/runner/run-notification-lane.d.ts +3 -1
- package/dist/core/runner/run-notification-lane.js +36 -12
- package/dist/core/runner/run-recovery-lanes.js +3 -2
- package/dist/core/runner/run-settle-and-teardown.js +14 -8
- package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
- package/dist/core/runner/run-stop-and-final-verify.js +12 -4
- package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
- package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
- package/dist/core/runner/run-terminal-adoption.js +26 -17
- package/dist/core/runner/run-turn-boundary.js +37 -19
- package/dist/core/runner/runtask.d.ts +25 -7
- package/dist/core/runner/runtask.js +46 -22
- package/dist/core/runner/session-rule-policy.d.ts +1 -1
- package/dist/core/runner/session-rule-policy.js +6 -1
- package/dist/core/runner/shell-env-withheld.d.ts +1 -1
- package/dist/core/runner/skills-seat.js +2 -2
- package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
- package/dist/core/runner/stream-halt-verbs.js +4 -3
- package/dist/core/runner/stream-reap.d.ts +7 -6
- package/dist/core/runner/stream-reap.js +13 -16
- package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
- package/dist/core/runner/stream-settle-backstop.js +5 -3
- package/dist/core/runner/stream-steer-verb.d.ts +5 -2
- package/dist/core/runner/stream-steer-verb.js +8 -7
- package/dist/core/runner/sub-agent-deny-lists.js +10 -7
- package/dist/core/runner/synthetic-tools.js +2 -2
- package/dist/core/runner/terminal-account.d.ts +11 -1
- package/dist/core/runner/terminal-account.js +20 -0
- package/dist/core/runner/terminal-projection.d.ts +8 -2
- package/dist/core/runner/terminal-projection.js +2 -2
- package/dist/core/runner/tool-disclosure.d.ts +3 -0
- package/dist/core/runner/tool-disclosure.js +5 -4
- package/dist/core/runner/tool-end-body.d.ts +3 -3
- package/dist/core/runner/tool-end-body.js +1 -1
- package/dist/core/runner/tool-face-overlay.d.ts +1 -1
- package/dist/core/runner/tool-face-overlay.js +26 -19
- package/dist/core/runner/tool-output-projection.d.ts +3 -3
- package/dist/core/runner/tool-output-projection.js +7 -6
- package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
- package/dist/core/runner/tool-result-media-seat.js +17 -1
- package/dist/core/runner/tool-table-view.d.ts +56 -0
- package/dist/core/runner/tool-table-view.js +51 -0
- package/dist/core/runner/turn-attachments.d.ts +6 -7
- package/dist/core/runner/turn-attachments.js +4 -17
- package/dist/core/runner/void-verifier-pause.d.ts +33 -0
- package/dist/core/runner/void-verifier-pause.js +41 -0
- package/dist/core/runner-deps.d.ts +55 -43
- package/dist/core/secret-env.d.ts +14 -13
- package/dist/core/secret-env.js +8 -9
- package/dist/core/session-log-transfer.js +9 -10
- package/dist/core/session-policy-store.d.ts +10 -3
- package/dist/core/session-policy-store.js +21 -3
- package/dist/core/session-reconcile.d.ts +3 -2
- package/dist/core/session-reconcile.js +7 -4
- package/dist/core/session-store.d.ts +5 -2
- package/dist/core/session-store.js +53 -16
- package/dist/core/session.d.ts +2 -1
- package/dist/core/shell-confinement.d.ts +37 -0
- package/dist/core/shell-confinement.js +56 -0
- package/dist/core/skill-grant.d.ts +9 -0
- package/dist/core/skill-grant.js +18 -0
- package/dist/core/store-contracts/checkpoint-store-contract.d.ts +2 -2
- package/dist/core/store-contracts/checkpoint-store-contract.js +15 -2
- package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
- package/dist/core/store-contracts/file-history-store-contract.js +25 -1
- package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
- package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
- package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
- package/dist/core/store-contracts/tool-result-store-contract.js +67 -0
- package/dist/core/stub-env.d.ts +5 -5
- package/dist/core/stub-env.js +11 -1
- package/dist/core/swappable-deps.d.ts +17 -43
- package/dist/core/swappable-deps.js +15 -5
- package/dist/core/synthetic-read-verdict.d.ts +1 -1
- package/dist/core/task-event.d.ts +35 -10
- package/dist/core/task-limits.d.ts +5 -0
- package/dist/core/task-notification.d.ts +172 -12
- package/dist/core/task-notification.js +209 -12
- package/dist/core/task-registry-agent.d.ts +23 -55
- package/dist/core/task-registry-agent.js +41 -56
- package/dist/core/task-registry-monitor.d.ts +8 -1
- package/dist/core/task-registry-monitor.js +43 -61
- package/dist/core/task-registry-shared.d.ts +52 -114
- package/dist/core/task-registry-shared.js +24 -48
- package/dist/core/task-registry-workflow.js +5 -22
- package/dist/core/task-registry.d.ts +64 -90
- package/dist/core/task-registry.js +73 -119
- package/dist/core/task-result.d.ts +27 -19
- package/dist/core/task-spec-members.d.ts +39 -0
- package/dist/core/task-spec-members.js +92 -0
- package/dist/core/task-spec.d.ts +13 -16
- package/dist/core/task-stream.d.ts +1 -1
- package/dist/core/task-tool-shape.d.ts +7 -57
- package/dist/core/task-tool-shape.js +7 -66
- package/dist/core/terminal-cause.d.ts +30 -0
- package/dist/core/terminal-cause.js +1 -0
- package/dist/core/tool-catalog-entries.js +3 -6
- package/dist/core/tool-check-reading.js +16 -10
- package/dist/core/tool-conformance.js +1 -2
- package/dist/core/tool-errors.d.ts +6 -3
- package/dist/core/tool-errors.js +2 -0
- package/dist/core/tool-face-reader.d.ts +7 -6
- package/dist/core/tool-face-reader.js +6 -4
- package/dist/core/tool-face.d.ts +2 -3
- package/dist/core/tool-name-aliases.d.ts +23 -28
- package/dist/core/tool-name-aliases.js +63 -7
- package/dist/core/tool-name-readings.d.ts +14 -3
- package/dist/core/tool-name-readings.js +2 -0
- package/dist/core/tool-policy.d.ts +113 -22
- package/dist/core/tool-policy.js +85 -15
- package/dist/core/tool-registry.d.ts +5 -5
- package/dist/core/tool-registry.js +2 -2
- package/dist/core/tool-result-store.d.ts +111 -5
- package/dist/core/tool-result-store.js +52 -12
- package/dist/core/tool-spec.d.ts +39 -10
- package/dist/core/trace.d.ts +18 -2
- package/dist/core/types.d.ts +3 -3
- package/dist/core/types.js +1 -1
- package/dist/core/untrusted-text.js +1 -1
- package/dist/core/user-attachment.d.ts +10 -5
- package/dist/core/user-attachment.js +40 -27
- package/dist/core/workflow-journal-store.d.ts +1 -1
- package/dist/core/workflow-run-store.d.ts +2 -0
- package/dist/core/workflow-run-store.js +6 -5
- package/dist/core/workflow-settled-run.d.ts +5 -0
- package/dist/core/workflow-settled-run.js +7 -0
- package/dist/engine/execution-env/node-execution-env.d.ts +37 -7
- package/dist/engine/execution-env/node-execution-env.js +224 -21
- package/dist/engine/harness/agent-harness.d.ts +66 -19
- package/dist/engine/harness/agent-harness.js +98 -27
- package/dist/engine/harness/messages.d.ts +4 -3
- package/dist/engine/harness/messages.js +2 -2
- package/dist/engine/harness/types.d.ts +151 -34
- package/dist/engine/llm/media-removed.d.ts +14 -0
- package/dist/engine/llm/media-removed.js +9 -0
- package/dist/engine/llm/rejected-images.d.ts +35 -25
- package/dist/engine/llm/rejected-images.js +59 -10
- package/dist/engine/llm/types.d.ts +24 -3
- package/dist/engine/llm/types.js +7 -3
- package/dist/engine/loop/agent-loop.d.ts +18 -13
- package/dist/engine/loop/agent-loop.js +173 -32
- package/dist/engine/loop/types.d.ts +21 -5
- package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
- package/dist/engine/lsp/node-lsp-manager.js +32 -13
- package/dist/engine/session/import-validate.js +7 -0
- package/dist/fixtures/index.d.ts +7 -5
- package/dist/fixtures/index.js +5 -3
- package/dist/index.d.ts +41 -23
- package/dist/index.js +29 -16
- package/dist/internal/harness-types.d.ts +3 -1
- package/dist/internal/llm.d.ts +2 -1
- package/dist/internal/llm.js +1 -0
- package/dist/orchestration/goal.d.ts +6 -2
- package/dist/orchestration/goal.js +6 -3
- package/dist/orchestration/run-workflow-tool.d.ts +20 -20
- package/dist/orchestration/run-workflow-tool.js +63 -56
- package/dist/orchestration/workflow-governance.d.ts +1 -1
- package/dist/orchestration/workflow-governance.js +2 -1
- package/dist/orchestration/workflow-types.d.ts +2 -2
- package/dist/orchestration/workflow.d.ts +8 -0
- package/dist/orchestration/workflow.js +33 -9
- package/dist/prompts/default.d.ts +1 -10
- package/dist/prompts/default.js +0 -2
- package/dist/stores/file/background-agent-store.d.ts +1 -1
- package/dist/stores/file/background-agent-store.js +19 -14
- package/dist/stores/file/checkpoint-store.d.ts +127 -2
- package/dist/stores/file/checkpoint-store.js +24 -16
- package/dist/stores/file/file-history-store.d.ts +1 -1
- package/dist/stores/file/file-history-store.js +4 -1
- package/dist/stores/file/index.d.ts +9 -6
- package/dist/stores/file/index.js +33 -9
- package/dist/stores/file/ledger-tuning.d.ts +23 -0
- package/dist/stores/file/ledger-tuning.js +21 -0
- package/dist/stores/file/mailbox-store.d.ts +1 -1
- package/dist/stores/file/mailbox-store.js +43 -21
- package/dist/stores/file/memory-store.d.ts +1 -1
- package/dist/stores/file/memory-store.js +4 -1
- package/dist/stores/file/permission-rule-adopt.js +24 -21
- package/dist/stores/file/permission-rule-store.js +6 -3
- package/dist/stores/file/session-policy-store.d.ts +1 -1
- package/dist/stores/file/session-policy-store.js +4 -1
- package/dist/stores/file/session-store.d.ts +17 -4
- package/dist/stores/file/session-store.js +22 -19
- package/dist/stores/file/shared-ledger.d.ts +26 -0
- package/dist/stores/file/shared-ledger.js +38 -9
- package/dist/stores/file/tool-result-store.d.ts +31 -2
- package/dist/stores/file/tool-result-store.js +129 -7
- package/dist/stores/file/usage-window-store.d.ts +1 -1
- package/dist/stores/file/usage-window-store.js +4 -1
- package/dist/stores/file/workflow-journal-store.d.ts +1 -13
- package/dist/stores/file/workflow-journal-store.js +4 -18
- package/dist/stores/file/workflow-run-store.d.ts +1 -1
- package/dist/stores/file/workflow-run-store.js +15 -10
- package/dist/tools/fs/containment-face.d.ts +5 -0
- package/dist/tools/fs/dead-cwd.d.ts +5 -5
- package/dist/tools/fs/dead-cwd.js +4 -11
- package/dist/tools/fs/encoding.d.ts +13 -4
- package/dist/tools/fs/encoding.js +17 -2
- package/dist/tools/fs/fs-bash-background-text.d.ts +13 -0
- package/dist/tools/fs/fs-bash-background-text.js +7 -0
- package/dist/tools/fs/fs-bash.d.ts +11 -22
- package/dist/tools/fs/fs-bash.js +58 -154
- package/dist/tools/fs/fs-pdf.d.ts +2 -2
- package/dist/tools/fs/fs-pdf.js +34 -27
- package/dist/tools/fs/fs-read.d.ts +5 -4
- package/dist/tools/fs/fs-read.js +35 -18
- package/dist/tools/fs/fs-search-tools.js +4 -1
- package/dist/tools/fs/fs-shared.d.ts +39 -16
- package/dist/tools/fs/fs-shared.js +25 -6
- package/dist/tools/fs/fs-write.js +5 -5
- package/dist/tools/fs/index.d.ts +15 -9
- package/dist/tools/fs/index.js +12 -18
- package/dist/tools/fs/pdf.d.ts +4 -4
- package/dist/tools/fs/pdf.js +6 -6
- package/dist/tools/fs/read-deny-home.js +8 -1
- package/dist/tools/fs/read-deny.d.ts +26 -2
- package/dist/tools/fs/read-deny.js +9 -2
- package/dist/tools/fs/read-floor.d.ts +57 -6
- package/dist/tools/fs/read-floor.js +241 -2
- package/dist/tools/fs/removal-targets.d.ts +9 -4
- package/dist/tools/fs/removal-targets.js +17 -9
- package/dist/tools/fs/search.d.ts +6 -5
- package/dist/tools/fs/search.js +10 -10
- package/dist/tools/fs/shell-read-establish.js +3 -1
- package/dist/tools/fs/shell-read-identity.d.ts +3 -1
- package/dist/tools/fs/shell-read-identity.js +4 -2
- package/dist/tools/fs/shell-read-judge.d.ts +7 -1
- package/dist/tools/fs/shell-read-judge.js +1 -1
- package/dist/tools/monitor.d.ts +12 -10
- package/dist/tools/monitor.js +22 -13
- package/dist/tools/scheduler-tools.js +42 -4
- package/dist/tools/web.d.ts +0 -10
- package/dist/tools/web.js +1 -4
- package/dist/tools/worktree.d.ts +5 -1
- package/dist/tools/worktree.js +20 -17
- package/package.json +8 -3
- package/test/export-surface.snapshot.json +166 -30
- package/wire-changes/core-stores-sql@7.60.0.json +30 -0
- package/wire-changes/core-stores-sql@7.61.0.json +480 -0
- package/wire-changes/core@7.60.0.json +3274 -0
- package/wire-changes/core@7.61.0.json +4405 -0
- package/wire-changes/mods-kernel@7.60.0.json +62 -0
- package/wire-changes/mods-kernel@7.61.0.json +65 -0
- package/wire-changes/primitives@7.60.0.json +30 -0
- package/wire-changes/primitives@7.61.0.json +30 -0
- package/dist/core/runner/image-removed-seat.d.ts +0 -12
- package/dist/core/runner/image-removed-seat.js +0 -19
|
@@ -1,9 +1,91 @@
|
|
|
1
1
|
import { type ExecutionOutcomeRecordWord } from "../../core/checkpoint-execution-record.js";
|
|
2
2
|
import { type HolderJudge } from "../../core/checkpoint-generation.js";
|
|
3
|
-
import { type Checkpoint, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
|
|
3
|
+
import { type Checkpoint, type PendingSteerEntry, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
|
|
4
4
|
import type { GateOutcome } from "../../core/gate-outcome.js";
|
|
5
5
|
import { type CheckpointDeleteGuard, type CheckpointOverdueCursor, type CheckpointOverdueQuery, type CheckpointPage, type CheckpointRowRead, type CheckpointSessionCursor, type CheckpointSessionQuery } from "../../core/checkpoint-queries.js";
|
|
6
|
+
import type { AssertAllKeysHandled } from "../../core/ask-origin.js";
|
|
6
7
|
import { type CorruptReadInfo } from "./corrupt-read-sink.js";
|
|
8
|
+
/**
|
|
9
|
+
* design/80 §2.4 — THE LOAD-BEARING file store: a {@link CheckpointStore} whose once-only CAS is
|
|
10
|
+
* behaviorally IDENTICAL to {@link import("../../core/checkpoint-store.js").InMemoryCheckpointStore}.
|
|
11
|
+
*
|
|
12
|
+
* **The decisive simplification (§2.4): the local binary is ONE process, one Node event loop.** So the
|
|
13
|
+
* multi-process file-locking literature (per-op `flock`, `O_EXCL` lockfiles) buys nothing — there is NO
|
|
14
|
+
* per-operation lock. Correctness instead rests on three things, exactly mirroring the in-memory store:
|
|
15
|
+
*
|
|
16
|
+
* 1. **In-process async mutex per token** — a `Map<token, Promise>` serialization chain (the SAME shape as
|
|
17
|
+
* `TtlSessionStore.pending`): `resolve`/`reopen`/`expire`/`setPendingSteer`/`put` on a given token chain
|
|
18
|
+
* behind one another, so no two interleaved async tasks can both read `pending` and both commit.
|
|
19
|
+
* 2. **Authoritative state = an in-memory `Map<token, Checkpoint>`**, rebuilt by replaying
|
|
20
|
+
* `checkpoints.jsonl` (+ a compacted `snapshot`) at boot, last-writer-wins by event order (the latest
|
|
21
|
+
* event's status / resolvedOutcome / reopenReason / rev win — the "authoritative fields outside the blob"
|
|
22
|
+
* rule Pg implements with columns).
|
|
23
|
+
* 3. **Commit ordering = appendLine the event + fsync BEFORE flipping the in-memory map** — so a crash can
|
|
24
|
+
* never leave "memory says resolved, disk says pending". A crash *before* the fsync'd append replays as
|
|
25
|
+
* `pending` (a retry can still win); a crash *after* replays as `resolved` (a retry is a no-op `false`).
|
|
26
|
+
* This matches the `testInjectFault` `resolve-before-commit` / `resolve-after-commit` contract exactly.
|
|
27
|
+
*
|
|
28
|
+
* The CAS predicate is byte-for-byte the in-memory one: `row && row.scope === scope && row.status ===
|
|
29
|
+
* 'pending'` plus the `expect.rev` OCC; `setPendingSteer` runs {@link validatePendingSteer} FIRST (before
|
|
30
|
+
* the row lookup); the winner comes from {@link winnerFromOutcome}. NO per-operation flock.
|
|
31
|
+
*
|
|
32
|
+
* **What makes premise 1 true (and what used to only assume it):** the CONSTRUCTOR takes a coarse
|
|
33
|
+
* cross-process writer fence on the ledger directory (`root/checkpoints/LOCK`, via
|
|
34
|
+
* {@link import("./fs-atomic.js").acquireStoreDirLock}) — a second OS process over the same data root is
|
|
35
|
+
* refused loudly ({@link import("./fs-atomic.js").FileStoreLockError}, code `store.dir_in_use`) instead
|
|
36
|
+
* of quietly replaying a private view. Instances INSIDE this process share that fence exactly as they
|
|
37
|
+
* share the authority (refcounted; the last {@link FileCheckpointStore.close} drops it), and a lock left
|
|
38
|
+
* by a dead pid is pruned as stale, so a crash never needs manual cleanup. Before this the doc named a
|
|
39
|
+
* fence this class never took — `FileStorageBackend`'s `root/LOCK` — which meant nothing at all for the
|
|
40
|
+
* direct construction the root export invites: two processes each won the once-only CAS on the same
|
|
41
|
+
* token (approval AND refusal both reported as the winner), and the process that had never loaded the
|
|
42
|
+
* other's rows erased them at its next compaction, with no error on either side.
|
|
43
|
+
*/
|
|
44
|
+
/** One persisted ledger event. The replay folds these in order into the authoritative map. */
|
|
45
|
+
type LedgerEvent = {
|
|
46
|
+
t: "put";
|
|
47
|
+
token: string;
|
|
48
|
+
cp: Checkpoint;
|
|
49
|
+
} | {
|
|
50
|
+
t: "resolve";
|
|
51
|
+
token: string;
|
|
52
|
+
rev: number;
|
|
53
|
+
resolvedOutcome?: Checkpoint["resolvedOutcome"];
|
|
54
|
+
} | {
|
|
55
|
+
t: "reopen";
|
|
56
|
+
token: string;
|
|
57
|
+
rev: number;
|
|
58
|
+
reason: ReopenReason;
|
|
59
|
+
}
|
|
60
|
+
/** The execution-outcome record (CheckpointRow.executionOutcome): written once per row by
|
|
61
|
+
* `recordExecutionOutcome`; the replay sets both columns together. A binary released before this kind
|
|
62
|
+
* refuses the replay at the discriminator fence below while the event is still in the live ledger;
|
|
63
|
+
* once compaction has folded it into a snapshot row, that older binary reads the row with a field it
|
|
64
|
+
* does not know and its `reopen` (the pre-record predicate) ignores it — the same rollback shape the
|
|
65
|
+
* queue event above documents, disclosed in the release notes rather than fenced here. */
|
|
66
|
+
| {
|
|
67
|
+
t: "execution";
|
|
68
|
+
token: string;
|
|
69
|
+
gate: GateOutcome;
|
|
70
|
+
atMs: number;
|
|
71
|
+
} | {
|
|
72
|
+
t: "expire";
|
|
73
|
+
token: string;
|
|
74
|
+
}
|
|
75
|
+
/** The row is gone (`deleteSessionCheckpoints`): the replay removes it from the map, and the next compaction writes no line for it. A
|
|
76
|
+
* binary released before this kind refuses the replay at the discriminator fence while the event is in the live ledger; once a
|
|
77
|
+
* compaction has folded it away the directory reads on that binary again — the store-format note the release carries. */
|
|
78
|
+
| {
|
|
79
|
+
t: "delete";
|
|
80
|
+
token: string;
|
|
81
|
+
}
|
|
82
|
+
/** design/171 §5.3 — one APPENDED queue entry, carrying the `seq` the append minted so the replay is
|
|
83
|
+
* deterministic and never re-runs the bound checks an already-committed append passed. */
|
|
84
|
+
| {
|
|
85
|
+
t: "steer_append";
|
|
86
|
+
token: string;
|
|
87
|
+
entry: PendingSteerEntry;
|
|
88
|
+
};
|
|
7
89
|
export interface FileCheckpointStoreOptions {
|
|
8
90
|
/** This store's half of {@link import("./shared-ledger.js").LedgerPaths.onCorruptRead}. */
|
|
9
91
|
onCorruptRead?: (info: CorruptReadInfo) => void;
|
|
@@ -21,6 +103,48 @@ export interface FileCheckpointStoreOptions {
|
|
|
21
103
|
/** The judge of a resolve's claim holder ({@link HolderJudge}); with it the store declares `fence = { holder: true }`. */
|
|
22
104
|
holderIsCurrent?: HolderJudge;
|
|
23
105
|
}
|
|
106
|
+
/**
|
|
107
|
+
* Every event kind this reader understands — the ledger's CLOSED SET, exported so a program that reads a `checkpoints.jsonl` itself judges
|
|
108
|
+
* a line against the words the store folds, not a copy of them. Kept as a VALUE (not just the type union) because the fence below judges
|
|
109
|
+
* DECODED JSON, which no compile-time union can vouch for.
|
|
110
|
+
*
|
|
111
|
+
* Total BOTH ways at compile time ({@link CheckpointLedgerKindsAreTheEventUnion}): a plain `Set<LedgerEvent["t"]>` would have accepted a list
|
|
112
|
+
* that silently forgot a member, and the failure shape of that drift is worse than the bug the fence fixes — a future release adding a
|
|
113
|
+
* supported kind (union arm, switch case, writer) but not this list would DURABLY append the event and only then have the replay refuse
|
|
114
|
+
* it: the write is on disk, memory is stale, and every later replay of that directory refuses the store. Forgetting a word, or listing
|
|
115
|
+
* one the union does not have, fails to compile.
|
|
116
|
+
*/
|
|
117
|
+
export declare const CHECKPOINT_LEDGER_EVENT_KINDS: readonly ["put", "resolve", "reopen", "execution", "expire", "delete", "steer_append"];
|
|
118
|
+
export type CheckpointLedgerEventKind = (typeof CHECKPOINT_LEDGER_EVENT_KINDS)[number];
|
|
119
|
+
/** The fence over {@link CHECKPOINT_LEDGER_EVENT_KINDS}: `never` while the list and the event union name the same words. */
|
|
120
|
+
export type CheckpointLedgerKindsAreTheEventUnion = AssertAllKeysHandled<Exclude<LedgerEvent["t"], CheckpointLedgerEventKind> | Exclude<CheckpointLedgerEventKind, LedgerEvent["t"]>>;
|
|
121
|
+
export interface ReadCheckpointLedgerOptions {
|
|
122
|
+
/** This reader's half of {@link FileCheckpointStoreOptions.onCorruptRead}: told of every snapshot row / ledger event dropped as damage. */
|
|
123
|
+
onCorruptRead?: (info: CorruptReadInfo) => void;
|
|
124
|
+
}
|
|
125
|
+
/** What {@link readCheckpointLedger} answers: the rows the ledger folds to, or no reading at all. */
|
|
126
|
+
export type CheckpointLedgerReading = {
|
|
127
|
+
/** The directory held still for one whole read. */
|
|
128
|
+
readonly settled: true;
|
|
129
|
+
/** token → row, folded exactly as a store would fold it: fresh objects, owned by the caller, shared with no store. */
|
|
130
|
+
readonly rows: ReadonlyMap<string, Checkpoint>;
|
|
131
|
+
/** Ledger events folded over the snapshot (zero right after a compaction). */
|
|
132
|
+
readonly events: number;
|
|
133
|
+
} | {
|
|
134
|
+
/** The snapshot kept being replaced under the read (a writer compacting, three reads running): no verdict — the last read is not offered in its place. */
|
|
135
|
+
readonly settled: false;
|
|
136
|
+
};
|
|
137
|
+
/**
|
|
138
|
+
* Read a data root's checkpoint ledger WITHOUT opening the store — for a program that must know what the ledger holds beside (or instead of) a
|
|
139
|
+
* running worker: a drain check asking whether a parked row still needs this engine's rows, an operator tool. It takes no writer fence
|
|
140
|
+
* (`checkpoints/LOCK` is neither created nor consulted, so it neither contends with a live store nor is refused by one), opens no append
|
|
141
|
+
* handle, and creates nothing — not the directory either: a root with no ledger reads as no rows. The fold is the store's own
|
|
142
|
+
* (`applyCheckpointEvent` through the same discriminator fence), so a ledger event kind this binary does not know refuses the read exactly as
|
|
143
|
+
* it refuses the store's replay (`checkpoint.unsupported_version`, `detail.reason` `ledger_event_unknown`); {@link CHECKPOINT_LEDGER_EVENT_KINDS}
|
|
144
|
+
* is the word list that fence judges by. A root whose adoption is in flight is refused as the store refuses it. Beside a compacting writer
|
|
145
|
+
* the read is bracketed (see {@link readLedgerSettled}) and is `settled: false` rather than a view that never existed.
|
|
146
|
+
*/
|
|
147
|
+
export declare function readCheckpointLedger(root: string, opts?: ReadCheckpointLedgerOptions): CheckpointLedgerReading;
|
|
24
148
|
export declare class FileCheckpointStore implements CheckpointStore {
|
|
25
149
|
/** design/173 §2.3 — honest declaration on the restart-survival axis the vocabulary claims: rows
|
|
26
150
|
* live on disk (fsync'd append log) and survive a process restart. Multi-replica coordination is
|
|
@@ -57,7 +181,7 @@ export declare class FileCheckpointStore implements CheckpointStore {
|
|
|
57
181
|
private readonly ledgerPath;
|
|
58
182
|
/** Present exactly when the store was built with a session head read (`FileCheckpointStoreOptions.sessionHeadOf`). */
|
|
59
183
|
readonly deleteSessionCheckpoints?: (sessionId: string, guard: CheckpointDeleteGuard) => Promise<number>;
|
|
60
|
-
constructor(root: string,
|
|
184
|
+
constructor(root: string, options?: FileCheckpointStoreOptions);
|
|
61
185
|
/** Serialize an op behind any in-flight op on the same token (the in-process per-token async mutex). */
|
|
62
186
|
private withLock;
|
|
63
187
|
/**
|
|
@@ -106,3 +230,4 @@ export declare class FileCheckpointStore implements CheckpointStore {
|
|
|
106
230
|
*/
|
|
107
231
|
close(): void;
|
|
108
232
|
}
|
|
233
|
+
export {};
|
|
@@ -1,21 +1,16 @@
|
|
|
1
1
|
import { join } from "node:path";
|
|
2
2
|
import { assertAdoptionBootGate } from "./adoption/marker.js";
|
|
3
|
+
import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
|
|
4
|
+
import { readLedgerTuning } from "./ledger-tuning.js";
|
|
3
5
|
import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "../../core/checkpoint-execution-record.js";
|
|
4
6
|
import { checkpointHolderMatches, checkpointOccMatches, checkpointRevOf } from "../../core/checkpoint-generation.js";
|
|
5
7
|
import { appendPendingSteer, CheckpointError, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
|
|
6
8
|
import { checkpointDeadlinePassed, deleteSessionRowsAtStart, readCheckpointOverdueQuery, readCheckpointSessionQuery, selectOverduePage, selectSessionPage, } from "../../core/checkpoint-queries.js";
|
|
7
|
-
import { SharedLedgerTable } from "./shared-ledger.js";
|
|
9
|
+
import { readLedgerSettled, SharedLedgerTable } from "./shared-ledger.js";
|
|
8
10
|
import { guardCorruptSink } from "./corrupt-read-sink.js";
|
|
9
|
-
const
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
reopen: true,
|
|
13
|
-
execution: true,
|
|
14
|
-
expire: true,
|
|
15
|
-
delete: true,
|
|
16
|
-
steer_append: true,
|
|
17
|
-
};
|
|
18
|
-
const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(Object.keys(CHECKPOINT_LEDGER_EVENT_REGISTRY));
|
|
11
|
+
const FILE_CHECKPOINT_STORE_OPTION_KEYS = optionKeys()({ onCorruptRead: 0, fsync: 0, compactEvery: 0, sessionHeadOf: 0, holderIsCurrent: 0 });
|
|
12
|
+
export const CHECKPOINT_LEDGER_EVENT_KINDS = Object.freeze(["put", "resolve", "reopen", "execution", "expire", "delete", "steer_append"]);
|
|
13
|
+
const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(CHECKPOINT_LEDGER_EVENT_KINDS);
|
|
19
14
|
function applyCheckpointEvent(cps, ev) {
|
|
20
15
|
if (!KNOWN_CHECKPOINT_LEDGER_EVENTS.has(ev.t)) {
|
|
21
16
|
throw new CheckpointError("checkpoint.unsupported_version", `file checkpoint ledger: unrecognised event kind "${String(ev.t)}" — ` +
|
|
@@ -69,7 +64,7 @@ const isCheckpointRow = (x) => x !== null &&
|
|
|
69
64
|
typeof x.token === "string" &&
|
|
70
65
|
typeof x.scope === "string" &&
|
|
71
66
|
typeof x.status === "string";
|
|
72
|
-
const
|
|
67
|
+
const checkpointLedgerModel = {
|
|
73
68
|
label: "checkpoint ledger",
|
|
74
69
|
keyOf: (cp) => cp.token,
|
|
75
70
|
apply: applyCheckpointEvent,
|
|
@@ -84,7 +79,18 @@ const checkpointLedgers = new SharedLedgerTable({
|
|
|
84
79
|
return false;
|
|
85
80
|
return ev.t === "put" ? isCheckpointRow(ev.cp) : true;
|
|
86
81
|
},
|
|
87
|
-
}
|
|
82
|
+
};
|
|
83
|
+
const checkpointLedgers = new SharedLedgerTable(checkpointLedgerModel);
|
|
84
|
+
export function readCheckpointLedger(root, opts = {}) {
|
|
85
|
+
assertAdoptionBootGate(root, "readCheckpointLedger");
|
|
86
|
+
const dir = join(root, "checkpoints");
|
|
87
|
+
const read = readLedgerSettled({
|
|
88
|
+
ledgerPath: join(dir, "checkpoints.jsonl"),
|
|
89
|
+
snapshotPath: join(dir, "checkpoints.snapshot.jsonl"),
|
|
90
|
+
...(opts.onCorruptRead !== undefined ? { onCorruptRead: guardCorruptSink(opts.onCorruptRead) } : {}),
|
|
91
|
+
}, checkpointLedgerModel);
|
|
92
|
+
return read.settled ? { settled: true, rows: read.rows, events: read.events } : { settled: false };
|
|
93
|
+
}
|
|
88
94
|
export class FileCheckpointStore {
|
|
89
95
|
durability = "durable";
|
|
90
96
|
fidelity = "json";
|
|
@@ -100,13 +106,15 @@ export class FileCheckpointStore {
|
|
|
100
106
|
fault = null;
|
|
101
107
|
discloseCorrupt;
|
|
102
108
|
ledgerPath;
|
|
103
|
-
constructor(root,
|
|
109
|
+
constructor(root, options) {
|
|
110
|
+
const opts = receiveOptions(options, "FileCheckpointStore", FILE_CHECKPOINT_STORE_OPTION_KEYS);
|
|
104
111
|
assertAdoptionBootGate(root, "FileCheckpointStore");
|
|
105
|
-
|
|
112
|
+
const tuning = readLedgerTuning(opts, "FileCheckpointStore", "FileCheckpointStore options");
|
|
113
|
+
this.fsyncEnabled = tuning.fsync;
|
|
106
114
|
this.holderIsCurrent = opts.holderIsCurrent;
|
|
107
115
|
if (opts.holderIsCurrent !== undefined)
|
|
108
116
|
this.fence = Object.freeze({ holder: true });
|
|
109
|
-
this.compactEvery =
|
|
117
|
+
this.compactEvery = tuning.compactEvery;
|
|
110
118
|
this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
|
|
111
119
|
const dir = join(root, "checkpoints");
|
|
112
120
|
this.ledgerPath = join(dir, "checkpoints.jsonl");
|
|
@@ -173,7 +173,7 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
|
|
|
173
173
|
* A tie is then decided by the entry id, which IS commit order for engine-minted uuidv7 ids.
|
|
174
174
|
*/
|
|
175
175
|
private nextCommittedAt;
|
|
176
|
-
constructor(root: string,
|
|
176
|
+
constructor(root: string, options?: FileFileHistoryStoreOptions);
|
|
177
177
|
/**
|
|
178
178
|
* The RETENTION pass, run after a boundary file is published (design/381 §片2 — see
|
|
179
179
|
* {@link FileHistoryStore.reap} for why the backend owns this rather than the host).
|
|
@@ -8,6 +8,8 @@ import { atomicWriteFile, ensureDir, sanitizePathComponent, sanitizeScope, write
|
|
|
8
8
|
import { guardCorruptSink } from "./corrupt-read-sink.js";
|
|
9
9
|
import { isAbsoluteForFamily } from "../../tools/fs/safety.js";
|
|
10
10
|
import { assertAdoptionBootGate } from "./adoption/marker.js";
|
|
11
|
+
import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
|
|
12
|
+
const FILE_FILE_HISTORY_STORE_OPTION_KEYS = optionKeys()({ onCorruptRead: 0, retention: 0 });
|
|
11
13
|
function trackedDigest(rows) {
|
|
12
14
|
const canonical = [...rows]
|
|
13
15
|
.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
|
|
@@ -155,7 +157,8 @@ export class FileFileHistoryStore {
|
|
|
155
157
|
this.lastCommittedAt = Math.max(Date.now(), this.lastCommittedAt + 1);
|
|
156
158
|
return this.lastCommittedAt;
|
|
157
159
|
}
|
|
158
|
-
constructor(root,
|
|
160
|
+
constructor(root, options) {
|
|
161
|
+
const opts = receiveOptions(options, "FileFileHistoryStore", FILE_FILE_HISTORY_STORE_OPTION_KEYS);
|
|
159
162
|
assertAdoptionBootGate(root, "FileFileHistoryStore");
|
|
160
163
|
this.boundaryKeep = resolveFileHistoryRetention("FileFileHistoryStore", opts?.retention);
|
|
161
164
|
this.base = join(root, "file-history");
|
|
@@ -11,17 +11,18 @@ import type { FileHistoryStore } from "../../core/file-history-store.js";
|
|
|
11
11
|
import type { BackgroundAgentStore } from "../../core/background-agent-store.js";
|
|
12
12
|
import type { MailboxStore } from "../../core/mailbox-store.js";
|
|
13
13
|
import type { RosterStore } from "../../agents/roster-store.js";
|
|
14
|
-
import type
|
|
14
|
+
import { type SessionPolicyStore } from "../../core/session-policy-store.js";
|
|
15
15
|
import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
|
|
16
16
|
import type { UsageWindowStore } from "../../core/usage-window-store.js";
|
|
17
17
|
import type { EngineStorageBackend } from "../../core/engine-storage-backend.js";
|
|
18
|
-
export { FileCheckpointStore, type FileCheckpointStoreOptions } from "./checkpoint-store.js";
|
|
18
|
+
export { FileCheckpointStore, CHECKPOINT_LEDGER_EVENT_KINDS, readCheckpointLedger, type CheckpointLedgerEventKind, type CheckpointLedgerReading, type FileCheckpointStoreOptions, type ReadCheckpointLedgerOptions, } from "./checkpoint-store.js";
|
|
19
19
|
export { FileMemoryStore } from "./memory-store.js";
|
|
20
20
|
export { FileSessionRepo, type FileSessionRepoOptions } from "./session-store.js";
|
|
21
21
|
export { FileToolResultStore } from "./tool-result-store.js";
|
|
22
22
|
export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type SessionPolicyCorruptReadInfo } from "./session-policy-store.js";
|
|
23
23
|
export { FileFileHistoryStore, type FileFileHistoryStoreOptions } from "./file-history-store.js";
|
|
24
|
-
export { FileWorkflowJournalStore
|
|
24
|
+
export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
|
|
25
|
+
export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
|
|
25
26
|
export { FileUsageWindowStore, type FileUsageWindowStoreOptions } from "./usage-window-store.js";
|
|
26
27
|
export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
|
|
27
28
|
export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
|
|
@@ -66,8 +67,10 @@ export interface FileStorageBackendOptions {
|
|
|
66
67
|
/** `TtlSessionStore` idle-eviction policy. Default `"forget"` (§7 decision 5 — durable history is never
|
|
67
68
|
* deleted by an idle timer). */
|
|
68
69
|
evict?: EvictPolicy;
|
|
69
|
-
/** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold).
|
|
70
|
-
|
|
70
|
+
/** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold, the holder judge). The
|
|
71
|
+
* corrupt-read sink and the session head read are the backend's own — the sink is {@link FileStorageBackendOptions.onCorruptRead}
|
|
72
|
+
* (one failure grammar, one sink) and the head read is its session store's — so neither is accepted here. */
|
|
73
|
+
checkpoint?: Omit<FileCheckpointStoreOptions, "onCorruptRead" | "sessionHeadOf">;
|
|
71
74
|
/**
|
|
72
75
|
* design/381 §片2 — file-history tuning, today just the boundary RETENTION bound (omitted ⇒ the
|
|
73
76
|
* engine default; `{ retention: { keep: "unbounded" } }` hands the GC schedule to the deployment).
|
|
@@ -184,7 +187,7 @@ export declare class FileStorageBackend implements EngineStorageBackend {
|
|
|
184
187
|
* descriptors) this backend joined; `TtlSessionStore.dispose()` only clears the sweep timer. */
|
|
185
188
|
private readonly fileSessions;
|
|
186
189
|
private readonly fileWorkflowJournal;
|
|
187
|
-
constructor(
|
|
190
|
+
constructor(options?: FileStorageBackendOptions);
|
|
188
191
|
/**
|
|
189
192
|
* The data-dir boot lock could not be handed back — a root that turned read-only under a running
|
|
190
193
|
* process, an unreadable lock file. Teardown here is best-effort by contract, but best-effort must not
|
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { join } from "node:path";
|
|
2
2
|
import { guardedMemoryStore } from "../../core/memory.js";
|
|
3
|
-
import { TtlSessionStore } from "../../core/session-store.js";
|
|
3
|
+
import { STORE_HOOK_KEYS, TtlSessionStore } from "../../core/session-store.js";
|
|
4
4
|
import { BootLock, createFileConsolidationLock, resolveDataRoot } from "./fs-atomic.js";
|
|
5
5
|
import { assertAdoptionBootGate } from "./adoption/marker.js";
|
|
6
6
|
import { FileCheckpointStore } from "./checkpoint-store.js";
|
|
7
|
+
import { readLedgerTuning } from "./ledger-tuning.js";
|
|
7
8
|
import { FileMemoryStore } from "./memory-store.js";
|
|
8
9
|
import { FileSessionRepo } from "./session-store.js";
|
|
9
10
|
import { FileToolResultStore } from "./tool-result-store.js";
|
|
@@ -14,13 +15,20 @@ import { FileBackgroundAgentStore } from "./background-agent-store.js";
|
|
|
14
15
|
import { FileMailboxStore } from "./mailbox-store.js";
|
|
15
16
|
import { FileRosterStore } from "../../agents/roster-store.js";
|
|
16
17
|
import { FileFileHistoryStore } from "./file-history-store.js";
|
|
17
|
-
|
|
18
|
+
import { readMountedToolNames } from "../../core/session-policy-store.js";
|
|
19
|
+
import { optionKeys, receiveMembers, receiveOptions, refuseProxy, refuseStrayMembers } from "../../core/own-property-receipt.js";
|
|
20
|
+
import { receiveFileHistoryRetention } from "../../core/file-history-retention.js";
|
|
21
|
+
function nestedOptions(value, member, keys) {
|
|
22
|
+
return value === undefined ? undefined : receiveMembers(value, { subject: `FileStorageBackendOptions.${member}`, unit: "option", moment: "at new FileStorageBackend" }, keys);
|
|
23
|
+
}
|
|
24
|
+
export { FileCheckpointStore, CHECKPOINT_LEDGER_EVENT_KINDS, readCheckpointLedger, } from "./checkpoint-store.js";
|
|
18
25
|
export { FileMemoryStore } from "./memory-store.js";
|
|
19
26
|
export { FileSessionRepo } from "./session-store.js";
|
|
20
27
|
export { FileToolResultStore } from "./tool-result-store.js";
|
|
21
28
|
export { FileSessionPolicyStore } from "./session-policy-store.js";
|
|
22
29
|
export { FileFileHistoryStore } from "./file-history-store.js";
|
|
23
|
-
export { FileWorkflowJournalStore
|
|
30
|
+
export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
|
|
31
|
+
export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
|
|
24
32
|
export { FileUsageWindowStore } from "./usage-window-store.js";
|
|
25
33
|
export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
|
|
26
34
|
export { FileStoreLockError } from "./fs-atomic.js";
|
|
@@ -28,6 +36,10 @@ export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog
|
|
|
28
36
|
export { processFingerprint, isProcessLive } from "./fs-atomic.js";
|
|
29
37
|
export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
|
|
30
38
|
export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./adoption/adopt.js";
|
|
39
|
+
const FILE_STORAGE_BACKEND_OPTION_KEYS = optionKeys()({ root: 0, utilityGate: 0, evict: 0, checkpoint: 0, fileHistory: 0, sessionPolicy: 0, embedder: 0, onCorruptRead: 0, sessions: 0 });
|
|
40
|
+
const NESTED_FILE_HISTORY_OPTION_KEYS = optionKeys()({ retention: 0 });
|
|
41
|
+
const NESTED_SESSION_POLICY_OPTION_KEYS = optionKeys()({ mountedToolNames: 0 });
|
|
42
|
+
const NESTED_CHECKPOINT_OPTION_KEYS = optionKeys()({ fsync: 0, compactEvery: 0, holderIsCurrent: 0 });
|
|
31
43
|
export class FileStorageBackend {
|
|
32
44
|
root;
|
|
33
45
|
sessionStore;
|
|
@@ -50,10 +62,22 @@ export class FileStorageBackend {
|
|
|
50
62
|
ttl;
|
|
51
63
|
fileSessions;
|
|
52
64
|
fileWorkflowJournal;
|
|
53
|
-
constructor(
|
|
54
|
-
if ("
|
|
55
|
-
|
|
65
|
+
constructor(options) {
|
|
66
|
+
if (options !== undefined && options !== null && typeof options === "object") {
|
|
67
|
+
refuseProxy(options, { subject: "FileStorageBackend options", unit: "option", moment: "at new FileStorageBackend" });
|
|
68
|
+
if (Object.hasOwn(options, "retention")) {
|
|
69
|
+
throw Object.assign(new Error(`FileStorageBackend runs no retention executor, so its options take no \`retention\` word: its stores declare "none".`), { code: "config.retention_capability" });
|
|
70
|
+
}
|
|
56
71
|
}
|
|
72
|
+
const opts = receiveOptions(options, "FileStorageBackend", FILE_STORAGE_BACKEND_OPTION_KEYS);
|
|
73
|
+
const checkpointRecord = nestedOptions(opts.checkpoint, "checkpoint", NESTED_CHECKPOINT_OPTION_KEYS);
|
|
74
|
+
const checkpointOptions = checkpointRecord === undefined ? undefined : { ...checkpointRecord, ...readLedgerTuning(checkpointRecord, "FileCheckpointStore", "FileStorageBackendOptions.checkpoint") };
|
|
75
|
+
const sessionPolicyRecord = nestedOptions(opts.sessionPolicy, "sessionPolicy", NESTED_SESSION_POLICY_OPTION_KEYS);
|
|
76
|
+
const sessionPolicyOptions = sessionPolicyRecord?.mountedToolNames === undefined ? sessionPolicyRecord : { ...sessionPolicyRecord, mountedToolNames: readMountedToolNames(sessionPolicyRecord.mountedToolNames) };
|
|
77
|
+
const fileHistoryRecord = nestedOptions(opts.fileHistory, "fileHistory", NESTED_FILE_HISTORY_OPTION_KEYS);
|
|
78
|
+
const fileHistoryOptions = fileHistoryRecord === undefined ? undefined : { ...fileHistoryRecord, retention: receiveFileHistoryRetention("FileStorageBackendOptions.fileHistory", fileHistoryRecord.retention) };
|
|
79
|
+
if (opts.sessions !== undefined)
|
|
80
|
+
refuseStrayMembers(opts.sessions, { subject: "FileStorageBackendOptions.sessions", unit: "hook", moment: "at new FileStorageBackend" }, STORE_HOOK_KEYS);
|
|
57
81
|
this.root = resolveDataRoot(opts.root);
|
|
58
82
|
assertAdoptionBootGate(this.root, "FileStorageBackend");
|
|
59
83
|
this.lock = new BootLock(join(this.root, "LOCK"));
|
|
@@ -66,14 +90,14 @@ export class FileStorageBackend {
|
|
|
66
90
|
this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } }, ...(opts.sessions !== undefined ? { hooks: opts.sessions } : {}) });
|
|
67
91
|
this.sessionStore = this.ttl;
|
|
68
92
|
const sessionHeadOf = this.ttl.headOf;
|
|
69
|
-
this.fileCheckpoints = new FileCheckpointStore(this.root, { ...
|
|
93
|
+
this.fileCheckpoints = new FileCheckpointStore(this.root, { ...checkpointOptions, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
|
|
70
94
|
built.push(() => this.fileCheckpoints.close());
|
|
71
95
|
this.checkpointStore = this.fileCheckpoints;
|
|
72
96
|
this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});
|
|
73
97
|
built.push(() => this.fileMemory.close());
|
|
74
98
|
this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
|
|
75
99
|
this.toolResultStore = new FileToolResultStore(this.root, corruptRead);
|
|
76
|
-
this.sessionPolicyStore = new FileSessionPolicyStore(this.root, { ...
|
|
100
|
+
this.sessionPolicyStore = new FileSessionPolicyStore(this.root, { ...sessionPolicyOptions, ...corruptRead });
|
|
77
101
|
this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root, true, corruptRead);
|
|
78
102
|
built.push(() => this.fileWorkflowJournal.dispose());
|
|
79
103
|
this.workflowJournalStore = this.fileWorkflowJournal;
|
|
@@ -85,7 +109,7 @@ export class FileStorageBackend {
|
|
|
85
109
|
built.push(() => this.fileMailbox.close());
|
|
86
110
|
this.mailboxStore = this.fileMailbox;
|
|
87
111
|
this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
|
|
88
|
-
this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...
|
|
112
|
+
this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...fileHistoryOptions, ...(corruptRead ?? {}) });
|
|
89
113
|
this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
|
|
90
114
|
}
|
|
91
115
|
catch (err) {
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/** Each store's compaction threshold when none is given. */
|
|
2
|
+
export declare const LEDGER_COMPACT_EVERY_DEFAULTS: Readonly<{
|
|
3
|
+
FileCheckpointStore: 1000;
|
|
4
|
+
FileMailboxStore: 500;
|
|
5
|
+
FileBackgroundAgentStore: 1000;
|
|
6
|
+
FileWorkflowRunStore: 1000;
|
|
7
|
+
}>;
|
|
8
|
+
/** A store that takes ledger tuning. */
|
|
9
|
+
export type LedgerTunedStore = keyof typeof LEDGER_COMPACT_EVERY_DEFAULTS;
|
|
10
|
+
/** A store's ledger tuning, read: every member present. */
|
|
11
|
+
export interface LedgerTuning {
|
|
12
|
+
readonly fsync: boolean;
|
|
13
|
+
readonly compactEvery: number;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Read a store's ledger tuning off an options record already received (the store door's copy, or a backend's nested record's):
|
|
17
|
+
* the values judged, the absent ones the store's defaults. `subject` names the record in a refusal (`FileMailboxStore options`,
|
|
18
|
+
* `FileStorageBackendOptions.checkpoint`).
|
|
19
|
+
*/
|
|
20
|
+
export declare function readLedgerTuning(given: {
|
|
21
|
+
readonly fsync?: unknown;
|
|
22
|
+
readonly compactEvery?: unknown;
|
|
23
|
+
}, store: LedgerTunedStore, subject: string): LedgerTuning;
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { receiptRefusal } from "../../core/own-property-receipt.js";
|
|
2
|
+
export const LEDGER_COMPACT_EVERY_DEFAULTS = Object.freeze({
|
|
3
|
+
FileCheckpointStore: 1000,
|
|
4
|
+
FileMailboxStore: 500,
|
|
5
|
+
FileBackgroundAgentStore: 1000,
|
|
6
|
+
FileWorkflowRunStore: 1000,
|
|
7
|
+
});
|
|
8
|
+
function shown(value) {
|
|
9
|
+
return typeof value === "number" ? String(value) : value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
|
|
10
|
+
}
|
|
11
|
+
export function readLedgerTuning(given, store, subject) {
|
|
12
|
+
const fsync = given.fsync;
|
|
13
|
+
if (fsync !== undefined && typeof fsync !== "boolean") {
|
|
14
|
+
throw receiptRefusal(`${subject}.fsync must be a boolean when given (got ${shown(fsync)}) — refused rather than read as on`);
|
|
15
|
+
}
|
|
16
|
+
const compactEvery = given.compactEvery;
|
|
17
|
+
if (compactEvery !== undefined && !(typeof compactEvery === "number" && Number.isSafeInteger(compactEvery) && compactEvery >= 1)) {
|
|
18
|
+
throw receiptRefusal(`${subject}.compactEvery must be a whole number of events of at least 1 when given (got ${shown(compactEvery)}) — refused rather than kept: such a threshold is never reached (the ledger grows without compacting) or reached at every event (a rewrite per write)`);
|
|
19
|
+
}
|
|
20
|
+
return Object.freeze({ fsync: fsync !== false, compactEvery: compactEvery ?? LEDGER_COMPACT_EVERY_DEFAULTS[store] });
|
|
21
|
+
}
|
|
@@ -66,7 +66,7 @@ export declare class FileMailboxStore implements MailboxStore {
|
|
|
66
66
|
private readonly touched;
|
|
67
67
|
/** The swallow-guarded corrupt-read seat (undefined = the old silent tolerance). */
|
|
68
68
|
private readonly discloseCorrupt;
|
|
69
|
-
constructor(root: string,
|
|
69
|
+
constructor(root: string, options?: FileMailboxStoreOptions);
|
|
70
70
|
/**
|
|
71
71
|
* RB-67 (2026-07-25, red probe): the on-disk name is CASE-FOLDED, so the in-memory key and the physical
|
|
72
72
|
* file can never disagree. Before this, `AgentOne` and `agentone` produced two DIFFERENT shared-state
|
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
import { join, resolve, sep } from "node:path";
|
|
2
2
|
import { createHash, randomBytes } from "node:crypto";
|
|
3
|
-
import {
|
|
3
|
+
import { receiveRetentionPolicy } from "../../core/retention-policy.js";
|
|
4
4
|
import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
|
|
5
|
-
import { assertMailboxDecisionMove, detachMailboxMessage, newestSentAt, readStoredMailboxDecision, readMailboxAppend, judgeMailboxAppendById, } from "../../core/mailbox-store.js";
|
|
5
|
+
import { assertMailboxDecisionMove, detachMailboxMessage, foldMailboxConsumed, MAILBOX_REAP_KNOBS, MAILBOX_REPLAY_FACETS, newestSentAt, readStoredMailboxDecision, readMailboxAppend, judgeMailboxAppendById, } from "../../core/mailbox-store.js";
|
|
6
6
|
import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
|
|
7
7
|
import { guardCorruptSink } from "./corrupt-read-sink.js";
|
|
8
8
|
import { physicalPathOf } from "../../core/physical-path.js";
|
|
9
9
|
import { assertAdoptionBootGate } from "./adoption/marker.js";
|
|
10
|
+
import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
|
|
11
|
+
import { readLedgerTuning } from "./ledger-tuning.js";
|
|
10
12
|
function diskMarkOf(path) {
|
|
11
13
|
try {
|
|
12
14
|
const st = statSync(path);
|
|
@@ -322,6 +324,7 @@ function sweepLockResidue(dir, lockName) {
|
|
|
322
324
|
}
|
|
323
325
|
}
|
|
324
326
|
}
|
|
327
|
+
const FILE_MAILBOX_STORE_OPTION_KEYS = optionKeys()({ fsync: 0, lockWaitMs: 0, compactEvery: 0, onCorruptRead: 0 });
|
|
325
328
|
export class FileMailboxStore {
|
|
326
329
|
crossProcessSafe = true;
|
|
327
330
|
identity;
|
|
@@ -332,10 +335,12 @@ export class FileMailboxStore {
|
|
|
332
335
|
lockWaitMs;
|
|
333
336
|
touched = new Map();
|
|
334
337
|
discloseCorrupt;
|
|
335
|
-
constructor(root,
|
|
338
|
+
constructor(root, options) {
|
|
339
|
+
const opts = receiveOptions(options, "FileMailboxStore", FILE_MAILBOX_STORE_OPTION_KEYS);
|
|
336
340
|
assertAdoptionBootGate(root, "FileMailboxStore");
|
|
337
|
-
|
|
338
|
-
this.
|
|
341
|
+
const tuning = readLedgerTuning(opts, "FileMailboxStore", "FileMailboxStore options");
|
|
342
|
+
this.fsyncEnabled = tuning.fsync;
|
|
343
|
+
this.compactEvery = tuning.compactEvery;
|
|
339
344
|
const lockWaitMs = opts.lockWaitMs ?? 10_000;
|
|
340
345
|
if (typeof lockWaitMs !== "number" || !Number.isFinite(lockWaitMs) || lockWaitMs <= 0) {
|
|
341
346
|
throw new Error(`FileMailboxStore: lockWaitMs must be a finite number > 0, got ${JSON.stringify(opts.lockWaitMs)}`);
|
|
@@ -384,10 +389,11 @@ export class FileMailboxStore {
|
|
|
384
389
|
const events = readJsonlRecords(b.path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE);
|
|
385
390
|
b.messages = [];
|
|
386
391
|
b.nextSeq = 1;
|
|
392
|
+
b.consumed = [];
|
|
387
393
|
delete b.lease;
|
|
388
394
|
for (const ev of events)
|
|
389
395
|
applyEvent(b, ev);
|
|
390
|
-
b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.lease !== undefined ? 1 : 0)));
|
|
396
|
+
b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.consumed.length > 0 ? 1 : 0) + (b.lease !== undefined ? 1 : 0)));
|
|
391
397
|
b.mark = now;
|
|
392
398
|
}
|
|
393
399
|
load(scope, handle) {
|
|
@@ -404,7 +410,7 @@ export class FileMailboxStore {
|
|
|
404
410
|
}
|
|
405
411
|
ensureDir(join(this.dir, sanitizeScope(scope)));
|
|
406
412
|
const events = readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE);
|
|
407
|
-
const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
|
|
413
|
+
const state = { messages: [], nextSeq: 1, consumed: [], log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
|
|
408
414
|
for (const ev of events)
|
|
409
415
|
applyEvent(state, ev);
|
|
410
416
|
state.mark = diskMarkOf(path);
|
|
@@ -427,14 +433,8 @@ export class FileMailboxStore {
|
|
|
427
433
|
b.mark = markAfterWrite(path);
|
|
428
434
|
}
|
|
429
435
|
compact(b, path) {
|
|
430
|
-
const lines = [];
|
|
431
|
-
lines.push(JSON.stringify({ t: "lease", owner: "", expiresAt: 0, maxSeq: b.nextSeq - 1 }));
|
|
432
|
-
for (const m of b.messages)
|
|
433
|
-
lines.push(JSON.stringify({ t: "append", m }));
|
|
434
|
-
if (b.lease !== undefined)
|
|
435
|
-
lines.push(JSON.stringify({ t: "lease", ...b.lease }));
|
|
436
436
|
b.log.closeForSwap();
|
|
437
|
-
atomicWriteFile(this.tmpDir, path,
|
|
437
|
+
atomicWriteFile(this.tmpDir, path, snapshotOf(b));
|
|
438
438
|
b.events = 0;
|
|
439
439
|
b.mark = markAfterWrite(path);
|
|
440
440
|
}
|
|
@@ -444,7 +444,7 @@ export class FileMailboxStore {
|
|
|
444
444
|
const record = readMailboxAppend(msg);
|
|
445
445
|
return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
|
|
446
446
|
const b = this.load(scope, handle);
|
|
447
|
-
const held = judgeMailboxAppendById(b.messages, record);
|
|
447
|
+
const held = judgeMailboxAppendById({ held: b.messages, consumed: b.consumed }, record);
|
|
448
448
|
if (held !== undefined)
|
|
449
449
|
return held;
|
|
450
450
|
const seq = b.nextSeq;
|
|
@@ -503,7 +503,7 @@ export class FileMailboxStore {
|
|
|
503
503
|
if (!existsSync(path))
|
|
504
504
|
return 0;
|
|
505
505
|
return withPathLock(this.lockKey(scope, handle), () => {
|
|
506
|
-
const b = { messages: [], nextSeq: 1 };
|
|
506
|
+
const b = { messages: [], nextSeq: 1, consumed: [] };
|
|
507
507
|
for (const ev of readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE))
|
|
508
508
|
applyEvent(b, ev);
|
|
509
509
|
return b.messages.length;
|
|
@@ -523,14 +523,14 @@ export class FileMailboxStore {
|
|
|
523
523
|
});
|
|
524
524
|
}
|
|
525
525
|
async reap(scope, now, opts) {
|
|
526
|
-
|
|
526
|
+
const policy = receiveRetentionPolicy("MailboxStore.reap", opts, MAILBOX_REAP_KNOBS);
|
|
527
527
|
sweepLockResidue(join(this.dir, sanitizeScope(scope)));
|
|
528
|
-
if (
|
|
528
|
+
if (policy.maxAgeMs === undefined)
|
|
529
529
|
return 0;
|
|
530
530
|
let dropped = 0;
|
|
531
531
|
const scopeDir = join(this.dir, sanitizeScope(scope));
|
|
532
532
|
const prefix = scopeDir + sep;
|
|
533
|
-
const maxAgeMs =
|
|
533
|
+
const maxAgeMs = policy.maxAgeMs;
|
|
534
534
|
for (const [key, b] of [...sharedBoxes]) {
|
|
535
535
|
if (!b.path.startsWith(prefix))
|
|
536
536
|
continue;
|
|
@@ -563,13 +563,13 @@ export class FileMailboxStore {
|
|
|
563
563
|
const swept = await this.withBox(key, path, () => {
|
|
564
564
|
if (sharedBoxes.has(key))
|
|
565
565
|
return false;
|
|
566
|
-
const b = { messages: [], nextSeq: 1 };
|
|
566
|
+
const b = { messages: [], nextSeq: 1, consumed: [] };
|
|
567
567
|
for (const ev of readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE))
|
|
568
568
|
applyEvent(b, ev);
|
|
569
569
|
const newest = newestSentAt(b.messages);
|
|
570
570
|
if (newest === undefined || newest >= now - maxAgeMs)
|
|
571
571
|
return false;
|
|
572
|
-
atomicWriteFile(this.tmpDir, path,
|
|
572
|
+
atomicWriteFile(this.tmpDir, path, snapshotOf({ messages: [], nextSeq: b.nextSeq, consumed: b.consumed }));
|
|
573
573
|
return true;
|
|
574
574
|
});
|
|
575
575
|
if (swept)
|
|
@@ -592,6 +592,22 @@ export class FileMailboxStore {
|
|
|
592
592
|
}
|
|
593
593
|
}
|
|
594
594
|
const num = (v) => typeof v === "number" && Number.isFinite(v);
|
|
595
|
+
function isConsumedRecord(v) {
|
|
596
|
+
if (v === null || typeof v !== "object")
|
|
597
|
+
return false;
|
|
598
|
+
const { id, seq, digests } = v;
|
|
599
|
+
return typeof id === "string" && id !== "" && num(seq) && digests !== null && typeof digests === "object" && MAILBOX_REPLAY_FACETS.every((f) => typeof digests[f] === "string");
|
|
600
|
+
}
|
|
601
|
+
function snapshotOf(b) {
|
|
602
|
+
const lines = [JSON.stringify({ t: "lease", owner: "", expiresAt: 0, maxSeq: b.nextSeq - 1 })];
|
|
603
|
+
if (b.consumed.length > 0)
|
|
604
|
+
lines.push(JSON.stringify({ t: "consumed", records: b.consumed }));
|
|
605
|
+
for (const m of b.messages)
|
|
606
|
+
lines.push(JSON.stringify({ t: "append", m }));
|
|
607
|
+
if (b.lease !== undefined)
|
|
608
|
+
lines.push(JSON.stringify({ t: "lease", ...b.lease }));
|
|
609
|
+
return `${lines.join("\n")}\n`;
|
|
610
|
+
}
|
|
595
611
|
const MAILBOX_EVENT_JUDGE = {
|
|
596
612
|
accepts: (r) => {
|
|
597
613
|
const ev = r;
|
|
@@ -603,6 +619,8 @@ const MAILBOX_EVENT_JUDGE = {
|
|
|
603
619
|
return num(ev.upToSeq);
|
|
604
620
|
if (ev.t === "decision")
|
|
605
621
|
return num(r.seq) && typeof r.state === "string";
|
|
622
|
+
if (ev.t === "consumed")
|
|
623
|
+
return Array.isArray(r.records) && r.records.every(isConsumedRecord);
|
|
606
624
|
return ev.t === "release" && typeof ev.owner === "string";
|
|
607
625
|
},
|
|
608
626
|
what: "a mailbox record is not one of this box's events — an unknown tag, or a known tag whose payload is missing",
|
|
@@ -625,10 +643,14 @@ function applyEvent(b, ev) {
|
|
|
625
643
|
b.lease = { owner: ev.owner, expiresAt: ev.expiresAt, maxSeq: ev.maxSeq };
|
|
626
644
|
}
|
|
627
645
|
else if (ev.t === "ack") {
|
|
646
|
+
b.consumed = foldMailboxConsumed(b.consumed, b.messages.filter((m) => m.seq <= ev.upToSeq));
|
|
628
647
|
b.messages = b.messages.filter((m) => m.seq > ev.upToSeq);
|
|
629
648
|
if (b.lease !== undefined && b.lease.maxSeq <= ev.upToSeq)
|
|
630
649
|
b.lease = undefined;
|
|
631
650
|
}
|
|
651
|
+
else if (ev.t === "consumed") {
|
|
652
|
+
b.consumed = foldMailboxConsumed(ev.records, []);
|
|
653
|
+
}
|
|
632
654
|
else if (ev.t === "decision") {
|
|
633
655
|
const m = b.messages.find((x) => x.seq === ev.seq);
|
|
634
656
|
if (m !== undefined)
|