@draht/coding-agent 2026.7.30 → 2026.9.5-1
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 +154 -0
- package/README.md +46 -2
- package/agents/debugger.md +12 -1
- package/agents/git-committer.md +1 -0
- package/agents/implementer.md +20 -0
- package/agents/investigator.md +75 -0
- package/agents/reviewer.md +7 -0
- package/agents/spec-reviewer.md +66 -0
- package/agents/verifier.md +4 -3
- package/bin/draht-tools.cjs +472 -41
- package/dist/agents/debugger.md +12 -1
- package/dist/agents/git-committer.md +1 -0
- package/dist/agents/implementer.md +20 -0
- package/dist/agents/investigator.md +75 -0
- package/dist/agents/reviewer.md +7 -0
- package/dist/agents/spec-reviewer.md +66 -0
- package/dist/agents/verifier.md +4 -3
- package/dist/cli/args.d.ts +10 -0
- package/dist/cli/args.d.ts.map +1 -1
- package/dist/cli/args.js +69 -2
- package/dist/cli/args.js.map +1 -1
- package/dist/cli/attach-mode.d.ts +61 -0
- package/dist/cli/attach-mode.d.ts.map +1 -1
- package/dist/cli/attach-mode.js +243 -5
- package/dist/cli/attach-mode.js.map +1 -1
- package/dist/cli/credential-print.d.ts +1 -1
- package/dist/cli/credential-print.d.ts.map +1 -1
- package/dist/cli/credential-print.js +5 -4
- package/dist/cli/credential-print.js.map +1 -1
- package/dist/config.d.ts +9 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +31 -4
- package/dist/config.js.map +1 -1
- package/dist/core/agent-session-runtime.d.ts +17 -1
- package/dist/core/agent-session-runtime.d.ts.map +1 -1
- package/dist/core/agent-session-runtime.js +87 -30
- package/dist/core/agent-session-runtime.js.map +1 -1
- package/dist/core/agent-session-services.d.ts +1 -1
- package/dist/core/agent-session-services.d.ts.map +1 -1
- package/dist/core/agent-session-services.js +1 -0
- package/dist/core/agent-session-services.js.map +1 -1
- package/dist/core/agent-session.d.ts +35 -16
- package/dist/core/agent-session.d.ts.map +1 -1
- package/dist/core/agent-session.js +149 -64
- package/dist/core/agent-session.js.map +1 -1
- package/dist/core/auth-storage.d.ts +5 -1
- package/dist/core/auth-storage.d.ts.map +1 -1
- package/dist/core/auth-storage.js +72 -15
- package/dist/core/auth-storage.js.map +1 -1
- package/dist/core/builtins/checkpoints.d.ts +20 -0
- package/dist/core/builtins/checkpoints.d.ts.map +1 -0
- package/dist/core/builtins/checkpoints.js +161 -0
- package/dist/core/builtins/checkpoints.js.map +1 -0
- package/dist/core/builtins/duet.d.ts +26 -0
- package/dist/core/builtins/duet.d.ts.map +1 -0
- package/dist/core/builtins/duet.js +660 -0
- package/dist/core/builtins/duet.js.map +1 -0
- package/dist/core/builtins/index.d.ts.map +1 -1
- package/dist/core/builtins/index.js +7 -1
- package/dist/core/builtins/index.js.map +1 -1
- package/dist/core/builtins/subagent.d.ts +24 -4
- package/dist/core/builtins/subagent.d.ts.map +1 -1
- package/dist/core/builtins/subagent.js +278 -35
- package/dist/core/builtins/subagent.js.map +1 -1
- package/dist/core/checkpoints/checkpoint-cli.d.ts +17 -0
- package/dist/core/checkpoints/checkpoint-cli.d.ts.map +1 -0
- package/dist/core/checkpoints/checkpoint-cli.js +78 -0
- package/dist/core/checkpoints/checkpoint-cli.js.map +1 -0
- package/dist/core/checkpoints/checkpoint-manager.d.ts +294 -0
- package/dist/core/checkpoints/checkpoint-manager.d.ts.map +1 -0
- package/dist/core/checkpoints/checkpoint-manager.js +865 -0
- package/dist/core/checkpoints/checkpoint-manager.js.map +1 -0
- package/dist/core/checkpoints/rewind.d.ts +141 -0
- package/dist/core/checkpoints/rewind.d.ts.map +1 -0
- package/dist/core/checkpoints/rewind.js +246 -0
- package/dist/core/checkpoints/rewind.js.map +1 -0
- package/dist/core/compaction/branch-summarization.d.ts +1 -1
- package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
- package/dist/core/compaction/branch-summarization.js +9 -4
- package/dist/core/compaction/branch-summarization.js.map +1 -1
- package/dist/core/compaction/compaction.d.ts +5 -0
- package/dist/core/compaction/compaction.d.ts.map +1 -1
- package/dist/core/compaction/compaction.js +25 -4
- package/dist/core/compaction/compaction.js.map +1 -1
- package/dist/core/extensions/index.d.ts +1 -1
- package/dist/core/extensions/index.d.ts.map +1 -1
- package/dist/core/extensions/index.js.map +1 -1
- package/dist/core/extensions/loader.d.ts.map +1 -1
- package/dist/core/extensions/loader.js +83 -20
- package/dist/core/extensions/loader.js.map +1 -1
- package/dist/core/extensions/runner.d.ts +13 -2
- package/dist/core/extensions/runner.d.ts.map +1 -1
- package/dist/core/extensions/runner.js +37 -2
- package/dist/core/extensions/runner.js.map +1 -1
- package/dist/core/extensions/types.d.ts +189 -6
- package/dist/core/extensions/types.d.ts.map +1 -1
- package/dist/core/extensions/types.js.map +1 -1
- package/dist/core/http-dispatcher.d.ts.map +1 -1
- package/dist/core/http-dispatcher.js +7 -0
- package/dist/core/http-dispatcher.js.map +1 -1
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.d.ts.map +1 -1
- package/dist/core/index.js.map +1 -1
- package/dist/core/keybindings.d.ts +5 -0
- package/dist/core/keybindings.d.ts.map +1 -1
- package/dist/core/keybindings.js +1 -0
- package/dist/core/keybindings.js.map +1 -1
- package/dist/core/model-registry.d.ts +3 -2
- package/dist/core/model-registry.d.ts.map +1 -1
- package/dist/core/model-registry.js +8 -8
- package/dist/core/model-registry.js.map +1 -1
- package/dist/core/model-resolver.d.ts.map +1 -1
- package/dist/core/model-resolver.js +34 -7
- package/dist/core/model-resolver.js.map +1 -1
- package/dist/core/model-runtime.d.ts +7 -1
- package/dist/core/model-runtime.d.ts.map +1 -1
- package/dist/core/model-runtime.js +30 -10
- package/dist/core/model-runtime.js.map +1 -1
- package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
- package/dist/core/multi-agent/permission-gate.js +4 -3
- package/dist/core/multi-agent/permission-gate.js.map +1 -1
- package/dist/core/multi-agent/worktree.d.ts +2 -0
- package/dist/core/multi-agent/worktree.d.ts.map +1 -1
- package/dist/core/multi-agent/worktree.js +2 -2
- package/dist/core/multi-agent/worktree.js.map +1 -1
- package/dist/core/package-manager.d.ts +7 -1
- package/dist/core/package-manager.d.ts.map +1 -1
- package/dist/core/package-manager.js +21 -44
- package/dist/core/package-manager.js.map +1 -1
- package/dist/core/permission-relay/index.d.ts +19 -0
- package/dist/core/permission-relay/index.d.ts.map +1 -0
- package/dist/core/permission-relay/index.js +49 -0
- package/dist/core/permission-relay/index.js.map +1 -0
- package/dist/core/permission-relay/relay-ui-context.d.ts +39 -0
- package/dist/core/permission-relay/relay-ui-context.d.ts.map +1 -0
- package/dist/core/permission-relay/relay-ui-context.js +788 -0
- package/dist/core/permission-relay/relay-ui-context.js.map +1 -0
- package/dist/core/permission-relay/types.d.ts +222 -0
- package/dist/core/permission-relay/types.d.ts.map +1 -0
- package/dist/core/permission-relay/types.js +15 -0
- package/dist/core/permission-relay/types.js.map +1 -0
- package/dist/core/pi-manifest.d.ts +14 -0
- package/dist/core/pi-manifest.d.ts.map +1 -0
- package/dist/core/pi-manifest.js +35 -0
- package/dist/core/pi-manifest.js.map +1 -0
- package/dist/core/project-trust.js +2 -2
- package/dist/core/project-trust.js.map +1 -1
- package/dist/core/resource-loader.d.ts +21 -0
- package/dist/core/resource-loader.d.ts.map +1 -1
- package/dist/core/resource-loader.js +101 -24
- package/dist/core/resource-loader.js.map +1 -1
- package/dist/core/sandbox/bash-operations.d.ts +149 -0
- package/dist/core/sandbox/bash-operations.d.ts.map +1 -0
- package/dist/core/sandbox/bash-operations.js +163 -0
- package/dist/core/sandbox/bash-operations.js.map +1 -0
- package/dist/core/sandbox/env.d.ts +83 -0
- package/dist/core/sandbox/env.d.ts.map +1 -0
- package/dist/core/sandbox/env.js +123 -0
- package/dist/core/sandbox/env.js.map +1 -0
- package/dist/core/sandbox/executor.d.ts +104 -0
- package/dist/core/sandbox/executor.d.ts.map +1 -0
- package/dist/core/sandbox/executor.js +92 -0
- package/dist/core/sandbox/executor.js.map +1 -0
- package/dist/core/sandbox/index.d.ts +36 -0
- package/dist/core/sandbox/index.d.ts.map +1 -0
- package/dist/core/sandbox/index.js +36 -0
- package/dist/core/sandbox/index.js.map +1 -0
- package/dist/core/sandbox/linux.d.ts +121 -0
- package/dist/core/sandbox/linux.d.ts.map +1 -0
- package/dist/core/sandbox/linux.js +260 -0
- package/dist/core/sandbox/linux.js.map +1 -0
- package/dist/core/sandbox/policy.d.ts +142 -0
- package/dist/core/sandbox/policy.d.ts.map +1 -0
- package/dist/core/sandbox/policy.js +297 -0
- package/dist/core/sandbox/policy.js.map +1 -0
- package/dist/core/sandbox/real-path.d.ts +112 -0
- package/dist/core/sandbox/real-path.d.ts.map +1 -0
- package/dist/core/sandbox/real-path.js +158 -0
- package/dist/core/sandbox/real-path.js.map +1 -0
- package/dist/core/sandbox/seatbelt-profile.d.ts +95 -0
- package/dist/core/sandbox/seatbelt-profile.d.ts.map +1 -0
- package/dist/core/sandbox/seatbelt-profile.js +239 -0
- package/dist/core/sandbox/seatbelt-profile.js.map +1 -0
- package/dist/core/sandbox/seatbelt.d.ts +95 -0
- package/dist/core/sandbox/seatbelt.d.ts.map +1 -0
- package/dist/core/sandbox/seatbelt.js +154 -0
- package/dist/core/sandbox/seatbelt.js.map +1 -0
- package/dist/core/sandbox/self-test.d.ts +109 -0
- package/dist/core/sandbox/self-test.d.ts.map +1 -0
- package/dist/core/sandbox/self-test.js +369 -0
- package/dist/core/sandbox/self-test.js.map +1 -0
- package/dist/core/sandbox/spawn.d.ts +33 -0
- package/dist/core/sandbox/spawn.d.ts.map +1 -0
- package/dist/core/sandbox/spawn.js +87 -0
- package/dist/core/sandbox/spawn.js.map +1 -0
- package/dist/core/sdk.d.ts.map +1 -1
- package/dist/core/sdk.js +3 -1
- package/dist/core/sdk.js.map +1 -1
- package/dist/core/session-manager.d.ts +60 -1
- package/dist/core/session-manager.d.ts.map +1 -1
- package/dist/core/session-manager.js +53 -6
- package/dist/core/session-manager.js.map +1 -1
- package/dist/core/settings-manager.d.ts +21 -0
- package/dist/core/settings-manager.d.ts.map +1 -1
- package/dist/core/settings-manager.js +36 -16
- package/dist/core/settings-manager.js.map +1 -1
- package/dist/core/skills.d.ts +3 -1
- package/dist/core/skills.d.ts.map +1 -1
- package/dist/core/skills.js +19 -6
- package/dist/core/skills.js.map +1 -1
- package/dist/core/slash-commands.d.ts.map +1 -1
- package/dist/core/slash-commands.js +1 -0
- package/dist/core/slash-commands.js.map +1 -1
- package/dist/core/soak/soak-log.d.ts +298 -0
- package/dist/core/soak/soak-log.d.ts.map +1 -0
- package/dist/core/soak/soak-log.js +660 -0
- package/dist/core/soak/soak-log.js.map +1 -0
- package/dist/core/soak/soak-reader.d.ts +60 -0
- package/dist/core/soak/soak-reader.d.ts.map +1 -0
- package/dist/core/soak/soak-reader.js +106 -0
- package/dist/core/soak/soak-reader.js.map +1 -0
- package/dist/core/socket-server/discovery.d.ts +78 -1
- package/dist/core/socket-server/discovery.d.ts.map +1 -1
- package/dist/core/socket-server/discovery.js +356 -37
- package/dist/core/socket-server/discovery.js.map +1 -1
- package/dist/core/socket-server/index.d.ts +10 -4
- package/dist/core/socket-server/index.d.ts.map +1 -1
- package/dist/core/socket-server/index.js +6 -3
- package/dist/core/socket-server/index.js.map +1 -1
- package/dist/core/socket-server/permission-delivery.d.ts +125 -0
- package/dist/core/socket-server/permission-delivery.d.ts.map +1 -0
- package/dist/core/socket-server/permission-delivery.js +152 -0
- package/dist/core/socket-server/permission-delivery.js.map +1 -0
- package/dist/core/socket-server/permission-registry.d.ts +301 -0
- package/dist/core/socket-server/permission-registry.d.ts.map +1 -0
- package/dist/core/socket-server/permission-registry.js +410 -0
- package/dist/core/socket-server/permission-registry.js.map +1 -0
- package/dist/core/socket-server/permission-relay.d.ts +81 -0
- package/dist/core/socket-server/permission-relay.d.ts.map +1 -0
- package/dist/core/socket-server/permission-relay.js +528 -0
- package/dist/core/socket-server/permission-relay.js.map +1 -0
- package/dist/core/socket-server/safe-text.d.ts +83 -0
- package/dist/core/socket-server/safe-text.d.ts.map +1 -0
- package/dist/core/socket-server/safe-text.js +277 -0
- package/dist/core/socket-server/safe-text.js.map +1 -0
- package/dist/core/socket-server/session-integration.d.ts +65 -2
- package/dist/core/socket-server/session-integration.d.ts.map +1 -1
- package/dist/core/socket-server/session-integration.js +434 -32
- package/dist/core/socket-server/session-integration.js.map +1 -1
- package/dist/core/socket-server/socket-client.d.ts +21 -2
- package/dist/core/socket-server/socket-client.d.ts.map +1 -1
- package/dist/core/socket-server/socket-client.js +52 -1
- package/dist/core/socket-server/socket-client.js.map +1 -1
- package/dist/core/socket-server/socket-server.d.ts +152 -1
- package/dist/core/socket-server/socket-server.d.ts.map +1 -1
- package/dist/core/socket-server/socket-server.js +775 -26
- package/dist/core/socket-server/socket-server.js.map +1 -1
- package/dist/core/socket-server/types.d.ts +106 -2
- package/dist/core/socket-server/types.d.ts.map +1 -1
- package/dist/core/socket-server/types.js +13 -1
- package/dist/core/socket-server/types.js.map +1 -1
- package/dist/core/system-prompt.d.ts.map +1 -1
- package/dist/core/system-prompt.js +8 -9
- package/dist/core/system-prompt.js.map +1 -1
- package/dist/core/tools/bash.d.ts +1 -1
- package/dist/core/tools/bash.d.ts.map +1 -1
- package/dist/core/tools/bash.js +5 -2
- package/dist/core/tools/bash.js.map +1 -1
- package/dist/core/tools/edit.d.ts.map +1 -1
- package/dist/core/tools/edit.js +17 -2
- package/dist/core/tools/edit.js.map +1 -1
- package/dist/core/tools/find.d.ts +3 -0
- package/dist/core/tools/find.d.ts.map +1 -1
- package/dist/core/tools/find.js +11 -18
- package/dist/core/tools/find.js.map +1 -1
- package/dist/core/trust-manager.d.ts +6 -4
- package/dist/core/trust-manager.d.ts.map +1 -1
- package/dist/core/trust-manager.js +55 -21
- package/dist/core/trust-manager.js.map +1 -1
- package/dist/extensions/index.d.ts.map +1 -1
- package/dist/extensions/index.js +5 -1
- package/dist/extensions/index.js.map +1 -1
- package/dist/extensions/llama/provider.d.ts.map +1 -1
- package/dist/extensions/llama/provider.js +5 -1
- package/dist/extensions/llama/provider.js.map +1 -1
- package/dist/extensions/stub-provider/index.d.ts +9 -0
- package/dist/extensions/stub-provider/index.d.ts.map +1 -0
- package/dist/extensions/stub-provider/index.js +13 -0
- package/dist/extensions/stub-provider/index.js.map +1 -0
- package/dist/extensions/stub-provider/provider.d.ts +77 -0
- package/dist/extensions/stub-provider/provider.d.ts.map +1 -0
- package/dist/extensions/stub-provider/provider.js +193 -0
- package/dist/extensions/stub-provider/provider.js.map +1 -0
- package/dist/hooks/gsd/draht-quality-gate.js +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +242 -45
- package/dist/main.js.map +1 -1
- package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/config-selector.js +3 -2
- package/dist/modes/interactive/components/config-selector.js.map +1 -1
- package/dist/modes/interactive/components/extension-selector.d.ts +49 -0
- package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/extension-selector.js +202 -5
- package/dist/modes/interactive/components/extension-selector.js.map +1 -1
- package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/session-selector.js +10 -2
- package/dist/modes/interactive/components/session-selector.js.map +1 -1
- package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
- package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/settings-selector.js +10 -0
- package/dist/modes/interactive/components/settings-selector.js.map +1 -1
- package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
- package/dist/modes/interactive/components/tool-execution.js +10 -1
- package/dist/modes/interactive/components/tool-execution.js.map +1 -1
- package/dist/modes/interactive/components/tree-selector.d.ts +20 -2
- package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
- package/dist/modes/interactive/components/tree-selector.js +21 -5
- package/dist/modes/interactive/components/tree-selector.js.map +1 -1
- package/dist/modes/interactive/interactive-mode.d.ts +97 -3
- package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
- package/dist/modes/interactive/interactive-mode.js +394 -24
- package/dist/modes/interactive/interactive-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-mode.js +165 -7
- package/dist/modes/rpc/rpc-mode.js.map +1 -1
- package/dist/modes/rpc/rpc-types.d.ts +68 -1
- package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
- package/dist/modes/rpc/rpc-types.js.map +1 -1
- package/dist/prompts/commands/atomic-commit.md +1 -12
- package/dist/prompts/commands/brainstorm.md +12 -15
- package/dist/prompts/commands/create-verification-skill.md +108 -0
- package/dist/prompts/commands/discuss-phase.md +3 -14
- package/dist/prompts/commands/execute-phase.md +3 -11
- package/dist/prompts/commands/fix.md +41 -18
- package/dist/prompts/commands/grill.md +66 -0
- package/dist/prompts/commands/init-project.md +5 -15
- package/dist/prompts/commands/map-codebase.md +1 -13
- package/dist/prompts/commands/new-project.md +5 -15
- package/dist/prompts/commands/next-milestone.md +1 -13
- package/dist/prompts/commands/orchestrate.md +1 -1
- package/dist/prompts/commands/pause-work.md +1 -13
- package/dist/prompts/commands/plan-phase.md +2 -11
- package/dist/prompts/commands/progress.md +0 -13
- package/dist/prompts/commands/quick.md +3 -11
- package/dist/prompts/commands/resolve-conflicts.md +71 -0
- package/dist/prompts/commands/resume-work.md +0 -13
- package/dist/prompts/commands/review.md +4 -13
- package/dist/prompts/commands/triage.md +159 -0
- package/dist/prompts/commands/verify-work.md +4 -14
- package/dist/prompts/commands/why.md +135 -0
- package/dist/skills/atomic-reasoning/SKILL.md +115 -0
- package/dist/skills/blast-radius/SKILL.md +55 -0
- package/dist/skills/epistemics/SKILL.md +99 -0
- package/dist/skills/hexagon-animation/SKILL.md +49 -0
- package/dist/skills/hexagon-animation/generate.mjs +81 -0
- package/dist/skills/hexagon-animation/template.html +361 -0
- package/dist/skills/typescript-discipline/SKILL.md +50 -0
- package/dist/skills/typescript-discipline/references/patterns.md +294 -0
- package/dist/skills/unslop/SKILL.md +101 -0
- package/dist/utils/canonical-path.d.ts +28 -0
- package/dist/utils/canonical-path.d.ts.map +1 -0
- package/dist/utils/canonical-path.js +90 -0
- package/dist/utils/canonical-path.js.map +1 -0
- package/dist/utils/child-process.d.ts +12 -1
- package/dist/utils/child-process.d.ts.map +1 -1
- package/dist/utils/child-process.js +25 -8
- package/dist/utils/child-process.js.map +1 -1
- package/dist/utils/clipboard.d.ts +1 -1
- package/dist/utils/clipboard.d.ts.map +1 -1
- package/dist/utils/clipboard.js +22 -2
- package/dist/utils/clipboard.js.map +1 -1
- package/dist/utils/exif-orientation.d.ts.map +1 -1
- package/dist/utils/exif-orientation.js +2 -3
- package/dist/utils/exif-orientation.js.map +1 -1
- package/dist/utils/paths.d.ts +2 -7
- package/dist/utils/paths.d.ts.map +1 -1
- package/dist/utils/paths.js +13 -15
- package/dist/utils/paths.js.map +1 -1
- package/dist/utils/shell.d.ts.map +1 -1
- package/dist/utils/shell.js +6 -4
- package/dist/utils/shell.js.map +1 -1
- package/dist/utils/tools-manager.d.ts.map +1 -1
- package/dist/utils/tools-manager.js +3 -5
- package/dist/utils/tools-manager.js.map +1 -1
- package/docs/attachable-sessions.md +79 -0
- package/docs/compaction.md +21 -21
- package/docs/containerization.md +23 -23
- package/docs/custom-provider.md +16 -16
- package/docs/development.md +9 -9
- package/docs/docs.json +6 -2
- package/docs/duet.md +42 -0
- package/docs/extensions.md +58 -58
- package/docs/index.md +10 -10
- package/docs/json.md +7 -7
- package/docs/keybindings.md +6 -5
- package/docs/llama-cpp.md +6 -6
- package/docs/models.md +6 -6
- package/docs/packages.md +43 -43
- package/docs/prompt-templates.md +4 -4
- package/docs/providers.md +12 -12
- package/docs/quickstart.md +32 -32
- package/docs/rpc.md +83 -12
- package/docs/sdk.md +15 -15
- package/docs/security.md +18 -18
- package/docs/session-format.md +35 -13
- package/docs/sessions.md +17 -14
- package/docs/settings.md +25 -18
- package/docs/shell-aliases.md +2 -2
- package/docs/skills.md +12 -11
- package/docs/terminal-setup.md +12 -12
- package/docs/termux.md +6 -6
- package/docs/themes.md +11 -11
- package/docs/tmux.md +4 -4
- package/docs/tui.md +5 -5
- package/docs/usage.md +50 -50
- package/docs/windows.md +2 -2
- package/examples/extensions/overlay-qa-tests.ts +3 -3
- package/hooks/gsd/draht-quality-gate.js +3 -3
- package/package.json +11 -10
- package/prompts/commands/atomic-commit.md +1 -12
- package/prompts/commands/brainstorm.md +12 -15
- package/prompts/commands/create-verification-skill.md +108 -0
- package/prompts/commands/discuss-phase.md +3 -14
- package/prompts/commands/execute-phase.md +3 -11
- package/prompts/commands/fix.md +41 -18
- package/prompts/commands/grill.md +66 -0
- package/prompts/commands/init-project.md +5 -15
- package/prompts/commands/map-codebase.md +1 -13
- package/prompts/commands/new-project.md +5 -15
- package/prompts/commands/next-milestone.md +1 -13
- package/prompts/commands/orchestrate.md +1 -1
- package/prompts/commands/pause-work.md +1 -13
- package/prompts/commands/plan-phase.md +2 -11
- package/prompts/commands/progress.md +0 -13
- package/prompts/commands/quick.md +3 -11
- package/prompts/commands/resolve-conflicts.md +71 -0
- package/prompts/commands/resume-work.md +0 -13
- package/prompts/commands/review.md +4 -13
- package/prompts/commands/triage.md +159 -0
- package/prompts/commands/verify-work.md +4 -14
- package/prompts/commands/why.md +135 -0
- package/skills/atomic-reasoning/SKILL.md +115 -0
- package/skills/blast-radius/SKILL.md +55 -0
- package/skills/epistemics/SKILL.md +99 -0
- package/skills/hexagon-animation/SKILL.md +49 -0
- package/skills/hexagon-animation/generate.mjs +81 -0
- package/skills/hexagon-animation/template.html +361 -0
- package/skills/typescript-discipline/SKILL.md +50 -0
- package/skills/typescript-discipline/references/patterns.md +294 -0
- package/skills/unslop/SKILL.md +101 -0
- package/dist/prompts/agents/build.md +0 -86
- package/dist/prompts/agents/plan.md +0 -79
- package/dist/prompts/agents/verify.md +0 -69
- package/prompts/agents/build.md +0 -86
- package/prompts/agents/plan.md +0 -79
- package/prompts/agents/verify.md +0 -69
|
@@ -0,0 +1,660 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SOAK LOG — the append-only, rotating, restart-surviving JSONL that a long-run
|
|
3
|
+
* verdict reads back weeks later.
|
|
4
|
+
*
|
|
5
|
+
* ─────────────────────────────────────────────────────────────────────────────
|
|
6
|
+
* FILE FORMAT CONTRACT (v1)
|
|
7
|
+
* ─────────────────────────────────────────────────────────────────────────────
|
|
8
|
+
* This comment is the contract, not a description of this implementation. A
|
|
9
|
+
* second writer — the daemon half, which lives on the far side of a package
|
|
10
|
+
* boundary that forbids importing this package — must be implementable from
|
|
11
|
+
* this section alone. Do NOT export a shared module across that boundary; the
|
|
12
|
+
* two halves agree on these bytes and on nothing else.
|
|
13
|
+
*
|
|
14
|
+
* LOCATION
|
|
15
|
+
* <agentDir>/soak/ directory, mode 0700
|
|
16
|
+
* <agentDir>/soak/<stem>.jsonl the ACTIVE file, mode 0600
|
|
17
|
+
* <agentDir>/soak/<stem>-<gen>.jsonl a ROTATED generation, mode 0600
|
|
18
|
+
* <agentDir>/soak/<stem>.rotate.lock the rotation lock, mode 0600
|
|
19
|
+
*
|
|
20
|
+
* `<agentDir>` is the coding agent's config dir (honours DRAHT_CODING_AGENT_DIR).
|
|
21
|
+
* `<stem>` names the WRITING HALF, one file per half: "session" for a session
|
|
22
|
+
* process, "daemon" for the gateway/daemon process. The halves observe
|
|
23
|
+
* different events from different lifecycles; they are never interleaved into
|
|
24
|
+
* one file and are joined by `sessionId`/`wall` at verdict time.
|
|
25
|
+
* `<gen>` is `<compact-utc>-<pid>-<counter>` and is UNIQUE FOREVER — a
|
|
26
|
+
* generation name is never reused, so a rotation can never clobber evidence.
|
|
27
|
+
* Example: `session-20260822T114530123Z-40321-0.jsonl`.
|
|
28
|
+
*
|
|
29
|
+
* RECORDS
|
|
30
|
+
* One JSON object per line, UTF-8, terminated by "\n". No trailing commas, no
|
|
31
|
+
* pretty printing, no multi-line values. Every record carries:
|
|
32
|
+
* level "info" | "warn" | "error" (matches the gateway logger shape)
|
|
33
|
+
* timestamp ISO-8601 string (matches the gateway logger shape)
|
|
34
|
+
* event string (see SOAK_EVENTS)
|
|
35
|
+
* v 1 (this format version)
|
|
36
|
+
* wall Date.now() milliseconds
|
|
37
|
+
* mono performance.now() milliseconds
|
|
38
|
+
* uptimeMs process.uptime() * 1000
|
|
39
|
+
* pid writing process id
|
|
40
|
+
* rss process.memoryUsage().rss bytes
|
|
41
|
+
* plus whatever fields the event carries. The fields above are stamped LAST,
|
|
42
|
+
* after the event's own: a caller field that collides with one of them is
|
|
43
|
+
* dropped rather than honoured, because a record whose `pid` or `wall` came
|
|
44
|
+
* from a call site is a record the reader classifies as malformed and drops.
|
|
45
|
+
* `sessionId` is present on every
|
|
46
|
+
* record a session process writes; prompt/permission records additionally
|
|
47
|
+
* carry `requestId`, so this stream can be JOINED against the durable
|
|
48
|
+
* per-session permission rows without duplicating any decision here.
|
|
49
|
+
*
|
|
50
|
+
* All three clocks are recorded on every record on purpose. A frozen process
|
|
51
|
+
* (SIGSTOP/SIGCONT, and by extension a suspended host) shows up as a WALL-CLOCK
|
|
52
|
+
* GAP between consecutive heartbeats, not as divergence between the clocks —
|
|
53
|
+
* measured, all three advanced identically across a 2,677 ms stop. Recording
|
|
54
|
+
* all three costs nothing and leaves the question answerable if a real lid-close
|
|
55
|
+
* behaves differently.
|
|
56
|
+
*
|
|
57
|
+
* APPENDING
|
|
58
|
+
* One open("a", 0600) / write / close per record. NOT a held descriptor: this
|
|
59
|
+
* writer reports an fd gauge, and holding its own fd would perturb the metric
|
|
60
|
+
* it publishes. Concurrent appends from many processes are safe because each
|
|
61
|
+
* record is a single write() to an O_APPEND descriptor.
|
|
62
|
+
*
|
|
63
|
+
* NO fsync. Measured 4.0–4.7 ms per record under Node against 0.017–0.025 ms
|
|
64
|
+
* under Bun; on seams that fire per client attach and per prompt that is a
|
|
65
|
+
* hot-path cost, and it would give materially different guarantees on the
|
|
66
|
+
* runtime this product actually ships as (a Bun-compiled binary). The tolerated
|
|
67
|
+
* failure is the loss of the last few records on a hard power cut; the reader
|
|
68
|
+
* is torn-tail tolerant, so that loss costs one line, never the file.
|
|
69
|
+
*
|
|
70
|
+
* ROTATION (the part that loses data if done naively — measured)
|
|
71
|
+
* A two-slot `rename(f, f.1)` scheme under 8 concurrent writers lost 11,148 of
|
|
72
|
+
* 12,000 records. The scheme below lost ZERO across 8 generations. Implement
|
|
73
|
+
* EXACTLY this order:
|
|
74
|
+
* 1. after appending, fstat the descriptor you just wrote through: that
|
|
75
|
+
* yields both the size and the INODE you filled;
|
|
76
|
+
* 2. if size < maxFileBytes, stop;
|
|
77
|
+
* 3. open(lockPath, "wx", 0600). EEXIST means another writer is rotating:
|
|
78
|
+
* give up silently and let the next append retry. (A lock whose mtime is
|
|
79
|
+
* older than the stale window is debris and may be removed once.)
|
|
80
|
+
* 4. stat the active path again and COMPARE THE INODE against step 1. A
|
|
81
|
+
* different inode means another writer already rotated the file you
|
|
82
|
+
* filled: release the lock and stop. This comparison is the whole
|
|
83
|
+
* correctness argument — without it, two writers rotate in sequence and
|
|
84
|
+
* the second one renames away a fresh file that other writers are still
|
|
85
|
+
* appending to.
|
|
86
|
+
* 5. rename the active path to a UNIQUE generation name.
|
|
87
|
+
* 6. prune (see RETENTION), then append ONE `rotation` record to the new
|
|
88
|
+
* active file naming the generation just closed and everything pruned.
|
|
89
|
+
* 7. unlink the lock.
|
|
90
|
+
*
|
|
91
|
+
* A writer holding a descriptor across step 5 keeps writing into the renamed
|
|
92
|
+
* inode. That is not loss: the reader reads every generation, so those records
|
|
93
|
+
* are still found. It is why generation files may keep growing after rotation
|
|
94
|
+
* and why file order — not byte order across files — is the only ordering the
|
|
95
|
+
* reader promises.
|
|
96
|
+
*
|
|
97
|
+
* RETENTION
|
|
98
|
+
* Two gates, BOTH must permit a delete:
|
|
99
|
+
* • a byte cap over the directory (maxTotalBytes), and
|
|
100
|
+
* • a retention FLOOR: a generation whose newest write is younger than
|
|
101
|
+
* `retentionFloorMs` (default 14 days) is NEVER pruned, even when the byte
|
|
102
|
+
* cap says prune.
|
|
103
|
+
* A byte-only cap sized for a quiet week silently rotates away the first days
|
|
104
|
+
* of a busy one, and a multi-week soak verdict would destroy its own evidence.
|
|
105
|
+
* When the floor blocks a prune the log simply grows; that is the intended
|
|
106
|
+
* trade. Every prune is named in the `rotation` record written into the
|
|
107
|
+
* surviving file, so a gap in the evidence is VISIBLE rather than invisible.
|
|
108
|
+
*
|
|
109
|
+
* HARD RULES FOR ANY IMPLEMENTATION
|
|
110
|
+
* • NEVER write to stdout or stderr. Not a warning, not a stack trace. The TUI
|
|
111
|
+
* owns the terminal, and a default-on session's streams are asserted
|
|
112
|
+
* byte-identical to a feature-off run; one stray line breaks that.
|
|
113
|
+
* • NEVER throw into a caller. Every failure is swallowed; the last one is
|
|
114
|
+
* retained on the instance for a debugger to look at, and that is all.
|
|
115
|
+
* • The soak directory is OUTSIDE the session store on purpose, which is what
|
|
116
|
+
* exempts it from the byte-identity claim.
|
|
117
|
+
*/
|
|
118
|
+
import { closeSync, fstatSync, mkdirSync, openSync, readdirSync, renameSync, statSync, unlinkSync, writeSync, } from "node:fs";
|
|
119
|
+
import { join } from "node:path";
|
|
120
|
+
import { getAgentDir } from "../../config.js";
|
|
121
|
+
/** Format version stamped on every record as `v`. */
|
|
122
|
+
export const SOAK_FORMAT_VERSION = 1;
|
|
123
|
+
/** Directory under the agent dir that holds every soak file. */
|
|
124
|
+
export const SOAK_DIR_NAME = "soak";
|
|
125
|
+
/** File stem for the half a session process writes. */
|
|
126
|
+
export const SOAK_STEM_SESSION = "session";
|
|
127
|
+
/** File stem for the half the daemon writes (a separate implementation of this same contract). */
|
|
128
|
+
export const SOAK_STEM_DAEMON = "daemon";
|
|
129
|
+
/**
|
|
130
|
+
* Canonical event names. Kept as a frozen map rather than a union type so a call
|
|
131
|
+
* site can add a field — or a new event — without editing this file.
|
|
132
|
+
*/
|
|
133
|
+
export const SOAK_EVENTS = Object.freeze({
|
|
134
|
+
SOCKET_BIND: "socket_bind",
|
|
135
|
+
SOCKET_REBIND: "socket_rebind",
|
|
136
|
+
SOCKET_TEARDOWN: "socket_teardown",
|
|
137
|
+
CLIENT_ATTACH: "client_attach",
|
|
138
|
+
CLIENT_DETACH: "client_detach",
|
|
139
|
+
CLIENT_REJECTED: "client_rejected",
|
|
140
|
+
PROMPT_REJECTED: "prompt_rejected",
|
|
141
|
+
SOCKETS_REAPED: "sockets_reaped",
|
|
142
|
+
HEARTBEAT: "heartbeat",
|
|
143
|
+
ROTATION: "rotation",
|
|
144
|
+
});
|
|
145
|
+
/** 4 MiB per generation: ~20k records of the size these events produce. */
|
|
146
|
+
const DEFAULT_MAX_FILE_BYTES = 4 * 1024 * 1024;
|
|
147
|
+
/** 64 MiB across the whole directory before the byte gate opens. */
|
|
148
|
+
const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
|
|
149
|
+
/** 14 days: a 7-day soak plus a full week of slack before its first day can be pruned. */
|
|
150
|
+
const DEFAULT_RETENTION_FLOOR_MS = 14 * 24 * 60 * 60 * 1000;
|
|
151
|
+
/** One heartbeat a minute: fine enough to see a sleep/wake gap, coarse enough to be free. */
|
|
152
|
+
const DEFAULT_HEARTBEAT_MS = 60_000;
|
|
153
|
+
/** A rotation lock older than this was left by a process that died mid-rotation. */
|
|
154
|
+
const LOCK_STALE_MS = 30_000;
|
|
155
|
+
/** Every soak file — active and rotated alike — carries this suffix. */
|
|
156
|
+
const GENERATION_SUFFIX = ".jsonl";
|
|
157
|
+
/** `process.memoryUsage().rss`, or 0 if the runtime refuses. Works under Node and Bun. */
|
|
158
|
+
export function currentRss() {
|
|
159
|
+
try {
|
|
160
|
+
return process.memoryUsage().rss;
|
|
161
|
+
}
|
|
162
|
+
catch {
|
|
163
|
+
return 0;
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Milliseconds since this process started, from `process.uptime()`.
|
|
168
|
+
*
|
|
169
|
+
* The in-tree `time()` helper cannot supply this: it compiles itself out unless
|
|
170
|
+
* DRAHT_TIMING=1, so a soak run would carry no startup delta at all.
|
|
171
|
+
*/
|
|
172
|
+
export function startupDeltaMs() {
|
|
173
|
+
try {
|
|
174
|
+
return Math.round(process.uptime() * 1000);
|
|
175
|
+
}
|
|
176
|
+
catch {
|
|
177
|
+
return 0;
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Open descriptor gauge: open /dev/null, record the descriptor number POSIX hands
|
|
182
|
+
* back (always the lowest free one), close it. 0.04 ms, and it tracks fd growth
|
|
183
|
+
* exactly.
|
|
184
|
+
*
|
|
185
|
+
* Deliberately NOT `lsof` (176–200 ms, 4,000x more — and `lsof -p <pid> -U` ORs
|
|
186
|
+
* its selectors and returns every socket on the machine; the correct form is
|
|
187
|
+
* `lsof -a -p <pid> -U`). Deliberately NOT `process.getActiveResourcesInfo()`,
|
|
188
|
+
* which reports 20 under Node with 20 live listeners and 0 under Bun with the
|
|
189
|
+
* same 20 — and the shipped draht is a Bun-compiled binary.
|
|
190
|
+
*/
|
|
191
|
+
export function fdGauge() {
|
|
192
|
+
let fd;
|
|
193
|
+
try {
|
|
194
|
+
fd = openSync("/dev/null", "r");
|
|
195
|
+
return fd;
|
|
196
|
+
}
|
|
197
|
+
catch {
|
|
198
|
+
return -1;
|
|
199
|
+
}
|
|
200
|
+
finally {
|
|
201
|
+
if (fd !== undefined) {
|
|
202
|
+
try {
|
|
203
|
+
closeSync(fd);
|
|
204
|
+
}
|
|
205
|
+
catch {
|
|
206
|
+
/* swallowed: the gauge must never disturb the caller */
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
/** Counts `.sock` and `.lock` entries with one readdir. Never `lsof`. */
|
|
212
|
+
export function socketDirCounts(socketsDir) {
|
|
213
|
+
let sockCount = 0;
|
|
214
|
+
let lockCount = 0;
|
|
215
|
+
try {
|
|
216
|
+
for (const entry of readdirSync(socketsDir)) {
|
|
217
|
+
if (entry.endsWith(".sock"))
|
|
218
|
+
sockCount++;
|
|
219
|
+
else if (entry.endsWith(".lock"))
|
|
220
|
+
lockCount++;
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
catch {
|
|
224
|
+
/* no sockets dir yet: both gauges are honestly zero */
|
|
225
|
+
}
|
|
226
|
+
return { sockCount, lockCount };
|
|
227
|
+
}
|
|
228
|
+
/** Default soak directory for this process. */
|
|
229
|
+
export function getSoakDir() {
|
|
230
|
+
return join(getAgentDir(), SOAK_DIR_NAME);
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* The rotating soak writer.
|
|
234
|
+
*
|
|
235
|
+
* Every public method swallows every failure — a soak log that can break a
|
|
236
|
+
* session is worse than no soak log — and NOTHING here writes to stdout or
|
|
237
|
+
* stderr under any condition.
|
|
238
|
+
*/
|
|
239
|
+
export class SoakLog {
|
|
240
|
+
#maxFileBytes;
|
|
241
|
+
#maxTotalBytes;
|
|
242
|
+
#retentionFloorMs;
|
|
243
|
+
#heartbeatMs;
|
|
244
|
+
#socketsDir;
|
|
245
|
+
#now;
|
|
246
|
+
#onRotateWindow;
|
|
247
|
+
#sessionId;
|
|
248
|
+
#clientCount;
|
|
249
|
+
#dirReady = false;
|
|
250
|
+
#generationCounter = 0;
|
|
251
|
+
#timer;
|
|
252
|
+
constructor(options = {}) {
|
|
253
|
+
let dir;
|
|
254
|
+
let socketsDir;
|
|
255
|
+
try {
|
|
256
|
+
dir = options.dir ?? getSoakDir();
|
|
257
|
+
socketsDir = options.socketsDir ?? join(getAgentDir(), "sockets");
|
|
258
|
+
}
|
|
259
|
+
catch (error) {
|
|
260
|
+
// getAgentDir() reads the environment and can in principle throw; a
|
|
261
|
+
// constructor that throws would take the session with it.
|
|
262
|
+
this.lastError = error;
|
|
263
|
+
dir = options.dir ?? join(".", SOAK_DIR_NAME);
|
|
264
|
+
socketsDir = options.socketsDir ?? join(".", "sockets");
|
|
265
|
+
}
|
|
266
|
+
this.dir = dir;
|
|
267
|
+
this.stem = options.stem ?? SOAK_STEM_SESSION;
|
|
268
|
+
this.activePath = join(this.dir, `${this.stem}${GENERATION_SUFFIX}`);
|
|
269
|
+
this.lockPath = join(this.dir, `${this.stem}.rotate.lock`);
|
|
270
|
+
this.#maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
|
|
271
|
+
this.#maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
|
|
272
|
+
this.#retentionFloorMs = options.retentionFloorMs ?? DEFAULT_RETENTION_FLOOR_MS;
|
|
273
|
+
this.#heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
|
|
274
|
+
this.#socketsDir = socketsDir;
|
|
275
|
+
this.#now = options.now ?? Date.now;
|
|
276
|
+
this.#sessionId = options.sessionId;
|
|
277
|
+
this.#clientCount = options.clientCount;
|
|
278
|
+
this.#onRotateWindow = options.onRotateWindow;
|
|
279
|
+
}
|
|
280
|
+
/** Stamp every subsequent record with this session id. */
|
|
281
|
+
setSessionId(sessionId) {
|
|
282
|
+
this.#sessionId = sessionId;
|
|
283
|
+
}
|
|
284
|
+
/** Supply a live client count for the heartbeat. */
|
|
285
|
+
setClientCountProvider(provider) {
|
|
286
|
+
this.#clientCount = provider;
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* Append one record. This is the whole write API: a new event or a new field
|
|
290
|
+
* needs no change to this file.
|
|
291
|
+
*
|
|
292
|
+
* `fields` may therefore carry ANY name, including one the contract reserves.
|
|
293
|
+
* A collision loses: the contract's value is stamped over it. The one
|
|
294
|
+
* exception is `sessionId` on a writer that has none of its own — the daemon
|
|
295
|
+
* half writes about sessions it does not belong to — where the caller's value
|
|
296
|
+
* stands.
|
|
297
|
+
*/
|
|
298
|
+
record(event, fields = {}, level = "info") {
|
|
299
|
+
try {
|
|
300
|
+
this.#write(event, fields, level, true);
|
|
301
|
+
}
|
|
302
|
+
catch (error) {
|
|
303
|
+
this.lastError = error;
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* Write one heartbeat now.
|
|
308
|
+
*
|
|
309
|
+
* Edge events cannot answer "how many days did this run", "did the host
|
|
310
|
+
* sleep", or "did fds grow" — only a periodic record can, so the heartbeat is
|
|
311
|
+
* part of the record set, not a nicety.
|
|
312
|
+
*/
|
|
313
|
+
heartbeat(fields = {}) {
|
|
314
|
+
try {
|
|
315
|
+
const counts = socketDirCounts(this.#socketsDir);
|
|
316
|
+
let clientCount;
|
|
317
|
+
try {
|
|
318
|
+
clientCount = this.#clientCount?.();
|
|
319
|
+
}
|
|
320
|
+
catch (error) {
|
|
321
|
+
this.lastError = error;
|
|
322
|
+
}
|
|
323
|
+
this.#write(SOAK_EVENTS.HEARTBEAT, {
|
|
324
|
+
// Same rule as #write: the measured gauges are stamped over a
|
|
325
|
+
// caller field of the same name, never under it. A heartbeat whose
|
|
326
|
+
// fdGauge came from its call site measures nothing.
|
|
327
|
+
...fields,
|
|
328
|
+
fdGauge: fdGauge(),
|
|
329
|
+
sockCount: counts.sockCount,
|
|
330
|
+
lockCount: counts.lockCount,
|
|
331
|
+
...(clientCount === undefined ? {} : { clientCount }),
|
|
332
|
+
}, "info", true);
|
|
333
|
+
}
|
|
334
|
+
catch (error) {
|
|
335
|
+
this.lastError = error;
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* Start the periodic heartbeat. The timer is `unref`'d, so it fires while the
|
|
340
|
+
* process is alive and does not by itself keep the process alive — the idiom
|
|
341
|
+
* the fleet route already uses. Idempotent.
|
|
342
|
+
*/
|
|
343
|
+
startHeartbeat(intervalMs = this.#heartbeatMs) {
|
|
344
|
+
try {
|
|
345
|
+
if (this.#timer)
|
|
346
|
+
return;
|
|
347
|
+
const timer = setInterval(() => this.heartbeat(), intervalMs);
|
|
348
|
+
timer.unref?.();
|
|
349
|
+
this.#timer = timer;
|
|
350
|
+
}
|
|
351
|
+
catch (error) {
|
|
352
|
+
this.lastError = error;
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
/** Stop the periodic heartbeat. Idempotent. */
|
|
356
|
+
stopHeartbeat() {
|
|
357
|
+
try {
|
|
358
|
+
if (!this.#timer)
|
|
359
|
+
return;
|
|
360
|
+
clearInterval(this.#timer);
|
|
361
|
+
this.#timer = undefined;
|
|
362
|
+
}
|
|
363
|
+
catch (error) {
|
|
364
|
+
this.lastError = error;
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
// ── internals ────────────────────────────────────────────────────────────
|
|
368
|
+
#write(event, fields, level, mayRotate) {
|
|
369
|
+
this.#ensureDir();
|
|
370
|
+
const record = {
|
|
371
|
+
// CALLER FIELDS FIRST, and the contract's fields last, so a caller can
|
|
372
|
+
// never shadow one. `record()` promises that a new event or a new field
|
|
373
|
+
// needs no edit to this file, which makes every call site free to pick a
|
|
374
|
+
// field name — and `pid` is an entirely plausible one at a socket seam,
|
|
375
|
+
// where the `.lock` files already carry one. Spread the other way round,
|
|
376
|
+
// `record("client_attach", { pid: "not-a-pid" })` writes a line the
|
|
377
|
+
// reader then rejects as malformed and drops: the seam that reported the
|
|
378
|
+
// event disappears from the evidence instead of failing loudly.
|
|
379
|
+
...fields,
|
|
380
|
+
level,
|
|
381
|
+
timestamp: new Date(this.#now()).toISOString(),
|
|
382
|
+
event,
|
|
383
|
+
v: SOAK_FORMAT_VERSION,
|
|
384
|
+
wall: this.#now(),
|
|
385
|
+
mono: Math.round(performance.now() * 1000) / 1000,
|
|
386
|
+
uptimeMs: startupDeltaMs(),
|
|
387
|
+
pid: process.pid,
|
|
388
|
+
rss: currentRss(),
|
|
389
|
+
...(this.#sessionId === undefined ? {} : { sessionId: this.#sessionId }),
|
|
390
|
+
};
|
|
391
|
+
const line = `${JSON.stringify(record)}\n`;
|
|
392
|
+
const filled = this.#append(line);
|
|
393
|
+
if (mayRotate && filled && filled.size >= this.#maxFileBytes) {
|
|
394
|
+
this.#rotate(filled.ino);
|
|
395
|
+
}
|
|
396
|
+
}
|
|
397
|
+
/**
|
|
398
|
+
* One open/write/close. The fstat before the close is what makes rotation
|
|
399
|
+
* safe: it yields the size AND the inode of the file this record actually
|
|
400
|
+
* landed in, so the rotator can prove it is renaming the file it filled.
|
|
401
|
+
*/
|
|
402
|
+
#append(line) {
|
|
403
|
+
let fd;
|
|
404
|
+
try {
|
|
405
|
+
fd = openSync(this.activePath, "a", 0o600);
|
|
406
|
+
const buf = Buffer.from(line, "utf8");
|
|
407
|
+
let offset = 0;
|
|
408
|
+
while (offset < buf.length) {
|
|
409
|
+
const written = writeSync(fd, buf, offset, buf.length - offset);
|
|
410
|
+
if (written <= 0)
|
|
411
|
+
break;
|
|
412
|
+
offset += written;
|
|
413
|
+
}
|
|
414
|
+
const st = fstatSync(fd);
|
|
415
|
+
return { size: st.size, ino: Number(st.ino) };
|
|
416
|
+
}
|
|
417
|
+
catch (error) {
|
|
418
|
+
this.lastError = error;
|
|
419
|
+
return undefined;
|
|
420
|
+
}
|
|
421
|
+
finally {
|
|
422
|
+
if (fd !== undefined) {
|
|
423
|
+
try {
|
|
424
|
+
closeSync(fd);
|
|
425
|
+
}
|
|
426
|
+
catch (error) {
|
|
427
|
+
this.lastError = error;
|
|
428
|
+
}
|
|
429
|
+
}
|
|
430
|
+
}
|
|
431
|
+
}
|
|
432
|
+
#ensureDir() {
|
|
433
|
+
if (this.#dirReady)
|
|
434
|
+
return;
|
|
435
|
+
mkdirSync(this.dir, { recursive: true, mode: 0o700 });
|
|
436
|
+
this.#dirReady = true;
|
|
437
|
+
}
|
|
438
|
+
/**
|
|
439
|
+
* Lock-guarded, inode-checked, unique-generation rotation. See the contract at
|
|
440
|
+
* the top of this file; the ORDER of the steps is the correctness argument and
|
|
441
|
+
* must not be rearranged.
|
|
442
|
+
*/
|
|
443
|
+
#rotate(filledIno) {
|
|
444
|
+
let lockFd;
|
|
445
|
+
try {
|
|
446
|
+
lockFd = this.#claimRotationLock();
|
|
447
|
+
if (lockFd === undefined)
|
|
448
|
+
return; // another writer is rotating; next append retries
|
|
449
|
+
if (this.#onRotateWindow) {
|
|
450
|
+
try {
|
|
451
|
+
this.#onRotateWindow();
|
|
452
|
+
}
|
|
453
|
+
catch (error) {
|
|
454
|
+
this.lastError = error;
|
|
455
|
+
}
|
|
456
|
+
}
|
|
457
|
+
let current;
|
|
458
|
+
try {
|
|
459
|
+
const st = statSync(this.activePath);
|
|
460
|
+
current = { size: st.size, ino: Number(st.ino) };
|
|
461
|
+
}
|
|
462
|
+
catch {
|
|
463
|
+
return; // already renamed away by someone else
|
|
464
|
+
}
|
|
465
|
+
// THE INODE CHECK: rotate the file THIS record landed in, or rotate
|
|
466
|
+
// nothing. Another writer that rotated while we queued for the lock has
|
|
467
|
+
// already replaced the active path, and renaming its fresh file away is
|
|
468
|
+
// closing a generation nobody filled.
|
|
469
|
+
//
|
|
470
|
+
// Honest note on its weight: with unique generation names the size guard
|
|
471
|
+
// below covers the common case, so this line is defence in depth rather
|
|
472
|
+
// than the thing standing between the log and data loss. It is what keeps
|
|
473
|
+
// the scheme correct if the cap is ever raised at runtime or the size
|
|
474
|
+
// guard is ever relaxed, and `onRotateWindow` exists so it can be killed
|
|
475
|
+
// by a test instead of surviving as unfalsifiable code.
|
|
476
|
+
if (current.ino !== filledIno)
|
|
477
|
+
return;
|
|
478
|
+
if (current.size < this.#maxFileBytes)
|
|
479
|
+
return;
|
|
480
|
+
const generation = this.#nextGenerationPath();
|
|
481
|
+
renameSync(this.activePath, generation);
|
|
482
|
+
const pruned = this.#prune();
|
|
483
|
+
// Into the SURVIVING file, so a pruned gap is visible rather than invisible.
|
|
484
|
+
this.#write(SOAK_EVENTS.ROTATION, {
|
|
485
|
+
rotatedTo: generation.slice(this.dir.length + 1),
|
|
486
|
+
rotatedBytes: current.size,
|
|
487
|
+
maxFileBytes: this.#maxFileBytes,
|
|
488
|
+
maxTotalBytes: this.#maxTotalBytes,
|
|
489
|
+
retentionFloorMs: this.#retentionFloorMs,
|
|
490
|
+
pruned: pruned.names,
|
|
491
|
+
prunedBytes: pruned.bytes,
|
|
492
|
+
retainedByFloor: pruned.retainedByFloor,
|
|
493
|
+
}, "info", false);
|
|
494
|
+
}
|
|
495
|
+
catch (error) {
|
|
496
|
+
this.lastError = error;
|
|
497
|
+
}
|
|
498
|
+
finally {
|
|
499
|
+
if (lockFd !== undefined) {
|
|
500
|
+
try {
|
|
501
|
+
closeSync(lockFd);
|
|
502
|
+
}
|
|
503
|
+
catch (error) {
|
|
504
|
+
this.lastError = error;
|
|
505
|
+
}
|
|
506
|
+
try {
|
|
507
|
+
unlinkSync(this.lockPath);
|
|
508
|
+
}
|
|
509
|
+
catch (error) {
|
|
510
|
+
this.lastError = error;
|
|
511
|
+
}
|
|
512
|
+
}
|
|
513
|
+
}
|
|
514
|
+
}
|
|
515
|
+
/** `wx` exclusive create — the idiom the socket lock already uses. Undefined means "someone else holds it". */
|
|
516
|
+
#claimRotationLock() {
|
|
517
|
+
for (let attempt = 0; attempt < 2; attempt++) {
|
|
518
|
+
try {
|
|
519
|
+
const fd = openSync(this.lockPath, "wx", 0o600);
|
|
520
|
+
try {
|
|
521
|
+
writeSync(fd, `${process.pid}\n${new Date(this.#now()).toISOString()}\n`);
|
|
522
|
+
}
|
|
523
|
+
catch (error) {
|
|
524
|
+
this.lastError = error;
|
|
525
|
+
}
|
|
526
|
+
return fd;
|
|
527
|
+
}
|
|
528
|
+
catch (error) {
|
|
529
|
+
if (error?.code !== "EEXIST") {
|
|
530
|
+
this.lastError = error;
|
|
531
|
+
return undefined;
|
|
532
|
+
}
|
|
533
|
+
}
|
|
534
|
+
// A lock that has sat far longer than any rotation takes was left by a
|
|
535
|
+
// process that died mid-rotation. Remove it once, then retry.
|
|
536
|
+
try {
|
|
537
|
+
const st = statSync(this.lockPath);
|
|
538
|
+
if (this.#now() - st.mtimeMs < LOCK_STALE_MS)
|
|
539
|
+
return undefined;
|
|
540
|
+
unlinkSync(this.lockPath);
|
|
541
|
+
}
|
|
542
|
+
catch {
|
|
543
|
+
return undefined;
|
|
544
|
+
}
|
|
545
|
+
}
|
|
546
|
+
return undefined;
|
|
547
|
+
}
|
|
548
|
+
/** Unique forever: compact UTC stamp + pid + a per-process counter, and never an existing path. */
|
|
549
|
+
#nextGenerationPath() {
|
|
550
|
+
for (;;) {
|
|
551
|
+
const stamp = new Date(this.#now()).toISOString().replace(/[-:.]/g, "");
|
|
552
|
+
const name = `${this.stem}-${stamp}-${process.pid}-${this.#generationCounter++}${GENERATION_SUFFIX}`;
|
|
553
|
+
const candidate = join(this.dir, name);
|
|
554
|
+
try {
|
|
555
|
+
statSync(candidate);
|
|
556
|
+
}
|
|
557
|
+
catch {
|
|
558
|
+
return candidate; // does not exist
|
|
559
|
+
}
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
/**
|
|
563
|
+
* Byte cap AND retention floor, both of which must permit a delete. Returns
|
|
564
|
+
* what went, what it weighed, and how many generations the floor saved — all
|
|
565
|
+
* of which land in the rotation record.
|
|
566
|
+
*/
|
|
567
|
+
#prune() {
|
|
568
|
+
const names = [];
|
|
569
|
+
let bytes = 0;
|
|
570
|
+
let retainedByFloor = 0;
|
|
571
|
+
try {
|
|
572
|
+
const generations = listGenerationFiles(this.dir, this.stem);
|
|
573
|
+
let total = 0;
|
|
574
|
+
for (const gen of generations)
|
|
575
|
+
total += gen.size;
|
|
576
|
+
try {
|
|
577
|
+
total += statSync(this.activePath).size;
|
|
578
|
+
}
|
|
579
|
+
catch {
|
|
580
|
+
/* no active file right now; it is about to be created */
|
|
581
|
+
}
|
|
582
|
+
const now = this.#now();
|
|
583
|
+
for (const gen of generations) {
|
|
584
|
+
if (total <= this.#maxTotalBytes)
|
|
585
|
+
break;
|
|
586
|
+
if (now - gen.mtimeMs < this.#retentionFloorMs) {
|
|
587
|
+
// The floor wins over the byte cap, always. Growing is the intended
|
|
588
|
+
// trade: a soak verdict that prunes its own first days is worthless.
|
|
589
|
+
retainedByFloor++;
|
|
590
|
+
continue;
|
|
591
|
+
}
|
|
592
|
+
try {
|
|
593
|
+
unlinkSync(gen.path);
|
|
594
|
+
names.push(gen.name);
|
|
595
|
+
bytes += gen.size;
|
|
596
|
+
total -= gen.size;
|
|
597
|
+
}
|
|
598
|
+
catch (error) {
|
|
599
|
+
this.lastError = error;
|
|
600
|
+
}
|
|
601
|
+
}
|
|
602
|
+
}
|
|
603
|
+
catch (error) {
|
|
604
|
+
this.lastError = error;
|
|
605
|
+
}
|
|
606
|
+
return { names, bytes, retainedByFloor };
|
|
607
|
+
}
|
|
608
|
+
}
|
|
609
|
+
/**
|
|
610
|
+
* Every rotated generation for `stem`, oldest first.
|
|
611
|
+
*
|
|
612
|
+
* Ordered by the timestamp embedded in the NAME, not by mtime: a straggler
|
|
613
|
+
* writer still holding a descriptor keeps appending to a generation after it was
|
|
614
|
+
* renamed, which moves its mtime but not its place in the sequence.
|
|
615
|
+
*/
|
|
616
|
+
export function listGenerationFiles(dir, stem) {
|
|
617
|
+
const prefix = `${stem}-`;
|
|
618
|
+
const files = [];
|
|
619
|
+
let entries;
|
|
620
|
+
try {
|
|
621
|
+
entries = readdirSync(dir);
|
|
622
|
+
}
|
|
623
|
+
catch {
|
|
624
|
+
return files;
|
|
625
|
+
}
|
|
626
|
+
for (const name of entries) {
|
|
627
|
+
if (!name.startsWith(prefix) || !name.endsWith(GENERATION_SUFFIX))
|
|
628
|
+
continue;
|
|
629
|
+
const path = join(dir, name);
|
|
630
|
+
try {
|
|
631
|
+
const st = statSync(path);
|
|
632
|
+
if (!st.isFile())
|
|
633
|
+
continue;
|
|
634
|
+
files.push({ name, path, size: st.size, mtimeMs: st.mtimeMs });
|
|
635
|
+
}
|
|
636
|
+
catch {
|
|
637
|
+
/* vanished between readdir and stat; another writer pruned it */
|
|
638
|
+
}
|
|
639
|
+
}
|
|
640
|
+
files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
|
|
641
|
+
return files;
|
|
642
|
+
}
|
|
643
|
+
let singleton;
|
|
644
|
+
/**
|
|
645
|
+
* Process-wide soak log for the session half.
|
|
646
|
+
*
|
|
647
|
+
* Constructed lazily so importing this module costs nothing and creates no
|
|
648
|
+
* directory; the first record makes the directory.
|
|
649
|
+
*/
|
|
650
|
+
export function getSoakLog() {
|
|
651
|
+
if (!singleton)
|
|
652
|
+
singleton = new SoakLog();
|
|
653
|
+
return singleton;
|
|
654
|
+
}
|
|
655
|
+
/** Replace the process-wide log (tests, and the daemon half if it ever shares a process). */
|
|
656
|
+
export function setSoakLog(log) {
|
|
657
|
+
singleton?.stopHeartbeat();
|
|
658
|
+
singleton = log;
|
|
659
|
+
}
|
|
660
|
+
//# sourceMappingURL=soak-log.js.map
|