patchwork-os 0.2.0-beta.2 → 0.2.0-beta.4

package/dist/recipes/connectorPreflight.js

@@ -0,0 +1,143 @@
+/**
+ * Tool-name prefix → connector id (matching the IDs returned by
+ * `/connections` — see src/connectors/gmail.ts handleConnectionsList).
+ * Both `google-calendar` and the dashboard's `googleCalendar` spelling
+ * are accepted on the caller side; this map is authoritative for the
+ * bridge.
+ */
+export const TOOL_PREFIX_TO_CONNECTOR = {
+    slack_: "slack",
+    github_: "github",
+    jira_: "jira",
+    linear_: "linear",
+    gmail_: "gmail",
+    calendar_: "google-calendar",
+    drive_: "google-drive",
+    intercom_: "intercom",
+    hubspot_: "hubspot",
+    datadog_: "datadog",
+    stripe_: "stripe",
+    sentry_: "sentry",
+    zendesk_: "zendesk",
+    asana_: "asana",
+    notion_: "notion",
+    confluence_: "confluence",
+    discord_: "discord",
+    gitlab_: "gitlab",
+    pagerduty_: "pagerduty",
+};
+function toolsOfStep(step) {
+    // agent: false steps carry a single `tool` field. agent: true steps
+    // optionally list permitted tools in `tools[]`. Other shapes (nested
+    // recipe calls, sub-agents) are not first-class in the schema today.
+    if (step.agent === false) {
+        return [step.tool];
+    }
+    if (step.agent === true && Array.isArray(step.tools)) {
+        return step.tools;
+    }
+    return [];
+}
+/**
+ * Compiled list of tool-name prefixes (without the trailing underscore)
+ * used by `promptMentionsConnector`. Built once at module load — the
+ * source map is small and stable, so caching this avoids regex churn
+ * inside the per-step loop.
+ */
+const PROMPT_PREFIX_PATTERNS = Object.entries(TOOL_PREFIX_TO_CONNECTOR).map(([prefix, connector]) => ({
+    // Strip trailing underscore — when the prompt mentions a tool name like
+    // `slack_post_message` the underscore is part of the literal we look
+    // for, but when an agent prompt is more conversational ("post to slack
+    // using slack.post_message"), we want to match the prefix without the
+    // separator too.
+    prefix: prefix.replace(/_$/, ""),
+    connector,
+}));
+/**
+ * Inspect an agent step's `prompt` for references to tool names from
+ * known connectors. Catches the common case where the LLM is told
+ * which tool to call inside the prompt body rather than via the
+ * `tools[]` allowlist — e.g.:
+ *
+ *   - id: notify
+ *     agent:
+ *       prompt: Use slack_post_message to send "{{summary}}" to #ops.
+ *
+ * That prompt previously fell through `toolsOfStep` entirely (no
+ * `tool`, empty `tools[]`) and the install panel told the user "no
+ * connectors needed" despite the recipe relying on Slack at runtime.
+ *
+ * Detection is deliberately lossy — we match `<prefix>_` followed by a
+ * word char (the literal tool-name shape `slack_post_message`) and we
+ * also match `<prefix>.` to catch prose like "use slack.fetch". False
+ * positives are tolerable: surfacing one extra "you may want to
+ * authorise X" hint is strictly better than the pre-fix silent miss.
+ *
+ * Audit 2026-05-17.
+ */
+function promptMentionsConnectors(prompt) {
+    const found = new Set();
+    // Only look at the prompt body — vars / outputs / context refs go
+    // through `{{...}}` interpolation which the runtime resolves later.
+    for (const { prefix, connector } of PROMPT_PREFIX_PATTERNS) {
+        // Anchor on a word boundary so `unrelated_slack_word` doesn't
+        // match (\\bslack[_.]\\w would also match `slack_alert`, which is
+        // the intended target).
+        const re = new RegExp(`\\b${escapeForRegex(prefix)}[_.]\\w`, "i");
+        if (re.test(prompt))
+            found.add(connector);
+    }
+    return [...found];
+}
+function escapeForRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Walk a recipe's steps and return the connector ids it likely needs.
+ * Stable order (sorted) so the response is deterministic.
+ */
+export function detectRequiredConnectors(recipe) {
+    const required = new Set();
+    for (const step of recipe.steps) {
+        // Explicit `tool` / `tools[]` fields (canonical detection path).
+        for (const tool of toolsOfStep(step)) {
+            for (const [prefix, connector] of Object.entries(TOOL_PREFIX_TO_CONNECTOR)) {
+                if (tool.startsWith(prefix)) {
+                    required.add(connector);
+                }
+            }
+        }
+        // Prompt body scan for agent-mode steps — catches recipes that
+        // tell the LLM which tool to call inline (e.g. "Use slack_post_message
+        // to ...") without listing it in `tools[]`. See
+        // `promptMentionsConnectors` above for the rationale.
+        if (step.agent === true && typeof step.prompt === "string") {
+            for (const connector of promptMentionsConnectors(step.prompt)) {
+                required.add(connector);
+            }
+        }
+    }
+    return [...required].sort();
+}
+/**
+ * Compare required connectors against the bridge's `/connections`
+ * payload. Returns the ids of connectors the recipe needs but the
+ * user hasn't connected (or whose status is not "connected").
+ *
+ * Lenient on input shape — the live `/connections` response has a
+ * stable contract, but tests + future surfaces may pass in something
+ * shaped slightly differently. Anything we can't classify is treated
+ * as "not connected" so a malformed connections payload doesn't
+ * silently make every recipe look healthy.
+ */
+export function findMissingConnectors(required, connections) {
+    const connectedSet = new Set();
+    for (const c of connections) {
+        if (typeof c?.id !== "string")
+            continue;
+        if (c.status === "connected")
+            connectedSet.add(c.id);
+    }
+    return required.filter((id) => !connectedSet.has(id));
+}
+//# sourceMappingURL=connectorPreflight.js.map

