patchwork-os 0.2.0-beta.10.canary.98 → 0.2.0-beta.11

package/dist/recipes/simulation/aggregateRunRisk.js

@@ -0,0 +1,117 @@
+/**
+ * What-If Preview — run-level risk aggregation.
+ *
+ * Two pure pieces:
+ *   1. `computeEffectiveRisks` — blast-radius propagation. A step's effective
+ *      risk is at least as high as the highest risk among the steps that must
+ *      have run before it (its transitive dependencies). Chained recipes use
+ *      the real dependency DAG; flat recipes model the linear sequence
+ *      (step N implicitly depends on N-1).
+ *   2. `summarizeRunRisk` — a transparent 0–100 workflow score derived from
+ *      step counts, returned WITH its components so it is never a black box.
+ *
+ * Risk tier source is `riskDefault` (already enriched onto the plan step),
+ * NOT `classifyTool` — which mis-tiers namespaced recipe tool ids to a uniform
+ * "medium" (see the investigation report, §3b).
+ */
+const RISK_ORDER = { low: 0, medium: 1, high: 2 };
+const RISK_BY_ORDER = ["low", "medium", "high"];
+export function maxRisk(a, b) {
+    return RISK_ORDER[a] >= RISK_ORDER[b] ? a : b;
+}
+/**
+ * Compute each step's effective (blast-radius-aware) risk.
+ *
+ * Returns a map keyed by step id. Cycles are broken safely: a step already on
+ * the current resolution stack contributes only its own base risk to break the
+ * loop, so a malformed DAG can never infinite-loop the planner.
+ */
+export function computeEffectiveRisks(steps, topology) {
+    const byId = new Map();
+    for (const s of steps)
+        byId.set(s.id, s);
+    const memo = new Map();
+    if (topology === "flat") {
+        // Linear: running max down the list.
+        let running = "low";
+        for (const s of steps) {
+            running = maxRisk(running, s.baseRisk);
+            memo.set(s.id, running);
+        }
+        return memo;
+    }
+    // Chained: forward propagation along the dependency edges.
+    const resolving = new Set();
+    const resolve = (id) => {
+        const cached = memo.get(id);
+        if (cached !== undefined)
+            return cached;
+        const step = byId.get(id);
+        if (!step)
+            return "low";
+        if (resolving.has(id))
+            return step.baseRisk; // cycle guard
+        resolving.add(id);
+        let eff = step.baseRisk;
+        for (const dep of step.dependencies ?? []) {
+            if (dep === id || !byId.has(dep))
+                continue;
+            eff = maxRisk(eff, resolve(dep));
+        }
+        resolving.delete(id);
+        memo.set(id, eff);
+        return eff;
+    };
+    for (const s of steps)
+        resolve(s.id);
+    return memo;
+}
+const clamp100 = (n) => Math.max(0, Math.min(100, n));
+/**
+ * Derive a transparent 0–100 workflow risk score + tier from per-step tallies.
+ * The weights are intentionally simple and surfaced via `components` so a
+ * consumer can always explain the number.
+ */
+export function summarizeRunRisk(steps) {
+    const components = {
+        highSteps: 0,
+        mediumSteps: 0,
+        writeSteps: 0,
+        connectorWriteSteps: 0,
+        externalHttpSteps: 0,
+        unresolvedSteps: 0,
+    };
+    let highestOrder = 0;
+    for (const s of steps) {
+        highestOrder = Math.max(highestOrder, RISK_ORDER[s.effectiveRisk]);
+        if (s.effectiveRisk === "high")
+            components.highSteps += 1;
+        else if (s.effectiveRisk === "medium")
+            components.mediumSteps += 1;
+        if (s.sideEffect === "local-write" || s.sideEffect === "connector-write") {
+            components.writeSteps += 1;
+        }
+        if (s.sideEffect === "connector-write")
+            components.connectorWriteSteps += 1;
+        if (s.sideEffect === "external-http")
+            components.externalHttpSteps += 1;
+        if (!s.resolved)
+            components.unresolvedSteps += 1;
+    }
+    const score = clamp100(components.highSteps * 30 +
+        components.mediumSteps * 10 +
+        components.writeSteps * 8 +
+        components.connectorWriteSteps * 10 +
+        components.externalHttpSteps * 6 +
+        components.unresolvedSteps * 5);
+    const highestStepRisk = RISK_BY_ORDER[highestOrder] ?? "low";
+    let tier;
+    if (highestStepRisk === "high" || score >= 60)
+        tier = "high";
+    else if (highestStepRisk === "medium" || score >= 25)
+        tier = "medium";
+    else
+        tier = "low";
+    return { score, tier, components, highestStepRisk };
+}
+//# sourceMappingURL=aggregateRunRisk.js.map

