@sema-agent/core 7.67.3 → 7.68.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 +1537 -0
- package/README.md +18 -9
- package/README.zh-CN.md +16 -8
- package/dist/agents/agent-definition.d.ts +1 -1
- package/dist/agents/agent-definition.js +4 -1
- package/dist/agents/cascade.d.ts +2 -2
- package/dist/agents/cascade.js +3 -1
- package/dist/agents/cumulative-stats.d.ts +2 -1
- package/dist/agents/cumulative-stats.js +4 -1
- package/dist/agents/list-agents-tool.d.ts +30 -0
- package/dist/agents/list-agents-tool.js +45 -3
- package/dist/agents/peer-admission.d.ts +2 -2
- package/dist/agents/peer-session-drain.d.ts +2 -0
- package/dist/agents/peer-session-drain.js +1 -0
- package/dist/agents/repair-loop.js +3 -1
- package/dist/agents/retain-ledger.d.ts +61 -8
- package/dist/agents/retain-ledger.js +25 -3
- package/dist/agents/roster-store.d.ts +4 -2
- package/dist/agents/send-message-tool.d.ts +1 -1
- package/dist/agents/send-message-tool.js +20 -15
- package/dist/agents/subagent-steps.js +2 -10
- package/dist/agents/subagent.d.ts +3 -0
- package/dist/agents/subagent.js +106 -76
- package/dist/agents/tool-filter.d.ts +20 -11
- package/dist/agents/tool-filter.js +8 -4
- package/dist/agents/verify.d.ts +3 -1
- package/dist/agents/verify.js +2 -0
- package/dist/brain/anthropic.js +4 -4
- package/dist/brain/open-responses.js +3 -1
- package/dist/brain/openai.js +3 -1
- package/dist/brain/reasoning-request.d.ts +73 -19
- package/dist/brain/reasoning-request.js +164 -72
- package/dist/brain/reasoning-stamp.d.ts +26 -0
- package/dist/brain/reasoning-stamp.js +10 -0
- package/dist/brain/reasoning.d.ts +95 -162
- package/dist/brain/reasoning.js +31 -86
- package/dist/brain/route-adjudicator.d.ts +9 -7
- package/dist/brain/route-adjudicator.js +12 -10
- package/dist/brain/status-sink.d.ts +19 -64
- package/dist/brain/status-sink.js +5 -21
- package/dist/brain/stream-engine.d.ts +11 -2
- package/dist/brain/stream-engine.js +10 -0
- package/dist/core/a2a.d.ts +17 -5
- package/dist/core/a2a.js +11 -3
- package/dist/core/allow-entry.d.ts +35 -15
- package/dist/core/allow-entry.js +47 -60
- package/dist/core/ask-headline.d.ts +68 -0
- package/dist/core/ask-headline.js +23 -0
- package/dist/core/ask-origin.d.ts +36 -8
- package/dist/core/ask-origin.js +17 -10
- package/dist/core/ask-question.d.ts +34 -7
- package/dist/core/ask-question.js +10 -1
- package/dist/core/ask-unresolvable-notice.d.ts +7 -0
- package/dist/core/ask-unresolvable-notice.js +9 -3
- package/dist/core/auto-strip.d.ts +53 -0
- package/dist/core/auto-strip.js +76 -0
- package/dist/core/background-agent-store.d.ts +45 -5
- package/dist/core/background-agent-store.js +69 -15
- package/dist/core/background-shell.d.ts +2 -2
- package/dist/core/caller-text.js +2 -2
- package/dist/core/canonical-json.d.ts +13 -0
- package/dist/core/canonical-json.js +7 -0
- package/dist/core/checkpoint-features.d.ts +66 -20
- package/dist/core/checkpoint-features.js +12 -1
- package/dist/core/checkpoint-generation.d.ts +1 -1
- package/dist/core/checkpoint-queries.d.ts +1 -1
- package/dist/core/checkpoint-queries.js +4 -1
- package/dist/core/checkpoint-requirements.d.ts +45 -2
- package/dist/core/checkpoint-requirements.js +16 -6
- package/dist/core/checkpoint-row-verdict.d.ts +1 -0
- package/dist/core/checkpoint-row-verdict.js +4 -0
- package/dist/core/checkpoint-store.d.ts +66 -38
- package/dist/core/checkpoint-store.js +15 -6
- package/dist/core/child-clamp-seats.d.ts +6 -0
- package/dist/core/child-clamp-seats.js +1 -0
- package/dist/core/config-refusal-codes.d.ts +1 -1
- package/dist/core/config-refusal-codes.js +1 -0
- package/dist/core/delegation-frames.d.ts +9 -12
- package/dist/core/delegation-frames.js +9 -8
- package/dist/core/engine-capabilities.d.ts +21 -8
- package/dist/core/engine-capabilities.js +1 -1
- package/dist/core/engine-notice.d.ts +147 -34
- package/dist/core/engine-notice.js +27 -16
- package/dist/core/engine-storage-backend.d.ts +2 -1
- package/dist/core/env-budget.js +3 -3
- package/dist/core/env-knob-announce.d.ts +10 -10
- package/dist/core/env-knob-announce.js +3 -6
- package/dist/core/file-history-store.d.ts +29 -4
- package/dist/core/file-history-store.js +13 -0
- package/dist/core/frame-settlement.d.ts +2 -1
- package/dist/core/gate-fold.js +1 -1
- package/dist/core/gate-lanes.js +56 -49
- package/dist/core/governance-codes.d.ts +39 -3
- package/dist/core/governance-codes.js +61 -3
- package/dist/core/hooks.d.ts +29 -11
- package/dist/core/hooks.js +5 -2
- package/dist/core/human-input-projection.js +3 -3
- package/dist/core/input-author.d.ts +17 -3
- package/dist/core/input-author.js +15 -3
- package/dist/core/leg-identity.d.ts +10 -28
- package/dist/core/leg-identity.js +1 -21
- package/dist/core/lsp.d.ts +18 -13
- package/dist/core/lsp.js +30 -22
- package/dist/core/mailbox-store.d.ts +1 -1
- package/dist/core/mailbox-store.js +4 -4
- package/dist/core/mcp-connection-pool.d.ts +93 -4
- package/dist/core/mcp-connection-pool.js +104 -1
- package/dist/core/mcp-failure.d.ts +38 -12
- package/dist/core/mcp-failure.js +9 -13
- package/dist/core/mcp-probe.d.ts +4 -3
- package/dist/core/mcp-server-link.d.ts +4 -2
- package/dist/core/mcp-server-link.js +4 -5
- package/dist/core/mcp-server-spec.d.ts +3 -3
- package/dist/core/mcp-server-unavailable-notice.d.ts +22 -8
- package/dist/core/mcp-server-unavailable-notice.js +18 -4
- package/dist/core/mcp.d.ts +40 -6
- package/dist/core/mcp.js +39 -13
- package/dist/core/memory-engine/content-origin.js +2 -2
- package/dist/core/memory-engine/control-objects.d.ts +2 -4
- package/dist/core/memory-engine/control-objects.js +2 -10
- package/dist/core/memory-engine/delegation-settlement.js +6 -1
- package/dist/core/memory-engine/dual-root.js +3 -0
- package/dist/core/memory-engine/engine.d.ts +6 -4
- package/dist/core/memory-engine/engine.js +32 -29
- package/dist/core/memory-engine/file-backend.d.ts +20 -5
- package/dist/core/memory-engine/file-backend.js +21 -31
- package/dist/core/memory-engine/frontmatter.d.ts +2 -0
- package/dist/core/memory-engine/frontmatter.js +4 -0
- package/dist/core/memory-engine/layout.d.ts +114 -20
- package/dist/core/memory-engine/layout.js +340 -22
- package/dist/core/memory-engine/memory-deployment.d.ts +7 -5
- package/dist/core/memory-engine/mount-failed-notice.d.ts +19 -7
- package/dist/core/memory-engine/mount-failed-notice.js +43 -10
- package/dist/core/memory-engine/sync-client.js +4 -5
- package/dist/core/model-fallbacks.d.ts +5 -1
- package/dist/core/model-fallbacks.js +3 -3
- package/dist/core/model-receipt.d.ts +2 -1
- package/dist/core/model-receipt.js +12 -1
- package/dist/core/mods/kernel/dispatch.d.ts +2 -2
- package/dist/core/mods/kernel/dispatch.js +14 -6
- package/dist/core/mods/kernel/events.d.ts +8 -5
- package/dist/core/mods/kernel/events.js +2 -2
- package/dist/core/mods/kernel/index.d.ts +1 -1
- package/dist/core/mods/kernel/registration.d.ts +9 -0
- package/dist/core/mods/package.js +1 -1
- package/dist/core/mods/session-append.d.ts +4 -2
- package/dist/core/mods/session-append.js +3 -0
- package/dist/core/mods/stations.d.ts +7 -11
- package/dist/core/mods/stations.js +4 -7
- package/dist/core/mods/tool-call.d.ts +10 -8
- package/dist/core/mods/tool-call.js +15 -18
- package/dist/core/mounted-mcp.d.ts +0 -4
- package/dist/core/mounted-mcp.js +1 -1
- package/dist/core/park-noun.d.ts +24 -0
- package/dist/core/park-noun.js +21 -0
- package/dist/core/park-resumability.d.ts +60 -0
- package/dist/core/park-resumability.js +30 -0
- package/dist/core/permission-rule-provider.d.ts +24 -2
- package/dist/core/permission-rule-provider.js +11 -8
- package/dist/core/permission-rule-store.d.ts +8 -1
- package/dist/core/permission-rule-store.js +2 -3
- package/dist/core/permission-rules.d.ts +2 -1
- package/dist/core/permission-rules.js +8 -4
- package/dist/core/persisted-rule-arms.d.ts +3 -0
- package/dist/core/persisted-rule-arms.js +2 -1
- package/dist/core/present-plan-tool.d.ts +47 -3
- package/dist/core/present-plan-tool.js +62 -4
- package/dist/core/principal-name.d.ts +1 -1
- package/dist/core/principal-name.js +5 -5
- package/dist/core/process-identity.js +10 -5
- package/dist/core/protocol-http-auth.d.ts +20 -14
- package/dist/core/protocol-http-auth.js +70 -50
- package/dist/core/read-only-shell.js +9 -5
- package/dist/core/redaction-marks.d.ts +4 -26
- package/dist/core/redaction-marks.js +9 -21
- package/dist/core/remote-env.d.ts +43 -16
- package/dist/core/remote-env.js +1 -1
- package/dist/core/request-copy-projection.d.ts +1 -1
- package/dist/core/request-copy-projection.js +40 -50
- package/dist/core/resume-config-judge.js +1 -1
- package/dist/core/resume-startup-cause.d.ts +35 -18
- package/dist/core/resume-startup-cause.js +13 -10
- package/dist/core/retention.d.ts +167 -25
- package/dist/core/retention.js +100 -20
- package/dist/core/roles.d.ts +6 -0
- package/dist/core/roles.js +11 -5
- package/dist/core/rule-lane-reads.d.ts +3 -0
- package/dist/core/rule-lane-reads.js +5 -1
- package/dist/core/rule-store-fault.d.ts +70 -0
- package/dist/core/rule-store-fault.js +102 -0
- package/dist/core/runner/advertised-writable-dirs.js +16 -31
- package/dist/core/runner/announce-once-ledger.d.ts +19 -2
- package/dist/core/runner/announce-once-ledger.js +24 -2
- package/dist/core/runner/assemble-result.d.ts +6 -0
- package/dist/core/runner/assemble-result.js +1 -1
- package/dist/core/runner/auto-strip-notice.d.ts +36 -0
- package/dist/core/runner/auto-strip-notice.js +59 -0
- package/dist/core/runner/branch-window.d.ts +3 -0
- package/dist/core/runner/branch-window.js +37 -0
- package/dist/core/runner/caller-roster.d.ts +8 -3
- package/dist/core/runner/capability-withheld-seat.js +3 -9
- package/dist/core/runner/clock-and-limits.d.ts +22 -1
- package/dist/core/runner/clock-and-limits.js +30 -0
- package/dist/core/runner/contracts.d.ts +58 -35
- package/dist/core/runner/credential-refusal-seat.d.ts +2 -0
- package/dist/core/runner/credential-refusal-seat.js +47 -0
- package/dist/core/runner/cross-boundary-lane.js +6 -4
- package/dist/core/runner/decide-continuation.js +1 -1
- package/dist/core/runner/file-history-restore.d.ts +53 -2
- package/dist/core/runner/file-history-restore.js +29 -10
- package/dist/core/runner/forward-sink.d.ts +14 -1
- package/dist/core/runner/forward-sink.js +14 -12
- package/dist/core/runner/gate-exit.d.ts +8 -7
- package/dist/core/runner/gate-exit.js +13 -13
- package/dist/core/runner/git-status-frame.js +2 -4
- package/dist/core/runner/initial-run-state.js +1 -1
- package/dist/core/runner/main-call-account.d.ts +3 -1
- package/dist/core/runner/main-call-account.js +5 -3
- package/dist/core/runner/mcp-redial.d.ts +2 -5
- package/dist/core/runner/mcp-redial.js +2 -2
- package/dist/core/runner/nested-memory-content.d.ts +7 -1
- package/dist/core/runner/nested-memory-content.js +73 -13
- package/dist/core/runner/nested-memory-lane.d.ts +44 -19
- package/dist/core/runner/nested-memory-lane.js +152 -76
- package/dist/core/runner/park-commit.js +3 -1
- package/dist/core/runner/permission-rule-lanes.d.ts +8 -2
- package/dist/core/runner/permission-rule-lanes.js +29 -3
- package/dist/core/runner/person-path-rows.d.ts +3 -11
- package/dist/core/runner/person-path-rows.js +21 -24
- package/dist/core/runner/prepare-acquire-reconcile.js +3 -1
- package/dist/core/runner/prepare-artifact.d.ts +1 -1
- package/dist/core/runner/prepare-artifact.js +20 -14
- package/dist/core/runner/prepare-ask-lane.d.ts +9 -6
- package/dist/core/runner/prepare-ask-lane.js +6 -5
- package/dist/core/runner/prepare-boundary-parks.d.ts +7 -1
- package/dist/core/runner/prepare-boundary-parks.js +27 -24
- package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -2
- package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
- package/dist/core/runner/prepare-config-doors.d.ts +9 -24
- package/dist/core/runner/prepare-config-doors.js +58 -41
- package/dist/core/runner/prepare-context-lane.d.ts +2 -2
- package/dist/core/runner/prepare-context-lane.js +3 -5
- package/dist/core/runner/prepare-defer-classify.d.ts +1 -1
- package/dist/core/runner/prepare-defer-classify.js +1 -1
- package/dist/core/runner/prepare-delegation-surface.d.ts +2 -2
- package/dist/core/runner/prepare-delegation-surface.js +3 -2
- package/dist/core/runner/prepare-file-history.d.ts +62 -26
- package/dist/core/runner/prepare-file-history.js +117 -46
- package/dist/core/runner/prepare-gate-stations.d.ts +4 -0
- package/dist/core/runner/prepare-gate-stations.js +6 -5
- package/dist/core/runner/prepare-hands-readface.d.ts +9 -4
- package/dist/core/runner/prepare-hands-readface.js +8 -4
- package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
- package/dist/core/runner/prepare-inherited-gate.js +6 -6
- package/dist/core/runner/prepare-listings.d.ts +1 -1
- package/dist/core/runner/prepare-listings.js +1 -1
- package/dist/core/runner/prepare-memory.js +2 -2
- package/dist/core/runner/prepare-offload-wrappers.d.ts +1 -1
- package/dist/core/runner/prepare-offload-wrappers.js +1 -1
- package/dist/core/runner/prepare-park-ask.d.ts +10 -3
- package/dist/core/runner/prepare-park-ask.js +7 -9
- package/dist/core/runner/prepare-policy-chain.d.ts +18 -9
- package/dist/core/runner/prepare-policy-chain.js +18 -13
- package/dist/core/runner/prepare-project-context.d.ts +1 -1
- package/dist/core/runner/prepare-project-context.js +5 -3
- package/dist/core/runner/prepare-prompt-assembly.js +2 -1
- package/dist/core/runner/prepare-prompt-inputs.d.ts +2 -2
- package/dist/core/runner/prepare-prompt-inputs.js +1 -1
- package/dist/core/runner/prepare-protocol-tools.d.ts +4 -5
- package/dist/core/runner/prepare-protocol-tools.js +7 -7
- package/dist/core/runner/prepare-question-face.d.ts +4 -2
- package/dist/core/runner/prepare-run-refs.d.ts +7 -2
- package/dist/core/runner/prepare-run-refs.js +8 -7
- package/dist/core/runner/prepare-safety-scan.d.ts +4 -3
- package/dist/core/runner/prepare-suspend-saga.d.ts +3 -7
- package/dist/core/runner/prepare-suspend-saga.js +4 -3
- package/dist/core/runner/prepare-task.js +66 -53
- package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +3 -2
- package/dist/core/runner/prepare-tool-disclosure-mount.js +2 -1
- package/dist/core/runner/prepare-turn-wiring.d.ts +3 -1
- package/dist/core/runner/prepare-turn-wiring.js +1 -1
- package/dist/core/runner/prepare-wiring-manifest.d.ts +9 -4
- package/dist/core/runner/prepare-wiring-manifest.js +14 -6
- package/dist/core/runner/prepare-workspace-restore.d.ts +4 -4
- package/dist/core/runner/prepare-workspace-restore.js +15 -6
- package/dist/core/runner/remote-env-retry.d.ts +3 -3
- package/dist/core/runner/restore-seat.d.ts +41 -0
- package/dist/core/runner/restore-seat.js +38 -0
- package/dist/core/runner/resume-admission.js +1 -1
- package/dist/core/runner/resume-apply.js +4 -3
- package/dist/core/runner/resume-checkpoint-screen.js +2 -1
- package/dist/core/runner/resume-internals-and-config.js +2 -1
- package/dist/core/runner/resume-preflight.js +2 -1
- package/dist/core/runner/rewind-files.js +22 -6
- package/dist/core/runner/rule-store-unreadable-notice.d.ts +8 -0
- package/dist/core/runner/rule-store-unreadable-notice.js +11 -0
- package/dist/core/runner/run-brain-sinks.d.ts +3 -6
- package/dist/core/runner/run-brain-sinks.js +6 -6
- package/dist/core/runner/run-compaction-machinery.d.ts +2 -2
- package/dist/core/runner/run-git-lane.d.ts +2 -0
- package/dist/core/runner/run-git-lane.js +2 -1
- package/dist/core/runner/run-harness-handlers.js +5 -4
- package/dist/core/runner/run-identity-wiring.js +20 -12
- package/dist/core/runner/run-leg.js +31 -72
- package/dist/core/runner/run-notification-lane.d.ts +3 -0
- package/dist/core/runner/run-notification-lane.js +2 -4
- package/dist/core/runner/run-reasoning-seat.d.ts +5 -6
- package/dist/core/runner/run-reasoning-seat.js +13 -18
- package/dist/core/runner/run-settle-and-teardown.js +13 -9
- package/dist/core/runner/run-terminal-adoption.js +4 -8
- package/dist/core/runner/run-turn-boundary.js +6 -3
- package/dist/core/runner/runtask.d.ts +9 -4
- package/dist/core/runner/runtask.js +29 -22
- package/dist/core/runner/session-rule-policy.d.ts +11 -1
- package/dist/core/runner/shell-env-withheld.js +2 -7
- package/dist/core/runner/side-call-account.d.ts +5 -6
- package/dist/core/runner/side-call-account.js +2 -2
- package/dist/core/runner/stream-lifecycle-verbs.d.ts +3 -0
- package/dist/core/runner/stream-lifecycle-verbs.js +5 -3
- package/dist/core/runner/stream-settle-backstop.js +4 -6
- package/dist/core/runner/stream-steer-verb.d.ts +1 -1
- package/dist/core/runner/stream-steer-verb.js +4 -4
- package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -3
- package/dist/core/runner/sub-agent-deny-lists.js +7 -4
- package/dist/core/runner/teardown-bounded.d.ts +7 -0
- package/dist/core/runner/teardown-bounded.js +7 -0
- package/dist/core/runner/terminal-account.js +41 -13
- package/dist/core/runner/terminal-projection.d.ts +1 -5
- package/dist/core/runner/tool-end-body.d.ts +9 -3
- package/dist/core/runner/tool-end-body.js +6 -3
- package/dist/core/runner/tool-output-projection.d.ts +13 -4
- package/dist/core/runner/tool-output-projection.js +10 -14
- package/dist/core/runner/turn-attachments.d.ts +3 -2
- package/dist/core/runner/turn-attachments.js +12 -5
- package/dist/core/runner-deps.d.ts +6 -6
- package/dist/core/runtime-caps.d.ts +2 -1
- package/dist/core/secret-env.d.ts +20 -3
- package/dist/core/secret-env.js +13 -15
- package/dist/core/session-checkout.d.ts +115 -15
- package/dist/core/session-checkout.js +435 -136
- package/dist/core/session-policy-store.js +21 -3
- package/dist/core/session-reconcile.js +1 -0
- package/dist/core/session-store.js +2 -0
- package/dist/core/session.d.ts +11 -1
- package/dist/core/shell-run-candidates.d.ts +1 -0
- package/dist/core/shell-run-candidates.js +1 -1
- package/dist/core/shutdown-debug.d.ts +6 -5
- package/dist/core/shutdown-debug.js +5 -1
- package/dist/core/skill-grant.js +4 -1
- package/dist/core/skills-directory.js +5 -3
- package/dist/core/spec-contract.d.ts +1 -1
- package/dist/core/store-contracts/checkpoint-store-contract.js +2 -7
- package/dist/core/store-contracts/file-history-store-contract.js +26 -2
- package/dist/core/store-contracts/session-deletion-cascade-contract.js +130 -14
- package/dist/core/store-contracts/task-list-store-contract.d.ts +2 -1
- package/dist/core/store-contracts/task-list-store-contract.js +28 -1
- package/dist/core/task-event.d.ts +48 -27
- package/dist/core/task-notification.d.ts +15 -9
- package/dist/core/task-notification.js +12 -0
- package/dist/core/task-registry-agent.d.ts +24 -22
- package/dist/core/task-registry-agent.js +65 -46
- package/dist/core/task-registry-shared.d.ts +17 -5
- package/dist/core/task-registry.d.ts +17 -6
- package/dist/core/task-registry.js +6 -1
- package/dist/core/task-result.d.ts +71 -25
- package/dist/core/task-spec-members.d.ts +0 -1
- package/dist/core/task-spec-members.js +1 -1
- package/dist/core/task-spec.d.ts +60 -52
- package/dist/core/task-stream.d.ts +45 -12
- package/dist/core/terminal-cause.d.ts +45 -8
- package/dist/core/terminal-cause.js +5 -0
- package/dist/core/tool-card-bound.d.ts +32 -0
- package/dist/core/tool-card-bound.js +33 -0
- package/dist/core/tool-catalog-entries.d.ts +9 -0
- package/dist/core/tool-catalog-entries.js +48 -0
- package/dist/core/tool-errors.d.ts +4 -3
- package/dist/core/tool-face.d.ts +3 -3
- package/dist/core/tool-mount-facts.d.ts +3 -2
- package/dist/core/tool-mount-facts.js +1 -1
- package/dist/core/tool-mount-static.js +7 -5
- package/dist/core/tool-policy.d.ts +21 -19
- package/dist/core/tool-policy.js +5 -6
- package/dist/core/tool-registry.d.ts +3 -1
- package/dist/core/tool-registry.js +15 -1
- package/dist/core/tool-result-store.d.ts +9 -3
- package/dist/core/tool-result-store.js +14 -1
- package/dist/core/tool-roster.d.ts +18 -0
- package/dist/core/tool-roster.js +30 -1
- package/dist/core/tool-spec.d.ts +17 -8
- package/dist/core/trace.d.ts +35 -31
- package/dist/core/types.d.ts +2 -2
- package/dist/core/untrusted-egress.d.ts +10 -9
- package/dist/core/untrusted-egress.js +9 -9
- package/dist/core/untrusted-text.d.ts +0 -18
- package/dist/core/untrusted-text.js +7 -3
- package/dist/core/user-attachment.d.ts +9 -6
- package/dist/core/user-attachment.js +12 -10
- package/dist/core/user-row-origin.d.ts +44 -25
- package/dist/core/user-row-origin.js +30 -20
- package/dist/core/wiring-manifest.d.ts +26 -7
- package/dist/core/wiring-manifest.js +14 -11
- package/dist/core/workspace-snapshot.d.ts +3 -1
- package/dist/core/workspace-snapshot.js +1 -0
- package/dist/engine/execution-env/node-execution-env.d.ts +23 -16
- package/dist/engine/execution-env/node-execution-env.js +127 -67
- package/dist/engine/harness/agent-harness.d.ts +4 -5
- package/dist/engine/harness/agent-harness.js +2 -7
- package/dist/engine/harness/types.d.ts +51 -19
- package/dist/engine/harness/types.js +28 -1
- package/dist/engine/llm/types.d.ts +26 -14
- package/dist/engine/llm/types.js +2 -2
- package/dist/engine/loop/agent-loop.d.ts +2 -2
- package/dist/engine/loop/agent-loop.js +51 -275
- package/dist/engine/loop/types.d.ts +0 -18
- package/dist/engine/session/import-validate.d.ts +3 -0
- package/dist/engine/session/import-validate.js +34 -2
- package/dist/engine/session/repo-utils.d.ts +42 -4
- package/dist/engine/session/repo-utils.js +33 -5
- package/dist/engine/session/session.d.ts +41 -14
- package/dist/engine/session/session.js +96 -25
- package/dist/index.d.ts +21 -16
- package/dist/index.js +16 -10
- package/dist/orchestration/run-spec.d.ts +1 -1
- package/dist/orchestration/run-workflow-tool.d.ts +12 -9
- package/dist/orchestration/run-workflow-tool.js +15 -19
- package/dist/orchestration/workflow-governance.js +13 -21
- package/dist/orchestration/workflow-observe.d.ts +4 -3
- package/dist/orchestration/workflow-primitives.d.ts +1 -1
- package/dist/orchestration/workflow-record-artifact.d.ts +14 -0
- package/dist/orchestration/workflow-record-artifact.js +32 -0
- package/dist/orchestration/workflow-script-store.d.ts +9 -0
- package/dist/orchestration/workflow-script-store.js +20 -1
- package/dist/orchestration/workflow-types.d.ts +33 -3
- package/dist/orchestration/workflow.d.ts +24 -14
- package/dist/orchestration/workflow.js +52 -23
- package/dist/prompt-assembly/artifact.js +4 -8
- package/dist/prompt-assembly/catalog/engine.d.ts +263 -0
- package/dist/prompt-assembly/catalog/engine.js +30 -0
- package/dist/prompt-assembly/catalog/index.d.ts +1 -1
- package/dist/prompt-assembly/catalog/index.js +2 -2
- package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +1 -1
- package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +29 -0
- package/dist/prompt-assembly/epoch.js +6 -8
- package/dist/prompt-assembly/turn-snapshot.js +8 -9
- package/dist/stores/file/background-agent-store.js +5 -6
- package/dist/stores/file/checkpoint-store.d.ts +0 -4
- package/dist/stores/file/checkpoint-store.js +7 -3
- package/dist/stores/file/file-history-store.d.ts +8 -0
- package/dist/stores/file/file-history-store.js +72 -0
- package/dist/stores/file/fs-atomic.js +17 -12
- package/dist/stores/file/index.js +11 -5
- package/dist/stores/file/mailbox-store.js +13 -4
- package/dist/stores/file/permission-rule-store.js +14 -13
- package/dist/stores/file/shared-ledger.d.ts +4 -0
- package/dist/stores/file/shared-ledger.js +4 -0
- package/dist/stores/file/task-list-store.js +12 -3
- package/dist/stores/file/workflow-run-store.js +1 -0
- package/dist/tools/fs/bash-program-position.d.ts +4 -2
- package/dist/tools/fs/bash-program-position.js +1 -1
- package/dist/tools/fs/bash-readonly-classifier.js +1 -1
- package/dist/tools/fs/bound-open.d.ts +97 -0
- package/dist/tools/fs/bound-open.js +103 -0
- package/dist/tools/fs/containment-face.d.ts +2 -2
- package/dist/tools/fs/fs-pdf.d.ts +7 -1
- package/dist/tools/fs/fs-pdf.js +31 -23
- package/dist/tools/fs/fs-read.d.ts +24 -17
- package/dist/tools/fs/fs-read.js +84 -53
- package/dist/tools/fs/fs-shared.d.ts +14 -12
- package/dist/tools/fs/fs-shared.js +5 -4
- package/dist/tools/fs/fs-write.d.ts +2 -2
- package/dist/tools/fs/fs-write.js +20 -12
- package/dist/tools/fs/index.d.ts +4 -4
- package/dist/tools/fs/index.js +2 -2
- package/dist/tools/fs/notebook.d.ts +1 -1
- package/dist/tools/fs/pdf.d.ts +12 -3
- package/dist/tools/fs/pdf.js +22 -9
- package/dist/tools/fs/read-deny-home.d.ts +3 -2
- package/dist/tools/fs/read-deny-home.js +8 -11
- package/dist/tools/fs/safety.d.ts +3 -2
- package/dist/tools/fs/shell-read-check.js +10 -9
- package/dist/tools/monitor.d.ts +6 -5
- package/dist/tools/task-list.d.ts +16 -6
- package/dist/tools/task-list.js +4 -0
- package/dist/tools/web.d.ts +9 -1
- package/dist/tools/web.js +8 -3
- package/dist/tools/worktree.d.ts +7 -5
- package/dist/tools/worktree.js +4 -3
- package/package.json +4 -3
- package/test/export-surface.snapshot.json +93 -7
- package/wire-changes/core-stores-sql@7.68.0.json +39 -0
- package/wire-changes/core-stores-sql@7.68.1.json +39 -0
- package/wire-changes/core@7.68.0.json +4257 -0
- package/wire-changes/core@7.68.1.json +95 -0
- package/wire-changes/mods-kernel@7.68.0.json +129 -0
- package/wire-changes/mods-kernel@7.68.1.json +39 -0
- package/wire-changes/primitives@7.68.0.json +253 -0
- package/wire-changes/primitives@7.68.1.json +39 -0
- package/wire-changes/wiki-gate@7.68.0.json +39 -0
- package/wire-changes/wiki-gate@7.68.1.json +39 -0
- package/dist/core/runner/credential-origin-seat.d.ts +0 -2
- package/dist/core/runner/credential-origin-seat.js +0 -20
package/README.md
CHANGED
|
@@ -40,8 +40,10 @@ const res = await runner.runTask({ objective: "...", model: "main" });
|
|
|
40
40
|
behavior of Claude Code's tool contract, continuously verified against live probes.
|
|
41
41
|
- **Durable checkpoints and human-in-the-loop.** Tasks can suspend on approval gates, budget
|
|
42
42
|
limits, or explicit checkpoints and resume later — on another process or machine — via a
|
|
43
|
-
pluggable `CheckpointStore` (in-memory and file-backed here; a database one is yours).
|
|
44
|
-
`
|
|
43
|
+
pluggable `CheckpointStore` (in-memory and file-backed here; a database one is yours). A task's ending is explicit:
|
|
44
|
+
`terminal.kind` is `completed | failed | blocked | paused`, and a `paused` run carries the token that resumes it.
|
|
45
|
+
The result has no `status` member; the older five-word status (`completed | blocked | failed | suspended | needs_review`)
|
|
46
|
+
is derived on demand, as [02 – Runner and Tasks](docs/sdk/02-runner-and-tasks.md) shows.
|
|
45
47
|
- **Memory engine.** Scoped long-term memory with a pluggable `MemoryBackend`
|
|
46
48
|
(file-backed here; a database backend is yours), plus automatic in-context compaction that keeps long runs inside the
|
|
47
49
|
model's context window without losing the thread.
|
|
@@ -60,10 +62,13 @@ const res = await runner.runTask({ objective: "...", model: "main" });
|
|
|
60
62
|
|
|
61
63
|
## Quick start (60 seconds)
|
|
62
64
|
|
|
63
|
-
Requirements: Node ≥ 20 and an OpenAI-compatible gateway (streaming + function calling).
|
|
65
|
+
Requirements: Node ≥ 20.18.1 and an OpenAI-compatible gateway (streaming + function calling).
|
|
64
66
|
|
|
65
67
|
```bash
|
|
68
|
+
mkdir my-agent && cd my-agent
|
|
69
|
+
npm init -y && npm pkg set type=module # the example below uses top-level await
|
|
66
70
|
npm install @sema-agent/core
|
|
71
|
+
npm install --save-dev tsx # runs the TypeScript file directly
|
|
67
72
|
```
|
|
68
73
|
|
|
69
74
|
```ts
|
|
@@ -74,14 +79,13 @@ const model: Model = {
|
|
|
74
79
|
id: "qwen-3.5-35b", name: "Qwen3.5-35B",
|
|
75
80
|
api: "openai-completions", provider: "vllm",
|
|
76
81
|
baseUrl: "http://localhost:8000/v1", // your gateway; no trailing /chat/completions
|
|
77
|
-
reasoning: true, input: ["text", "image"],
|
|
78
|
-
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
79
82
|
contextWindow: 262144, maxTokens: 4096,
|
|
80
83
|
};
|
|
81
84
|
|
|
82
85
|
// 2) Build a Runner (brain = the external LLM; models = your catalog).
|
|
86
|
+
// The brain gets the same address as the model entry, and the key if your gateway wants one.
|
|
83
87
|
const runner = new Runner({
|
|
84
|
-
brain: createOpenAIBrain(),
|
|
88
|
+
brain: createOpenAIBrain({ baseUrl: model.baseUrl, apiKey: process.env.MODEL_API_KEY }),
|
|
85
89
|
models: { main: model },
|
|
86
90
|
});
|
|
87
91
|
|
|
@@ -89,13 +93,18 @@ const runner = new Runner({
|
|
|
89
93
|
const res = await runner.runTask({
|
|
90
94
|
objective: "Summarize the trade-offs between SSE and WebSockets in three bullet points.",
|
|
91
95
|
model: "main",
|
|
92
|
-
sessionId: "chat-42", // pass the same id to continue a conversation; omit for a fresh one
|
|
93
96
|
});
|
|
94
97
|
|
|
95
|
-
console.log(res.
|
|
96
|
-
console.log(res.result);
|
|
98
|
+
console.log(res.terminal.kind); // "completed" | "failed" | "blocked" | "paused"
|
|
99
|
+
console.log(res.result); // final assistant text
|
|
97
100
|
```
|
|
98
101
|
|
|
102
|
+
Save it as `main.ts` and run `npx tsx main.ts` (export `MODEL_API_KEY` first if your gateway wants a
|
|
103
|
+
key; if you load it with `--env-file=.env` instead, a `MODEL_API_KEY` your shell already has wins over
|
|
104
|
+
the file's). It prints `completed`, then the model's answer; if the first line is anything else, print
|
|
105
|
+
`res.terminal` to see why (a failure carries a `code` and a `message`). This page keeps the example to
|
|
106
|
+
the minimum.
|
|
107
|
+
|
|
99
108
|
Add tools (`defineTool`, the built-in SQL tool, or task-scoped MCP servers), stream events
|
|
100
109
|
token-by-token (`runTaskStream`: answer text is `text_delta`; thinking is `reasoning_delta` — the
|
|
101
110
|
provider-level `thinking_delta` name is not on the task stream, and there is no thinking start / end
|
package/README.zh-CN.md
CHANGED
|
@@ -38,7 +38,9 @@ const res = await runner.runTask({ objective: "...", model: "main" });
|
|
|
38
38
|
并持续用活体探针验证。
|
|
39
39
|
- **持久化检查点与人在环。**任务可以在审批闸、预算上限或显式检查点处挂起,稍后恢复——
|
|
40
40
|
甚至在另一个进程或机器上——背后是可插拔的 `CheckpointStore`(内存/文件/Postgres)。
|
|
41
|
-
|
|
41
|
+
任务怎么结束是明确的:`terminal.kind` 取 `completed | failed | blocked | paused` 之一,`paused` 的任务带着续跑它的 token。
|
|
42
|
+
结果对象上没有 `status` 成员;旧的五词状态(`completed | blocked | failed | suspended | needs_review`)
|
|
43
|
+
需要时现场派生,做法见 [02 – Runner and Tasks](docs/sdk/02-runner-and-tasks.md)。
|
|
42
44
|
- **记忆引擎。**带作用域的长期记忆,`MemoryBackend` 可插拔(文件或 Postgres);
|
|
43
45
|
配合自动压缩,长任务不会撑爆上下文窗口,也不会丢线索。
|
|
44
46
|
- **多 agent。**子 agent 委派、team 讨论、确定性的 `runWorkflow` 编排(带可恢复日志),
|
|
@@ -54,10 +56,13 @@ const res = await runner.runTask({ objective: "...", model: "main" });
|
|
|
54
56
|
|
|
55
57
|
## 60 秒上手
|
|
56
58
|
|
|
57
|
-
要求:Node ≥ 20,以及一个 OpenAI 兼容网关(流式 + function calling)。
|
|
59
|
+
要求:Node ≥ 20.18.1,以及一个 OpenAI 兼容网关(流式 + function calling)。
|
|
58
60
|
|
|
59
61
|
```bash
|
|
62
|
+
mkdir my-agent && cd my-agent
|
|
63
|
+
npm init -y && npm pkg set type=module # 下面的例子用了顶层 await
|
|
60
64
|
npm install @sema-agent/core
|
|
65
|
+
npm install --save-dev tsx # 直接运行 TypeScript 文件
|
|
61
66
|
```
|
|
62
67
|
|
|
63
68
|
```ts
|
|
@@ -68,14 +73,13 @@ const model: Model = {
|
|
|
68
73
|
id: "qwen-3.5-35b", name: "Qwen3.5-35B",
|
|
69
74
|
api: "openai-completions", provider: "vllm",
|
|
70
75
|
baseUrl: "http://localhost:8000/v1", // 你的网关,结尾不带 /chat/completions
|
|
71
|
-
reasoning: true, input: ["text", "image"],
|
|
72
|
-
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
|
73
76
|
contextWindow: 262144, maxTokens: 4096,
|
|
74
77
|
};
|
|
75
78
|
|
|
76
79
|
// 2) 建 Runner(brain = 外部 LLM;models = 你的模型目录)
|
|
80
|
+
// brain 要拿到与模型条目相同的地址;网关要钥匙的话,钥匙也交给 brain
|
|
77
81
|
const runner = new Runner({
|
|
78
|
-
brain: createOpenAIBrain(),
|
|
82
|
+
brain: createOpenAIBrain({ baseUrl: model.baseUrl, apiKey: process.env.MODEL_API_KEY }),
|
|
79
83
|
models: { main: model },
|
|
80
84
|
});
|
|
81
85
|
|
|
@@ -83,13 +87,17 @@ const runner = new Runner({
|
|
|
83
87
|
const res = await runner.runTask({
|
|
84
88
|
objective: "用三个要点总结 SSE 与 WebSocket 的取舍。",
|
|
85
89
|
model: "main",
|
|
86
|
-
sessionId: "chat-42", // 传同一个 id 即继续对话;不传则开新会话
|
|
87
90
|
});
|
|
88
91
|
|
|
89
|
-
console.log(res.
|
|
90
|
-
console.log(res.result);
|
|
92
|
+
console.log(res.terminal.kind); // "completed" | "failed" | "blocked" | "paused"
|
|
93
|
+
console.log(res.result); // 最终回复文本
|
|
91
94
|
```
|
|
92
95
|
|
|
96
|
+
存成 `main.ts`,运行 `npx tsx main.ts`(网关要钥匙的话,先导出 `MODEL_API_KEY`;改用 `--env-file=.env`
|
|
97
|
+
载入时,shell 里已有的同名 `MODEL_API_KEY` 会压过文件里的)。它先打印
|
|
98
|
+
`completed`,再打印模型的回答;第一行若是别的,就打印 `res.terminal` 看原因(失败带着 `code` 与
|
|
99
|
+
`message`)。这里只留最小的例子。
|
|
100
|
+
|
|
93
101
|
接下来:挂工具(`defineTool`、内置 SQL 工具、任务级 MCP)、逐 token 消费事件流、
|
|
94
102
|
或把 Runner 暴露成 HTTP + SSE 服务——[SDK 指南](docs/sdk/README.md)按主题分章覆盖,
|
|
95
103
|
从 [01 – Getting Started](docs/sdk/01-getting-started.md) 读起。
|
|
@@ -3,7 +3,7 @@ import type { AgentDefinition } from "../core/types.js";
|
|
|
3
3
|
* A definition as the engine receives it — where it is handed to the delegation tool and where a task carries it: its two tool-name
|
|
4
4
|
* lists replaced by their one copy (the copy every later reader takes instead of the host's container), and its MCP server declarations
|
|
5
5
|
* by the copy the door that judges `TaskSpec.mcp` makes of them ({@link snapshotAndValidateMcpEntries}) — a declaration that door refuses
|
|
6
|
-
* is refused here, by the same code and sentence.
|
|
6
|
+
* is refused here, by the same code and sentence — and its `thinking` is judged by the one tier judge (`judgeThinkingLevel`).
|
|
7
7
|
*/
|
|
8
8
|
export declare function snapshotDefinitionLists(def: AgentDefinition): AgentDefinition;
|
|
9
9
|
/**
|
|
@@ -1,14 +1,17 @@
|
|
|
1
1
|
import { describeRejectedValue } from "../core/tool-search-setting.js";
|
|
2
2
|
import { snapshotToolNameList } from "../core/tool-name-list.js";
|
|
3
3
|
import { snapshotAndValidateMcpEntries } from "../core/locked-config.js";
|
|
4
|
+
import { judgeThinkingLevel } from "../brain/reasoning.js";
|
|
4
5
|
export function snapshotDefinitionLists(def) {
|
|
5
6
|
const copy = { ...def };
|
|
6
7
|
if (copy.allowTools !== undefined)
|
|
7
8
|
copy.allowTools = snapshotToolNameList(copy.allowTools);
|
|
8
9
|
if (copy.denyTools !== undefined)
|
|
9
10
|
copy.denyTools = snapshotToolNameList(copy.denyTools);
|
|
11
|
+
const named = typeof copy.name === "string" ? JSON.stringify(copy.name.slice(0, 80)) : "an unnamed definition";
|
|
10
12
|
if (copy.mcp !== undefined)
|
|
11
|
-
copy.mcp = snapshotAndValidateMcpEntries(copy.mcp, `AgentDefinition.mcp of ${
|
|
13
|
+
copy.mcp = snapshotAndValidateMcpEntries(copy.mcp, `AgentDefinition.mcp of ${named}`);
|
|
14
|
+
judgeThinkingLevel(copy.thinking, `AgentDefinition.thinking of ${named}`);
|
|
12
15
|
return copy;
|
|
13
16
|
}
|
|
14
17
|
export function defineAgent(def) {
|
package/dist/agents/cascade.d.ts
CHANGED
|
@@ -184,8 +184,8 @@ export declare function runCascade(runner: RunnerSelfSeat, spec: TaskSpec, confi
|
|
|
184
184
|
* spawned it — its frames can arrive inside the next rung's segment.
|
|
185
185
|
*
|
|
186
186
|
* FAILURE-ISOLATED, by the same primitive as {@link CascadeConfig.onRung}: engine-invoked through a
|
|
187
|
-
* run-scoped safe notifier — a throwing `onActivity` is contained (first failure per site
|
|
188
|
-
*
|
|
187
|
+
* run-scoped safe notifier — a throwing `onActivity` is contained (first failure per site told as
|
|
188
|
+
* `config.host_sink_failed` on the runner's notice seat, later ones counted) and never faults the rung. Uncontained, the fault
|
|
189
189
|
* AMPLIFIES: the faulted rung is rejected by the gate, the cascade escalates, and a non-idempotent
|
|
190
190
|
* tool the rung had ALREADY executed runs AGAIN on the next rung — the MEASURED HAZARD pin holds
|
|
191
191
|
* containment.
|
package/dist/agents/cascade.js
CHANGED
|
@@ -70,7 +70,7 @@ async function climbLadder(entryName, runner, spec, config, internals, opening)
|
|
|
70
70
|
let ceilingCostKnown = true;
|
|
71
71
|
let ownTokens = 0, ownTurns = 0, ownPrompt = 0, ownCached = 0, ownOutput = 0, ownCostMicro = 0;
|
|
72
72
|
let ownTotalInput = 0;
|
|
73
|
-
let ownCacheWrite = 0, ownCacheWriteLong = 0;
|
|
73
|
+
let ownCacheWrite = 0, ownCacheWriteLong = 0, ownApiDuration = 0;
|
|
74
74
|
const ownUsageFacts = emptyCumulativeUsageFacts();
|
|
75
75
|
let nestedTokens = 0, nestedTurns = 0, nestedTasks = 0, nestedCostMicro = 0;
|
|
76
76
|
let ownLlmRootMicro = 0, ownCompactionMicro = 0;
|
|
@@ -87,6 +87,7 @@ async function climbLadder(entryName, runner, spec, config, internals, opening)
|
|
|
87
87
|
outputTokens: ownOutput,
|
|
88
88
|
cacheWriteTokens: ownCacheWrite,
|
|
89
89
|
cacheWriteTokensLong: ownCacheWriteLong,
|
|
90
|
+
apiDurationMs: ownApiDuration,
|
|
90
91
|
costMicroUsd: ownCostMicro,
|
|
91
92
|
anyLegUnpriced: anyRungUnpriced,
|
|
92
93
|
llmRootMicroUsd: ownLlmRootMicro,
|
|
@@ -165,6 +166,7 @@ async function climbLadder(entryName, runner, spec, config, internals, opening)
|
|
|
165
166
|
ownOutput += s.outputTokens ?? 0;
|
|
166
167
|
ownCacheWrite += s.cacheWriteTokens ?? 0;
|
|
167
168
|
ownCacheWriteLong += s.cacheWriteTokensLong ?? 0;
|
|
169
|
+
ownApiDuration += s.apiDurationMs ?? 0;
|
|
168
170
|
foldUsageFacts(ownUsageFacts, s);
|
|
169
171
|
ownCostMicro += s.costMicroUsd ?? 0;
|
|
170
172
|
if (s.costMicroUsd === undefined)
|
|
@@ -36,7 +36,7 @@ export interface CumulativeHumanReviewTotals {
|
|
|
36
36
|
}
|
|
37
37
|
/** The usage sums a leg's stats may publish — each summed over the legs, and published on the cumulative stats exactly when some
|
|
38
38
|
* leg published it (a leg's 0 is a measured 0 and is kept; a member no leg published stays absent). */
|
|
39
|
-
declare const USAGE_SUM_KEYS: readonly ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong"];
|
|
39
|
+
declare const USAGE_SUM_KEYS: readonly ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong", "apiDurationMs"];
|
|
40
40
|
type UsageSumKey = (typeof USAGE_SUM_KEYS)[number];
|
|
41
41
|
/**
|
|
42
42
|
* What the legs said about their usage beyond the sums, folded leg by leg ({@link foldUsageFacts}): which sums any leg published,
|
|
@@ -76,6 +76,7 @@ export interface CumulativeStatsAccumulator {
|
|
|
76
76
|
outputTokens: number;
|
|
77
77
|
cacheWriteTokens: number;
|
|
78
78
|
cacheWriteTokensLong: number;
|
|
79
|
+
apiDurationMs: number;
|
|
79
80
|
/**
|
|
80
81
|
* Cumulative own LLM cost (micro-USD): a plain `0` when every leg was priced and cost nothing measurable.
|
|
81
82
|
*
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { cacheHitOperandsOf } from "../core/runner/cache-hit-account.js";
|
|
2
|
-
const USAGE_SUM_KEYS = ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong"];
|
|
2
|
+
const USAGE_SUM_KEYS = ["promptTokens", "totalInputTokens", "cachedTokens", "outputTokens", "cacheWriteTokens", "cacheWriteTokensLong", "apiDurationMs"];
|
|
3
3
|
export function emptyCumulativeUsageFacts() {
|
|
4
4
|
return { published: new Set(), usageMissing: false, cacheReadUnreported: false, cacheWriteUnreported: false, cacheHitRateExcludes: new Map(), rateNumeratorShort: false };
|
|
5
5
|
}
|
|
@@ -37,6 +37,7 @@ export function buildCumulativeStats(base, acc) {
|
|
|
37
37
|
outputTokens: sum("outputTokens"),
|
|
38
38
|
cacheWriteTokens: sum("cacheWriteTokens"),
|
|
39
39
|
cacheWriteTokensLong: sum("cacheWriteTokensLong"),
|
|
40
|
+
apiDurationMs: sum("apiDurationMs"),
|
|
40
41
|
cacheHitRate: !facts.rateNumeratorShort && operands.totalInputTokens > 0 ? Math.min(1, operands.cachedTokens / operands.totalInputTokens) : undefined,
|
|
41
42
|
cacheHitRateExcludes: excludes.length > 0 ? excludes : undefined,
|
|
42
43
|
usageMissing: facts.usageMissing ? true : undefined,
|
|
@@ -70,6 +71,7 @@ export function createCumulativeStatsTracker() {
|
|
|
70
71
|
outputTokens: 0,
|
|
71
72
|
cacheWriteTokens: 0,
|
|
72
73
|
cacheWriteTokensLong: 0,
|
|
74
|
+
apiDurationMs: 0,
|
|
73
75
|
costMicroUsd: 0,
|
|
74
76
|
anyLegUnpriced: false,
|
|
75
77
|
llmRootMicroUsd: 0,
|
|
@@ -92,6 +94,7 @@ export function createCumulativeStatsTracker() {
|
|
|
92
94
|
acc.outputTokens += s.outputTokens ?? 0;
|
|
93
95
|
acc.cacheWriteTokens += s.cacheWriteTokens ?? 0;
|
|
94
96
|
acc.cacheWriteTokensLong += s.cacheWriteTokensLong ?? 0;
|
|
97
|
+
acc.apiDurationMs += s.apiDurationMs ?? 0;
|
|
95
98
|
foldUsageFacts(acc.usageFacts, s);
|
|
96
99
|
acc.costMicroUsd += s.costMicroUsd ?? 0;
|
|
97
100
|
if (s.costMicroUsd === undefined)
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { Type } from "typebox";
|
|
2
2
|
import type { TaskAccess } from "../core/task-registry.js";
|
|
3
|
+
import { type RetainLedgerSeats } from "./retain-ledger.js";
|
|
3
4
|
import { type RosterEntry } from "./roster-store.js";
|
|
4
5
|
import { type PeerDirectory, type PeerPresence, type PeerSessionRecord, type PeerSessionWhere } from "./peer-directory.js";
|
|
5
6
|
import type { SubagentTranscriptTier } from "../core/wiring-manifest.js";
|
|
@@ -39,15 +40,25 @@ export interface ListAgentsToolOptions {
|
|
|
39
40
|
type: string;
|
|
40
41
|
status: string;
|
|
41
42
|
description?: string;
|
|
43
|
+
toolUseId?: string;
|
|
42
44
|
}>;
|
|
43
45
|
getAccessibleTask(id: string, access: TaskAccess): {
|
|
44
46
|
name?: string;
|
|
45
47
|
status: string;
|
|
48
|
+
agentType?: string;
|
|
46
49
|
} | undefined;
|
|
47
50
|
/** The live background-agent row's state facts ({@link import("../core/task-registry.js").TaskRegistry.agentStateSource}).
|
|
48
51
|
* Absent on a registry that does not offer it ⇒ agent rows carry no `agentState` and no state columns. */
|
|
49
52
|
agentStateSource?(id: string, access: TaskAccess): AgentStateSource | undefined;
|
|
53
|
+
/** Who stopped a killed agent — a user's stop is not continued. Absent ⇒ not known (read as not a user's stop). */
|
|
54
|
+
getStopAttribution?(id: string): string | undefined;
|
|
55
|
+
/** A probe confirming the agent's durable record exists (absent ⇒ the row has no durable lane). */
|
|
56
|
+
durableAgentRowProbe?(id: string): (() => Promise<boolean>) | undefined;
|
|
50
57
|
};
|
|
58
|
+
/** The retain ledgers the SendMessage beside this tool continues agents from, read at each call (a session's ledger is
|
|
59
|
+
* minted by its first session-scoped spawn). With the registry facts above they answer each stopped agent's
|
|
60
|
+
* {@link AgentContinuation}; absent ⇒ no retained continuation is known to this listing. */
|
|
61
|
+
retainLedgers?: () => RetainLedgerSeats;
|
|
51
62
|
access?: TaskAccess;
|
|
52
63
|
/** design/147 S3a parity — a delegated child's TRUSTED parent view (owner = the parent's task id,
|
|
53
64
|
* sessionId = the parent's session), so the siblings SendMessage can reach by name are listed too.
|
|
@@ -105,7 +116,26 @@ export interface ListAgentsRow {
|
|
|
105
116
|
* render too); {@link state} is this status word through the lane table. Absent on peer rows and on a
|
|
106
117
|
* roster row with no live row. */
|
|
107
118
|
agentState?: AgentState;
|
|
119
|
+
/** Agent lanes, a stopped agent (`finished` / `failed` / `killed`) with a live row: whether, and until when, SendMessage
|
|
120
|
+
* can continue it. Absent on a live or parked agent (a message reaches it as it is) and on rows with no live row. */
|
|
121
|
+
continuation?: AgentContinuation;
|
|
108
122
|
}
|
|
123
|
+
/**
|
|
124
|
+
* How long SendMessage can continue a stopped agent — the continuation ladder's own answer
|
|
125
|
+
* ({@link resumabilityClaim} over {@link liveRetainEntryOf}), with the retention window as a fact:
|
|
126
|
+
* · `retained` — this engine process holds its conversation until `until` (epoch ms: the retain entry's last settle plus its
|
|
127
|
+
* window, {@link import("./retain-ledger.js").SubagentRetainLedger.continuableUntil}); past it the entry is evicted;
|
|
128
|
+
* · `durable` — no retained conversation, but its durable record revives it by name (no deadline this engine sets);
|
|
129
|
+
* · `none` — SendMessage answers with a refusal (stopped by the user, resume budget spent, nothing retained or recorded).
|
|
130
|
+
*/
|
|
131
|
+
export type AgentContinuation = {
|
|
132
|
+
readonly by: "retained";
|
|
133
|
+
readonly until: number;
|
|
134
|
+
} | {
|
|
135
|
+
readonly by: "durable";
|
|
136
|
+
} | {
|
|
137
|
+
readonly by: "none";
|
|
138
|
+
};
|
|
109
139
|
export declare function createListAgentsTool(opts: ListAgentsToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
|
|
110
140
|
includeAll: Type.TOptional<Type.TBoolean>;
|
|
111
141
|
}>, unknown>;
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { Type } from "typebox";
|
|
2
2
|
import { defineTool } from "../core/tools.js";
|
|
3
|
+
import { SUBAGENT_RESUME_CAP, liveRetainEntryOf, resumabilityClaim } from "./retain-ledger.js";
|
|
3
4
|
import { inlineUntrusted } from "../core/untrusted-text.js";
|
|
4
5
|
import { formatPeerNameRef } from "./cross-session-ref.js";
|
|
5
6
|
import { entryAccessible } from "./roster-store.js";
|
|
@@ -25,6 +26,12 @@ export function cwdTail(cwd) {
|
|
|
25
26
|
const parts = cwd.split(/[\\/]+/).filter((p) => p !== "");
|
|
26
27
|
return parts.slice(-2).join("/");
|
|
27
28
|
}
|
|
29
|
+
const FORK_AGENT_TYPE = "fork";
|
|
30
|
+
function continuationClause(c, now) {
|
|
31
|
+
if (c.by === "retained")
|
|
32
|
+
return `continuable for ${formatAgo(c.until - now)}`;
|
|
33
|
+
return c.by === "durable" ? "continuable (durable record)" : "not continuable";
|
|
34
|
+
}
|
|
28
35
|
const AGENT_ROW_STATE = {
|
|
29
36
|
pending: "running",
|
|
30
37
|
running: "running",
|
|
@@ -70,7 +77,7 @@ export function createListAgentsTool(opts) {
|
|
|
70
77
|
`pass includeAll: true to also list stale and offline ones. A peer that is offline or unlisted still accepts messages — they are parked ` +
|
|
71
78
|
`durably in its session box and delivered when it next runs. `
|
|
72
79
|
: `Peer sessions of this engine are not addressable on this mount (no session directory). `) +
|
|
73
|
-
`Background agents you spawned are listed with their task_id, their status, when they last did anything, and — for one that is parked — what its park waits on (a person's approval, or a yield that continues when its owner runs again), the card id, state and deadline. ` +
|
|
80
|
+
`Background agents you spawned are listed with their task_id, their status, when they last did anything, and — for one that is parked — what its park waits on (a person's approval, or a yield that continues when its owner runs again), the card id, state and deadline; for one that stopped, whether SendMessage can still continue it and for how long. ` +
|
|
74
81
|
`A ref is only valid against the listing (or disambiguation error) you read it from — do not invent one.`,
|
|
75
82
|
parameters: Type.Object({
|
|
76
83
|
includeAll: Type.Optional(Type.Boolean({ description: "Also list stale (no activity within the freshness window) and offline peer sessions. Default false." })),
|
|
@@ -115,6 +122,37 @@ export function createListAgentsTool(opts) {
|
|
|
115
122
|
const src = opts.registry?.agentStateSource?.(id, view);
|
|
116
123
|
return src === undefined ? undefined : readAgentState(src, opts.checkpointSeat, opts.now?.() ?? Date.now());
|
|
117
124
|
};
|
|
125
|
+
const tier = opts.continuationTier ?? "none";
|
|
126
|
+
const retainSeats = opts.retainLedgers?.();
|
|
127
|
+
const continuationOf = async (id, status, toolUseId, agentType) => {
|
|
128
|
+
if (status !== "completed" && status !== "failed" && status !== "killed")
|
|
129
|
+
return undefined;
|
|
130
|
+
const live = toolUseId !== undefined && retainSeats !== undefined ? liveRetainEntryOf(retainSeats, toolUseId) : undefined;
|
|
131
|
+
const durableRungServes = agentType !== FORK_AGENT_TYPE;
|
|
132
|
+
let durableRow = false;
|
|
133
|
+
if (live === undefined && durableRungServes && tier !== "none") {
|
|
134
|
+
try {
|
|
135
|
+
durableRow = (await opts.registry?.durableAgentRowProbe?.(id)?.()) === true;
|
|
136
|
+
}
|
|
137
|
+
catch {
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
const stoppedBy = status === "killed" ? opts.registry?.getStopAttribution?.(id) : undefined;
|
|
141
|
+
const claim = resumabilityClaim({
|
|
142
|
+
status,
|
|
143
|
+
...(stoppedBy !== undefined ? { stoppedBy } : {}),
|
|
144
|
+
liveRetainPresent: live !== undefined,
|
|
145
|
+
liveRetainHasBudget: live !== undefined && live.entry.resumeCount < SUBAGENT_RESUME_CAP,
|
|
146
|
+
durableRow,
|
|
147
|
+
durableRungServes,
|
|
148
|
+
});
|
|
149
|
+
if (!claim)
|
|
150
|
+
return { by: "none" };
|
|
151
|
+
if (live === undefined)
|
|
152
|
+
return { by: "durable" };
|
|
153
|
+
const until = live.ledger.continuableUntil(live.entry);
|
|
154
|
+
return until > now ? { by: "retained", until } : { by: "none" };
|
|
155
|
+
};
|
|
118
156
|
const views = [opts.access, opts.parentAccess].filter((a) => a !== undefined);
|
|
119
157
|
const seenIds = new Set();
|
|
120
158
|
if (opts.registry !== undefined) {
|
|
@@ -128,12 +166,14 @@ export function createListAgentsTool(opts) {
|
|
|
128
166
|
const full = opts.registry.getAccessibleTask(t.task_id, view);
|
|
129
167
|
const stateRead = agentStateOf(t.task_id, view);
|
|
130
168
|
const agentState = stateRead instanceof Promise ? await stateRead : stateRead;
|
|
169
|
+
const continuation = await continuationOf(t.task_id, agentState?.status ?? t.status, t.toolUseId, full?.agentType);
|
|
131
170
|
rows.push({
|
|
132
171
|
kind: "background_agent",
|
|
133
172
|
name: full?.name ?? t.description ?? t.task_id,
|
|
134
173
|
address: t.task_id,
|
|
135
174
|
state: agentRowState(agentState?.status ?? t.status),
|
|
136
175
|
...(agentState !== undefined ? { agentState } : {}),
|
|
176
|
+
...(continuation !== undefined ? { continuation } : {}),
|
|
137
177
|
});
|
|
138
178
|
}
|
|
139
179
|
}
|
|
@@ -148,19 +188,20 @@ export function createListAgentsTool(opts) {
|
|
|
148
188
|
const live = opts.registry?.getAccessibleTask(e.agentId, view);
|
|
149
189
|
const stateRead = live === undefined ? undefined : agentStateOf(e.agentId, view);
|
|
150
190
|
const agentState = stateRead instanceof Promise ? await stateRead : stateRead;
|
|
191
|
+
const continuation = live === undefined ? undefined : await continuationOf(e.agentId, agentState?.status ?? live.status, e.toolUseId, live.agentType);
|
|
151
192
|
rows.push({
|
|
152
193
|
kind: "roster",
|
|
153
194
|
name: e.name,
|
|
154
195
|
address: e.agentId,
|
|
155
196
|
state: live === undefined ? "unknown" : agentRowState(agentState?.status ?? live.status),
|
|
156
197
|
...(agentState !== undefined ? { agentState } : {}),
|
|
198
|
+
...(continuation !== undefined ? { continuation } : {}),
|
|
157
199
|
});
|
|
158
200
|
}
|
|
159
201
|
}
|
|
160
202
|
catch {
|
|
161
203
|
}
|
|
162
204
|
}
|
|
163
|
-
const tier = opts.continuationTier ?? "none";
|
|
164
205
|
const rosterLabel = tier === "full" ? "agent (durable record)" : tier === "rows" ? "agent (record kept; conversation not kept across restarts)" : "agent (recorded name)";
|
|
165
206
|
const finishedReach = tier === "full"
|
|
166
207
|
? "while its session is retained or a durable record exists"
|
|
@@ -172,7 +213,8 @@ export function createListAgentsTool(opts) {
|
|
|
172
213
|
const age = r.kind !== "peer_session" ? undefined : r.lastActiveAt !== undefined ? `active ${formatAgo(now - r.lastActiveAt)} ago` : r.offlineAt !== undefined ? `offline ${formatAgo(now - r.offlineAt)} ago` : "offline";
|
|
173
214
|
const activity = r.agentState !== undefined ? agentActivityClause(r.agentState) : undefined;
|
|
174
215
|
const park = r.agentState?.park !== undefined ? agentParkClause(r.agentState.park, r.agentState.readAt) : undefined;
|
|
175
|
-
const
|
|
216
|
+
const continuation = r.continuation !== undefined ? continuationClause(r.continuation, now) : undefined;
|
|
217
|
+
const cols = [label, r.state, age, activity, park, continuation, r.cwd !== undefined ? inlineUntrusted(r.cwd, 64) : undefined, r.presence !== undefined ? renderPresence(r.presence) : undefined, r.kind === "peer_session" ? `peer session ${PEER_SESSION_WHERE_LABELS[r.where]}` : r.kind === "roster" ? rosterLabel : "agent", r.address];
|
|
176
218
|
return cols.filter((c) => c !== undefined).join(" · ");
|
|
177
219
|
});
|
|
178
220
|
const finishedCount = rows.filter((r) => r.state === "finished").length;
|
|
@@ -55,8 +55,8 @@ export declare function __resetPeerLaneRangeAnnouncements(): void;
|
|
|
55
55
|
* a value outside the legal window, and a value that is not a finite number at all (a string off an
|
|
56
56
|
* untyped host's JSON wiring, `NaN`, `Infinity`). Two bad fields in one call are two notices — the
|
|
57
57
|
* operator has two things to fix and folding them into one line would hide the second. `onNotice` is
|
|
58
|
-
* the deployment's sink; absent, the announcement still reaches
|
|
59
|
-
* delivery throat (an unwired host is not a silent one).
|
|
58
|
+
* the deployment's sink; absent, the announcement still reaches the process's default seat, else one process line,
|
|
59
|
+
* through the shared delivery throat (an unwired host is not a silent one).
|
|
60
60
|
*/
|
|
61
61
|
export declare function resolvePeerLaneConfig(overrides?: Partial<PeerLaneConfig>, onNotice?: (notice: EngineNotice) => void): PeerLaneConfig;
|
|
62
62
|
/** Hop-chain carrier sliding window: a chain keeps its most recent entries (upstream `Xbr`=32).
|
|
@@ -391,6 +391,8 @@ export declare function mountListAgents(args: {
|
|
|
391
391
|
}>;
|
|
392
392
|
/** The read faces' store seats, handed to the tool unchanged (see {@link ListAgentsReadSeats}). */
|
|
393
393
|
readSeats?: ListAgentsReadSeats;
|
|
394
|
+
/** The retain ledgers of the SendMessage beside it (see the tool option), read at each call. */
|
|
395
|
+
retainLedgers?: NonNullable<Parameters<typeof createListAgentsTool>[0]["retainLedgers"]>;
|
|
394
396
|
}): ReturnType<typeof createListAgentsTool> | undefined;
|
|
395
397
|
type ListAgentsToolRegistry = NonNullable<Parameters<typeof createListAgentsTool>[0]["registry"]>;
|
|
396
398
|
/** The harness surface the binding needs (structural — the machine itself never sees the harness). */
|
|
@@ -1086,6 +1086,7 @@ export function mountListAgents(args) {
|
|
|
1086
1086
|
...(args.parentTaskId !== undefined ? { parentAccess: { owner: args.parentTaskId, scope: args.scope, ...(args.parentSessionId !== undefined ? { sessionId: args.parentSessionId } : {}) } } : {}),
|
|
1087
1087
|
...(args.roster !== undefined ? { roster: args.roster } : {}),
|
|
1088
1088
|
...(args.continuationTier !== undefined ? { continuationTier: args.continuationTier } : {}),
|
|
1089
|
+
...(args.retainLedgers !== undefined ? { retainLedgers: args.retainLedgers } : {}),
|
|
1089
1090
|
...(args.readSeats ?? {}),
|
|
1090
1091
|
});
|
|
1091
1092
|
}
|
|
@@ -103,7 +103,7 @@ export async function runRepairLoop(runner, implSpec, config) {
|
|
|
103
103
|
const attemptIntakes = [];
|
|
104
104
|
let lastOracle;
|
|
105
105
|
let ownTokens = 0, ownTurns = 0, ownPrompt = 0, ownTotalInput = 0, ownCached = 0, ownOutput = 0;
|
|
106
|
-
let ownCacheWrite = 0, ownCacheWriteLong = 0, ownCostMicro = 0;
|
|
106
|
+
let ownCacheWrite = 0, ownCacheWriteLong = 0, ownApiDuration = 0, ownCostMicro = 0;
|
|
107
107
|
const ownUsageFacts = emptyCumulativeUsageFacts();
|
|
108
108
|
let ownLlmRootMicro = 0, ownCompactionMicro = 0;
|
|
109
109
|
let ownSideCallMicro;
|
|
@@ -121,6 +121,7 @@ export async function runRepairLoop(runner, implSpec, config) {
|
|
|
121
121
|
ownOutput += s.outputTokens ?? 0;
|
|
122
122
|
ownCacheWrite += s.cacheWriteTokens ?? 0;
|
|
123
123
|
ownCacheWriteLong += s.cacheWriteTokensLong ?? 0;
|
|
124
|
+
ownApiDuration += s.apiDurationMs ?? 0;
|
|
124
125
|
foldUsageFacts(ownUsageFacts, s);
|
|
125
126
|
ownCostMicro += s.costMicroUsd ?? 0;
|
|
126
127
|
if (s.costMicroUsd === undefined)
|
|
@@ -153,6 +154,7 @@ export async function runRepairLoop(runner, implSpec, config) {
|
|
|
153
154
|
outputTokens: ownOutput,
|
|
154
155
|
cacheWriteTokens: ownCacheWrite,
|
|
155
156
|
cacheWriteTokensLong: ownCacheWriteLong,
|
|
157
|
+
apiDurationMs: ownApiDuration,
|
|
156
158
|
costMicroUsd: ownCostMicro,
|
|
157
159
|
anyLegUnpriced: anyAttemptUnpriced,
|
|
158
160
|
llmRootMicroUsd: ownLlmRootMicro,
|
|
@@ -3,6 +3,62 @@ import type { TaskSpec } from "../core/types.js";
|
|
|
3
3
|
import type { PeerDeclarationHold, PeerDeclarations } from "../core/peer-seat.js";
|
|
4
4
|
/** design/122 D2 — per-child resume cap (default 8): a child can be revived at most this many times. */
|
|
5
5
|
export declare const SUBAGENT_RESUME_CAP = 8;
|
|
6
|
+
/**
|
|
7
|
+
* Residual lane E — THE resumability claim, derived from the REVIVAL LADDER's own preconditions.
|
|
8
|
+
*
|
|
9
|
+
* `resumable` answers "what will the next SendMessage do with this child?", so the flat
|
|
10
|
+
* `status !== "killed"` it used to be was not a narrower answer, it was a different question. Only a
|
|
11
|
+
* USER stop is a hard refusal on that ladder; a parent teardown, a reap or a host death is exactly what
|
|
12
|
+
* the durable revival lane exists to recover from, and a named row with a durable record is revived
|
|
13
|
+
* through it whatever ended the run. A frame that says `false` there sends the parent to relaunch a
|
|
14
|
+
* child it could have continued — with the child's whole transcript still sitting in the store.
|
|
15
|
+
*
|
|
16
|
+
* The two lanes it reads are the two the ladder walks, in the ladder's own order:
|
|
17
|
+
* · the LIVE retain entry — a continuation in this process. A live entry WINS the ladder (retain holds
|
|
18
|
+
* the committed spawn snapshot and the cheaper same-process resume, so the durable lane is not even
|
|
19
|
+
* attempted while one exists), which cuts both ways: its refusals are final for the row, and an entry
|
|
20
|
+
* that has spent its per-child resume budget answers `false` with nothing behind it — however good
|
|
21
|
+
* the durable row looks. Whether a kill leaves an entry behind is the PRODUCER's fact, not this
|
|
22
|
+
* predicate's: the spawn cycle evicts on a kill, the resume cycle settles instead, so each passes
|
|
23
|
+
* what its own lane actually did rather than assuming a shared rule (they do not share one).
|
|
24
|
+
* · the DURABLE row — tier-3 lazy revival, reached only with NO live entry. It speaks only for NAMED
|
|
25
|
+
* rows (an anonymous one falls through to the pre-revival honest texts) and needs a confirmed
|
|
26
|
+
* record, not merely an armed lane.
|
|
27
|
+
*
|
|
28
|
+
* Its readers: the terminal frames of both background lanes (the producer — it claims nothing about the
|
|
29
|
+
* RECIPIENT side of the ladder, whether the parent's SendMessage mount was wired with a mailbox and a spawn
|
|
30
|
+
* face, so `durableRow` is the row-side fact alone), and the ListAgents listing (which is mounted beside that
|
|
31
|
+
* SendMessage and passes `durableRow` only when the mount's tier can revive).
|
|
32
|
+
*/
|
|
33
|
+
export declare function resumabilityClaim(f: {
|
|
34
|
+
status: "completed" | "failed" | "killed";
|
|
35
|
+
stoppedBy?: string;
|
|
36
|
+
/** A live retain entry SURVIVES this settle — it OWNS the ladder while it does, so its own answer is
|
|
37
|
+
* the whole answer. The caller decides this per lane (a killed spawn cycle evicts; a killed resume
|
|
38
|
+
* cycle settles the entry and keeps it). */
|
|
39
|
+
liveRetainPresent: boolean;
|
|
40
|
+
/** …and it still has resume budget (below {@link SUBAGENT_RESUME_CAP}). */
|
|
41
|
+
liveRetainHasBudget: boolean;
|
|
42
|
+
durableRow: boolean;
|
|
43
|
+
/** The durable rung serves this row. SendMessage's tier-3 rung serves any row but a fork's (by handle, named or not);
|
|
44
|
+
* the terminal-frame producers answer for named rows only — a narrower claim than the rung, kept as it was. */
|
|
45
|
+
durableRungServes: boolean;
|
|
46
|
+
}): boolean;
|
|
47
|
+
/** The retain ledgers a continuation of an agent looks in: the session's (a session-scoped child outlives the run that
|
|
48
|
+
* spawned it), the run's own, and — for a delegated child reaching a sibling — the parent run's. */
|
|
49
|
+
export interface RetainLedgerSeats {
|
|
50
|
+
readonly session?: SubagentRetainLedger | undefined;
|
|
51
|
+
readonly run?: SubagentRetainLedger | undefined;
|
|
52
|
+
readonly sibling?: SubagentRetainLedger | undefined;
|
|
53
|
+
}
|
|
54
|
+
/** The live retain entry of one spawn (keyed by the spawn's tool-call id), read in the continuation ladder's order —
|
|
55
|
+
* session, run, sibling — with the ledger that holds it. The first ledger that KNOWS the spawn decides, a live entry or
|
|
56
|
+
* an eviction's tombstone alike: the ladder resumes through that ledger, so a tombstone ahead of a later ledger's entry
|
|
57
|
+
* answers "none live" here too. The one read SendMessage's ladder and the agent listing share. */
|
|
58
|
+
export declare function liveRetainEntryOf(seats: RetainLedgerSeats, toolUseId: string): {
|
|
59
|
+
ledger: SubagentRetainLedger;
|
|
60
|
+
entry: SubagentRetainEntry;
|
|
61
|
+
} | undefined;
|
|
6
62
|
/** The one read of a seat's `holdDeclarations` — both retention registrations take their hold here. The member is required, so a typed host
|
|
7
63
|
* is stopped by the compiler; a seat built by hand without it (untyped, cast) is refused by name, where the bare call was a TypeError
|
|
8
64
|
* from the middle of a delegation. */
|
|
@@ -50,13 +106,6 @@ export interface SubagentRetainEntry {
|
|
|
50
106
|
/** Last settle timestamp (epoch ms) — the retain-TTL base. */
|
|
51
107
|
settledAt: number;
|
|
52
108
|
resumeCount: number;
|
|
53
|
-
/** design/144 §1.1 — the child's STOP-CYCLE number (207-equivalent per-stop notification identity).
|
|
54
|
-
* Minted 1 at registration (the spawn run's settle notifies cycle 1); every resume that actually
|
|
55
|
-
* LAUNCHES bumps it, so the resumed run's settle notifies 2, 3, … The background_agent notification
|
|
56
|
-
* producers ride it as `TaskNotificationPayload.seq`, which uniquifies the `task_id:status[:seq]`
|
|
57
|
-
* dedup key per stop cycle — without it a stop→wake→stop chain's second `completed` frame collided
|
|
58
|
-
* with the first and was silently swallowed by the SystemInjectionQueue/inbox/shell dedup layers. */
|
|
59
|
-
cycleSeq: number;
|
|
60
109
|
/** design/144 §1.2 (child gate) — the PARKED completion notification of this child's spawn settle:
|
|
61
110
|
* present while a `completed` frame sits deferred behind the child's still-running background tasks
|
|
62
111
|
* (owner key = childSessionId). `seq` is the parked frame's stop-cycle number (park does not change
|
|
@@ -163,6 +212,10 @@ export declare class SubagentRetainLedger {
|
|
|
163
212
|
private tombstone;
|
|
164
213
|
/** fix-C5: an entry's own retain window when it carries one, the ledger default otherwise. */
|
|
165
214
|
private effectiveTtlMs;
|
|
215
|
+
/** The instant (epoch ms) a settled, idle entry stops being continuable: its last settle plus its retain window. The one
|
|
216
|
+
* expiry fact — both reapers (the lazy sweep, the per-entry timer) evict past it, and a listing states the time left
|
|
217
|
+
* until it. While the entry runs it does not expire (its next settle moves this instant). */
|
|
218
|
+
continuableUntil(e: SubagentRetainEntry): number;
|
|
166
219
|
get disposed(): boolean;
|
|
167
220
|
get size(): number;
|
|
168
221
|
get(parentToolCallId: string): SubagentRetainEntry | undefined;
|
|
@@ -179,7 +232,7 @@ export declare class SubagentRetainLedger {
|
|
|
179
232
|
* evicted (unpin+release); when every slot is still running, the NEW child is NOT retained (tombstoned →
|
|
180
233
|
* its resume rejects `resume.evicted`) and `undefined` is returned — the caller falls back to throwaway.
|
|
181
234
|
* The entry's `declarations` hold is the ledger's from this call on: a row not taken releases it here. */
|
|
182
|
-
register(parentToolCallId: string, entry: Omit<SubagentRetainEntry, "running" | "settled" | "settledAt" | "resumeCount" | "
|
|
235
|
+
register(parentToolCallId: string, entry: Omit<SubagentRetainEntry, "running" | "settled" | "settledAt" | "resumeCount" | "activeAbort" | "deferredNotify">): SubagentRetainEntry | undefined;
|
|
183
236
|
/** Flip a child to settled (idle, resumable) — called when the initial run's stream drains.
|
|
184
237
|
* fidelity R4-1: also (re-)arms the entry's own TTL timer, so the retain window expires by TIME,
|
|
185
238
|
* not only at the next ledger touch. */
|