package/dist/recipes/connectorPreflight.js.map

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

package/dist/recipes/githubInstallSource.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Parses + allowlists the `github:<owner>/<repo>/(recipes|bundles)/<name>`
+ * source format used by `POST /recipes/install`.
+ *
+ * Before this module existed, the install handler hard-coded
+ * `github:patchworkos/recipes/...` everywhere — every URL, every
+ * prefix match. Third-party orgs / forks / private mirrors could not
+ * host recipe catalogs even though the rest of the install pipeline
+ * (SSRF guard, parser, scheduler) is org-agnostic.
+ *
+ * Allowlist policy:
+ *   - Always includes `patchworkos/recipes` (backward compat).
+ *   - Operator opts in additional `<owner>/<repo>` entries via the
+ *     `PATCHWORK_RECIPE_REPO_ALLOWLIST` env var (comma-separated).
+ *   - Allowlist matching is case-insensitive (GitHub itself is).
+ *   - Both owner and repo segments must match the strict regex
+ *     `[a-z0-9_.-]{1,100}` AFTER lowercasing — guards against
+ *     traversal segments smuggled into the source string.
+ *
+ * The default-only behaviour matches the audit recommendation: real
+ * multi-org support is opt-in, so existing single-org deployments
+ * don't see a behaviour change.
+ */
+export type GithubInstallKind = "recipe" | "bundle";
+export interface ParsedGithubInstallSource {
+    kind: GithubInstallKind;
+    owner: string;
+    repo: string;
+    /** Recipe name (single basename) or bundle name. */
+    name: string;
+}
+export type GithubInstallParseResult = {
+    ok: true;
+    parsed: ParsedGithubInstallSource;
+} | {
+    ok: false;
+    code: "bad_shape" | "bad_segment" | "not_allowlisted";
+    error: string;
+};
+/**
+ * Read the runtime allowlist. Combines the always-on default with
+ * whatever the operator has set in PATCHWORK_RECIPE_REPO_ALLOWLIST.
+ * Entries are lowercased + de-duplicated; trailing whitespace, empty
+ * fragments, and shapes that don't look like `owner/repo` are
+ * silently dropped (logging here is the install handler's job, not
+ * this pure helper's).
+ */
+export declare function loadAllowlist(env?: NodeJS.ProcessEnv): string[];
+/**
+ * Parse a `github:owner/repo/(recipes|bundles)/name` source string
+ * against the active allowlist. Pure — does NOT fetch anything; the
+ * install handler is responsible for the network leg and the SSRF
+ * guard. Returns a discriminated union the caller can map to a 400
+ * (bad_shape / bad_segment) or 403 (not_allowlisted) response.
+ */
+export declare function parseGithubInstallSource(source: string, allowlist?: ReadonlyArray<string>): GithubInstallParseResult;
+/**
+ * Build the raw.githubusercontent URL for a parsed install source.
+ * Always pulls `main` branch HEAD — version pinning is on the
+ * deferred audit backlog.
+ */
+export declare function buildGithubRawUrl(parsed: ParsedGithubInstallSource): string;