package/dist/recipes/simulation/aggregateRunRisk.js.map

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

package/dist/recipes/simulation/costProjector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What-If Preview (P3) — cost projection from the P1 token corpus.
+ *
+ * Walks a recipe's agent steps and projects per-step token usage from the
+ * persisted history (`RunStepResult.inputTokens/outputTokens/costUsd`, P1).
+ * When a step has >= `threshold` historical samples the projection is the
+ * MEDIAN of those runs ("history" basis); otherwise it falls back to the
+ * coarse chars/4 prompt heuristic ("heuristic"); a recipe with no agent steps
+ * is "unavailable".
+ *
+ * Honesty rules carried over from P1:
+ *   - USD is projected ONLY from historical `costUsd` (present only for billable
+ *     drivers + priced models). The default `claude-code`/subprocess driver has
+ *     tokens but NO cost → we project TOKENS with a notional note and leave
+ *     `usd` null. Never a $0 placeholder.
+ *   - `confidence` is a first-class, loud field. `high` only when every agent
+ *     step has enough samples; `low` when some are heuristic; `none` when there
+ *     is nothing to go on.
+ */
+import type { RecipeDryRunPlan } from "../../commands/recipe.js";
+import type { RecipeRunLog } from "../../runLog.js";
+import type { SimulationCost } from "./types.js";
+/**
+ * Project the cost of a recipe from its accrued run history. Pure except the
+ * `runLog` read. Degrades to the P0 heuristic/unavailable shape when there is
+ * no usable history, so callers can apply it unconditionally when a runLog is
+ * available.
+ */
+export declare function projectCost(plan: RecipeDryRunPlan, runLog: RecipeRunLog, opts?: {
+    maxRuns?: number;
+    threshold?: number;
+}): SimulationCost;

package/dist/recipes/simulation/costProjector.js

