@sema-agent/core 1.279.0

package/dist/core/permission-rules.d.ts

@@ -0,0 +1,35 @@
+import type { ToolPolicy } from "./tool-policy.js";
+export declare const BASH_GENERIC_PARAMS: ReadonlySet<string>;
+export interface PermissionRule {
+    rule: string;
+    behavior: "deny" | "ask" | "allow";
+    source?: string;
+}
+export interface ParsedPermissionRule {
+    toolName: string;
+    ruleContent?: string;
+}
+export interface PermissionRuleIssue {
+    rule: string;
+    code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.allow_param_rule" | "invalid.primary_field" | "invalid.cap_exceeded" | "unsupported.bash_prefix" | "unsupported.file_glob" | "unsupported.mcp_paren";
+    message: string;
+}
+export interface PermissionRuleCaps {
+    maxRules: number;
+    maxRuleLength: number;
+    maxPatternLength: number;
+    maxStars: number;
+    maxScalarValueChars: number;
+}
+export interface PermissionRulePolicyOptions {
+    onInvalidRule?: "throw" | "skip";
+    onIssue?: (issue: PermissionRuleIssue) => void;
+    defaultAction?: "allow" | "ask" | "deny";
+    primaryFieldGeneric?: "reject" | "allow-lexical";
+    caps?: Partial<PermissionRuleCaps>;
+}
+export declare function parsePermissionRule(rule: string): ParsedPermissionRule;
+export declare function wildcardMatch(pattern: string, value: string): boolean;
+export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps">): PermissionRuleIssue[];
+export declare function createPermissionRulePolicy(rules: PermissionRule[], opts?: PermissionRulePolicyOptions): ToolPolicy;
+//# sourceMappingURL=permission-rules.d.ts.map

package/dist/core/permission-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-rules.d.ts","sourceRoot":"","sources":["../../src/core/permission-rules.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAqC,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAOtF,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAAuE,CAAC;AAM5H,MAAM,WAAW,cAAc;IAE7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;IAGnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IAGb,IAAI,EACA,oBAAoB,GACpB,eAAe,GACf,qBAAqB,GACrB,0BAA0B,GAC1B,uBAAuB,GACvB,sBAAsB,GACtB,yBAAyB,GACzB,uBAAuB,GACvB,uBAAuB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IAIjB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAUD,MAAM,WAAW,2BAA2B;IAK1C,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAGjC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAI/C,aAAa,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IAGzC,mBAAmB,CAAC,EAAE,QAAQ,GAAG,eAAe,CAAC;IACjD,IAAI,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACpC;AAsCD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAWtE;AAWD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAqBrE;AAkKD,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EAAE,EACvB,IAAI,CAAC,EAAE,IAAI,CAAC,2BAA2B,EAAE,qBAAqB,GAAG,MAAM,CAAC,GACvE,mBAAmB,EAAE,CAGvB;AA8CD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,IAAI,CAAC,EAAE,2BAA2B,GAAG,UAAU,CA4DlH"}

package/dist/core/permission-rules.js