package/dist/recipes/githubInstallSource.js

@@ -0,0 +1,125 @@
+/**
+ * Parses + allowlists the `github:<owner>/<repo>/(recipes|bundles)/<name>`
+ * source format used by `POST /recipes/install`.
+ *
+ * Before this module existed, the install handler hard-coded
+ * `github:patchworkos/recipes/...` everywhere — every URL, every
+ * prefix match. Third-party orgs / forks / private mirrors could not
+ * host recipe catalogs even though the rest of the install pipeline
+ * (SSRF guard, parser, scheduler) is org-agnostic.
+ *
+ * Allowlist policy:
+ *   - Always includes `patchworkos/recipes` (backward compat).
+ *   - Operator opts in additional `<owner>/<repo>` entries via the
+ *     `PATCHWORK_RECIPE_REPO_ALLOWLIST` env var (comma-separated).
+ *   - Allowlist matching is case-insensitive (GitHub itself is).
+ *   - Both owner and repo segments must match the strict regex
+ *     `[a-z0-9_.-]{1,100}` AFTER lowercasing — guards against
+ *     traversal segments smuggled into the source string.
+ *
+ * The default-only behaviour matches the audit recommendation: real
+ * multi-org support is opt-in, so existing single-org deployments
+ * don't see a behaviour change.
+ */
+const DEFAULT_ALLOWLIST = ["patchworkos/recipes"];
+const SEGMENT_RE = /^[a-z0-9_.-]{1,100}$/;
+/**
+ * Read the runtime allowlist. Combines the always-on default with
+ * whatever the operator has set in PATCHWORK_RECIPE_REPO_ALLOWLIST.
+ * Entries are lowercased + de-duplicated; trailing whitespace, empty
+ * fragments, and shapes that don't look like `owner/repo` are
+ * silently dropped (logging here is the install handler's job, not
+ * this pure helper's).
+ */
+export function loadAllowlist(env = process.env) {
+    const fromEnv = (env.PATCHWORK_RECIPE_REPO_ALLOWLIST ?? "")
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0 && s.includes("/"));
+    return Array.from(new Set([...DEFAULT_ALLOWLIST, ...fromEnv]));
+}
+/**
+ * Parse a `github:owner/repo/(recipes|bundles)/name` source string
+ * against the active allowlist. Pure — does NOT fetch anything; the
+ * install handler is responsible for the network leg and the SSRF
+ * guard. Returns a discriminated union the caller can map to a 400
+ * (bad_shape / bad_segment) or 403 (not_allowlisted) response.
+ */
+export function parseGithubInstallSource(source, allowlist = loadAllowlist()) {
+    if (!source.startsWith("github:")) {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "source must start with 'github:'",
+        };
+    }
+    // After the `github:` prefix we expect <owner>/<repo>/<kind>/<name>.
+    // We split into exactly 4 segments — extra trailing slashes or
+    // missing components are rejected with `bad_shape` so the response
+    // is actionable.
+    const tail = source.slice("github:".length);
+    const segments = tail.split("/");
+    if (segments.length !== 4) {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "source must match 'github:<owner>/<repo>/(recipes|bundles)/<name>'",
+        };
+    }
+    const [ownerRaw, repoRaw, kindRaw, nameRaw] = segments;
+    const owner = ownerRaw.toLowerCase();
+    const repo = repoRaw.toLowerCase();
+    if (!SEGMENT_RE.test(owner) || !SEGMENT_RE.test(repo)) {
+        return {
+            ok: false,
+            code: "bad_segment",
+            error: "owner and repo must match [a-z0-9_.-]{1,100}",
+        };
+    }
+    if (kindRaw !== "recipes" && kindRaw !== "bundles") {
+        return {
+            ok: false,
+            code: "bad_shape",
+            error: "third path segment must be 'recipes' or 'bundles'",
+        };
+    }
+    // Reuse the strict basename predicate inline rather than importing
+    // recipeInstall.ts here (circular deps), but match its rules:
+    // single segment, no `..`, no slashes, conservative charset, ≤100.
+    if (!SEGMENT_RE.test(nameRaw.toLowerCase())) {
+        return {
+            ok: false,
+            code: "bad_segment",
+            error: "name must match [a-z0-9_.-]{1,100}",
+        };
+    }
+    const allowSet = new Set(allowlist.map((s) => s.toLowerCase()));
+    if (!allowSet.has(`${owner}/${repo}`)) {
+        return {
+            ok: false,
+            code: "not_allowlisted",
+            error: `'${owner}/${repo}' is not in the recipe-repo allowlist. Set PATCHWORK_RECIPE_REPO_ALLOWLIST=${owner}/${repo} to opt in.`,
+        };
+    }
+    return {
+        ok: true,
+        parsed: {
+            kind: kindRaw === "recipes" ? "recipe" : "bundle",
+            owner,
+            repo,
+            name: nameRaw,
+        },
+    };
+}
+/**
+ * Build the raw.githubusercontent URL for a parsed install source.
+ * Always pulls `main` branch HEAD — version pinning is on the
+ * deferred audit backlog.
+ */
+export function buildGithubRawUrl(parsed) {
+    if (parsed.kind === "recipe") {
+        return `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/main/recipes/${parsed.name}/${parsed.name}.yaml`;
+    }
+    return `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/main/bundles/${parsed.name}/patchwork-bundle.json`;
+}
+//# sourceMappingURL=githubInstallSource.js.map

