@sema-ai/core 1.275.1

package/dist/core/runner/usage-accounting.d.ts

@@ -0,0 +1,35 @@
+import type { Model } from "../../internal/llm.js";
+import { type ModelPricing } from "../pricing.js";
+/** How a provider counts cached tokens in its reported `input`. */
+export type CacheFamily = "input-includes-cached" | "input-excludes-cached";
+/**
+ * Resolve the prompt-cache accounting family for a model. **Auto-inferred from `model.api`** by
+ * default (Anthropic/Bedrock report `input` EXCLUDING cached tokens; OpenAI/vLLM/Google INCLUDE them),
+ * but a deployment can **override** it via `model.params.promptCacheFamily` when `model.api` doesn't
+ * match the brain that actually serves the model — e.g. a routing brain that dispatches by `provider`
+ * while `api` is left at a default. Accepts the explicit values or the aliases `"anthropic"`/`"openai"`.
+ * (design/18: a route-by-provider setup with `api` hardcoded misjudged the family → 1090% hit rate.)
+ */
+export declare function cacheFamilyOf(model: Model): CacheFamily;
+/** Total prompt tokens presented this turn, normalized so `cachedTokens` is always ⊆ `promptTokens`. */
+export declare function promptTokensOf(family: CacheFamily, u: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+}): number;
+/**
+ * Normalize one turn's reported usage into its `{ totalInputTokens, costMicroUsd }` — the authoritative
+ * cost re-priced in core from injected pricing (so cached tokens aren't charged at full price). Shared
+ * by the run loop's per-turn accounting and post-task memory consolidation (design/41) so a pricing
+ * change lives in ONE place. We emit only 5-min-TTL cache writes, so `cacheWriteTokensLong` is 0.
+ */
+export declare function usageCostMicroUsd(family: CacheFamily, u: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}, pricing: ModelPricing): {
+    totalInputTokens: number;
+    costMicroUsd: number;
+};
+//# sourceMappingURL=usage-accounting.d.ts.map

package/dist/core/runner/usage-accounting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-accounting.d.ts","sourceRoot":"","sources":["../../../src/core/runner/usage-accounting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAEvE,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG,uBAAuB,GAAG,uBAAuB,CAAC;AAE5E;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,CAOvD;AAED,wGAAwG;AACxG,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEvH;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/E,OAAO,EAAE,YAAY,GACpB;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAiBpD"}

package/dist/core/runner/usage-accounting.js

@@ -0,0 +1,45 @@
+import { computeCostMicroUsd } from "../pricing.js";
+/**
+ * Resolve the prompt-cache accounting family for a model. **Auto-inferred from `model.api`** by
+ * default (Anthropic/Bedrock report `input` EXCLUDING cached tokens; OpenAI/vLLM/Google INCLUDE them),
+ * but a deployment can **override** it via `model.params.promptCacheFamily` when `model.api` doesn't
+ * match the brain that actually serves the model — e.g. a routing brain that dispatches by `provider`
+ * while `api` is left at a default. Accepts the explicit values or the aliases `"anthropic"`/`"openai"`.
+ * (design/18: a route-by-provider setup with `api` hardcoded misjudged the family → 1090% hit rate.)
+ */
+export function cacheFamilyOf(model) {
+    const override = model.params?.promptCacheFamily;
+    if (override === "input-excludes-cached" || override === "anthropic")
+        return "input-excludes-cached";
+    if (override === "input-includes-cached" || override === "openai")
+        return "input-includes-cached";
+    return model.api === "anthropic-messages" || model.api === "bedrock-converse-stream"
+        ? "input-excludes-cached"
+        : "input-includes-cached";
+}
+/** Total prompt tokens presented this turn, normalized so `cachedTokens` is always ⊆ `promptTokens`. */
+export function promptTokensOf(family, u) {
+    return family === "input-excludes-cached" ? u.input + u.cacheRead + u.cacheWrite : u.input;
+}
+/**
+ * Normalize one turn's reported usage into its `{ totalInputTokens, costMicroUsd }` — the authoritative
+ * cost re-priced in core from injected pricing (so cached tokens aren't charged at full price). Shared
+ * by the run loop's per-turn accounting and post-task memory consolidation (design/41) so a pricing
+ * change lives in ONE place. We emit only 5-min-TTL cache writes, so `cacheWriteTokensLong` is 0.
+ */
+export function usageCostMicroUsd(family, u, pricing) {
+    const totalInputTokens = promptTokensOf(family, {
+        input: u.input || 0,
+        cacheRead: u.cacheRead || 0,
+        cacheWrite: u.cacheWrite || 0,
+    });
+    const costMicroUsd = computeCostMicroUsd({
+        totalInputTokens,
+        cacheReadTokens: u.cacheRead || 0,
+        cacheWriteTokens: u.cacheWrite || 0,
+        cacheWriteTokensLong: 0,
+        outputTokens: u.output || 0,
+    }, pricing);
+    return { totalInputTokens, costMicroUsd };
+}
+//# sourceMappingURL=usage-accounting.js.map