@@ -0,0 +1,270 @@
+import { canonicalToolName } from "./tool-name-aliases.js";
+export const BASH_GENERIC_PARAMS = new Set(["command", "timeout", "description", "run_in_background"]);
+const DEFAULT_CAPS = {
+    maxRules: 256,
+    maxRuleLength: 512,
+    maxPatternLength: 256,
+    maxStars: 16,
+    maxScalarValueChars: 16_384,
+};
+function indexOfUnescaped(s, ch) {
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] !== ch)
+            continue;
+        let backslashes = 0;
+        for (let j = i - 1; j >= 0 && s[j] === "\\"; j--)
+            backslashes++;
+        if (backslashes % 2 === 0)
+            return i;
+    }
+    return -1;
+}
+function lastIndexOfUnescaped(s, ch) {
+    for (let i = s.length - 1; i >= 0; i--) {
+        if (s[i] !== ch)
+            continue;
+        let backslashes = 0;
+        for (let j = i - 1; j >= 0 && s[j] === "\\"; j--)
+            backslashes++;
+        if (backslashes % 2 === 0)
+            return i;
+    }
+    return -1;
+}
+function unescapeRuleContent(s) {
+    return s.replaceAll("\\(", "(").replaceAll("\\)", ")").replaceAll("\\\\", "\\");
+}
+export function parsePermissionRule(rule) {
+    const open = indexOfUnescaped(rule, "(");
+    if (open === -1)
+        return { toolName: rule.trim() };
+    const close = lastIndexOfUnescaped(rule, ")");
+    if (close === -1 || close <= open)
+        return { toolName: rule.trim() };
+    if (close !== rule.length - 1)
+        return { toolName: rule.trim() };
+    const name = rule.substring(0, open);
+    const content = rule.substring(open + 1, close);
+    if (!name)
+        return { toolName: rule.trim() };
+    if (content === "" || content === "*")
+        return { toolName: name.trim() };
+    return { toolName: name.trim(), ruleContent: unescapeRuleContent(content) };
+}
+export function wildcardMatch(pattern, value) {
+    let p = 0;
+    let v = 0;
+    let star = -1;
+    let mark = 0;
+    while (v < value.length) {
+        if (p < pattern.length && pattern[p] === value[v] && pattern[p] !== "*") {
+            p++;
+            v++;
+        }
+        else if (p < pattern.length && pattern[p] === "*") {
+            star = p++;
+            mark = v;
+        }
+        else if (star >= 0) {
+            p = star + 1;
+            v = ++mark;
+        }
+        else {
+            return false;
+        }
+    }
+    while (p < pattern.length && pattern[p] === "*")
+        p++;
+    return p === pattern.length;
+}
+const PRIMARY_FIELDS = {
+    Bash: new Set(["command"]),
+    Read: new Set(["file_path", "path"]),
+    Edit: new Set(["file_path", "path"]),
+    Write: new Set(["file_path", "path"]),
+    MultiEdit: new Set(["file_path", "path"]),
+    NotebookEdit: new Set(["notebook_path", "path"]),
+    Grep: new Set(["path"]),
+    Glob: new Set(["path"]),
+    WebFetch: new Set(["url"]),
+    WebSearch: new Set(["query"]),
+};
+const FILE_TOOLS = new Set(["Read", "Edit", "Write", "MultiEdit", "NotebookEdit", "Grep", "Glob"]);
+function countStars(s) {
+    let n = 0;
+    for (const c of s)
+        if (c === "*")
+            n++;
+    return n;
+}
+function compile(rules, caps, primaryFieldGeneric) {
+    const byTool = new Map();
+    const issues = [];
+    const bad = (rule, code, message) => {
+        issues.push({ rule, code, message });
+    };
+    if (rules.length > caps.maxRules) {
+        return { byTool, issues: [{ rule: "", code: "invalid.cap_exceeded", message: `${rules.length} rules > maxRules ${caps.maxRules}` }] };
+    }
+    for (const r of rules) {
+        const text = r.rule;
+        if (text.length > caps.maxRuleLength) {
+            bad(text, "invalid.cap_exceeded", `rule longer than ${caps.maxRuleLength} chars`);
+            continue;
+        }
+        const parsed = parsePermissionRule(text);
+        if (!parsed.toolName) {
+            bad(text, "invalid.empty_tool", "tool name cannot be empty");
+            continue;
+        }
+        if (parsed.ruleContent === undefined && /[()\\]/.test(parsed.toolName)) {
+            bad(text, "invalid.paren", "tool name still contains paren/escape characters — a mis-escaped rule would compile to a dead bare rule");
+            continue;
+        }
+        if (parsed.ruleContent === undefined && indexOfUnescaped(text, "(") !== -1) {
+            const open = indexOfUnescaped(text, "(");
+            const close = lastIndexOfUnescaped(text, ")");
+            const legitimateBare = close === text.length - 1 && ["", "*"].includes(text.substring(open + 1, close));
+            if (!legitimateBare) {
+                bad(text, "invalid.paren", "malformed parentheses / trailing characters (would silently downgrade to a bare-tool rule)");
+                continue;
+            }
+        }
+        const toolName = canonicalToolName(parsed.toolName);
+        if (toolName.startsWith("mcp__") && (parsed.ruleContent !== undefined || indexOfUnescaped(text, "(") !== -1)) {
+            bad(text, "unsupported.mcp_paren", "MCP rules do not support patterns in parentheses (CC parity); use the toolAxes system");
+            continue;
+        }
+        const entry = byTool.get(toolName) ?? { bare: {}, param: { deny: [], ask: [] } };
+        if (parsed.ruleContent === undefined) {
+            entry.bare[r.behavior] = { ruleText: text, source: r.source };
+            byTool.set(toolName, entry);
+            continue;
+        }
+        const content = parsed.ruleContent;
+        const colon = content.indexOf(":");
+        if (toolName === "Bash") {
+            const paramPart = colon > 0 ? content.slice(0, colon).trim() : "";
+            const looksLikeParamRule = colon > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(paramPart) && BASH_GENERIC_PARAMS.has(paramPart);
+            if (!looksLikeParamRule || content.endsWith(":*")) {
+                bad(text, "unsupported.bash_prefix", "Bash prefix/legacy rules (`Bash(npm run:*)`, `Bash(git *)`) are the tool-specific lane — not supported by the generic param DSL (use createCoarseCommandNamePolicy or a dedicated batch)");
+                continue;
+            }
+        }
+        else if (FILE_TOOLS.has(toolName) && colon <= 0) {
+            bad(text, "unsupported.file_glob", "file-tool glob rules (`Edit(src/**)`) are the tool-specific lane — not supported by the generic param DSL");
+            continue;
+        }
+        if (colon <= 0) {
+            bad(text, "invalid.param_split", "param-level ruleContent must be `param:pattern`");
+            continue;
+        }
+        const param = content.slice(0, colon).trim();
+        const pattern = content.slice(colon + 1).trim();
+        if (param === "" || pattern === "") {
+            bad(text, "invalid.param_split", "param and pattern must both be non-empty");
+            continue;
+        }
+        if (r.behavior === "allow") {
+            bad(text, "invalid.allow_param_rule", "param-level rules cannot `allow` (CC parity: the generic lane is deny/ask only; auto-allow comes from bare-tool rules)");
+            continue;
+        }
+        if (pattern.length > caps.maxPatternLength || countStars(pattern) > caps.maxStars) {
+            bad(text, "invalid.cap_exceeded", `pattern exceeds maxPatternLength ${caps.maxPatternLength} or maxStars ${caps.maxStars}`);
+            continue;
+        }
+        if (PRIMARY_FIELDS[toolName]?.has(param) && primaryFieldGeneric === "reject") {
+            bad(text, "invalid.primary_field", `"${param}" is ${toolName}'s primary field — the generic matcher is a trim+FULL-STRING lexical match (no shell/path semantics); '${toolName}(${param}:git push*)' would NOT match 'cd /x && git push'. Opt in with primaryFieldGeneric:"allow-lexical" if you understand this.`);
+            continue;
+        }
+        entry.param[r.behavior].push({ param, pattern, behavior: r.behavior, ruleText: text, source: r.source });
+        byTool.set(toolName, entry);
+    }
+    return { byTool, issues };
+}
+export function validatePermissionRules(rules, opts) {
+    const caps = { ...DEFAULT_CAPS, ...opts?.caps };
+    return compile(rules, caps, opts?.primaryFieldGeneric ?? "reject").issues;
+}
+function isPlainObjectArgs(args) {
+    return typeof args === "object" && args !== null && !Array.isArray(args);
+}
+function matchParamRules(rules, args, maxScalarValueChars) {
+    if (!isPlainObjectArgs(args))
+        return undefined;
+    for (const r of rules) {
+        if (!Object.hasOwn(args, r.param))
+            continue;
+        const raw = args[r.param];
+        if (raw === undefined || raw === null)
+            continue;
+        const t = typeof raw;
+        if (t === "object" || t === "function" || t === "symbol")
+            continue;
+        const value = String(raw).trim();
+        if (value.length > maxScalarValueChars)
+            return r;
+        if (wildcardMatch(r.pattern, value))
+            return r;
+    }
+    return undefined;
+}
+function ruleMessage(kind, ruleText, source) {
+    return `${kind} by permission rule "${ruleText}"${source ? ` (${source})` : ""}`;
+}
+export function createPermissionRulePolicy(rules, opts) {
+    const caps = { ...DEFAULT_CAPS, ...opts?.caps };
+    const { byTool, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject");
+    const setLevelCap = issues.some((i) => i.code === "invalid.cap_exceeded" && i.rule === "");
+    if (issues.length > 0 && ((opts?.onInvalidRule ?? "throw") === "throw" || setLevelCap)) {
+        const e = new Error(`createPermissionRulePolicy: ${issues.length} invalid/unsupported rule(s):\n` +
+            issues.map((i) => `  [${i.code}] ${i.rule || "(rule set)"}: ${i.message}`).join("\n"));
+        e.code = "config.invalid_permission_rules";
+        e.issues = issues;
+        throw e;
+    }
+    if (issues.length > 0) {
+        if (opts?.onIssue) {
+            for (const i of issues) {
+                try {
+                    opts.onIssue(i);
+                }
+                catch {
+                }
+            }
+        }
+        else {
+            console.warn(`createPermissionRulePolicy: skipped ${issues.length} invalid/unsupported rule(s): ` +
+                issues.map((i) => `[${i.code}] ${i.rule}`).join("; "));
+        }
+    }
+    const defaultAction = opts?.defaultAction ?? "allow";
+    return {
+        check(req) {
+            const entry = byTool.get(canonicalToolName(req.toolName));
+            if (entry) {
+                if (entry.bare.deny) {
+                    return { action: "deny", reason: ruleMessage("denied", entry.bare.deny.ruleText, entry.bare.deny.source) };
+                }
+                const paramDeny = matchParamRules(entry.param.deny, req.args, caps.maxScalarValueChars);
+                if (paramDeny) {
+                    return { action: "deny", reason: ruleMessage("denied", paramDeny.ruleText, paramDeny.source) };
+                }
+                if (entry.bare.ask) {
+                    return { action: "ask", reason: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source) };
+                }
+                const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
+                if (paramAsk) {
+                    return { action: "ask", reason: ruleMessage("flagged", paramAsk.ruleText, paramAsk.source) };
+                }
+                if (entry.bare.allow) {
+                    return { action: "allow" };
+                }
+            }
+            if (defaultAction === "allow")
+                return { action: "allow" };
+            return { action: defaultAction, reason: `no permission rule matched "${req.toolName}" (default-${defaultAction} rule set)` };
+        },
+    };
+}
+//# sourceMappingURL=permission-rules.js.map

