@sema-agent/core 7.56.0 → 7.58.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +926 -0
- package/LICENSE +1 -1
- package/dist/agents/org-delivery-gate.js +3 -4
- package/dist/agents/peer-held-queue.d.ts +69 -49
- package/dist/agents/peer-held-queue.js +255 -106
- package/dist/agents/peer-session-drain.js +63 -43
- package/dist/agents/send-message-tool.js +3 -2
- package/dist/agents/subagent-steps.js +2 -4
- package/dist/agents/subagent.js +8 -8
- package/dist/brain/anthropic.js +16 -8
- package/dist/brain/open-responses.js +10 -8
- package/dist/brain/openai.js +11 -9
- package/dist/brain/provider-dialect.d.ts +3 -2
- package/dist/brain/provider-dialect.js +2 -2
- package/dist/brain/request-params.d.ts +6 -0
- package/dist/brain/request-params.js +14 -1
- package/dist/brain/route-adjudicator.js +2 -1
- package/dist/brain/stream-engine.d.ts +9 -0
- package/dist/brain/stream-engine.js +24 -10
- package/dist/brain/stream-shared.d.ts +5 -4
- package/dist/brain/stream-shared.js +4 -4
- package/dist/core/a2a.d.ts +2 -1
- package/dist/core/a2a.js +23 -10
- package/dist/core/allow-entry.d.ts +5 -11
- package/dist/core/allow-entry.js +19 -26
- package/dist/core/approval-object.d.ts +21 -5
- package/dist/core/approval-object.js +44 -17
- package/dist/core/ask-origin.d.ts +23 -4
- package/dist/core/ask-origin.js +5 -1
- package/dist/core/auto-compaction.d.ts +75 -6
- package/dist/core/auto-compaction.js +43 -27
- package/dist/core/auto-mode-directive.d.ts +29 -5
- package/dist/core/auto-mode-directive.js +38 -8
- package/dist/core/background-agent-store.d.ts +6 -2
- package/dist/core/background-agent-store.js +1 -1
- package/dist/core/checkpoint-requirements.d.ts +13 -1
- package/dist/core/checkpoint-requirements.js +4 -0
- package/dist/core/checkpoint-store.d.ts +44 -40
- package/dist/core/checkpoint-store.js +32 -14
- package/dist/core/cross-boundary-taint.js +4 -2
- package/dist/core/engine-notice.d.ts +4 -3
- package/dist/core/engine-notice.js +6 -0
- package/dist/core/file-history-store.d.ts +14 -8
- package/dist/core/file-history-store.js +14 -4
- package/dist/core/fs-write-gate-policy.d.ts +4 -2
- package/dist/core/fs-write-gate-policy.js +7 -3
- package/dist/core/gate-fold.js +6 -3
- package/dist/core/gate-lanes.js +13 -5
- package/dist/core/git-worktree-env.d.ts +53 -11
- package/dist/core/git-worktree-env.js +96 -12
- package/dist/core/hooks.d.ts +6 -3
- package/dist/core/hooks.js +12 -5
- package/dist/core/human-input-projection.d.ts +1 -0
- package/dist/core/human-input-projection.js +3 -0
- package/dist/core/locked-config.d.ts +15 -1
- package/dist/core/locked-config.js +38 -2
- package/dist/core/mailbox-store.d.ts +62 -1
- package/dist/core/mailbox-store.js +59 -0
- package/dist/core/mcp-call-meta.d.ts +66 -0
- package/dist/core/mcp-call-meta.js +103 -0
- package/dist/core/mcp-connection-pool.d.ts +3 -1
- package/dist/core/mcp-connection-pool.js +3 -1
- package/dist/core/mcp-failure.d.ts +7 -1
- package/dist/core/mcp-failure.js +10 -0
- package/dist/core/mcp-name-judge.d.ts +46 -0
- package/dist/core/mcp-name-judge.js +61 -0
- package/dist/core/mcp-probe.d.ts +5 -1
- package/dist/core/mcp-probe.js +3 -6
- package/dist/core/mcp-server-link.d.ts +5 -2
- package/dist/core/mcp-server-spec.d.ts +46 -18
- package/dist/core/mcp-server-spec.js +1 -18
- package/dist/core/mcp.d.ts +6 -14
- package/dist/core/mcp.js +85 -65
- package/dist/core/memory-engine/consolidation-driver.js +4 -3
- package/dist/core/memory-engine/distiller.js +26 -17
- package/dist/core/memory-engine/layout.js +5 -2
- package/dist/core/memory-engine/scope-contract.d.ts +45 -4
- package/dist/core/memory-engine/scope-contract.js +80 -11
- package/dist/core/mode-policy.d.ts +8 -5
- package/dist/core/mode-policy.js +5 -4
- package/dist/core/mods/host.js +1 -1
- package/dist/core/mods/kernel/dispatch.d.ts +3 -0
- package/dist/core/mods/kernel/dispatch.js +10 -8
- package/dist/core/mods/kernel/events.d.ts +5 -1
- package/dist/core/mods/kernel/events.js +1 -1
- package/dist/core/mods/kernel/registration.d.ts +5 -1
- package/dist/core/mods/kernel/site-rules.d.ts +3 -0
- package/dist/core/mods/kernel/site-rules.js +10 -0
- package/dist/core/mods/package.d.ts +23 -0
- package/dist/core/mods/package.js +118 -0
- package/dist/core/mods/stations.d.ts +2 -2
- package/dist/core/mods/stations.js +1 -1
- package/dist/core/mods/tool-call.d.ts +5 -1
- package/dist/core/mods/tool-call.js +12 -3
- package/dist/core/park-selfcheck.js +2 -0
- package/dist/core/path-guard-rows.d.ts +20 -0
- package/dist/core/path-guard-rows.js +11 -0
- package/dist/core/peer-seat.d.ts +186 -0
- package/dist/core/peer-seat.js +307 -0
- package/dist/core/permission-rule-consent.d.ts +5 -3
- package/dist/core/permission-rule-consent.js +20 -15
- package/dist/core/permission-rule-model.d.ts +43 -2
- package/dist/core/permission-rule-model.js +52 -8
- package/dist/core/permission-rule-org.js +1 -1
- package/dist/core/present-plan-tool.d.ts +10 -1
- package/dist/core/present-plan-tool.js +46 -2
- package/dist/core/protocol-http-auth.d.ts +56 -31
- package/dist/core/protocol-http-auth.js +71 -42
- package/dist/core/protocol-naming.d.ts +20 -0
- package/dist/core/protocol-naming.js +20 -3
- package/dist/core/read-only-shell.d.ts +20 -5
- package/dist/core/read-only-shell.js +29 -14
- package/dist/core/redaction-marks.d.ts +16 -0
- package/dist/core/redaction-marks.js +16 -0
- package/dist/core/redaction-passes.js +8 -9
- package/dist/core/remote-env.d.ts +37 -1
- package/dist/core/remote-env.js +11 -0
- package/dist/core/resume-startup-cause.d.ts +24 -2
- package/dist/core/resume-startup-cause.js +20 -1
- package/dist/core/retention.d.ts +41 -15
- package/dist/core/retention.js +59 -12
- package/dist/core/rewrite-rejudge.d.ts +37 -0
- package/dist/core/rewrite-rejudge.js +40 -0
- package/dist/core/roles.js +50 -7
- package/dist/core/run-origin.d.ts +40 -0
- package/dist/core/run-origin.js +37 -0
- package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
- package/dist/core/runner/advertised-writable-dirs.js +126 -0
- package/dist/core/runner/compact-session.d.ts +10 -0
- package/dist/core/runner/compact-session.js +202 -0
- package/dist/core/runner/compaction-call-options.d.ts +2 -2
- package/dist/core/runner/compaction-restate.d.ts +15 -6
- package/dist/core/runner/compaction-restate.js +28 -2
- package/dist/core/runner/compaction-seams.d.ts +21 -1
- package/dist/core/runner/compaction-seams.js +11 -8
- package/dist/core/runner/contracts.d.ts +36 -21
- package/dist/core/runner/derived-route-fallback.d.ts +13 -0
- package/dist/core/runner/derived-route-fallback.js +6 -0
- package/dist/core/runner/env-capability-census.d.ts +3 -2
- package/dist/core/runner/env-capability-census.js +9 -3
- package/dist/core/runner/gate-exit.d.ts +18 -4
- package/dist/core/runner/gate-exit.js +5 -1
- package/dist/core/runner/permission-rule-lanes.d.ts +7 -7
- package/dist/core/runner/permission-rule-lanes.js +17 -11
- package/dist/core/runner/prepare-acquire-reconcile.d.ts +3 -0
- package/dist/core/runner/prepare-acquire-reconcile.js +2 -1
- package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
- package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
- package/dist/core/runner/prepare-config-doors.d.ts +14 -5
- package/dist/core/runner/prepare-config-doors.js +16 -13
- package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
- package/dist/core/runner/prepare-delegation-surface.js +15 -18
- package/dist/core/runner/prepare-gate-stations.js +1 -1
- package/dist/core/runner/prepare-hands-readface.d.ts +10 -4
- package/dist/core/runner/prepare-hands-readface.js +6 -1
- package/dist/core/runner/prepare-memory.d.ts +3 -0
- package/dist/core/runner/prepare-memory.js +19 -23
- package/dist/core/runner/prepare-park-ask.d.ts +2 -0
- package/dist/core/runner/prepare-park-ask.js +2 -2
- package/dist/core/runner/prepare-policy-chain.d.ts +4 -4
- package/dist/core/runner/prepare-policy-chain.js +4 -6
- package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
- package/dist/core/runner/prepare-protocol-tools.js +3 -3
- package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
- package/dist/core/runner/prepare-suspend-saga.js +2 -1
- package/dist/core/runner/prepare-task.d.ts +4 -1
- package/dist/core/runner/prepare-task.js +46 -37
- package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +13 -0
- package/dist/core/runner/prepare-tool-disclosure-mount.js +13 -7
- package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -0
- package/dist/core/runner/prepare-wiring-manifest.js +2 -2
- package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
- package/dist/core/runner/prepare-workspace-restore.js +4 -4
- package/dist/core/runner/resume-admission.js +1 -1
- package/dist/core/runner/resume-checkpoint-screen.js +2 -0
- package/dist/core/runner/rewind-files.d.ts +2 -5
- package/dist/core/runner/rewind-files.js +9 -51
- package/dist/core/runner/run-harness-handlers.d.ts +3 -4
- package/dist/core/runner/run-harness-handlers.js +1 -8
- package/dist/core/runner/run-identity-wiring.js +1 -0
- package/dist/core/runner/run-leg.js +15 -22
- package/dist/core/runner/run-notification-lane.d.ts +2 -0
- package/dist/core/runner/run-notification-lane.js +5 -2
- package/dist/core/runner/run-recovery-lanes.js +3 -4
- package/dist/core/runner/run-settle-and-teardown.js +5 -11
- package/dist/core/runner/run-terminal-adoption.js +3 -4
- package/dist/core/runner/run-turn-boundary.js +3 -5
- package/dist/core/runner/runtask.d.ts +8 -1
- package/dist/core/runner/runtask.js +28 -34
- package/dist/core/runner/send-message-continuation.js +1 -1
- package/dist/core/runner/session-verb-doors.d.ts +28 -0
- package/dist/core/runner/session-verb-doors.js +48 -0
- package/dist/core/runner/session-write-ledger.d.ts +30 -0
- package/dist/core/runner/session-write-ledger.js +101 -0
- package/dist/core/runner/stream-settle-backstop.js +11 -14
- package/dist/core/runner/sub-agent-deny-lists.d.ts +25 -3
- package/dist/core/runner/sub-agent-deny-lists.js +21 -10
- package/dist/core/runner/teardown-bounded.d.ts +1 -0
- package/dist/core/runner/teardown-bounded.js +1 -0
- package/dist/core/runner/terminal-account.js +3 -3
- package/dist/core/runner/tool-end-body.js +1 -0
- package/dist/core/runner/tool-occurrence.d.ts +4 -1
- package/dist/core/runner/tool-occurrence.js +2 -1
- package/dist/core/runner/write-protection-station.d.ts +8 -2
- package/dist/core/runner/write-protection-station.js +2 -0
- package/dist/core/runner-deps.d.ts +4 -4
- package/dist/core/secret-env.d.ts +4 -0
- package/dist/core/secret-env.js +3 -0
- package/dist/core/sensitive-path-policy.js +6 -7
- package/dist/core/session-log-transfer.d.ts +24 -0
- package/dist/core/session-log-transfer.js +166 -0
- package/dist/core/session-policy-store.d.ts +7 -2
- package/dist/core/session-policy-store.js +1 -1
- package/dist/core/session-store.d.ts +84 -19
- package/dist/core/session-store.js +162 -24
- package/dist/core/session.d.ts +92 -1
- package/dist/core/shell-read-silence.js +1 -0
- package/dist/core/shell-wrapper-projection.d.ts +1 -1
- package/dist/core/steer-replay.d.ts +4 -2
- package/dist/core/steer-replay.js +2 -1
- package/dist/core/store-contracts/background-agent-store-contract.js +1 -0
- package/dist/core/store-contracts/checkpoint-store-contract.js +19 -1
- package/dist/core/store-contracts/file-history-store-contract.js +9 -0
- package/dist/core/store-contracts/mailbox-store-contract.js +49 -1
- package/dist/core/store-contracts/session-repo-contract.js +112 -5
- package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
- package/dist/core/store-contracts/session-store-contract.js +236 -2
- package/dist/core/task-event.d.ts +68 -8
- package/dist/core/task-registry-agent.d.ts +8 -4
- package/dist/core/task-registry-agent.js +14 -8
- package/dist/core/task-registry-shared.d.ts +36 -6
- package/dist/core/task-registry-shared.js +11 -0
- package/dist/core/task-registry.d.ts +1 -1
- package/dist/core/task-registry.js +1 -1
- package/dist/core/task-spec.d.ts +37 -0
- package/dist/core/task-stream.d.ts +2 -1
- package/dist/core/terminal-cause.d.ts +1 -1
- package/dist/core/tool-catalog-entries.d.ts +6 -0
- package/dist/core/tool-catalog-entries.js +2 -0
- package/dist/core/tool-name-aliases.d.ts +32 -2
- package/dist/core/tool-name-aliases.js +23 -0
- package/dist/core/tool-name-readings.d.ts +4 -0
- package/dist/core/tool-name-readings.js +1 -0
- package/dist/core/tool-policy.d.ts +10 -6
- package/dist/core/tool-policy.js +4 -7
- package/dist/core/tool-result-store.d.ts +17 -10
- package/dist/core/tool-result-store.js +3 -1
- package/dist/core/trace.d.ts +4 -1
- package/dist/core/trace.js +2 -1
- package/dist/core/types.d.ts +1 -1
- package/dist/core/untrusted-egress.d.ts +18 -0
- package/dist/core/untrusted-egress.js +82 -12
- package/dist/core/wiring-manifest.d.ts +12 -3
- package/dist/core/wiring-manifest.js +4 -3
- package/dist/core/workspace-snapshot.d.ts +44 -0
- package/dist/core/workspace-snapshot.js +34 -0
- package/dist/core/write-protect.d.ts +43 -3
- package/dist/core/write-protect.js +43 -16
- package/dist/engine/execution-env/node-execution-env.js +15 -11
- package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
- package/dist/engine/harness/agent-harness.d.ts +12 -5
- package/dist/engine/harness/agent-harness.js +13 -2
- package/dist/engine/harness/types.d.ts +48 -7
- package/dist/engine/harness/types.js +5 -1
- package/dist/engine/llm/types.d.ts +12 -3
- package/dist/engine/llm/types.js +1 -1
- package/dist/engine/loop/agent-loop.d.ts +1 -4
- package/dist/engine/loop/agent-loop.js +26 -4
- package/dist/engine/session/import-validate.js +3 -0
- package/dist/engine/session/memory-repo.d.ts +17 -9
- package/dist/engine/session/memory-repo.js +44 -34
- package/dist/engine/session/repo-utils.d.ts +22 -4
- package/dist/engine/session/repo-utils.js +49 -1
- package/dist/engine/session/storage-base.d.ts +10 -1
- package/dist/engine/session/storage-base.js +7 -1
- package/dist/index.d.ts +23 -11
- package/dist/index.js +15 -6
- package/dist/internal/harness-types.d.ts +1 -1
- package/dist/internal/harness.d.ts +4 -3
- package/dist/internal/harness.js +3 -2
- package/dist/stores/file/checkpoint-store.d.ts +0 -4
- package/dist/stores/file/checkpoint-store.js +0 -1
- package/dist/stores/file/file-history-store.js +12 -4
- package/dist/stores/file/index.d.ts +4 -1
- package/dist/stores/file/index.js +4 -1
- package/dist/stores/file/mailbox-store.d.ts +2 -1
- package/dist/stores/file/mailbox-store.js +26 -1
- package/dist/stores/file/session-store.d.ts +15 -8
- package/dist/stores/file/session-store.js +28 -13
- package/dist/tools/fs/bash-readonly-classifier.d.ts +15 -19
- package/dist/tools/fs/bash-readonly-classifier.js +5 -10
- package/dist/tools/fs/fs-bash.js +10 -3
- package/dist/tools/fs/fs-write.d.ts +6 -3
- package/dist/tools/fs/fs-write.js +8 -7
- package/dist/tools/fs/index.d.ts +3 -0
- package/dist/tools/fs/index.js +1 -1
- package/dist/tools/fs/pattern-kill-guard.d.ts +3 -2
- package/dist/tools/fs/pattern-kill-guard.js +68 -36
- package/dist/tools/fs/safety.js +40 -8
- package/dist/tools/fs/search.js +6 -24
- package/dist/tools/fs/shell-read-check.d.ts +18 -1
- package/dist/tools/fs/shell-read-check.js +66 -16
- package/dist/tools/fs/shell-read-establish.js +2 -1
- package/dist/tools/fs/shell-read-identity.d.ts +12 -9
- package/dist/tools/fs/shell-read-identity.js +10 -5
- package/dist/tools/fs/shell-read-judge.d.ts +10 -1
- package/dist/tools/web.js +9 -7
- package/dist/tools/worktree.d.ts +42 -15
- package/dist/tools/worktree.js +60 -32
- package/package.json +4 -2
- package/test/export-surface.snapshot.json +141 -3
- package/wire-changes/core-stores-sql@7.57.0.json +29 -0
- package/wire-changes/core-stores-sql@7.58.0.json +29 -0
- package/wire-changes/core@7.57.0.json +1487 -0
- package/wire-changes/core@7.58.0.json +2188 -0
- package/wire-changes/mods-kernel@7.57.0.json +29 -0
- package/wire-changes/mods-kernel@7.58.0.json +81 -0
- package/wire-changes/primitives@7.57.0.json +245 -0
- package/wire-changes/primitives@7.58.0.json +29 -0
|
@@ -317,11 +317,13 @@ export declare function prepareCardApproval(opts: {
|
|
|
317
317
|
principal?: string;
|
|
318
318
|
/** design/182 §4.5 (additive): the structural owner — only the local-owner path needs it. */
|
|
319
319
|
owner?: RuleOwner;
|
|
320
|
-
/** The tool whose ask this card belongs to
|
|
321
|
-
* card)
|
|
320
|
+
/** The tool whose ask this card belongs to: a tool whose card the offer factory mints a rule on (`cardRuleFormOf`) — the shell
|
|
321
|
+
* tool, a name tool (the skill-activation card), a host tool (the fetch card), a tool with no rule grammar (the whole-tool card).
|
|
322
|
+
* Any other tool (a path tool, a shell-face sibling) draws no card. */
|
|
322
323
|
toolName: string;
|
|
323
324
|
/** The command as adjudicated — the same bytes the ask carried; for a name tool (`Skill`), the name its call carried (`args.skill`);
|
|
324
|
-
* for a host tool (`WebFetch`), the host its call reaches (the offer's `command`)
|
|
325
|
+
* for a host tool (`WebFetch`), the host its call reaches (the offer's `command`); for a tool with no rule grammar, `""` (the
|
|
326
|
+
* offer's `command`: the whole tool binds no value). */
|
|
325
327
|
command: string;
|
|
326
328
|
/** The ask's call id and argument digest, recorded for reconciliation. */
|
|
327
329
|
toolCallId?: string;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { randomBytes } from "node:crypto";
|
|
2
|
-
import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf,
|
|
2
|
+
import { COMMAND_RULE_TOOL, cardRuleFormOf, escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, segmentCoverageOf, suggestRuleForHost, suggestRuleForName, suggestRuleForTool, suggestRulesForCommand, EDITED_RULE_BREADTH_WARNING_CODES, RULE_OFFER_KINDS, UNCOVERED_SEGMENT_REASONS, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
|
|
3
3
|
import { readRuleOwner, sameRuleOwner } from "./rule-owner.js";
|
|
4
4
|
import { principalNameOf, readPrincipal } from "./principal-name.js";
|
|
5
5
|
import { isPlainRecord } from "./mods/kernel/receive.js";
|
|
@@ -236,6 +236,12 @@ function approvalRecordDamageOf(rec) {
|
|
|
236
236
|
if (rec.kind === "card" && cand.behavior !== "allow") {
|
|
237
237
|
return `card offer ${at} references candidate ${member}, a ${cand.behavior} rule — a card mints allow candidates only`;
|
|
238
238
|
}
|
|
239
|
+
if (rec.kind === "card") {
|
|
240
|
+
const read = parseRuleText(cand.rule, cand.behavior);
|
|
241
|
+
if ("rule" in read && read.rule.match === "tool" && (typeof rec.command === "string" || cardRuleFormOf(read.rule.tool) !== "tool")) {
|
|
242
|
+
return `card offer ${at} references candidate ${member}, the whole-tool rule "${escapeForDisclosure(read.rule.rule)}" — the engine mints one only on the whole-tool card of a tool with no rule grammar`;
|
|
243
|
+
}
|
|
244
|
+
}
|
|
239
245
|
if (!isValidConsentScope(cand.scope)) {
|
|
240
246
|
return `offer ${at} references candidate ${member}, whose scope is not a consent-face scope (global, project, or session)`;
|
|
241
247
|
}
|
|
@@ -262,7 +268,7 @@ function approvalRecordDamageOf(rec) {
|
|
|
262
268
|
}
|
|
263
269
|
if (detail.length > 0) {
|
|
264
270
|
const rows = detail;
|
|
265
|
-
const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool:
|
|
271
|
+
const table = typeof rec.command === "string" ? segmentCoverageOf(rec.command, { persisted: [] }, { tool: COMMAND_RULE_TOOL, cwd: undefined }) : undefined;
|
|
266
272
|
if (table === undefined) {
|
|
267
273
|
return `card batch offer ${at} carries reason rows but the record's command cannot back them — a row without a readable source command is a row nobody can audit`;
|
|
268
274
|
}
|
|
@@ -379,10 +385,10 @@ export async function prepareCardApproval(opts) {
|
|
|
379
385
|
e.code = "config.invalid_argument";
|
|
380
386
|
throw e;
|
|
381
387
|
}
|
|
382
|
-
const
|
|
383
|
-
|
|
384
|
-
if (opts.toolName !== CARD_RULE_TOOL && oneRuleCard === undefined)
|
|
388
|
+
const form = cardRuleFormOf(opts.toolName);
|
|
389
|
+
if (form === undefined)
|
|
385
390
|
return undefined;
|
|
391
|
+
const oneRuleCard = form === "command" ? undefined : form;
|
|
386
392
|
const scope = (() => {
|
|
387
393
|
if (opts.scope !== undefined) {
|
|
388
394
|
if (!isValidConsentScope(opts.scope)) {
|
|
@@ -409,14 +415,14 @@ export async function prepareCardApproval(opts) {
|
|
|
409
415
|
try {
|
|
410
416
|
const view = await effectiveOrThrow(storeForOwner(opts.deps.provider, owner), opts.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined);
|
|
411
417
|
const table = view.rules;
|
|
412
|
-
coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool:
|
|
418
|
+
coverage = segmentCoverageOf(opts.command, { persisted: table }, { tool: COMMAND_RULE_TOOL, cwd: opts.cwd, sessionId: opts.sessionId, ...(opts.execCwd !== undefined ? { execCwd: opts.execCwd } : {}) });
|
|
413
419
|
}
|
|
414
420
|
catch {
|
|
415
421
|
coverage = undefined;
|
|
416
422
|
}
|
|
417
423
|
}
|
|
418
424
|
const suggested = oneRuleCard !== undefined
|
|
419
|
-
? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : suggestRuleForHost(opts.toolName, opts.command)].filter((o) => o !== undefined)
|
|
425
|
+
? [oneRuleCard === "name" ? suggestRuleForName(opts.toolName, opts.command) : oneRuleCard === "domain" ? suggestRuleForHost(opts.toolName, opts.command) : opts.command === "" ? suggestRuleForTool(opts.toolName) : undefined].filter((o) => o !== undefined)
|
|
420
426
|
: suggestRulesForCommand(opts.command, {
|
|
421
427
|
...(coverage !== undefined ? { coverage } : {}),
|
|
422
428
|
scope,
|
|
@@ -468,7 +474,6 @@ export async function prepareCardApproval(opts) {
|
|
|
468
474
|
candidates,
|
|
469
475
|
};
|
|
470
476
|
}
|
|
471
|
-
const CARD_RULE_TOOL = "Bash";
|
|
472
477
|
export async function confirmRuleApproval(opts) {
|
|
473
478
|
const caller = resolveCallerOwner(opts.principal, opts.owner, "confirmRuleApproval");
|
|
474
479
|
const no = (reason, detail) => ({
|
|
@@ -546,6 +551,9 @@ function checkEditedRuleText(text, command) {
|
|
|
546
551
|
const parsed = parseSubmittedSpelling(text);
|
|
547
552
|
if ("reject" in parsed)
|
|
548
553
|
return { ok: false, code: parsed.reject.code, message: parsed.reject.message };
|
|
554
|
+
if (parsed.rule.match === "tool") {
|
|
555
|
+
return { ok: false, message: `the edited rule "${parsed.rule.rule}" names the whole tool — a card's edit names a command rule, and a standing yes to every command is not one a card mints` };
|
|
556
|
+
}
|
|
549
557
|
if (!ruleAdmitsCommand(parsed.rule, command)) {
|
|
550
558
|
return {
|
|
551
559
|
ok: false,
|
|
@@ -838,18 +846,15 @@ export async function prepareCcImport(opts) {
|
|
|
838
846
|
skipped.push({ rule: String(entry), reason: `settings ${behavior} entry is not a string` });
|
|
839
847
|
continue;
|
|
840
848
|
}
|
|
841
|
-
if (!/^[A-Za-z][A-Za-z0-9_]*\(.*\)$/.test(entry)) {
|
|
842
|
-
const reason = /^[A-Za-z][A-Za-z0-9_-]*$/.test(entry)
|
|
843
|
-
? "unsupported.form: a bare tool-name entry is a name-set item, not a command rule — it stays in the settings file, unimported"
|
|
844
|
-
: "unsupported.form: not a command rule spelling this version imports — it stays in the settings file, unimported";
|
|
845
|
-
skipped.push({ rule: entry, reason });
|
|
846
|
-
continue;
|
|
847
|
-
}
|
|
848
849
|
const parsed = parseRuleText(entry, behavior);
|
|
849
850
|
if ("reject" in parsed) {
|
|
850
851
|
skipped.push({ rule: entry, reason: `${parsed.reject.code}: ${parsed.reject.message}` });
|
|
851
852
|
continue;
|
|
852
853
|
}
|
|
854
|
+
if (parsed.rule.match === "tool") {
|
|
855
|
+
skipped.push({ rule: entry, reason: "unsupported.form: a bare tool-name entry is a name-set item the host carries from the settings layer's own lists — it stays in the settings file, unimported" });
|
|
856
|
+
continue;
|
|
857
|
+
}
|
|
853
858
|
if (candidates.some((c) => c.behavior === behavior && c.rule === parsed.rule.rule && sameScope(c.scope, scope)))
|
|
854
859
|
continue;
|
|
855
860
|
candidates.push({ behavior, rule: parsed.rule.rule, scope });
|
|
@@ -77,6 +77,7 @@ import { type DenyFace } from "../tools/fs/read-deny.js";
|
|
|
77
77
|
import type { AssertAllKeysHandled, RuleOffersAbsence } from "./ask-origin.js";
|
|
78
78
|
import { type ToolCallLike } from "./tool-registry.js";
|
|
79
79
|
import { type HostReading } from "./host-target.js";
|
|
80
|
+
import { type NamedCall } from "./tool-name-readings.js";
|
|
80
81
|
import { type PathDenialEvidence, type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
|
|
81
82
|
import { type TargetViews } from "./path-rule-binding.js";
|
|
82
83
|
/**
|
|
@@ -284,6 +285,18 @@ export declare const DOMAIN_RULE_MARKER = "domain:";
|
|
|
284
285
|
*/
|
|
285
286
|
export type RuleGrammar = "command" | "path" | "name" | "domain";
|
|
286
287
|
export declare function ruleToolGrammarOf(toolName: string): RuleGrammar | undefined;
|
|
288
|
+
/**
|
|
289
|
+
* THE rule a tool's approval card mints a "don't ask again" option in — one answer, read by the offer factory and the consent door
|
|
290
|
+
* alike: `command` for the command rule word (the shell card's command rules), `name` / `domain` for a tool of those grammars (the one
|
|
291
|
+
* exact value rule), `tool` for a call no rule word speaks for under any name it answers to ({@link laneToolNamesOf} empty: the
|
|
292
|
+
* whole-tool rule, the reference's fallback card), and `undefined` for the rest — a path tool (no path offer is minted), a shell-face
|
|
293
|
+
* sibling of the command word (its commands are `Bash(…)` rules), and a tool that answers to one of those under an alias it declares
|
|
294
|
+
* (a caller's shell wearing `Bash`: a one-click whole-tool yes on it would be a licence for every program): its card names that it has
|
|
295
|
+
* no rule to offer. `toolName` is the wire name the card mints on; `call` the call's names (absent: the wire name alone — the
|
|
296
|
+
* consent door, which holds no face).
|
|
297
|
+
*/
|
|
298
|
+
export type CardRuleForm = "command" | "name" | "domain" | "tool";
|
|
299
|
+
export declare function cardRuleFormOf(toolName: string, call?: NamedCall): CardRuleForm | undefined;
|
|
287
300
|
/** The parameter a shell-face tool's rule content names as one of the tool's own scalar arguments (`Monitor(description:*)`,
|
|
288
301
|
* `Bash(timeout:5)`), or undefined — the content is then a command spelling. */
|
|
289
302
|
export declare function shellRuleParamOf(tool: string, content: string): string | undefined;
|
|
@@ -311,11 +324,11 @@ export declare function nameRuleSubjectOf(toolName: string, args: unknown): stri
|
|
|
311
324
|
* domain tool's its own name — so a stored `Bash(…)` or `Edit(…)` row reaches a tool that answers to that name under another wire
|
|
312
325
|
* name, as a policy's rule does. Every lane that judges a call by a rule's word reads it here: the policy compiler, the
|
|
313
326
|
* person's stored rows, the org partition, the allow lists. Empty ⇒ no grammar speaks for the call. */
|
|
314
|
-
export declare function laneToolNamesOf(req:
|
|
327
|
+
export declare function laneToolNamesOf(req: NamedCall): readonly string[];
|
|
315
328
|
/** The match words a persisted rule is stored with, spelled once: {@link PersistedRuleMatch} is derived from this
|
|
316
329
|
* tuple (each form is documented there). A store backend that checks a stored row's `match` reads this value
|
|
317
330
|
* rather than keeping its own list. */
|
|
318
|
-
export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain"];
|
|
331
|
+
export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain", "tool"];
|
|
319
332
|
/**
|
|
320
333
|
* Match forms, one family per grammar (`prefix` and `wildcard` are one predicate):
|
|
321
334
|
* · `exact` — admits the one string the rule spells.
|
|
@@ -347,6 +360,8 @@ export declare const PERSISTED_RULE_MATCHES: readonly ["exact", "prefix", "wildc
|
|
|
347
360
|
* · `name` / `name_prefix` — the NAME grammar ({@link parseNameRuleContent}).
|
|
348
361
|
* · `host` / `subdomain` — the DOMAIN grammar ({@link parseDomainRuleContent}): one exact host, or every
|
|
349
362
|
* host below one domain.
|
|
363
|
+
* · `tool` — the WHOLE-TOOL form, a rule with no content (`SendUserFile`, `Bash`, `mcp__srv__get_issue`), on any tool:
|
|
364
|
+
* `command` is empty and the rule reaches every call that answers to the name it spells ({@link wholeToolRuleReaches}).
|
|
350
365
|
*/
|
|
351
366
|
export type PersistedRuleMatch = (typeof PERSISTED_RULE_MATCHES)[number];
|
|
352
367
|
/**
|
|
@@ -1275,6 +1290,32 @@ export declare function adjudicatePersistedDomainRules(rules: readonly Persisted
|
|
|
1275
1290
|
sessionId?: string;
|
|
1276
1291
|
scopeIdentity?: ScopeRootIdentity;
|
|
1277
1292
|
}): PersistedRuleVerdict | undefined;
|
|
1293
|
+
/**
|
|
1294
|
+
* THE predicate of a whole-tool rule (`match: "tool"`) over one call: the rule reaches the call iff the call answers to the name it
|
|
1295
|
+
* spells, under every name the call answers to (the model's spelling, the wire name, the aliases that resolve to it) — the
|
|
1296
|
+
* reference's tool-wide matcher. Every reader of a rule with no content asks it: an entry list's whole-tool row and a person's stored
|
|
1297
|
+
* whole-tool row alike.
|
|
1298
|
+
*/
|
|
1299
|
+
export declare function wholeToolRuleReaches(tool: string, call: NamedCall): boolean;
|
|
1300
|
+
/**
|
|
1301
|
+
* The whole-tool sibling of {@link adjudicatePersistedRules}: the same precedence walk (deny > ask > allow) over the whole-tool rows
|
|
1302
|
+
* (`match: "tool"`) that reach the call ({@link wholeToolRuleReaches}) and are eligible under their own tool ({@link eligiblePersisted},
|
|
1303
|
+
* the one predicate); the first behavior with such a row decides, the first table-order row of it is the answer.
|
|
1304
|
+
*/
|
|
1305
|
+
export declare function adjudicatePersistedToolRules(rules: readonly PersistedRule[], call: {
|
|
1306
|
+
request: NamedCall;
|
|
1307
|
+
cwd: string | undefined;
|
|
1308
|
+
sessionId?: string;
|
|
1309
|
+
scopeIdentity?: ScopeRootIdentity;
|
|
1310
|
+
}): PersistedRuleVerdict | undefined;
|
|
1311
|
+
/**
|
|
1312
|
+
* The ONE offer the card of a tool with no rule grammar carries ({@link cardRuleFormOf} `tool`): the whole-tool rule on its name (the
|
|
1313
|
+
* reference's fallback card, "don't ask again for <tool>"), or undefined when the name has no such rule (the round-trip law: the bare
|
|
1314
|
+
* name, parsed back as an allow, must be the whole-tool rule on that very name).
|
|
1315
|
+
*/
|
|
1316
|
+
export declare function suggestRuleForTool(tool: string): Extract<RuleOffer, {
|
|
1317
|
+
kind: "single";
|
|
1318
|
+
}> | undefined;
|
|
1278
1319
|
/**
|
|
1279
1320
|
* The ONE offer a host tool's approval card carries: the exact rule for the host the call reaches (`WebFetch(domain:<host>)`, the
|
|
1280
1321
|
* reference's "don't ask again for <host>" row), or undefined when no rule spells exactly that host (the round-trip law: the
|
|
@@ -2,13 +2,15 @@ import { homedir } from "node:os";
|
|
|
2
2
|
import { shellWordsOf } from "../shell/shell-words.js";
|
|
3
3
|
import { lexShell } from "../shell/lex.js";
|
|
4
4
|
import { readProgramPosition } from "../tools/fs/bash-program-position.js";
|
|
5
|
-
import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
|
|
5
|
+
import { isNameableToolName, parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
|
|
6
|
+
import { isCoveringRuleName } from "./namespaced-rule-name.js";
|
|
7
|
+
import { toolNameFaultOf } from "./tool-name-aliases.js";
|
|
6
8
|
import { compileReadDeny } from "../tools/fs/read-deny.js";
|
|
7
9
|
import { carriesShellRedirection, parseLeadingCommandName, splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
|
|
8
10
|
import { INLINE_TRUNCATION_MARK, inlineUntrusted } from "./untrusted-text.js";
|
|
9
|
-
import { catalogRuleFaceOf, hostTargetOf, isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
|
|
11
|
+
import { catalogRuleFaceOf, catalogToolNames, hostTargetOf, isShellFaceToolName, pathTargetOf, protectivePathTargetOf } from "./tool-registry.js";
|
|
10
12
|
import { HOST_UNREADABLE_SENTENCE, hostPatternAdmits, readHostPattern, spelledHostPattern } from "./host-target.js";
|
|
11
|
-
import { heldValues } from "./tool-name-readings.js";
|
|
13
|
+
import { heldBy, heldValues } from "./tool-name-readings.js";
|
|
12
14
|
import { carriesDotSegment, isAbsoluteForFamily, isIdentityDir, isPathIdentity, isShellRootedSpellingUnmapped, isUncIdentity, pathFamilyOf, pathIdentityOf } from "../tools/fs/safety.js";
|
|
13
15
|
import { bindPathRules, judgeRuleRows, rowsWhereTheyLead } from "./path-rule-binding.js";
|
|
14
16
|
import { readShellCommand } from "./shell-run-candidates.js";
|
|
@@ -135,6 +137,14 @@ export function ruleToolGrammarOf(toolName) {
|
|
|
135
137
|
return "domain";
|
|
136
138
|
return pathTargetOf(toolName) !== undefined ? "path" : undefined;
|
|
137
139
|
}
|
|
140
|
+
export function cardRuleFormOf(toolName, call = { toolName }) {
|
|
141
|
+
if (toolName === COMMAND_RULE_TOOL)
|
|
142
|
+
return "command";
|
|
143
|
+
const grammar = ruleToolGrammarOf(toolName);
|
|
144
|
+
if (grammar === "name" || grammar === "domain")
|
|
145
|
+
return grammar;
|
|
146
|
+
return grammar === undefined && laneToolNamesOf(call).length === 0 && laneToolNamesOf({ toolName }).length === 0 ? "tool" : undefined;
|
|
147
|
+
}
|
|
138
148
|
export function shellRuleParamOf(tool, content) {
|
|
139
149
|
const colon = content.indexOf(":");
|
|
140
150
|
if (colon <= 0)
|
|
@@ -172,7 +182,7 @@ function ruleWordOf(name) {
|
|
|
172
182
|
return COMMAND_RULE_TOOL;
|
|
173
183
|
return ruleToolGrammarOf(name) !== undefined ? name : undefined;
|
|
174
184
|
}
|
|
175
|
-
export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain"]);
|
|
185
|
+
export const PERSISTED_RULE_MATCHES = Object.freeze(["exact", "prefix", "wildcard", "pattern", "subpath", "path", "name", "name_prefix", "host", "subdomain", "tool"]);
|
|
176
186
|
function isCommandMatch(match) {
|
|
177
187
|
return match === "exact" || match === "prefix" || match === "wildcard" || match === "pattern";
|
|
178
188
|
}
|
|
@@ -415,6 +425,19 @@ export function respelledRuleTextOf(text, behavior) {
|
|
|
415
425
|
const read = parseRuleText(candidate, behavior);
|
|
416
426
|
return "rule" in read ? read.rule.rule : undefined;
|
|
417
427
|
}
|
|
428
|
+
function parseWholeToolRule(text, tool, behavior) {
|
|
429
|
+
if (!isNameableToolName(tool) || isCoveringRuleName(tool, behavior)) {
|
|
430
|
+
return reject("invalid.grammar", `"${text}" names a set of tools — a stored rule names one tool, or one tool's content; a set of tools is a list entry's form`);
|
|
431
|
+
}
|
|
432
|
+
const fault = toolNameFaultOf(tool, catalogToolNames(), behavior);
|
|
433
|
+
if (fault === undefined)
|
|
434
|
+
return { rule: { behavior, rule: tool, tool, match: "tool", command: "" } };
|
|
435
|
+
const why = fault.reason === "near_miss"
|
|
436
|
+
? `is another spelling of "${fault.currentName}", which the engine's tool catalog names — a rule names its tool exactly as spelled, so this one would reach no tool`
|
|
437
|
+
: `names no tool under that name${fault.guidance !== undefined ? ` — ${fault.guidance}` : ""}`;
|
|
438
|
+
const write = fault.currentName !== undefined && !why.includes(`"${fault.currentName}"`) ? `; write "${fault.currentName}"` : "";
|
|
439
|
+
return reject("unsupported.tool", `"${text}" ${why}${write}`);
|
|
440
|
+
}
|
|
418
441
|
export function parseRuleText(text, behavior) {
|
|
419
442
|
if (!isRuleBehavior(behavior)) {
|
|
420
443
|
return reject("invalid.grammar", `rule "${text}" was parsed under behavior ${escapeForDisclosure(behavior)}, which is not one of ${RULE_BEHAVIORS.join("/")}`);
|
|
@@ -438,9 +461,8 @@ export function parseRuleText(text, behavior) {
|
|
|
438
461
|
};
|
|
439
462
|
}
|
|
440
463
|
const ruleContent = ruleContentOf(parsed);
|
|
441
|
-
if (ruleContent === undefined)
|
|
442
|
-
return
|
|
443
|
-
}
|
|
464
|
+
if (ruleContent === undefined)
|
|
465
|
+
return parseWholeToolRule(text, parsed.toolName, behavior);
|
|
444
466
|
if (parsed.toolName !== COMMAND_RULE_TOOL) {
|
|
445
467
|
const grammar = ruleToolGrammarOf(parsed.toolName);
|
|
446
468
|
if (grammar === undefined) {
|
|
@@ -510,6 +532,8 @@ export function parseRuleText(text, behavior) {
|
|
|
510
532
|
return { rule: { behavior, rule: formatRuleText(command, match, COMMAND_RULE_TOOL), tool: COMMAND_RULE_TOOL, match, command } };
|
|
511
533
|
}
|
|
512
534
|
export function formatRuleText(command, match, tool) {
|
|
535
|
+
if (match === "tool")
|
|
536
|
+
return tool;
|
|
513
537
|
if (match === "subpath")
|
|
514
538
|
return `${tool}(//${command.startsWith("/") ? command.slice(1) : command}/**)`;
|
|
515
539
|
if (match === "path")
|
|
@@ -1318,7 +1342,7 @@ export function commandCoverageOf(rules, call) {
|
|
|
1318
1342
|
return covering.length > 0 ? { covering } : { uncovered: undefined };
|
|
1319
1343
|
}
|
|
1320
1344
|
function readsOnlyAsSegment(segment, lineObjection, whole) {
|
|
1321
|
-
return lineObjection === undefined && !movesShellCursor(segment) && readOnlyShellVerdict(segment,
|
|
1345
|
+
return lineObjection === undefined && !movesShellCursor(segment) && readOnlyShellVerdict(segment, { bound: () => lineDescriptorsOfText(whole) }).readOnly;
|
|
1322
1346
|
}
|
|
1323
1347
|
function firstEligibleDirectoryRule(rules, directory, call) {
|
|
1324
1348
|
for (const rule of rules) {
|
|
@@ -1434,6 +1458,26 @@ export function adjudicatePersistedDomainRules(rules, call) {
|
|
|
1434
1458
|
}
|
|
1435
1459
|
return undefined;
|
|
1436
1460
|
}
|
|
1461
|
+
export function wholeToolRuleReaches(tool, call) {
|
|
1462
|
+
return heldBy("policy.persistedToolRule", { has: (name) => name === tool }, call);
|
|
1463
|
+
}
|
|
1464
|
+
export function adjudicatePersistedToolRules(rules, call) {
|
|
1465
|
+
const at = { cwd: call.cwd, ...(call.sessionId !== undefined ? { sessionId: call.sessionId } : {}), ...(call.scopeIdentity !== undefined ? { scopeIdentity: call.scopeIdentity } : {}) };
|
|
1466
|
+
for (const behavior of RULE_BEHAVIORS_BY_PRECEDENCE) {
|
|
1467
|
+
const row = rules.find((rule) => rule.match === "tool" && wholeToolRuleReaches(rule.tool, call.request) && eligiblePersisted(rule, { ...at, tool: rule.tool }, behavior));
|
|
1468
|
+
if (row !== undefined)
|
|
1469
|
+
return { behavior, rules: [row] };
|
|
1470
|
+
}
|
|
1471
|
+
return undefined;
|
|
1472
|
+
}
|
|
1473
|
+
export function suggestRuleForTool(tool) {
|
|
1474
|
+
if (cardRuleFormOf(tool) !== "tool")
|
|
1475
|
+
return undefined;
|
|
1476
|
+
const parsed = parseRuleText(formatRuleText("", "tool", tool), "allow");
|
|
1477
|
+
if (!("rule" in parsed) || parsed.rule.match !== "tool" || parsed.rule.tool !== tool)
|
|
1478
|
+
return undefined;
|
|
1479
|
+
return { kind: "single", rule: parsed.rule.rule, match: "tool", command: "" };
|
|
1480
|
+
}
|
|
1437
1481
|
export function suggestRuleForHost(tool, host) {
|
|
1438
1482
|
if (ruleToolGrammarOf(tool) !== "domain")
|
|
1439
1483
|
return undefined;
|
|
@@ -301,7 +301,7 @@ function readOrgRow(row, index) {
|
|
|
301
301
|
const parsed = parseRuleText(text, said);
|
|
302
302
|
if ("reject" in parsed)
|
|
303
303
|
return unreadable(parsed.reject.code, undefined, parsed.reject.respelling);
|
|
304
|
-
if (parsed.rule.tool !== COMMAND_RULE_TOOL)
|
|
304
|
+
if (parsed.rule.tool !== COMMAND_RULE_TOOL || parsed.rule.match === "tool")
|
|
305
305
|
return unreadable("unsupported.tool");
|
|
306
306
|
return { kind: "read", index, rule: text, behavior: said, parsed: parsed.rule };
|
|
307
307
|
}
|
|
@@ -14,6 +14,15 @@ export declare const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
|
|
|
14
14
|
* Exit is via `present_plan` (→ plan_review → human approve-resume), not by this tool.
|
|
15
15
|
*/
|
|
16
16
|
export declare function createEnterPlanModeTool(enterPlanMode: () => Promise<void> | void): ToolSpec;
|
|
17
|
+
/** The plan file a leg declared (`TaskSpec.planFile`), as the plan-exit tool's file arm reads it: the declared spelling (the
|
|
18
|
+
* card's `filePath`), the same path as the seat tells it to the model (`shown` — `planFileShown`, one line, verbatim, at
|
|
19
|
+
* most 4096 characters: the seat refuses any other), and the seat's one reader of what the file holds (`readPlanFile`,
|
|
20
|
+
* advertised-writable-dirs.ts). Type-only import: this module is below the seat and must not load it. */
|
|
21
|
+
export interface PlanFileSource {
|
|
22
|
+
readonly path: string;
|
|
23
|
+
readonly shown: string;
|
|
24
|
+
readonly read: (signal?: AbortSignal) => Promise<import("./runner/advertised-writable-dirs.js").PlanFileReading>;
|
|
25
|
+
}
|
|
17
26
|
/**
|
|
18
27
|
* design/80 D-B — the first-party `present_plan` tool (CC `ExitPlanMode` parity). A THIN composition over the
|
|
19
28
|
* general `ctx.requestReview()` primitive: the model calls it with a plan; the tool returns the plan as its
|
|
@@ -24,4 +33,4 @@ export declare function createEnterPlanModeTool(enterPlanMode: () => Promise<voi
|
|
|
24
33
|
*/
|
|
25
34
|
export declare function createPresentPlanTool(requestReview: (opts?: {
|
|
26
35
|
reason?: string;
|
|
27
|
-
}) => void): ToolSpec;
|
|
36
|
+
}) => void, planFile?: PlanFileSource): ToolSpec;
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { Type } from "typebox";
|
|
2
|
-
import { delimitUntrusted } from "./untrusted-text.js";
|
|
2
|
+
import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
|
|
3
3
|
import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
|
|
4
|
+
import { errorResult } from "./tools.js";
|
|
5
|
+
const READ_REASON_MAX = 600;
|
|
4
6
|
export const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
|
|
5
7
|
export const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
|
|
6
8
|
const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, every write/edit/mutating tool call ASKS the user first ("Cannot write to <path> while in plan mode."; where nobody can answer, it is refused) while read-only tools (Read, Grep, Glob, etc.) still work. When your plan is ready, call ${PRESENT_PLAN_TOOL_NAME} with it — the run PAUSES for a human to approve it, then continues (read-only lifted) so you can execute.
|
|
@@ -59,7 +61,49 @@ const PRESENT_PLAN_DESCRIPTION = [
|
|
|
59
61
|
"If the plan is approved, the run continues (and any read-only restriction is lifted) so you can execute it;",
|
|
60
62
|
"if it is rejected or edited, follow the reviewer's feedback instead of the original plan.",
|
|
61
63
|
].join(" ");
|
|
62
|
-
|
|
64
|
+
const PRESENT_PLAN_FILE_DESCRIPTION = (shown) => `Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
|
|
65
|
+
|
|
66
|
+
## How This Tool Works
|
|
67
|
+
- You should have already written your plan to the plan file: ${shown}
|
|
68
|
+
- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
|
|
69
|
+
- This tool simply signals that you're done planning and ready for the user to review and approve; the run PAUSES for a human to approve, edit, or reject it
|
|
70
|
+
- The user will see the contents of your plan file when they review it
|
|
71
|
+
|
|
72
|
+
## When to Use This Tool
|
|
73
|
+
IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
|
|
74
|
+
|
|
75
|
+
## Before Using This Tool
|
|
76
|
+
Ensure your plan is complete and unambiguous:
|
|
77
|
+
- If you have unresolved questions about requirements or approach, resolve them first (in earlier phases)
|
|
78
|
+
- Once your plan is finalized, use THIS tool to request approval
|
|
79
|
+
|
|
80
|
+
**Important:** Do NOT separately ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.`;
|
|
81
|
+
function createPresentPlanFileTool(requestReview, planFile) {
|
|
82
|
+
return {
|
|
83
|
+
name: PRESENT_PLAN_TOOL_NAME,
|
|
84
|
+
...toolFace("exit-plan-mode-file"),
|
|
85
|
+
ruleFace: mountRuleFace("exit-plan-mode-file"),
|
|
86
|
+
description: PRESENT_PLAN_FILE_DESCRIPTION(planFile.shown),
|
|
87
|
+
parameters: Type.Object({}),
|
|
88
|
+
execute: async (_args, ctx) => {
|
|
89
|
+
const read = await planFile.read(ctx?.signal);
|
|
90
|
+
if (!read.ok)
|
|
91
|
+
return errorResult(`The plan file ${planFile.shown} could not be read (${inlineUntrusted(read.reason, READ_REASON_MAX)}), so plan mode was not exited. Write your plan to this file and call ExitPlanMode again.`);
|
|
92
|
+
if (read.text === undefined)
|
|
93
|
+
return errorResult(`No plan file found at ${planFile.shown}. Please write your plan to this file before calling ExitPlanMode.`);
|
|
94
|
+
const plan = read.text;
|
|
95
|
+
requestReview({ reason: "ExitPlanMode" });
|
|
96
|
+
return {
|
|
97
|
+
content: `Plan presented for human review (from ${planFile.shown}):\n\n${delimitUntrusted("plan", plan)}\n\n` +
|
|
98
|
+
"(The run is pausing for approval — you will continue once the plan is approved, edited, or rejected.)",
|
|
99
|
+
details: { type: "exit-plan-mode", plan, isAgent: false, filePath: planFile.path },
|
|
100
|
+
};
|
|
101
|
+
},
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
export function createPresentPlanTool(requestReview, planFile) {
|
|
105
|
+
if (planFile !== undefined)
|
|
106
|
+
return createPresentPlanFileTool(requestReview, planFile);
|
|
63
107
|
return {
|
|
64
108
|
name: PRESENT_PLAN_TOOL_NAME,
|
|
65
109
|
...toolFace("exit-plan-mode"),
|
|
@@ -1,48 +1,59 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The HTTP
|
|
3
|
-
*
|
|
4
|
-
*
|
|
5
|
-
* compares names (case-insensitively). The principal header's owner is the
|
|
6
|
-
* principal under that name, or nothing under it when the task has none. A
|
|
7
|
-
*
|
|
8
|
-
* a
|
|
2
|
+
* The HTTP headers one send to a protocol peer carries — the pieces the deployment's peer seat answered for it
|
|
3
|
+
* (src/core/peer-seat.ts) and the per-task principal header the declaration names (`principalHeader`) — and the one
|
|
4
|
+
* rule they obey, for MCP and A2A alike: they travel only to the endpoints the declaration names, and every header name
|
|
5
|
+
* has exactly one owner, compared the way HTTP compares names (case-insensitively). The principal header's owner is the
|
|
6
|
+
* engine: it sends the task's principal under that name, or nothing under it when the task has none. A name a protocol's
|
|
7
|
+
* transport writes itself (an MCP request's session, protocol version, content type, accept and resume headers) is the
|
|
8
|
+
* protocol's: neither a seat's answer nor the principal header owns it. The hosted-connector assertion header
|
|
9
|
+
* ({@link MCP_ASSERTION_HEADER}) is the seat's to answer and never the principal header's name. A header the credential
|
|
10
|
+
* vocabulary reads as a credential is one the engine holds from the moment it resolves it: no child spawned on this host
|
|
11
|
+
* inherits a variable whose value equals it (`holdOwnCredentialValues`, src/core/secret-env.ts).
|
|
9
12
|
*
|
|
10
|
-
* A
|
|
11
|
-
*
|
|
12
|
-
* endpoint by dialing only the declared URL with redirects not followed (
|
|
13
|
-
* peer, whose card may name another endpoint, is bound
|
|
14
|
-
*
|
|
13
|
+
* A principal header that breaks the rule is that peer's defect: the resolver throws inside the peer's own dial, so the
|
|
14
|
+
* peer is skipped with a coded warning and its siblings still mount; an answer that breaks it is the seat's, and that send
|
|
15
|
+
* is not made. The MCP transport binds its endpoint by dialing only the declared URL with redirects not followed (the seat's
|
|
16
|
+
* fetch, `peerFetch`); the A2A peer, whose card may name another endpoint, is bound at each send that carries pieces by
|
|
17
|
+
* {@link assertEndpointBound} and by its follow law (a request carrying them follows no redirect, {@link carriesDeclaredHeaders}).
|
|
15
18
|
*/
|
|
16
19
|
import type { ProtocolId } from "./protocol-table.js";
|
|
17
|
-
|
|
20
|
+
import { type Egress } from "./untrusted-egress.js";
|
|
21
|
+
/**
|
|
22
|
+
* The HTTP header NAME a hosted connector reads the principal assertion from: the engine's one definition of that name, exported from
|
|
23
|
+
* the package root so a deployment, a host and a connector each read it here instead of spelling it again. The name only — the
|
|
24
|
+
* value (the assertion itself) is not minted or held by this constant: the deployment's peer seat answers it under this name, per
|
|
25
|
+
* send. It is never the principal header's name (in any letter case): a declaration naming it so is refused at its dial with
|
|
26
|
+
* `config.protocol_header_collision`.
|
|
27
|
+
*/
|
|
28
|
+
export declare const MCP_ASSERTION_HEADER = "connector-assertion";
|
|
29
|
+
/** The headers one send carries: the seat's answered `headers` and the declaration's `principalHeader` name. */
|
|
18
30
|
export interface ProtocolHttpAuth {
|
|
19
31
|
headers?: Record<string, string>;
|
|
20
32
|
principalHeader?: string;
|
|
21
33
|
}
|
|
22
|
-
/**
|
|
23
|
-
|
|
34
|
+
/**
|
|
35
|
+
* The first header name (any case) one send to a `protocol` peer would give two owners, with both spellings: two spellings among the
|
|
36
|
+
* answered `headers`, an answered header under the principal header's name, a name the protocol's transport writes itself (`first` is
|
|
37
|
+
* then the protocol's spelling, `engineOwned` true), or a principal header named as the engine's {@link MCP_ASSERTION_HEADER}
|
|
38
|
+
* (`first` the engine's spelling, `engineOwned` true). The assertion header among the answered headers is the seat's to send.
|
|
39
|
+
*/
|
|
40
|
+
export declare function headerOwnershipCollision(t: ProtocolHttpAuth, protocol: ProtocolId): {
|
|
24
41
|
readonly first: string;
|
|
25
42
|
readonly second: string;
|
|
43
|
+
readonly engineOwned: boolean;
|
|
26
44
|
} | undefined;
|
|
27
45
|
/**
|
|
28
|
-
* Resolve the HTTP request headers
|
|
46
|
+
* Resolve the HTTP request headers of one send to a peer of `protocol`: the seat's answered headers, plus the
|
|
29
47
|
* principal under `principalHeader` when both are present. Throws `config.protocol_header_collision` when
|
|
30
|
-
* one header name
|
|
31
|
-
* name — which would otherwise be sent merged beside the principal, or
|
|
32
|
-
*
|
|
48
|
+
* one header name would have two owners ({@link headerOwnershipCollision}: two spellings of one answered name, an
|
|
49
|
+
* answered header under the principal header's name — which would otherwise be sent merged beside the principal, or
|
|
50
|
+
* alone when the task has none — a name the protocol's transport writes, or a principal header named as the engine's
|
|
51
|
+
* {@link MCP_ASSERTION_HEADER}), and on a principal carrying CR/LF. Callers invoke it INSIDE their per-peer boundary.
|
|
33
52
|
*/
|
|
34
53
|
export declare function resolveProtocolHttpHeaders(protocol: ProtocolId, t: ProtocolHttpAuth, principal?: string): Readonly<Record<string, string>> | undefined;
|
|
35
54
|
/** The engine's default request headers under the declared ones: a declared name, in any case, owns that header
|
|
36
55
|
* (the default of the same name is not sent beside it). */
|
|
37
56
|
export declare function underDeclaredHeaders(defaults: Readonly<Record<string, string>>, declared: Record<string, string> | undefined): Record<string, string>;
|
|
38
|
-
/**
|
|
39
|
-
* Every header VALUE one HTTP peer's requests carry, whatever the header's NAME: each string value of the declaration's static
|
|
40
|
-
* `headers` and the principal the engine sends under `principalHeader`, as declared. The transport knows these; the credential vocabulary
|
|
41
|
-
* can only guess by name. How an endpoint can print one back — edges dropped, its credentials part, percent-encoded — is derived from
|
|
42
|
-
* each value by {@link requestEchoSpellings}, once, and nowhere else.
|
|
43
|
-
* Total: a declaration whose members cannot be read yields what could be read, because it is called on a failure path.
|
|
44
|
-
*/
|
|
45
|
-
export declare function declaredHeaderValues(transport: unknown, principal?: string): readonly string[];
|
|
46
57
|
/**
|
|
47
58
|
* A peer's error text with what the peer was SENT taken out of it. Both kinds of removal are found on the ORIGINAL text (so no marker is
|
|
48
59
|
* rescanned and no replacement can disturb what another one reads) and the ranges they take are merged, one marker per merged range: every
|
|
@@ -53,15 +64,29 @@ export declare function declaredHeaderValues(transport: unknown, principal?: str
|
|
|
53
64
|
* from outside takes its own range and the member's value goes with it. A declared value that is also an ordinary word or number (`en`, `1`,
|
|
54
65
|
* `application/json`) goes wherever it occurs in the remote's words, in any case — a legibility cost, never a leak; the failure's closed
|
|
55
66
|
* fields (code, status, delivery) are not text. A declaration too large for one matcher (tens of thousands of characters, which no header
|
|
56
|
-
* carries) makes the whole text the marker: the pass never throws and never shows what it could not match.
|
|
57
|
-
*
|
|
67
|
+
* carries) makes the whole text the marker: the pass never throws and never shows what it could not match. A hit that lies wholly inside
|
|
68
|
+
* a marker a pass already wrote (the exact literals, `redactionMarkerSpans`) is no hit, and one that reaches into a marker takes the
|
|
69
|
+
* whole marker with it, so the pass over its own output answers the same text.
|
|
58
70
|
*/
|
|
59
71
|
export declare function scrubRequestEcho(text: string, declared: readonly string[]): string;
|
|
72
|
+
/**
|
|
73
|
+
* THE one form a remote endpoint's words take when the engine carries them in its own words — an MCP server's failure, a model
|
|
74
|
+
* provider's error body, frame or transport failure, a memory distiller seat's failure: what the request was declared with
|
|
75
|
+
* ({@link scrubRequestEcho}: `declared` is required, so no mint reads a remote's words without naming its request), then the credential
|
|
76
|
+
* vocabulary. Words with no declared value in them read exactly as the vocabulary renders them. Where a declared value is there, the
|
|
77
|
+
* values the vocabulary finds in the ORIGINAL words are taken out with it, so neither disarms the other: removing a declared `Bearer`
|
|
78
|
+
* cannot hide the token after it from the vocabulary, and the vocabulary rewriting part of a declared value cannot leave the rest. A
|
|
79
|
+
* caller that bounds the text for display cuts what this returns, never the remote's raw words, so a cut can leave no part of a value.
|
|
80
|
+
* The function is a fixed point (its own output answers the same text). A store, a log or an event lane that receives the result does
|
|
81
|
+
* not redact again: persistence is not an exit, the mint is.
|
|
82
|
+
*/
|
|
83
|
+
export declare function remoteWords(text: string, declared: readonly string[]): Egress<"same-principal">;
|
|
60
84
|
/** Whether a resolved header set carries anything the declaration bound to its endpoints — a request that does follows no redirect (the
|
|
61
85
|
* next hop is not a declared endpoint; A2A's follow law reads this). */
|
|
62
86
|
export declare function carriesDeclaredHeaders(headers: Record<string, string> | undefined): boolean;
|
|
63
87
|
/**
|
|
64
|
-
* Refuse
|
|
65
|
-
* declaration names and the
|
|
88
|
+
* Refuse a send to `endpoint` (an A2A card's interface URL, judged at every send) when it lies outside every origin the
|
|
89
|
+
* declaration names and the send carries pieces the peer seat answered: `config.protocol_endpoint_unbound`. A send that
|
|
90
|
+
* carries none goes where the card says.
|
|
66
91
|
*/
|
|
67
92
|
export declare function assertEndpointBound(protocol: ProtocolId, peer: string, endpoint: string, declared: readonly string[], headers: Record<string, string> | undefined): void;
|