@@ -0,0 +1,194 @@
+/**
+ * What-If Preview (P3) — cost projection from the P1 token corpus.
+ *
+ * Walks a recipe's agent steps and projects per-step token usage from the
+ * persisted history (`RunStepResult.inputTokens/outputTokens/costUsd`, P1).
+ * When a step has >= `threshold` historical samples the projection is the
+ * MEDIAN of those runs ("history" basis); otherwise it falls back to the
+ * coarse chars/4 prompt heuristic ("heuristic"); a recipe with no agent steps
+ * is "unavailable".
+ *
+ * Honesty rules carried over from P1:
+ *   - USD is projected ONLY from historical `costUsd` (present only for billable
+ *     drivers + priced models). The default `claude-code`/subprocess driver has
+ *     tokens but NO cost → we project TOKENS with a notional note and leave
+ *     `usd` null. Never a $0 placeholder.
+ *   - `confidence` is a first-class, loud field. `high` only when every agent
+ *     step has enough samples; `low` when some are heuristic; `none` when there
+ *     is nothing to go on.
+ */
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_MAX_RUNS = 50;
+const DEFAULT_THRESHOLD = 5;
+/** Median of a numeric array (average of the two middle values for even n). */
+function median(nums) {
+    if (nums.length === 0)
+        return 0;
+    const sorted = [...nums].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0
+        ? (sorted[mid - 1] + sorted[mid]) / 2
+        : sorted[mid];
+}
+/**
+ * Project the cost of a recipe from its accrued run history. Pure except the
+ * `runLog` read. Degrades to the P0 heuristic/unavailable shape when there is
+ * no usable history, so callers can apply it unconditionally when a runLog is
+ * available.
+ */
+export function projectCost(plan, runLog, opts = {}) {
+    const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
+    const agentStepIds = plan.steps
+        .filter((s) => s.type === "agent")
+        .map((s) => s.id);
+    const agentSteps = agentStepIds.length;
+    // Prompt-heuristic fallback (chars/4) for steps lacking history. Only flat
+    // agent steps carry `prompt` in the plan; chained ones don't.
+    const promptTokensById = new Map();
+    for (const s of plan.steps) {
+        if (s.type === "agent" && typeof s.prompt === "string" && s.prompt.length) {
+            promptTokensById.set(s.id, Math.ceil(s.prompt.length / CHARS_PER_TOKEN));
+        }
+    }
+    if (agentSteps === 0) {
+        return {
+            basis: "unavailable",
+            confidence: "none",
+            sampleRuns: 0,
+            agentSteps: 0,
+            estimatedAgentSteps: 0,
+            estPromptTokens: null,
+            estInputTokens: null,
+            estOutputTokens: null,
+            usd: null,
+            minUsd: null,
+            maxUsd: null,
+            historyAgentSteps: 0,
+            note: "No AI/agent steps — this recipe incurs no model cost.",
+        };
+    }
+    const runs = runLog.query({
+        recipe: plan.recipe,
+        limit: opts.maxRuns ?? DEFAULT_MAX_RUNS,
+    });
+    // Collect per-step samples across history.
+    const samples = new Map();
+    for (const id of agentStepIds) {
+        samples.set(id, { input: [], output: [], cost: [] });
+    }
+    let sampleRuns = 0;
+    for (const run of runs) {
+        let contributed = false;
+        for (const step of run.stepResults ?? []) {
+            const bucket = samples.get(step.id);
+            if (!bucket)
+                continue;
+            if (typeof step.inputTokens === "number") {
+                bucket.input.push(step.inputTokens);
+                contributed = true;
+            }
+            if (typeof step.outputTokens === "number") {
+                bucket.output.push(step.outputTokens);
+            }
+            if (typeof step.costUsd === "number") {
+                bucket.cost.push(step.costUsd);
+            }
+        }
+        if (contributed)
+            sampleRuns += 1;
+    }
+    let estInput = 0;
+    let estOutput = 0;
+    let expectedUsd = 0;
+    let minUsd = 0;
+    let maxUsd = 0;
+    let anyTokenEstimate = false;
+    let anyCost = false;
+    let historyAgentSteps = 0;
+    let estimatedAgentSteps = 0;
+    let allStepsConfident = true;
+    for (const id of agentStepIds) {
+        const bucket = samples.get(id);
+        const hasHistory = bucket.input.length > 0;
+        if (hasHistory) {
+            historyAgentSteps += 1;
+            estimatedAgentSteps += 1;
+            anyTokenEstimate = true;
+            estInput += median(bucket.input);
+            estOutput += bucket.output.length > 0 ? median(bucket.output) : 0;
+            if (bucket.input.length < threshold)
+                allStepsConfident = false;
+            if (bucket.cost.length > 0) {
+                anyCost = true;
+                expectedUsd += median(bucket.cost);
+                minUsd += Math.min(...bucket.cost);
+                maxUsd += Math.max(...bucket.cost);
+            }
+        }
+        else {
+            // No history — chars/4 prompt heuristic when available.
+            const promptTokens = promptTokensById.get(id);
+            allStepsConfident = false;
+            if (promptTokens !== undefined) {
+                estimatedAgentSteps += 1;
+                anyTokenEstimate = true;
+                estInput += promptTokens;
+            }
+        }
+    }
+    const basis = historyAgentSteps > 0
+        ? "history"
+        : estimatedAgentSteps > 0
+            ? "heuristic"
+            : "unavailable";
+    const confidence = basis === "history"
+        ? allStepsConfident && historyAgentSteps === agentSteps
+            ? "high"
+            : "low"
+        : basis === "heuristic"
+            ? "low"
+            : "none";
+    const note = buildNote({
+        basis,
+        confidence,
+        sampleRuns,
+        historyAgentSteps,
+        agentSteps,
+        anyCost,
+        expectedUsd,
+    });
+    return {
+        basis,
+        confidence,
+        sampleRuns,
+        agentSteps,
+        estimatedAgentSteps,
+        // Back-compat: estPromptTokens kept as the chars/4 sum (input-only proxy).
+        estPromptTokens: anyTokenEstimate ? estInput : null,
+        estInputTokens: anyTokenEstimate ? estInput : null,
+        estOutputTokens: anyTokenEstimate ? estOutput : null,
+        usd: anyCost ? round4(expectedUsd) : null,
+        minUsd: anyCost ? round4(minUsd) : null,
+        maxUsd: anyCost ? round4(maxUsd) : null,
+        historyAgentSteps,
+        note,
+    };
+}
+function round4(n) {
+    return Math.round(n * 1e4) / 1e4;
+}
+function buildNote(p) {
+    if (p.basis === "unavailable") {
+        return "No usable history or prompts — cost not estimable.";
+    }
+    if (p.basis === "heuristic") {
+        return "Low-confidence chars/4 token estimate over agent prompts (no run history yet). USD not projected — accrue runs for a history-backed estimate.";
+    }
+    // history
+    const cov = `${p.historyAgentSteps}/${p.agentSteps} agent step(s) backed by ${p.sampleRuns} prior run(s) (median; ${p.confidence} confidence)`;
+    if (p.anyCost) {
+        return `Token + USD projection from history — ${cov}. USD covers billable-driver steps only.`;
+    }
+    return `Token projection from history — ${cov}. USD not projected: the served driver is a subscription/subprocess driver that is not billed (notional only).`;
+}
+//# sourceMappingURL=costProjector.js.map