package/dist/core/permission-rules.js.map

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

package/dist/core/present-plan-tool.d.ts

@@ -0,0 +1,8 @@
+import type { ToolSpec } from "./types.js";
+export declare const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
+export declare const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
+export declare function createEnterPlanModeTool(enterPlanMode: () => void): ToolSpec;
+export declare function createPresentPlanTool(requestReview: (opts?: {
+    reason?: string;
+}) => void): ToolSpec;
+//# sourceMappingURL=present-plan-tool.d.ts.map

package/dist/core/present-plan-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"present-plan-tool.d.ts","sourceRoot":"","sources":["../../src/core/present-plan-tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAK3C,eAAO,MAAM,sBAAsB,iBAAiB,CAAC;AAIrD,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AA0CzD,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,IAAI,GAAG,QAAQ,CAmB3E;AAyBD,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,GAAG,QAAQ,CA8BnG"}

package/dist/core/present-plan-tool.js

@@ -0,0 +1,82 @@
+import { Type } from "typebox";
+import { delimitUntrusted } from "./untrusted-text.js";
+export const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
+export const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
+const ENTER_PLAN_MODE_DESCRIPTION = `Enter PLAN MODE (read-only): stop making changes and switch to exploration/planning. For the rest of this run, write/edit/mutating tool calls are REJECTED 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.
+
+Use this when a task has genuine ambiguity about the right approach and getting human sign-off before acting would prevent significant rework.
+
+## When to Use This Tool
+1. Significant architectural ambiguity: multiple reasonable approaches exist and the choice meaningfully affects the codebase
+   - Example: "Add caching to the API" — Redis vs in-memory vs file-based
+   - Example: "Add real-time updates" — WebSockets vs SSE vs polling
+2. Unclear requirements: you need to explore and clarify before you can make progress
+   - Example: "Make the app faster" — need to profile and identify bottlenecks first
+3. High-impact or destructive restructuring: the work significantly restructures, migrates, or deletes existing code, and buy-in first reduces risk
+   - Example: "Redesign the authentication system"
+
+## When NOT to Use This Tool
+Skip plan mode when you can reasonably infer the right approach:
+- The task is straightforward even if it touches multiple files
+- The user's request is specific enough that the implementation path is clear
+- You're adding a feature with an obvious implementation pattern (e.g. a button, a new endpoint following existing conventions)
+- Bug fixes where the fix is clear once you understand the bug
+- Pure research/exploration tasks — just read; no plan approval is needed
+- The user says something like "can we work on X" or "let's do X" — just get started
+
+When in doubt, prefer starting work and asking the human targeted questions over entering a full planning phase.
+
+## Examples
+GOOD: "Add user authentication to the app" (genuinely ambiguous: session vs JWT, token storage, middleware). "Redesign the data pipeline" (major restructuring where the wrong approach wastes significant effort).
+BAD: "Add a delete button to the user profile" (implementation path is clear; just do it). "Update the error handling in the API" (start working; ask specific questions if needed). "Fix the typo in the README" (straightforward, no planning needed).`;
+export function createEnterPlanModeTool(enterPlanMode) {
+    return {
+        name: ENTER_PLAN_MODE_TOOL_NAME,
+        description: ENTER_PLAN_MODE_DESCRIPTION,
+        parameters: Type.Object({}),
+        effect: "read",
+        executionMode: "sequential",
+        execute: async () => {
+            enterPlanMode();
+            const message = "Entered plan mode (read-only). Write/edit/mutating tools are now rejected for the rest of this run; " +
+                `research with read-only tools, then call ${PRESENT_PLAN_TOOL_NAME} with your plan to get it approved before acting.`;
+            return {
+                content: message,
+                details: { type: "enter-plan-mode", message },
+            };
+        },
+    };
+}
+const PRESENT_PLAN_DESCRIPTION = [
+    "Present your proposed PLAN for human approval BEFORE taking any action (CC plan-mode parity).",
+    "Use this when you are in plan mode (read-only research): once you have explored enough and formed a concrete plan,",
+    "provide the full plan here. The run PAUSES for a human to approve, edit, or reject it.",
+    "IMPORTANT: only use this when the task requires planning the implementation steps of work that changes things;",
+    "for research tasks (gathering information, reading files, understanding the codebase) do NOT use this tool.",
+    "This tool inherently requests approval of your plan — do not separately ask \"Is this plan okay?\".",
+    "Do NOT attempt edits / writes / mutating commands before the plan is approved — present the plan first.",
+    "If the plan is approved, the run continues (and any read-only restriction is lifted) so you can execute it;",
+    "if it is rejected or edited, follow the reviewer's feedback instead of the original plan.",
+].join(" ");
+export function createPresentPlanTool(requestReview) {
+    return {
+        name: PRESENT_PLAN_TOOL_NAME,
+        description: PRESENT_PLAN_DESCRIPTION,
+        parameters: Type.Object({
+            plan: Type.String({
+                description: "Your full proposed plan, in markdown. The human reviewer approves / edits / rejects it before you act.",
+            }),
+        }),
+        effect: "read",
+        execute: async (args) => {
+            const { plan } = args;
+            requestReview({ reason: "ExitPlanMode" });
+            return {
+                content: `Plan presented for human review:\n\n${delimitUntrusted("plan", plan)}\n\n` +
+                    "(The run is pausing for approval — you will continue once the plan is approved, edited, or rejected.)",
+                details: { type: "exit-plan-mode", plan, isAgent: false },
+            };
+        },
+    };
+}
+//# sourceMappingURL=present-plan-tool.js.map