package/dist/recipes/githubInstallSource.js.map

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

package/dist/recipes/haltCategory.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Halt-category derivation.
+ *
+ * PR1c of the Val-inspired plan. PR1 attached a `haltReason` sentence to
+ * every error-status StepResult; this module categorises those sentences
+ * into a small bounded enum so the dashboard / metrics layer can count
+ * them over time. Foundation for "is the haltReason work actually
+ * surfacing useful signal, or is everything landing in `unknown`?"
+ *
+ * The mapping is intentionally pattern-based against the 5 phrases
+ * emitted by yamlRunner.ts. Keep this file and those phrases in sync.
+ * When a new error site is added, add a category here AND a test.
+ */
+export type HaltCategory = "agent_silent_fail" | "agent_narration_only" | "agent_threw" | "tool_threw" | "tool_error"
+/** Write blocked by the global kill-switch (#422). Distinct from a real tool failure. */
+ | "kill_switch"
+/** Recipe's `tokensMax` budget breached (PR2b). */
+ | "budget_exceeded"
+/** Whole-recipe failure (e.g. circular dependencies) — has no step row. */
+ | "run_level" | "unknown";
+export declare function categoriseHaltReason(reason: string | undefined): HaltCategory;
+export interface HaltSummary {
+    /** Total error-status step results scanned. */
+    total: number;
+    /** Per-category counts; categories with zero hits are omitted. */
+    byCategory: Partial<Record<HaltCategory, number>>;
+    /** Most recent 5 halt reasons (verbatim) for surfacing in the UI. */
+    recent: Array<{
+        reason: string;
+        category: HaltCategory;
+        runSeq: number;
+    }>;
+}
+interface HaltSummaryInputRun {
+    seq: number;
+    /** Top-level run status — `run_level` halts are runs with status === "error" but no error stepResults (e.g. circular-dep failure before any step ran). */
+    status?: "running" | "done" | "error" | "cancelled" | "interrupted";
+    /** Top-level errorMessage — surfaced as a `run_level` halt when no per-step halts cover it. */
+    errorMessage?: string;
+    stepResults?: Array<{
+        status: "ok" | "skipped" | "error";
+        haltReason?: string;
+    }>;
+}
+/**
+ * Aggregate halt categories across a set of runs. Runs are expected to be
+ * sorted newest-first so `recent` reflects the most recent halts.
+ *
+ * A run contributes:
+ * - one entry per error-status stepResult that has a `haltReason`
+ * - plus one `run_level` entry if `status === "error"` and there were no
+ *   per-step halts that already explained it (avoids double-counting).
+ */
+export declare function summariseHalts(runs: HaltSummaryInputRun[]): HaltSummary;
+/**
+ * Format a `HaltSummary` as Prometheus text-exposition lines for the
+ * `bridge_recipe_halts{category="..."} N` gauge. Returns an empty array
+ * when the summary is empty (no HELP/TYPE block emitted in that case so
+ * Prom scrapers don't see an orphan declaration).
+ *
+ * Surfaced via `/metrics` so users with their own observability stack
+ * can dashboard halts without using Patchwork's UI.
+ */
+export declare function haltSummaryToPrometheus(summary: HaltSummary): string[];
+/**
+ * Derive a one-sentence haltReason from a step's error-status + raw error
+ * string. Used by `chainedRunner` to mirror the convention emitted by
+ * `yamlRunner`. Returns `undefined` for non-error rows or missing error.
+ *
+ * Pattern-matches the same phrases `categoriseHaltReason` knows about,
+ * so chained-run haltReasons categorise into the same buckets.
+ */
+export declare function deriveHaltReasonFromError(opts: {
+    stepId: string;
+    toolName?: string;
+    isAgent?: boolean;
+    status: "ok" | "skipped" | "error";
+    error?: string;
+}): string | undefined;
+export {};