package/dist/recipes/simulation/costProjector.js.map

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

package/dist/recipes/simulation/sideEffects.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What-If Preview — static side-effect classification.
+ *
+ * Classifies a single plan step into a {@link SideEffectKind} using ONLY
+ * registry metadata already present on the dry-run plan step
+ * (`type` / `tool` / `namespace` / `isWrite` / `isConnector` / `resolved`).
+ * No execution, no network, no token resolution.
+ */
+import type { SideEffectKind } from "./types.js";
+export interface SideEffectInput {
+    type: "tool" | "agent" | "recipe";
+    tool?: string;
+    namespace?: string;
+    resolved?: boolean;
+    isWrite?: boolean;
+    isConnector?: boolean;
+}
+/**
+ * Map a plan step to its side-effect class. Pure and total.
+ *
+ * Precedence:
+ *   agent → agent-llm; recipe → nested-recipe.
+ *   unresolved tool → unknown (we cannot claim a side effect we can't see).
+ *   http/webhook namespace → external-http (write or read).
+ *   connector → connector-write / connector-read on isWrite.
+ *   otherwise local-write / local-read on isWrite.
+ */
+export declare function classifyStepSideEffect(step: SideEffectInput): SideEffectKind;
+/** Human-readable, one-line description of a side-effect class. */
+export declare const SIDE_EFFECT_LABELS: Record<SideEffectKind, string>;
+/** Empty side-effect tally with every kind present (so consumers can index safely). */
+export declare function emptySideEffectCounts(): Record<SideEffectKind, number>;

package/dist/recipes/simulation/sideEffects.js

@@ -0,0 +1,62 @@
+/**
+ * What-If Preview — static side-effect classification.
+ *
+ * Classifies a single plan step into a {@link SideEffectKind} using ONLY
+ * registry metadata already present on the dry-run plan step
+ * (`type` / `tool` / `namespace` / `isWrite` / `isConnector` / `resolved`).
+ * No execution, no network, no token resolution.
+ */
+/** Namespaces whose writes are arbitrary outbound HTTP rather than a SaaS connector. */
+const EXTERNAL_HTTP_NAMESPACES = new Set(["http", "webhook"]);
+/**
+ * Map a plan step to its side-effect class. Pure and total.
+ *
+ * Precedence:
+ *   agent → agent-llm; recipe → nested-recipe.
+ *   unresolved tool → unknown (we cannot claim a side effect we can't see).
+ *   http/webhook namespace → external-http (write or read).
+ *   connector → connector-write / connector-read on isWrite.
+ *   otherwise local-write / local-read on isWrite.
+ */
+export function classifyStepSideEffect(step) {
+    if (step.type === "agent")
+        return "agent-llm";
+    if (step.type === "recipe")
+        return "nested-recipe";
+    // type === "tool"
+    if (step.resolved === false)
+        return "unknown";
+    const ns = step.namespace ?? step.tool?.split(".")[0];
+    if (ns && EXTERNAL_HTTP_NAMESPACES.has(ns))
+        return "external-http";
+    const isWrite = step.isWrite === true;
+    if (step.isConnector === true) {
+        return isWrite ? "connector-write" : "connector-read";
+    }
+    return isWrite ? "local-write" : "local-read";
+}
+/** Human-readable, one-line description of a side-effect class. */
+export const SIDE_EFFECT_LABELS = {
+    "local-read": "reads local/workspace state",
+    "local-write": "writes local/workspace state",
+    "connector-read": "reads an external connector",
+    "connector-write": "writes to an external connector",
+    "external-http": "makes an outbound HTTP/webhook call",
+    "agent-llm": "runs an AI/agent step (not executed in simulation)",
+    "nested-recipe": "delegates to a nested recipe",
+    unknown: "unresolved tool — side effect unknown",
+};
+/** Empty side-effect tally with every kind present (so consumers can index safely). */
+export function emptySideEffectCounts() {
+    return {
+        "local-read": 0,
+        "local-write": 0,
+        "connector-read": 0,
+        "connector-write": 0,
+        "external-http": 0,
+        "agent-llm": 0,
+        "nested-recipe": 0,
+        unknown: 0,
+    };
+}
+//# sourceMappingURL=sideEffects.js.map