package/dist/core/present-plan-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"present-plan-tool.js","sourceRoot":"","sources":["../../src/core/present-plan-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAIvD,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAc,CAAC;AAIrD,MAAM,CAAC,MAAM,yBAAyB,GAAG,eAAe,CAAC;AAMzD,MAAM,2BAA2B,GAAG,uPAAuP,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;yPA0BxD,CAAC;AAU1P,MAAM,UAAU,uBAAuB,CAAC,aAAyB;IAC/D,OAAO;QACL,IAAI,EAAE,yBAAyB;QAC/B,WAAW,EAAE,2BAA2B;QACxC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,EAAE,MAAM;QACd,aAAa,EAAE,YAAY;QAC3B,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,aAAa,EAAE,CAAC;YAChB,MAAM,OAAO,GACX,sGAAsG;gBACtG,4CAA4C,sBAAsB,mDAAmD,CAAC;YACxH,OAAO;gBACL,OAAO,EAAE,OAAO;gBAEhB,OAAO,EAAE,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE;aAC9C,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAKD,MAAM,wBAAwB,GAAG;IAC/B,+FAA+F;IAC/F,oHAAoH;IACpH,wFAAwF;IACxF,gHAAgH;IAChH,6GAA6G;IAC7G,qGAAqG;IACrG,yGAAyG;IACzG,6GAA6G;IAC7G,2FAA2F;CAC5F,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAUZ,MAAM,UAAU,qBAAqB,CAAC,aAAmD;IACvF,OAAO;QACL,IAAI,EAAE,sBAAsB;QAC5B,WAAW,EAAE,wBAAwB;QACrC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;YACtB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;gBAChB,WAAW,EAAE,wGAAwG;aACtH,CAAC;SACH,CAAC;QACF,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YACtB,MAAM,EAAE,IAAI,EAAE,GAAG,IAAwB,CAAC;YAG1C,aAAa,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;YAG1C,OAAO;gBACL,OAAO,EACL,uCAAuC,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM;oBAC3E,uGAAuG;gBAMzG,OAAO,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE;aAC1D,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/core/pricing.d.ts

@@ -0,0 +1,22 @@
+export interface ModelPricing {
+    inputPer1M: number;
+    outputPer1M: number;
+    cacheReadPer1M?: number;
+    cacheWritePer1M?: number;
+    cacheWriteLongPer1M?: number;
+}
+export interface TokenCounts {
+    totalInputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    cacheWriteTokensLong: number;
+    outputTokens: number;
+}
+export declare function computeCostMicroUsd(counts: TokenCounts, pricing: ModelPricing): number;
+export declare function modelCostToPricing(cost: {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+} | undefined): ModelPricing;
+//# sourceMappingURL=pricing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/core/pricing.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IAEpB,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAOD,MAAM,WAAW,WAAW;IAC1B,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;CACtB;AAcD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAkBtF;AAID,wBAAgB,kBAAkB,CAChC,IAAI,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,GAAG,SAAS,GAC7F,YAAY,CAQd"}

package/dist/core/pricing.js

@@ -0,0 +1,23 @@
+const per1M = (tokens, price) => price && tokens ? (tokens * price) / 1e6 : 0;
+export function computeCostMicroUsd(counts, pricing) {
+    const billedCacheRead = pricing.cacheReadPer1M !== undefined ? counts.cacheReadTokens : 0;
+    const billedCacheWrite = pricing.cacheWritePer1M !== undefined ? counts.cacheWriteTokens : 0;
+    const billedCacheWriteLong = pricing.cacheWriteLongPer1M !== undefined ? counts.cacheWriteTokensLong : 0;
+    const fullInput = Math.max(0, counts.totalInputTokens - billedCacheRead - billedCacheWrite - billedCacheWriteLong);
+    const usd = per1M(fullInput, pricing.inputPer1M) +
+        per1M(billedCacheRead, pricing.cacheReadPer1M) +
+        per1M(billedCacheWrite, pricing.cacheWritePer1M) +
+        per1M(billedCacheWriteLong, pricing.cacheWriteLongPer1M) +
+        per1M(counts.outputTokens, pricing.outputPer1M);
+    return Math.round(usd * 1e6);
+}
+export function modelCostToPricing(cost) {
+    return {
+        inputPer1M: cost?.input ?? 0,
+        outputPer1M: cost?.output ?? 0,
+        cacheReadPer1M: cost?.cacheRead,
+        cacheWritePer1M: cost?.cacheWrite,
+        cacheWriteLongPer1M: cost?.cacheWrite,
+    };
+}
+//# sourceMappingURL=pricing.js.map

package/dist/core/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/core/pricing.ts"],"names":[],"mappings":"AAgCA,MAAM,KAAK,GAAG,CAAC,MAAc,EAAE,KAAyB,EAAU,EAAE,CAClE,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AAW/C,MAAM,UAAU,mBAAmB,CAAC,MAAmB,EAAE,OAAqB;IAM5E,MAAM,eAAe,GAAG,OAAO,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1F,MAAM,gBAAgB,GAAG,OAAO,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7F,MAAM,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEzG,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,gBAAgB,GAAG,eAAe,GAAG,gBAAgB,GAAG,oBAAoB,CAAC,CAAC;IACnH,MAAM,GAAG,GACP,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC;QACpC,KAAK,CAAC,eAAe,EAAE,OAAO,CAAC,cAAc,CAAC;QAC9C,KAAK,CAAC,gBAAgB,EAAE,OAAO,CAAC,eAAe,CAAC;QAChD,KAAK,CAAC,oBAAoB,EAAE,OAAO,CAAC,mBAAmB,CAAC;QACxD,KAAK,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;AAC/B,CAAC;AAID,MAAM,UAAU,kBAAkB,CAChC,IAA8F;IAE9F,OAAO;QACL,UAAU,EAAE,IAAI,EAAE,KAAK,IAAI,CAAC;QAC5B,WAAW,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;QAC9B,cAAc,EAAE,IAAI,EAAE,SAAS;QAC/B,eAAe,EAAE,IAAI,EAAE,UAAU;QACjC,mBAAmB,EAAE,IAAI,EAAE,UAAU;KACtC,CAAC;AACJ,CAAC"}

package/dist/core/property-harness.d.ts

@@ -0,0 +1,40 @@
+export type InvariantKind = "permutation" | "lengthPreserving" | "subset" | "distinctOutput" | "idempotent" | "involution" | "outputPredicate" | "rangeBound" | "nonNegative" | "nonEmptyPreserving" | "concatPreserving" | "chunkMaxLen" | "lengthEq" | "roundtrip" | "totalNoThrow";
+export interface FunctionContract {
+    permutation?: boolean;
+    lengthPreserving?: boolean;
+    subset?: boolean;
+    distinctOutput?: boolean;
+    idempotent?: boolean;
+    involution?: boolean;
+    nonNegative?: boolean;
+    nonEmptyPreserving?: boolean;
+    concatPreserving?: boolean;
+    roundtrip?: boolean;
+    totalNoThrow?: boolean;
+    outputPredicate?: (el: any) => boolean;
+    rangeBound?: (input: any) => readonly [number, number];
+    chunkMaxLen?: (input: any) => number;
+    lengthEq?: (input: any) => number;
+    inputCollection?: (input: any) => unknown[];
+}
+export interface Invariant {
+    kind: InvariantKind;
+    description: string;
+    check: (fn: any, input: any) => boolean;
+}
+export interface InvariantViolation {
+    kind: InvariantKind;
+    description: string;
+    input: unknown;
+    evaluationThrew?: true;
+}
+export interface CheckResult {
+    ok: boolean;
+    violations: InvariantViolation[];
+    trials: number;
+}
+export declare function deriveInvariants(contract: FunctionContract): Invariant[];
+export declare function checkInvariants(fn: unknown, genInput: (i: number) => unknown, invariants: Invariant[], opts?: {
+    trials?: number;
+}): CheckResult;
+//# sourceMappingURL=property-harness.d.ts.map

package/dist/core/property-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-harness.d.ts","sourceRoot":"","sources":["../../src/core/property-harness.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,kBAAkB,GAClB,QAAQ,GACR,gBAAgB,GAChB,YAAY,GACZ,YAAY,GACZ,iBAAiB,GACjB,YAAY,GACZ,aAAa,GACb,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,GACb,UAAU,GACV,WAAW,GACX,cAAc,CAAC;AAOnB,MAAM,WAAW,gBAAgB;IAE/B,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,OAAO,CAAC;IAEvC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAC;IAErC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,CAAC;IAMlC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,EAAE,CAAC;CAC7C;AAGD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,CAAC;IAEpB,WAAW,EAAE,MAAM,CAAC;IAEpB,KAAK,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC;CACzC;AAGD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IAEpB,KAAK,EAAE,OAAO,CAAC;IAIf,eAAe,CAAC,EAAE,IAAI,CAAC;CACxB;AAGD,MAAM,WAAW,WAAW;IAE1B,EAAE,EAAE,OAAO,CAAC;IAEZ,UAAU,EAAE,kBAAkB,EAAE,CAAC;IAEjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAqDD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EAAE,CA0BxE;AAcD,wBAAgB,eAAe,CAC7B,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,EAChC,UAAU,EAAE,SAAS,EAAE,EACvB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,WAAW,CAgCb"}