@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/cross-repo/allowlist.js

@@ -0,0 +1,87 @@
+/**
+ * Cross-org correlation allowlist loader.
+ *
+ * Reads `.agent/correlate.allow.yaml` from the repo root.
+ * The file declares which orgs this repo permits cross-org correlation with.
+ * Both sides must allowlist each other for a dependency to resolve.
+ *
+ * File format:
+ *   permits:
+ *     - other-org
+ *     - trusted-partner
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { load as yamlLoad } from 'js-yaml';
+import { z } from 'zod';
+import { bothSidesAllowlistEntries } from './resolver.js';
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const correlateAllowSchema = z.object({
+    permits: z.array(z.string()).default([]),
+});
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+/**
+ * Reads `.agent/correlate.allow.yaml` from `cwd`, validates it, and returns
+ * a flat array of `AllowlistEntry` rows ready for SQL insert.
+ *
+ * The source_org is derived from the git remote of `cwd`.
+ * Missing file or invalid YAML returns an empty array (no error thrown).
+ */
+export function loadAllowlist(cwd) {
+    const filePath = path.join(cwd, '.agent', 'correlate.allow.yaml');
+    if (!existsSync(filePath))
+        return [];
+    let raw;
+    try {
+        raw = yamlLoad(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const parsed = correlateAllowSchema.safeParse(raw ?? {});
+    if (!parsed.success)
+        return [];
+    const sourceOrg = detectOrgFromCwd(cwd);
+    return parsed.data.permits.map((permittedOrg) => ({
+        source_org: sourceOrg,
+        permitted_org: permittedOrg,
+    }));
+}
+/**
+ * Returns true when both `sourceOrg` and `targetOrg` have allowlisted each
+ * other in the provided entries.
+ */
+export function bothSidesAllowlist(sourceOrg, targetOrg, allowlist) {
+    return bothSidesAllowlistEntries(sourceOrg, targetOrg, allowlist);
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Detect the org name from the git remote of `cwd`.
+ * Parses SSH (`git@github.com:org/repo.git`) and HTTPS URLs.
+ * Falls back to `'unknown'` on any failure.
+ */
+function detectOrgFromCwd(cwd) {
+    try {
+        const remote = execSync('git remote get-url origin', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 5000,
+        }).trim();
+        const match = remote.match(/[:/]([^/]+)\/[^/]+(?:\.git)?$/);
+        if (match?.[1])
+            return match[1];
+    }
+    catch {
+        // silent — no remote or git not available
+    }
+    return 'unknown';
+}
+//# sourceMappingURL=allowlist.js.map

package/dist/esm/blueprint/cross-repo/audit.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cross-repo correlation audit.
+ *
+ * Detects two classes of violation:
+ *
+ * 1. LEAKS — a public blueprint has an unredacted (is_redacted=0) cross-repo
+ *    dependency on a private-repo blueprint. The slug has leaked into public
+ *    markdown. FAIL LOUD, do NOT auto-mutate.
+ *
+ * 2. MISSING ALLOWLISTS — a cross-org dependency exists but at least one side
+ *    has not allowlisted the other.
+ *
+ * The audit only detects and reports. Remediation requires manual intervention
+ * via `wp fix cross-repo-leak <slug>` (or `fixCrossRepoLeak()` below).
+ */
+export interface CrossRepoLeak {
+    readonly blueprintSlug: string;
+    readonly targetRepo: string;
+    readonly targetSlug: string;
+    readonly sourceVisibility: string;
+    readonly targetVisibility: string | null;
+}
+export interface MissingAllowlist {
+    readonly blueprintSlug: string;
+    readonly sourceOrg: string;
+    readonly targetOrg: string;
+    readonly targetRepo: string;
+    readonly missingSides: ReadonlyArray<'source' | 'target'>;
+}
+export interface CrossRepoAuditResult {
+    readonly pass: boolean;
+    readonly leaks: ReadonlyArray<CrossRepoLeak>;
+    readonly missingAllowlists: ReadonlyArray<MissingAllowlist>;
+}
+export declare function auditCrossRepoCorrelation(cwd: string, _dryRun?: boolean): Promise<CrossRepoAuditResult>;
+export interface FixResult {
+    readonly fixed: boolean;
+    readonly reason: string;
+}
+/**
+ * Remediate a single leak for `blueprintSlug` by redacting its cross-repo
+ * target slug in the DB: sets `target_slug=null`, `target_slug_hash=sha256(slug)`,
+ * `is_redacted=1`.
+ *
+ * This function is intentionally NOT called by `auditCrossRepoCorrelation`.
+ * It must be invoked explicitly via `wp fix cross-repo-leak <slug>`.
+ */
+export declare function fixCrossRepoLeak(cwd: string, blueprintSlug: string): Promise<FixResult>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/esm/blueprint/cross-repo/audit.js

@@ -0,0 +1,161 @@
+/**
+ * Cross-repo correlation audit.
+ *
+ * Detects two classes of violation:
+ *
+ * 1. LEAKS — a public blueprint has an unredacted (is_redacted=0) cross-repo
+ *    dependency on a private-repo blueprint. The slug has leaked into public
+ *    markdown. FAIL LOUD, do NOT auto-mutate.
+ *
+ * 2. MISSING ALLOWLISTS — a cross-org dependency exists but at least one side
+ *    has not allowlisted the other.
+ *
+ * The audit only detects and reports. Remediation requires manual intervention
+ * via `wp fix cross-repo-leak <slug>` (or `fixCrossRepoLeak()` below).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { Database } from '#db/sqlite.js';
+import { bothSidesAllowlistEntries } from './resolver.js';
+// ---------------------------------------------------------------------------
+// Main audit
+// ---------------------------------------------------------------------------
+const DB_PATH = path.join('.agent', '.blueprints.db');
+export async function auditCrossRepoCorrelation(cwd, _dryRun) {
+    const dbFile = path.join(cwd, DB_PATH);
+    if (!existsSync(dbFile)) {
+        // No DB — nothing to audit
+        return { pass: true, leaks: [], missingAllowlists: [] };
+    }
+    const db = new Database(dbFile, { readonly: true });
+    try {
+        return runAudit(db);
+    }
+    finally {
+        db.close();
+    }
+}
+function runAudit(db) {
+    // -------------------------------------------------------------------------
+    // 1. Load cross_repo_dependencies joined with blueprint visibility
+    // -------------------------------------------------------------------------
+    const rows = db
+        .prepare(`SELECT crd.blueprint_slug,
+              crd.target_repo,
+              crd.target_slug,
+              crd.target_slug_hash,
+              crd.is_redacted,
+              crd.is_cross_org,
+              b.organization AS source_org,
+              b.visibility   AS source_visibility
+         FROM cross_repo_dependencies crd
+         JOIN blueprints b ON b.slug = crd.blueprint_slug`)
+        .all();
+    // -------------------------------------------------------------------------
+    // 2. Load workspace_repos for target visibility lookup
+    // -------------------------------------------------------------------------
+    const workspaceRepos = db
+        .prepare('SELECT repo_path, organization, repo_name, visibility FROM workspace_repos')
+        .all();
+    const repoVisibility = new Map();
+    for (const wr of workspaceRepos) {
+        // Key by "org/repo-name" to match target_repo in cross_repo_dependencies
+        repoVisibility.set(`${wr.organization}/${wr.repo_name}`, wr.visibility);
+    }
+    // -------------------------------------------------------------------------
+    // 3. Load correlate_allowlist
+    // -------------------------------------------------------------------------
+    const allowlistRows = db
+        .prepare('SELECT source_org, permitted_org FROM correlate_allowlist')
+        .all();
+    const allowlist = allowlistRows.map((r) => ({
+        source_org: r.source_org,
+        permitted_org: r.permitted_org,
+    }));
+    // -------------------------------------------------------------------------
+    // 4. Detect leaks and missing allowlists
+    // -------------------------------------------------------------------------
+    const leaks = [];
+    const missingAllowlists = [];
+    for (const row of rows) {
+        const targetVisibility = repoVisibility.get(row.target_repo) ?? null;
+        // Leak: is_redacted=0 but target is private and source is public
+        if (row.is_redacted === 0 &&
+            row.target_slug !== null &&
+            targetVisibility === 'private' &&
+            row.source_visibility === 'public') {
+            leaks.push({
+                blueprintSlug: row.blueprint_slug,
+                targetRepo: row.target_repo,
+                targetSlug: row.target_slug,
+                sourceVisibility: row.source_visibility,
+                targetVisibility,
+            });
+        }
+        // Missing allowlist: cross-org dep without mutual allowlist
+        if (row.is_cross_org === 1) {
+            const sourceOrg = row.source_org;
+            const targetOrg = row.target_repo.split('/')[0] ?? 'unknown';
+            if (!bothSidesAllowlistEntries(sourceOrg, targetOrg, allowlist)) {
+                const sourcePerm = allowlist.some((e) => e.source_org === sourceOrg && e.permitted_org === targetOrg);
+                const targetPerm = allowlist.some((e) => e.source_org === targetOrg && e.permitted_org === sourceOrg);
+                const missingSides = [];
+                if (!sourcePerm)
+                    missingSides.push('source');
+                if (!targetPerm)
+                    missingSides.push('target');
+                missingAllowlists.push({
+                    blueprintSlug: row.blueprint_slug,
+                    sourceOrg,
+                    targetOrg,
+                    targetRepo: row.target_repo,
+                    missingSides,
+                });
+            }
+        }
+    }
+    return {
+        pass: leaks.length === 0 && missingAllowlists.length === 0,
+        leaks,
+        missingAllowlists,
+    };
+}
+/**
+ * Remediate a single leak for `blueprintSlug` by redacting its cross-repo
+ * target slug in the DB: sets `target_slug=null`, `target_slug_hash=sha256(slug)`,
+ * `is_redacted=1`.
+ *
+ * This function is intentionally NOT called by `auditCrossRepoCorrelation`.
+ * It must be invoked explicitly via `wp fix cross-repo-leak <slug>`.
+ */
+export async function fixCrossRepoLeak(cwd, blueprintSlug) {
+    const dbFile = path.join(cwd, DB_PATH);
+    if (!existsSync(dbFile)) {
+        return { fixed: false, reason: 'DB file not found' };
+    }
+    const db = new Database(dbFile);
+    try {
+        const rows = db
+            .prepare('SELECT target_slug, target_repo FROM cross_repo_dependencies WHERE blueprint_slug = ? AND is_redacted = 0')
+            .all(blueprintSlug);
+        if (rows.length === 0) {
+            return { fixed: false, reason: 'No unredacted cross-repo dependency found for this slug' };
+        }
+        db.transaction(() => {
+            for (const row of rows) {
+                if (row.target_slug === null)
+                    continue;
+                const hash = createHash('sha256').update(row.target_slug).digest('hex');
+                db.prepare(`UPDATE cross_repo_dependencies
+             SET target_slug = NULL, target_slug_hash = ?, is_redacted = 1
+           WHERE blueprint_slug = ? AND target_repo = ?`).run(hash, blueprintSlug, row.target_repo);
+            }
+        })();
+        return { fixed: true, reason: `Redacted ${rows.length} cross-repo dependency row(s)` };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/esm/blueprint/cross-repo/resolver.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cross-repo correlation resolver.
+ *
+ * Default deny for cross-org references: a dependency only resolves when both
+ * the source org and the target org have each other in their allowlist.
+ * Same-org dependencies always resolve (no allowlist needed).
+ */
+export interface AllowlistEntry {
+    readonly source_org: string;
+    readonly permitted_org: string;
+}
+/**
+ * Returns true when a cross-repo dependency between `sourceOrg` and
+ * `targetOrg` should resolve.
+ *
+ * Resolution rules:
+ * - Same org → always resolves.
+ * - Different org → both sides must have a mutual allowlist entry:
+ *     source_org=sourceOrg permits targetOrg  AND
+ *     source_org=targetOrg permits sourceOrg
+ */
+export declare function resolvesCrossRepo(sourceOrg: string, targetOrg: string, allowlist: readonly AllowlistEntry[]): boolean;
+/**
+ * Checks whether *both* sides have allowlisted each other.
+ * Exported for use by the allowlist loader and the audit.
+ */
+export declare function bothSidesAllowlistEntries(sourceOrg: string, targetOrg: string, allowlist: readonly AllowlistEntry[]): boolean;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/esm/blueprint/cross-repo/resolver.js

@@ -0,0 +1,32 @@
+/**
+ * Cross-repo correlation resolver.
+ *
+ * Default deny for cross-org references: a dependency only resolves when both
+ * the source org and the target org have each other in their allowlist.
+ * Same-org dependencies always resolve (no allowlist needed).
+ */
+/**
+ * Returns true when a cross-repo dependency between `sourceOrg` and
+ * `targetOrg` should resolve.
+ *
+ * Resolution rules:
+ * - Same org → always resolves.
+ * - Different org → both sides must have a mutual allowlist entry:
+ *     source_org=sourceOrg permits targetOrg  AND
+ *     source_org=targetOrg permits sourceOrg
+ */
+export function resolvesCrossRepo(sourceOrg, targetOrg, allowlist) {
+    if (sourceOrg === targetOrg)
+        return true;
+    return bothSidesAllowlistEntries(sourceOrg, targetOrg, allowlist);
+}
+/**
+ * Checks whether *both* sides have allowlisted each other.
+ * Exported for use by the allowlist loader and the audit.
+ */
+export function bothSidesAllowlistEntries(sourceOrg, targetOrg, allowlist) {
+    const sourcePernmitsTarget = allowlist.some((e) => e.source_org === sourceOrg && e.permitted_org === targetOrg);
+    const targetPermitsSource = allowlist.some((e) => e.source_org === targetOrg && e.permitted_org === sourceOrg);
+    return sourcePernmitsTarget && targetPermitsSource;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/esm/blueprint/dag/cycle-detector.d.ts

@@ -0,0 +1,12 @@
+export declare class CycleDetector {
+    private edges;
+    private visited;
+    private recStack;
+    private path;
+    private cycles;
+    constructor(edges: Map<string, Set<string>>);
+    detect(nodes: IterableIterator<string>): string[][] | null;
+    private dfs;
+    private processNeighbor;
+}
+//# sourceMappingURL=cycle-detector.d.ts.map

package/dist/esm/blueprint/dag/cycle-detector.js

@@ -0,0 +1,46 @@
+export class CycleDetector {
+    edges;
+    visited = new Set();
+    recStack = new Set();
+    path = [];
+    cycles = [];
+    constructor(edges) {
+        this.edges = edges;
+    }
+    detect(nodes) {
+        for (const nodeId of nodes) {
+            if (!this.visited.has(nodeId) && this.dfs(nodeId)) {
+                return this.cycles;
+            }
+        }
+        return this.cycles.length > 0 ? this.cycles : null;
+    }
+    dfs(nodeId) {
+        this.visited.add(nodeId);
+        this.recStack.add(nodeId);
+        this.path.push(nodeId);
+        const edges = this.edges.get(nodeId);
+        if (edges) {
+            for (const neighbor of edges) {
+                if (this.processNeighbor(neighbor))
+                    return true;
+            }
+        }
+        this.path.pop();
+        this.recStack.delete(nodeId);
+        return false;
+    }
+    processNeighbor(neighbor) {
+        if (!this.visited.has(neighbor)) {
+            if (this.dfs(neighbor))
+                return true;
+        }
+        else if (this.recStack.has(neighbor)) {
+            const cycleStart = this.path.indexOf(neighbor);
+            this.cycles.push([...this.path.slice(cycleStart), neighbor]);
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=cycle-detector.js.map

package/dist/esm/blueprint/dag/executor.d.ts

@@ -0,0 +1,140 @@
+import type { IClock } from './interfaces.js';
+import type { Task } from './types.js';
+import { TaskGraph } from './task-graph.js';
+/**
+ * Task execution result
+ */
+export interface TaskResult<T = unknown> {
+    taskId: string;
+    status: 'completed' | 'failed' | 'skipped';
+    output?: T;
+    error?: Error;
+    durationMs: number;
+    startedAt: number;
+    completedAt: number;
+}
+/**
+ * Concurrency configuration by task type
+ */
+export interface ConcurrencyConfig {
+    /** Global max concurrent tasks across all types */
+    global?: number;
+    /** Default max concurrent tasks per type (when no type-specific limit) */
+    default: number;
+    /** Per-type limits (overrides default) */
+    byType?: Record<string, number>;
+}
+/**
+ * Task executor function signature
+ * Receives task and returns result (or throws)
+ */
+export type TaskExecutorFn<T, R> = (task: Task<T>) => Promise<R>;
+/**
+ * Execution progress callback
+ */
+export interface ExecutionProgress<T = unknown> {
+    totalTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    runningTasks: string[];
+    pendingTasks: number;
+    currentWave: number;
+    totalWaves: number;
+    latestResult?: TaskResult<T>;
+}
+export type ProgressCallback<T = unknown> = (progress: ExecutionProgress<T>) => void;
+/**
+ * Executor options
+ */
+export interface ExecutorOptions<R> {
+    concurrency?: ConcurrencyConfig;
+    onProgress?: ProgressCallback<R>;
+    /** Clock for time operations (injectable for testing) */
+    clock?: IClock;
+    /** Skip tasks whose dependencies failed */
+    skipOnFailedDependency?: boolean;
+    /** Timeout for individual tasks in milliseconds (0 = no timeout) */
+    taskTimeoutMs?: number;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Parallel DAG executor with concurrency controls.
+ *
+ * Uses Kahn's algorithm for topological execution order.
+ * Supports per-task-type concurrency limits.
+ *
+ * Runtime-agnostic - works in Node.js, Bun, Deno, Cloudflare Workers.
+ */
+export declare class ParallelExecutor<T = unknown, R = unknown> {
+    private graph;
+    private concurrency;
+    private executorFn;
+    private onProgress?;
+    private clock;
+    private skipOnFailedDependency;
+    private taskTimeoutMs;
+    private completed;
+    private failed;
+    private skipped;
+    private running;
+    private results;
+    private signal?;
+    private abortController?;
+    constructor(graph: TaskGraph<T>, executorFn: TaskExecutorFn<T, R>, options?: ExecutorOptions<R>);
+    /**
+     * Execute all tasks in parallel, respecting dependencies and concurrency limits.
+     * Returns results in completion order.
+     * @throws {Error} If graph is invalid or execution is aborted
+     */
+    execute(): Promise<TaskResult<R>[]>;
+    /**
+     * Check if execution has been aborted and throw if so.
+     * Checks both internal controller and external signal.
+     */
+    private throwIfAborted;
+    /**
+     * Get current execution state.
+     */
+    getState(): {
+        completed: string[];
+        failed: string[];
+        skipped: string[];
+        running: string[];
+    };
+    private executeWave;
+    private startPendingTasks;
+    private shouldSkipTask;
+    private skipTask;
+    private canStartTask;
+    private getTaskType;
+    /**
+     * Count running tasks of a specific type.
+     * FIX: Now properly tracks task types.
+     */
+    private countRunningByType;
+    private startTask;
+    /**
+     * Execute task with optional timeout support.
+     * State-of-the-art: proper timeout handling with AbortController pattern.
+     */
+    private executeWithTimeout;
+    private createTimeoutPromise;
+    private emitTaskStart;
+    private waitForAny;
+    private emitProgress;
+}
+/**
+ * Create executor from task array with dependencies.
+ * Convenience function for common use case.
+ */
+export declare function createExecutor<T, R>(tasks: Array<{
+    task: Task<T>;
+    dependsOn?: string[];
+}>, executorFn: TaskExecutorFn<T, R>, options?: ExecutorOptions<R>): ParallelExecutor<T, R>;
+/**
+ * Create executor directly from tasks using their dependencies arrays.
+ * Most convenient for LLM agents.
+ */
+export declare function createExecutorFromTasks<T, R>(tasks: Task<T>[], executorFn: TaskExecutorFn<T, R>, options?: ExecutorOptions<R>): ParallelExecutor<T, R>;
+//# sourceMappingURL=executor.d.ts.map