package/dist/recipes/simulation/sideEffects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sideEffects.js","sourceRoot":"","sources":["../../../src/recipes/simulation/sideEffects.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,wFAAwF;AACxF,MAAM,wBAAwB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAW9D;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAqB;IAC1D,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,WAAW,CAAC;IAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,eAAe,CAAC;IAEnD,kBAAkB;IAClB,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAE9C,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,EAAE,IAAI,wBAAwB,CAAC,GAAG,CAAC,EAAE,CAAC;QAAE,OAAO,eAAe,CAAC;IAEnE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC;IACtC,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACxD,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC;AAChD,CAAC;AAED,mEAAmE;AACnE,MAAM,CAAC,MAAM,kBAAkB,GAAmC;IAChE,YAAY,EAAE,6BAA6B;IAC3C,aAAa,EAAE,8BAA8B;IAC7C,gBAAgB,EAAE,6BAA6B;IAC/C,iBAAiB,EAAE,iCAAiC;IACpD,eAAe,EAAE,qCAAqC;IACtD,WAAW,EAAE,oDAAoD;IACjE,eAAe,EAAE,8BAA8B;IAC/C,OAAO,EAAE,uCAAuC;CACjD,CAAC;AAEF,uFAAuF;AACvF,MAAM,UAAU,qBAAqB;IACnC,OAAO;QACL,YAAY,EAAE,CAAC;QACf,aAAa,EAAE,CAAC;QAChB,gBAAgB,EAAE,CAAC;QACnB,iBAAiB,EAAE,CAAC;QACpB,eAAe,EAAE,CAAC;QAClB,WAAW,EAAE,CAAC;QACd,eAAe,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;KACX,CAAC;AACJ,CAAC"}

package/dist/recipes/simulation/simulate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What-If Preview — static simulation core.
+ *
+ * `simulateFromPlan` is a PURE transform: dry-run plan → simulation report.
+ * It performs no I/O and has no clock dependency (it reuses the plan's
+ * `generatedAt`), so it is fully deterministic and unit-testable. The
+ * I/O-bearing entrypoint (`runRecipeSimulate`, which produces the plan first)
+ * lives in `src/commands/recipe.ts`.
+ */
+import type { RecipeDryRunPlan } from "../../commands/recipe.js";
+import type { MockedRunResult } from "./simulateMockedRun.js";
+import { type RecipeSimulationReport } from "./types.js";
+/** Pure transform: a dry-run plan → a What-If Preview simulation report. */
+export declare function simulateFromPlan(plan: RecipeDryRunPlan): RecipeSimulationReport;
+/**
+ * Extract the step ids a `when:` condition references via `{{ ... }}`
+ * placeholders. Covers the common dotted forms the chained runner exposes
+ * (`steps.<id>.data`, `outputs.<id>`, or a bare `<id>`). A coarse regex is
+ * deliberate — we only need to know WHICH step ids the branch depends on so we
+ * can decide whether the branch is determinable from history.
+ */
+export declare function extractReferencedStepIds(condition: string): Set<string>;
+/**
+ * P2 — compose the mocked report: take the static report and OVERLAY the
+ * results of the trace-seeded mocked sandbox run.
+ *
+ *   - `fidelity:"mocked"` + `sampleRuns`.
+ *   - each step's `mockedFrom` ("history" | "synthesized").
+ *   - `branches[].outcome` recomputed: `"taken"`/`"skipped"` when EVERY step id
+ *     the `when:` references is in `historyStepIds` (determinable from real
+ *     data), else `"undetermined"`.
+ *
+ * Risk / side-effect / cost / approvals sections are carried over unchanged
+ * from the static report. `gatedOnRecipeSteps` stays false (P0/P4 truth).
+ */
+export declare function simulateMockedFromPlan(plan: RecipeDryRunPlan, mocked: MockedRunResult): RecipeSimulationReport;