package/dist/core/runner/usage-accounting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-accounting.js","sourceRoot":"","sources":["../../../src/core/runner/usage-accounting.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAqB,MAAM,eAAe,CAAC;AAKvE;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAY;IACxC,MAAM,QAAQ,GAAI,KAAK,CAAC,MAAqD,EAAE,iBAAiB,CAAC;IACjG,IAAI,QAAQ,KAAK,uBAAuB,IAAI,QAAQ,KAAK,WAAW;QAAE,OAAO,uBAAuB,CAAC;IACrG,IAAI,QAAQ,KAAK,uBAAuB,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,uBAAuB,CAAC;IAClG,OAAO,KAAK,CAAC,GAAG,KAAK,oBAAoB,IAAI,KAAK,CAAC,GAAG,KAAK,yBAAyB;QAClF,CAAC,CAAC,uBAAuB;QACzB,CAAC,CAAC,uBAAuB,CAAC;AAC9B,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,CAA2D;IAC7G,OAAO,MAAM,KAAK,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AAC7F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,CAA+E,EAC/E,OAAqB;IAErB,MAAM,gBAAgB,GAAG,cAAc,CAAC,MAAM,EAAE;QAC9C,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;QACnB,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,CAAC;QAC3B,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC;KAC9B,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,mBAAmB,CACtC;QACE,gBAAgB;QAChB,eAAe,EAAE,CAAC,CAAC,SAAS,IAAI,CAAC;QACjC,gBAAgB,EAAE,CAAC,CAAC,UAAU,IAAI,CAAC;QACnC,oBAAoB,EAAE,CAAC;QACvB,YAAY,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC;KAC5B,EACD,OAAO,CACR,CAAC;IACF,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,CAAC;AAC5C,CAAC"}

package/dist/core/runtime.d.ts

@@ -0,0 +1,9 @@
+import type { AgentCoreRuntimeDeps } from "../internal/harness.js";
+import type { Brain } from "./types.js";
+/**
+ * Build the agent-core runtime dependency object from a Brain.
+ * `completeSimple` (used by compaction/summarization) is derived from `stream`
+ * when the brain does not provide one explicitly.
+ */
+export declare function brainToRuntime(brain: Brain): AgentCoreRuntimeDeps;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/core/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/core/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAMnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,oBAAoB,CAejE"}

package/dist/core/runtime.js