package/dist/recipes/haltCategory.js

@@ -0,0 +1,125 @@
+/**
+ * Halt-category derivation.
+ *
+ * PR1c of the Val-inspired plan. PR1 attached a `haltReason` sentence to
+ * every error-status StepResult; this module categorises those sentences
+ * into a small bounded enum so the dashboard / metrics layer can count
+ * them over time. Foundation for "is the haltReason work actually
+ * surfacing useful signal, or is everything landing in `unknown`?"
+ *
+ * The mapping is intentionally pattern-based against the 5 phrases
+ * emitted by yamlRunner.ts. Keep this file and those phrases in sync.
+ * When a new error site is added, add a category here AND a test.
+ */
+export function categoriseHaltReason(reason) {
+    if (!reason)
+        return "unknown";
+    // Order matters: more specific phrases (silent-fail, narration, kill
+    // switch) must match before the general "Agent step ... threw" /
+    // "Tool ... threw" patterns. The phrases below mirror
+    // yamlRunner.ts:558-606,677-684,693-708 and
+    // featureFlags.ts:assertWriteAllowed.
+    if (/silent-fail/i.test(reason))
+        return "agent_silent_fail";
+    if (/narration|whitespace|no content/i.test(reason))
+        return "agent_narration_only";
+    if (/kill[- _]?switch/i.test(reason))
+        return "kill_switch";
+    if (/budget[_ ]?exceeded|exceeded its token budget/i.test(reason))
+        return "budget_exceeded";
+    if (/^Agent step .* threw/i.test(reason))
+        return "agent_threw";
+    if (/^Tool .* threw/i.test(reason))
+        return "tool_threw";
+    if (/^Tool .* reported an error/i.test(reason))
+        return "tool_error";
+    return "unknown";
+}
+/**
+ * Aggregate halt categories across a set of runs. Runs are expected to be
+ * sorted newest-first so `recent` reflects the most recent halts.
+ *
+ * A run contributes:
+ * - one entry per error-status stepResult that has a `haltReason`
+ * - plus one `run_level` entry if `status === "error"` and there were no
+ *   per-step halts that already explained it (avoids double-counting).
+ */
+export function summariseHalts(runs) {
+    const byCategory = {};
+    const recent = [];
+    let total = 0;
+    for (const run of runs) {
+        let stepHaltsForRun = 0;
+        for (const step of run.stepResults ?? []) {
+            if (step.status !== "error" || !step.haltReason)
+                continue;
+            stepHaltsForRun++;
+            total++;
+            const cat = categoriseHaltReason(step.haltReason);
+            byCategory[cat] = (byCategory[cat] ?? 0) + 1;
+            if (recent.length < 5) {
+                recent.push({
+                    reason: step.haltReason,
+                    category: cat,
+                    runSeq: run.seq,
+                });
+            }
+        }
+        if (stepHaltsForRun === 0 && run.status === "error" && run.errorMessage) {
+            total++;
+            byCategory.run_level = (byCategory.run_level ?? 0) + 1;
+            if (recent.length < 5) {
+                recent.push({
+                    reason: run.errorMessage,
+                    category: "run_level",
+                    runSeq: run.seq,
+                });
+            }
+        }
+    }
+    return { total, byCategory, recent };
+}
+/**
+ * Format a `HaltSummary` as Prometheus text-exposition lines for the
+ * `bridge_recipe_halts{category="..."} N` gauge. Returns an empty array
+ * when the summary is empty (no HELP/TYPE block emitted in that case so
+ * Prom scrapers don't see an orphan declaration).
+ *
+ * Surfaced via `/metrics` so users with their own observability stack
+ * can dashboard halts without using Patchwork's UI.
+ */
+export function haltSummaryToPrometheus(summary) {
+    if (summary.total === 0)
+        return [];
+    const lines = [
+        "# HELP bridge_recipe_halts Recipe halts in the in-memory run-log window, by category",
+        "# TYPE bridge_recipe_halts gauge",
+    ];
+    for (const [category, count] of Object.entries(summary.byCategory)) {
+        lines.push(`bridge_recipe_halts{category="${category}"} ${count}`);
+    }
+    return lines;
+}
+/**
+ * Derive a one-sentence haltReason from a step's error-status + raw error
+ * string. Used by `chainedRunner` to mirror the convention emitted by
+ * `yamlRunner`. Returns `undefined` for non-error rows or missing error.
+ *
+ * Pattern-matches the same phrases `categoriseHaltReason` knows about,
+ * so chained-run haltReasons categorise into the same buckets.
+ */
+export function deriveHaltReasonFromError(opts) {
+    if (opts.status !== "error" || !opts.error)
+        return undefined;
+    if (/silent-fail/i.test(opts.error)) {
+        return `Step "${opts.stepId}" returned no usable output (silent-fail).`;
+    }
+    if (/narration|whitespace|no content/i.test(opts.error)) {
+        return `Step "${opts.stepId}" returned only narration or whitespace — no content.`;
+    }
+    if (opts.isAgent) {
+        return `Agent step "${opts.stepId}" threw before completing: ${opts.error}`;
+    }
+    return `Tool "${opts.toolName ?? "?"}" in step "${opts.stepId}" reported an error: ${opts.error}`;
+}
+//# sourceMappingURL=haltCategory.js.map

package/dist/recipes/haltCategory.js.map

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