@@ -0,0 +1,17 @@
+/**
+ * Build the agent-core runtime dependency object from a Brain.
+ * `completeSimple` (used by compaction/summarization) is derived from `stream`
+ * when the brain does not provide one explicitly.
+ */
+export function brainToRuntime(brain) {
+    const completeSimple = brain.complete ??
+        (async (model, context, options) => {
+            const stream = await brain.stream(model, context, options);
+            return stream.result();
+        });
+    return {
+        streamSimple: brain.stream,
+        completeSimple,
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/core/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/core/runtime.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAY;IACzC,MAAM,cAAc,GACjB,KAAK,CAAC,QAA+D;QACtE,CAAC,KAAK,EACJ,KAAK,EACL,OAAmD,EACnD,OAA6B,EACF,EAAE;YAC7B,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,OAAkB,EAAE,OAAO,CAAC,CAAC;YACtE,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;IACL,OAAO;QACL,YAAY,EAAE,KAAK,CAAC,MAAM;QAC1B,cAAc;KACf,CAAC;AACJ,CAAC"}

package/dist/core/safety-axis-vocab.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `SAFETY_AXIS_VOCABULARY` — the PUBLISHED safety-axis vocabulary as a zero-logic, zero-runtime-dependency DATA
+ * artifact (pure string / number / boolean literal constants).
+ *
+ * **design/99 center control-plane seam (channel [281], 2026-06-27).** The sema-registry control plane's per-field
+ * safety-classification table lives in `@sema-ai/registry-core` and, for every safety-critical config field, cites a
+ * core axis VALUE (e.g. `effect: "write"`, `irreversibility: "always"`). That contract package **must not depend on
+ * `@sema-ai/core` (the engine) at runtime** — so it dev-imports THIS const (test-only) and runs a conformance test
+ * asserting every `coreAxis` string it ships is a legal value here, failing CI if core ever drops / renames one.
+ *
+ * Anti-drift discipline (mirrors {@link import("./safety-merge-corpus.js").SAFETY_MERGE_CONFORMANCE_CORPUS}, design/87):
+ * the arrays are pinned to the engine's safety-axis source unions; `test/safety-axis-vocab.test.ts` regression-tests
+ * them in lockstep with the engine version, and the `_AssertEqual` below fails `tsc` if `toolEffect` drifts from the
+ * {@link ToolEffect} union (either direction). The const carries NO logic and imports NO runtime value — the emitted
+ * JS is pure data, so a consumer can `JSON`-shaped-read it without pulling any engine code.
+ */
+export declare const SAFETY_AXIS_VOCABULARY: {
+    /** `ToolSpec.effect` — the data-flow effect class ({@link ToolEffect}, types.ts:74). */
+    readonly toolEffect: readonly ["read", "write", "idempotent"];
+    /** `ToolSpec.egress` — marks an external write (push / open PR / send a message). */
+    readonly egress: readonly [true, false];
+    /** `ToolSpec.irreversibility` — reversibility class (types.ts:128; the `toolAxes` record uses the {never,always} subset). */
+    readonly irreversibility: readonly ["never", "maybe", "always"];
+    /** `SafetyAxis` keys — which axes a gated call trips, for the escalation inbox (checkpoint-store.ts). */
+    readonly safetyAxis: readonly ["egress", "irreversible", "shell"];
+    /** `RiskDescriptor.severity` — ToolEmu-style tier (5 = most severe), the inbox triage key (checkpoint-store.ts:85). */
+    readonly severity: readonly [1, 2, 3, 4, 5];
+    /** `TaskSpec.shellGate` — deployment shell-command gate rank, `off` < `classify` < `always` (types.ts:632). */
+    readonly shellGate: readonly ["off", "classify", "always"];
+    /** `ToolPolicy` decision — per-tool adjudication; `deny` short-circuits the `deny > ask > allow` fold (tool-policy.ts). */
+    readonly permissionDecision: readonly ["allow", "ask", "deny"];
+};
+//# sourceMappingURL=safety-axis-vocab.d.ts.map

package/dist/core/safety-axis-vocab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-axis-vocab.d.ts","sourceRoot":"","sources":["../../src/core/safety-axis-vocab.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB;IACjC,wFAAwF;;IAExF,qFAAqF;;IAErF,6HAA6H;;IAE7H,yGAAyG;;IAEzG,uHAAuH;;IAEvH,+GAA+G;;IAE/G,2HAA2H;;CAEnH,CAAC"}

package/dist/core/safety-axis-vocab.js

@@ -0,0 +1,35 @@
+/**
+ * `SAFETY_AXIS_VOCABULARY` — the PUBLISHED safety-axis vocabulary as a zero-logic, zero-runtime-dependency DATA
+ * artifact (pure string / number / boolean literal constants).
+ *
+ * **design/99 center control-plane seam (channel [281], 2026-06-27).** The sema-registry control plane's per-field
+ * safety-classification table lives in `@sema-ai/registry-core` and, for every safety-critical config field, cites a
+ * core axis VALUE (e.g. `effect: "write"`, `irreversibility: "always"`). That contract package **must not depend on
+ * `@sema-ai/core` (the engine) at runtime** — so it dev-imports THIS const (test-only) and runs a conformance test
+ * asserting every `coreAxis` string it ships is a legal value here, failing CI if core ever drops / renames one.
+ *
+ * Anti-drift discipline (mirrors {@link import("./safety-merge-corpus.js").SAFETY_MERGE_CONFORMANCE_CORPUS}, design/87):
+ * the arrays are pinned to the engine's safety-axis source unions; `test/safety-axis-vocab.test.ts` regression-tests
+ * them in lockstep with the engine version, and the `_AssertEqual` below fails `tsc` if `toolEffect` drifts from the
+ * {@link ToolEffect} union (either direction). The const carries NO logic and imports NO runtime value — the emitted
+ * JS is pure data, so a consumer can `JSON`-shaped-read it without pulling any engine code.
+ */
+export const SAFETY_AXIS_VOCABULARY = {
+    /** `ToolSpec.effect` — the data-flow effect class ({@link ToolEffect}, types.ts:74). */
+    toolEffect: ["read", "write", "idempotent"],
+    /** `ToolSpec.egress` — marks an external write (push / open PR / send a message). */
+    egress: [true, false],
+    /** `ToolSpec.irreversibility` — reversibility class (types.ts:128; the `toolAxes` record uses the {never,always} subset). */
+    irreversibility: ["never", "maybe", "always"],
+    /** `SafetyAxis` keys — which axes a gated call trips, for the escalation inbox (checkpoint-store.ts). */
+    safetyAxis: ["egress", "irreversible", "shell"],
+    /** `RiskDescriptor.severity` — ToolEmu-style tier (5 = most severe), the inbox triage key (checkpoint-store.ts:85). */
+    severity: [1, 2, 3, 4, 5],
+    /** `TaskSpec.shellGate` — deployment shell-command gate rank, `off` < `classify` < `always` (types.ts:632). */
+    shellGate: ["off", "classify", "always"],
+    /** `ToolPolicy` decision — per-tool adjudication; `deny` short-circuits the `deny > ask > allow` fold (tool-policy.ts). */
+    permissionDecision: ["allow", "ask", "deny"],
+};
+const _toolEffectExhaustive = true;
+void _toolEffectExhaustive;
+//# sourceMappingURL=safety-axis-vocab.js.map

package/dist/core/safety-axis-vocab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-axis-vocab.js","sourceRoot":"","sources":["../../src/core/safety-axis-vocab.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,wFAAwF;IACxF,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC;IAC3C,qFAAqF;IACrF,MAAM,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,6HAA6H;IAC7H,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC;IAC7C,yGAAyG;IACzG,UAAU,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC;IAC/C,uHAAuH;IACvH,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACzB,+GAA+G;IAC/G,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,CAAC;IACxC,2HAA2H;IAC3H,kBAAkB,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;CACpC,CAAC;AAMX,MAAM,qBAAqB,GAAiF,IAAI,CAAC;AACjH,KAAK,qBAAqB,CAAC"}

package/dist/core/safety-merge-corpus.d.ts

@@ -0,0 +1,48 @@
+import type { SessionPermissionRules } from "./session-policy-store.js";
+/**
+ * design/99 (sema-registry center control-plane seam, channel review R2): the PUBLISHED golden conformance corpus
+ * for the safety-domain MERGE predicate {@link loosenReasons}.
+ *
+ * THE SEAM. The center control-plane's ConfigBundle merger is a DISPATCHER: for any field it classifies
+ * safety-critical (the permissions / tool-policy domain), it MUST delegate the org-published-vs-workspace-override
+ * decision to core's {@link loosenReasons} (NOT re-implement "deny>allow" — a forked safety law is the exact
+ * "mixed = security incident" failure). Core owns the safety SEMANTICS; center owns the bundle merger that calls it.
+ *
+ * THIS CORPUS is the anti-drift anchor between the two codebases (the design/87 gold-corpus discipline):
+ *  - CORE runs it as a regression test (`test/safety-merge-corpus.test.ts`) — every vector's `reasons` MUST equal
+ *    `loosenReasons(prior, next)`. If core ever changes the loosen law, this test fails and the corpus updates in
+ *    lockstep with the engine version, so the published contract can never silently drift from the implementation.
+ *  - The CENTER imports this corpus from `@sema-ai/core` and runs it as a CONTRACT test in its merger CI: for each
+ *    vector, its merger's accept/reject of a non-operator workspace override on the permissions domain MUST match
+ *    `loosens` (reject iff `loosens`). That proves center's dispatcher actually routes through core's predicate.
+ *
+ * Invariant under test: a workspace override that LOOSENS an org-published safety rule (removes a deny, widens an
+ * allowlist, removes/widens a path confinement) is a tighten-only violation — `loosens === true`, and a
+ * non-operator write of it MUST be rejected. A pure tighten / no-op is `loosens === false`.
+ */
+export interface SafetyMergeVector {
+    /** Stable case id (appears in test output + the published contract). */
+    name: string;
+    /** What this vector proves. */
+    intent: string;
+    /** The org-published baseline (the lower, authoritative layer). */
+    prior: SessionPermissionRules;
+    /** The proposed workspace-override (the upper layer being merged down). */
+    next: SessionPermissionRules;
+    /** Whether `next` LOOSENS `prior` — true ⇒ a non-operator merge of this override MUST be rejected. */
+    loosens: boolean;
+    /** The EXACT reasons {@link loosenReasons}(prior, next) returns (compared order-insensitively). Empty iff
+     *  `loosens` is false. Pinned so CORE's regression test catches a change in the loosen SEMANTICS, not just the
+     *  boolean. ⚠️ CENTER CONTRACT: depend ONLY on `loosens` (reject-iff-loosens) — `reasons` is core's internal
+     *  message wording, anti-drift for core; a center CI that asserts on `reasons` would break on a core reword. On
+     *  ACCEPT (`loosens === false`) the resolved safety-domain value is `next` (the tightened override applied). */
+    reasons: string[];
+}
+/**
+ * The published vectors. Covers every loosen path in {@link loosenReasons} (deny removal, allowlist widen, allowlist
+ * removal = all-allowed, path-confinement removal, path widen, and a multi-axis loosen) plus the tighten / safe /
+ * no-op cases (adding a deny, narrowing an allowlist, narrowing-to-a-subdir, adding confinement from none, identical,
+ * empty). Extend it as the safety domain grows — both core and center re-run it.
+ */
+export declare const SAFETY_MERGE_CONFORMANCE_CORPUS: readonly SafetyMergeVector[];
+//# sourceMappingURL=safety-merge-corpus.d.ts.map

package/dist/core/safety-merge-corpus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-merge-corpus.d.ts","sourceRoot":"","sources":["../../src/core/safety-merge-corpus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,KAAK,EAAE,sBAAsB,CAAC;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,sBAAsB,CAAC;IAC7B,sGAAsG;IACtG,OAAO,EAAE,OAAO,CAAC;IACjB;;;;oHAIgH;IAChH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,iBAAiB,EAmMvE,CAAC"}

package/dist/core/safety-merge-corpus.js

@@ -0,0 +1,203 @@
+/**
+ * The published vectors. Covers every loosen path in {@link loosenReasons} (deny removal, allowlist widen, allowlist
+ * removal = all-allowed, path-confinement removal, path widen, and a multi-axis loosen) plus the tighten / safe /
+ * no-op cases (adding a deny, narrowing an allowlist, narrowing-to-a-subdir, adding confinement from none, identical,
+ * empty). Extend it as the safety domain grows — both core and center re-run it.
+ */
+export const SAFETY_MERGE_CONFORMANCE_CORPUS = [
+    // ── LOOSEN (a non-operator override MUST be rejected) ──────────────────────────────────────────────
+    {
+        name: "deny-removed",
+        intent: "removing an org-published toolDeny loosens (the tool becomes usable again)",
+        prior: { toolDeny: ["Bash"] },
+        next: {},
+        loosens: true,
+        reasons: ['removed toolDeny "Bash"'],
+    },
+    {
+        name: "command-deny-removed",
+        intent: "removing a commandDeny loosens",
+        prior: { commandDeny: ["rm -rf"] },
+        next: { commandDeny: [] },
+        loosens: true,
+        reasons: ['removed commandDeny "rm -rf"'],
+    },
+    {
+        name: "toolAllow-removed-all-allowed",
+        intent: "dropping an allowlist entirely = all-allowed = the maximal loosen",
+        prior: { toolAllow: ["Read"] },
+        next: {},
+        loosens: true,
+        reasons: ["removed toolAllow allowlist (all allowed)"],
+    },
+    {
+        name: "toolAllow-widened",
+        intent: "adding a tool outside the org allowlist loosens",
+        prior: { toolAllow: ["Read"] },
+        next: { toolAllow: ["Read", "Bash"] },
+        loosens: true,
+        reasons: ['widened toolAllow with "Bash"'],
+    },
+    {
+        name: "commandAllow-widened",
+        intent: "adding a command outside the org command allowlist loosens",
+        prior: { commandAllow: ["ls"] },
+        next: { commandAllow: ["ls", "curl"] },
+        loosens: true,
+        reasons: ['widened commandAllow with "curl"'],
+    },
+    {
+        name: "allowDirs-confinement-removed",
+        intent: "removing path confinement (next has none) loosens to the whole filesystem",
+        prior: { allowDirs: ["/repo"] },
+        next: {},
+        loosens: true,
+        reasons: ["removed allowDirs confinement"],
+    },
+    {
+        name: "allowDirs-widened-outside",
+        intent: "adding a dir not lexically within any org dir loosens",
+        prior: { allowDirs: ["/repo"] },
+        next: { allowDirs: ["/repo", "/etc"] },
+        loosens: true,
+        reasons: ['widened allowDirs with "/etc"'],
+    },
+    {
+        name: "multi-axis-loosen",
+        intent: "a single override can loosen on multiple axes — all reasons surface",
+        prior: { toolDeny: ["Bash"], allowDirs: ["/repo"] },
+        next: { allowDirs: ["/repo", "/x"] },
+        loosens: true,
+        reasons: ['removed toolDeny "Bash"', 'widened allowDirs with "/x"'],
+    },
+    {
+        name: "commandAllow-removed-all-allowed",
+        intent: "dropping the COMMAND allowlist (distinct field from toolAllow) re-permits every command — the max loosen on the command axis (review: this branch was unpinned)",
+        prior: { commandAllow: ["ls"] },
+        next: {},
+        loosens: true,
+        reasons: ["removed commandAllow allowlist (all allowed)"],
+    },
+    {
+        name: "allowDirs-confinement-removed-empty-array",
+        intent: "an EXPLICIT empty allowDirs [] removes confinement exactly like undefined (loosenReasons branches on .length===0) — center must treat [] and absent identically",
+        prior: { allowDirs: ["/repo"] },
+        next: { allowDirs: [] },
+        loosens: true,
+        reasons: ["removed allowDirs confinement"],
+    },
+    {
+        name: "allowDirs-prefix-not-boundary-loosen",
+        intent: "🔴 the classic path bug: /repository is NOT within /repo (containment is BOUNDARY-aware, not naive startsWith) → this LOOSENS; a forked center predicate using startsWith would wrongly accept it",
+        prior: { allowDirs: ["/repo"] },
+        next: { allowDirs: ["/repository"] },
+        loosens: true,
+        reasons: ['widened allowDirs with "/repository"'],
+    },
+    {
+        name: "allowDirs-relative-dir-loosen",
+        intent: "a relative dir is not within an absolute org dir → loosens (loosenReasons compares RAW inputs; normalization is the store's job, not the predicate's)",
+        prior: { allowDirs: ["/repo"] },
+        next: { allowDirs: ["repo"] },
+        loosens: true,
+        reasons: ['widened allowDirs with "repo"'],
+    },
+    {
+        name: "multi-entry-deny-removed",
+        intent: "removing multiple deny entries in one override emits one reason PER entry — pins that center must ACCUMULATE reasons, not short-circuit on the first",
+        prior: { toolDeny: ["A", "B", "C"] },
+        next: { toolDeny: ["B"] },
+        loosens: true,
+        reasons: ['removed toolDeny "A"', 'removed toolDeny "C"'],
+    },
+    // ── TIGHTEN / SAFE / NO-OP (the override may merge without operator authority) ──────────────────────
+    {
+        name: "deny-added",
+        intent: "adding a deny only tightens",
+        prior: {},
+        next: { toolDeny: ["Bash"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "toolAllow-narrowed",
+        intent: "removing an entry from an allowlist only tightens",
+        prior: { toolAllow: ["Read", "Bash"] },
+        next: { toolAllow: ["Read"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "allowlist-added-from-all",
+        intent: "introducing an allowlist where there was none narrows from all-allowed (safe)",
+        prior: {},
+        next: { toolAllow: ["Read"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "allowDirs-narrowed-to-subdir",
+        intent: "narrowing confinement to a subdir within the org dir is safe",
+        prior: { allowDirs: ["/repo"] },
+        next: { allowDirs: ["/repo/src"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "allowDirs-added-confinement",
+        intent: "adding confinement where there was none (org had no allowDirs) only tightens",
+        prior: {},
+        next: { allowDirs: ["/repo"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "identical-noop",
+        intent: "an identical override is a no-op (safe)",
+        prior: { toolDeny: ["Bash"], allowDirs: ["/repo"] },
+        next: { toolDeny: ["Bash"], allowDirs: ["/repo"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "empty-empty",
+        intent: "no rules either side is safe",
+        prior: {},
+        next: {},
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "allowDirs-prior-empty-array-safe",
+        intent: "an org-published EMPTY allowDirs [] imposes NO confinement (the .length>0 guard is false), so widening it is genuinely not a loosen — center must not treat [] as a confinement",
+        prior: { allowDirs: [] },
+        next: { allowDirs: ["/etc"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "allowDirs-trailing-slash-safe",
+        intent: "/repo/ is within /repo (trailing-slash boundary normalization in lexWithin) → safe",
+        prior: { allowDirs: ["/repo"] },
+        next: { allowDirs: ["/repo/"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "allowDirs-root-prior-safe",
+        intent: "an org dir of '/' contains everything (root special-case) → any narrower next is safe",
+        prior: { allowDirs: ["/"] },
+        next: { allowDirs: ["/anything"] },
+        loosens: false,
+        reasons: [],
+    },
+    {
+        name: "commandAllow-added-from-all",
+        intent: "introducing a command allowlist where there was none narrows from all-allowed (per-field symmetry with toolAllow)",
+        prior: {},
+        next: { commandAllow: ["ls"] },
+        loosens: false,
+        reasons: [],
+    },
+];
+//# sourceMappingURL=safety-merge-corpus.js.map

package/dist/core/safety-merge-corpus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-merge-corpus.js","sourceRoot":"","sources":["../../src/core/safety-merge-corpus.ts"],"names":[],"mappings":"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"}

package/dist/core/scheduler.d.ts

@@ -0,0 +1,126 @@
+/**
+ * design/105 — Scheduler seam（自唤醒/自调度）。「手」腿（`ExecutionEnv`）的**跨-task** 未来意图能力：一个 run 里的模型
+ * 把「未来要做的活」（cron 排程 / 延迟唤醒）持久化交给一个**常驻 backend**（TOC = shell daemon），由它在未来重起一个
+ * **新** task。
+ *
+ * 🔴 与 {@link import("./background-shell.js").BackgroundShellCapability} 的根本区别（design/105 §3.1 D1）：
+ * background-shell 的进程 ⊆ task（在每条退出路径 dispose，不跨 suspend）；scheduler 的意图必须 **SURVIVE task 结束**
+ * （schedule 的全部意义就是当前 task 结束后 daemon 还能重起）——镜像反转，**绝不 dispose-on-exit**。
+ *
+ * core 薄壳裁定：core 只出接口 + 工具壳 + `hasScheduler` 门控；**持久化存储 / cron 时钟 / idle 触发 / 起新 task 全在
+ * backend（daemon）**——core 是 request-driven 不常驻，绝不假装调度器。NodeExecutionEnv 不自带 daemon（不同于
+ * background-shell 自带 spawn），而是**委托一个注入的 backend**（飞轮的 shell daemon 实现本接口）。
+ */
+import type { ExecutionEnv, Result } from "../internal/harness.js";
+/** 一个已排未来意图的句柄。**backend-local、durable（daemon 持久化、重启存活）、对调用方不透明** —— 绝不暴露可枚举的 raw id。 */
+export type ScheduledTaskId = string & {
+    readonly __brand: "ScheduledTaskId";
+};
+/**
+ * 类型化错误码（对齐 background-shell 风格）。方法 MUST NOT throw（返回 {@link Result}）。
+ */
+export type SchedulerErrorCode = "unsupported" | "not_found" | "limit_exceeded" | "invalid_schedule" | "io";
+/** scheduler 操作的类型化错误。`code` 给程序分类，`message` 给模型自纠。 */
+export declare class SchedulerError extends Error {
+    readonly code: SchedulerErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: SchedulerErrorCode, message: string, cause?: unknown | undefined);
+}
+/**
+ * 🔴 **模型可控面（不可信）**：纯意图，**无任何身份字段** —— 防模型经自排 prompt 提权（design/62 同款红线：身份是
+ * Runner-held，非工具参数）。`prompt` = 未来 task 的不可信 `objective`（daemon 起 task 时经完整 prepare-task gate）。
+ */
+export interface ScheduledIntent {
+    /** 未来要跑的 prompt（agent 自排）。daemon 起新 task 时作 `objective`。 */
+    prompt: string;
+    /** 何时触发。`cron`=重复（受 minCronIntervalSec 约束）；`at`=一次性绝对时刻；`delay`=相对延迟（一次性 self re-wake 用）。 */
+    when: {
+        kind: "cron";
+        expr: string;
+    } | {
+        kind: "at";
+        atMs: number;
+    } | {
+        kind: "delay";
+        delaySec: number;
+    };
+    /** 可选短标签；与 `(scope, when)` 一起做 upsert 去重键（防工具重试产生重复 intent）。 */
+    label?: string;
+    /**
+     * 执行形态（CC ScheduleWakeup 对齐批 2026-07-11；缺省 `"task"` = 既有行为，全向后兼容）。
+     * - `"task"`：daemon 起一个**无上下文新 task**（`prompt` 作 objective，经完整 prepare-task gate）——CronCreate 语义。
+     * - `"session-wakeup"`：daemon **续 `ctx.sessionId` 指定的同一会话**（`prompt` 作该会话下一轮输入；同上下文、
+     *   同 prompt cache）——CC ScheduleWakeup 的 /loop dynamic 语义。🔴 契约：`mode:"session-wakeup"` 的 intent
+     *   MUST 随一个带 `sessionId` 的 {@link SchedulerContext} 排入（工具壳保证）；daemon 触发时 MUST resume 该
+     *   session 而非起新 task，且 principal 原样（不升权）。不支持续会话的 daemon MUST 拒（`invalid_schedule`），
+     *   绝不静默降级成新 task（丢上下文=静默换语义）。
+     */
+    mode?: "task" | "session-wakeup";
+}
+/**
+ * 🔴 **Runner-held 可信面**（工具工厂闭包捕获，模型无法触及）。镜像 subagent 经 `ctx.principal` 继承的代码层强制
+ * （`agents/subagent.ts`）。`schedule` 的实现 MUST 把 `principal` 钉死进持久化 intent；daemon 触发时原样传
+ * `runTask({ principal })` —— **不升权、不省略**。
+ */
+export interface SchedulerContext {
+    /** 越权隔离键（cancel/list 只能操作同 scope 排的）。由 Runner 填（sessionId ?? principal ?? taskId）。 */
+    scope: string;
+    /** 排程者身份；daemon 触发时原样传给 runTask（防提权）。 */
+    principal?: string;
+    /** 可选：daemon 触发新 task 时复用的 session（chat-continuity；缺省=fresh-session）。⚠️ 复用需 durable sessionStore（design/105 §3.4）。 */
+    sessionId?: string;
+    /**
+     * 可选 opaque 起-task 配置（model/policy 提示）。v1 daemon 可忽略、用部署默认模板起 task（intent.prompt + 继承的
+     * principal 已足）；未来精细化时由 daemon 解释。core 不定其 schema（最薄）。**不可由模型提供**（Runner-held）。
+     */
+    taskConfig?: unknown;
+}
+/** {@link SchedulerCapability.list} 的条目：足够 self-discovery + 防重复排，不含完整意图。 */
+export interface ScheduledTaskSummary {
+    id: ScheduledTaskId;
+    /** 渲染用：cron expr / at 时刻 / delay 秒 的人读摘要。 */
+    when: string;
+    label?: string;
+    /** 下次触发的 epoch ms（cron/at 可算；daemon 提供）。 */
+    nextRunMs?: number;
+    /** 执行形态回显（{@link ScheduledIntent.mode}）。ScheduleWakeup 的 stop:true 靠它定位要取消的 pending
+     *  wakeup（cron/task 意图不受 stop 影响——CC 206 D9 语义）。老 backend 不回 = undefined（工具壳以
+     *  label 兜底过滤）。 */
+    mode?: "task" | "session-wakeup";
+}
+/**
+ * 「手」腿的跨-task 调度能力。一个具体 `ExecutionEnv` 可选附加它（交叉类型），经 {@link hasScheduler} 检测。不支持的
+ * env（无注入 daemon backend）= `schedulerCapabilities.supported=false`，四个 scheduler 工具自动不挂（INERT）。
+ */
+export interface SchedulerCapability {
+    /** 显式声明能力（像 background-shell 一样不猜）。`supported:false` → 工具不挂（design/105 §3.9 TOB / 无 daemon）。 */
+    readonly schedulerCapabilities: {
+        readonly supported: boolean;
+        /** 单 scope 存量 intent 上限（防自排炸弹；超限 `limit_exceeded`）。 */
+        readonly maxScheduledPerScope: number;
+        /** delay/at 最小延迟秒（防 busy 自醒）。 */
+        readonly minDelaySec: number;
+        /** cron 解析后实际触发间隔下限秒（`* * * * *` 占 1 slot 但无限触发 → 须有下限）。 */
+        readonly minCronIntervalSec: number;
+        /** 最远排程地平线秒（fail-closed 有界，绝不无限未来）。 */
+        readonly maxScheduledHorizonSec: number;
+    };
+    /**
+     * 持久化一个未来意图。`intent` = 模型可控（无身份）；`ctx` = Runner-held 可信上下文（principal/scope/...）。返回不透明
+     * 句柄。🔴 实现 MUST 把 `ctx.principal` 钉死进持久化 intent（daemon 触发原样传 runTask，不升权）；MUST 用 cron 库
+     * 解析 `when.expr` **禁 shell-exec**（RCE 红线）；MUST 持久化（durable，daemon 重启存活）。upsert：同 `(scope, when, label)` 覆盖（幂等）。
+     */
+    schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{
+        id: ScheduledTaskId;
+    }, SchedulerError>>;
+    /** 取消一个已排意图（幂等：取消不存在的是 ok no-op）。🔴 越权：`id` MUST 属本 scope；非本 scope 一律 `not_found`，不泄露存在性。 */
+    cancel(id: ScheduledTaskId, ctx: SchedulerContext): Promise<Result<void, SchedulerError>>;
+    /** 列**本 scope** 已排意图（self-discovery + 防重复排）。范围 = `ctx.scope`，非全局。 */
+    list(ctx: SchedulerContext): Promise<Result<ScheduledTaskSummary[], SchedulerError>>;
+}
+/**
+ * 结构 + 语义检测：`env` 是否暴露 scheduler 能力且声明 `supported:true`。挂载门控用此（对齐 `hasBackgroundShell`）。
+ */
+export declare function hasScheduler(env: ExecutionEnv): env is ExecutionEnv & SchedulerCapability;
+export declare function isValidCronExpr(expr: string): boolean;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/core/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/core/scheduler.ts"],"names":[],"mappings":"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"}