pi-harness-runtime 0.10.12 → 0.10.13

package/packages/performance-optimizer/dist/types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Performance Optimizer Types (RFC-0056)
+ *
+ * Interfaces for performance analysis and recommendations.
+ */
+export interface RuntimeMetricSnapshot {
+    jobId: string;
+    timestamp: string;
+    /** Total tokens used */
+    totalTokens: number;
+    /** Tokens used in last request */
+    lastRequestTokens: number;
+    /** Average latency in milliseconds */
+    avgLatencyMs: number;
+    /** Number of retries */
+    retryCount: number;
+    /** Number of successful calls */
+    successCount: number;
+    /** Number of failed calls */
+    failureCount: number;
+    /** Current context size in tokens */
+    currentContextTokens: number;
+    /** Max context window */
+    contextWindow: number;
+    /** Provider-specific metrics */
+    providerMetrics: Record<string, ProviderMetric>;
+}
+export interface ProviderMetric {
+    providerId: string;
+    callCount: number;
+    successCount: number;
+    failureCount: number;
+    avgLatencyMs: number;
+    avgTokensPerCall: number;
+}
+export interface ProviderRuntimeState {
+    providerId: string;
+    state: "available" | "limited" | "exhausted" | "disabled" | "unknown";
+    remainingQuota?: number;
+    avgLatencyMs?: number;
+    lastError?: string;
+}
+export interface PerformancePolicy {
+    /** Minimum context usage to consider reduction */
+    minContextReductionPercent: number;
+    /** Maximum parallelism allowed */
+    maxParallelism: number;
+    /** Minimum improvement threshold for recommendations */
+    minImprovementPercent: number;
+    /** Whether to allow provider switching */
+    allowProviderSwitch: boolean;
+    /** Mandatory stages that cannot be skipped */
+    mandatoryStages: string[];
+}
+export interface TaskGraphSnapshot {
+    nodes: Array<{
+        id: string;
+        status: string;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+}
+export interface PerformanceOptimizationRequest {
+    jobId: string;
+    taskId?: string;
+    metrics: RuntimeMetricSnapshot;
+    providerStates: ProviderRuntimeState[];
+    taskGraph: TaskGraphSnapshot;
+    policy: PerformancePolicy;
+}
+export type PerformanceRecommendation = {
+    type: "reduce_context";
+    targetTokens: number;
+    reason: string;
+} | {
+    type: "change_provider";
+    provider: string;
+    reason: string;
+} | {
+    type: "increase_parallelism";
+    limit: number;
+    reason: string;
+} | {
+    type: "decrease_parallelism";
+    limit: number;
+    reason: string;
+} | {
+    type: "reuse_checkpoint";
+    checkpointId: string;
+    reason: string;
+} | {
+    type: "skip_redundant_step";
+    taskId: string;
+    reason: string;
+};
+export interface PerformanceOptimizationPlan {
+    jobId: string;
+    recommendations: PerformanceRecommendation[];
+    expectedImpact: {
+        tokenReductionPercent?: number;
+        latencyReductionPercent?: number;
+        retryReductionPercent?: number;
+    };
+    generatedAt: string;
+}
+export type PerformanceOptimizerEvent = {
+    type: "performance.analysis.started";
+    jobId: string;
+} | {
+    type: "performance.recommendation.created";
+    jobId: string;
+    recommendation: PerformanceRecommendation;
+} | {
+    type: "performance.analysis.completed";
+    jobId: string;
+} | {
+    type: "performance.analysis.failed";
+    jobId: string;
+    error: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/packages/performance-optimizer/dist/types.d.ts.map

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

package/packages/performance-optimizer/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Performance Optimizer Types (RFC-0056)
+ *
+ * Interfaces for performance analysis and recommendations.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/packages/performance-optimizer/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/packages/privilege-broker/dist/approval.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Approval Class — RFC-0101 §8
+ *
+ * Replaces runtime-wide `require-approval` flag with per-capability policies.
+ * Human approves or denies on first use; decision is cached for subsequent uses
+ * within the same session.
+ */
+import type { ApprovalClass, CapabilityName } from "./types.js";
+/** Result of an approval check. */
+export type ApprovalResult = "granted" | "denied" | "error";
+/**
+ * Register an approval class by id.
+ * Must be called before any checkApproval() call.
+ */
+export declare function registerApprovalClass(cls: ApprovalClass): void;
+/**
+ * Check if a capability is approved for an actor.
+ * Asks the human via requestor() on first use; caches for the session.
+ */
+export declare function checkApproval(capability: CapabilityName, actor: string, requestor: (msg: string) => Promise<boolean>): Promise<ApprovalResult>;
+/** Clear the approval cache (e.g., at session start). */
+export declare function clearApprovalCache(): void;
+//# sourceMappingURL=approval.d.ts.map

package/packages/privilege-broker/dist/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEhE,mCAAmC;AACnC,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAY5D;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAE9D;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAClC,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC1C,OAAO,CAAC,cAAc,CAAC,CA0BzB;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/packages/privilege-broker/dist/approval.js

@@ -0,0 +1,45 @@
+/** Cache of session-level approval decisions. */
+const approved = new Map();
+/** Map from class id → its policy. */
+const classes = new Map();
+function cacheKey(capability, actor) {
+    return `${actor}::${capability}`;
+}
+/**
+ * Register an approval class by id.
+ * Must be called before any checkApproval() call.
+ */
+export function registerApprovalClass(cls) {
+    classes.set(cls.id, cls);
+}
+/**
+ * Check if a capability is approved for an actor.
+ * Asks the human via requestor() on first use; caches for the session.
+ */
+export async function checkApproval(capability, actor, requestor) {
+    const key = cacheKey(capability, actor);
+    if (approved.has(key)) {
+        return approved.get(key);
+    }
+    // Find the approval class for this capability
+    const cls = classes.get(capability);
+    if (!cls) {
+        // No approval class registered — default deny
+        approved.set(key, "denied");
+        return "denied";
+    }
+    try {
+        const decision = await cls.prompt(capability, actor, `Allow capability "${capability}" for actor "${actor}"?`);
+        approved.set(key, decision);
+        return decision;
+    }
+    catch {
+        approved.set(key, "error");
+        return "error";
+    }
+}
+/** Clear the approval cache (e.g., at session start). */
+export function clearApprovalCache() {
+    approved.clear();
+}
+//# sourceMappingURL=approval.js.map

package/packages/privilege-broker/dist/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AAYA,iDAAiD;AACjD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEnD,sCAAsC;AACtC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEjD,SAAS,QAAQ,CAAC,UAA0B,EAAE,KAAa;IAC1D,OAAO,GAAG,KAAK,KAAK,UAAU,EAAE,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAkB;IACvD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,UAA0B,EAC1B,KAAa,EACb,SAA4C;IAE5C,MAAM,GAAG,GAAG,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACxC,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;IAC3B,CAAC;IAED,8CAA8C;IAC9C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,8CAA8C;QAC9C,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5B,OAAO,QAAQ,CAAC;IACjB,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,MAAM,CAChC,UAAU,EACV,KAAK,EACL,qBAAqB,UAAU,gBAAgB,KAAK,IAAI,CACxD,CAAC;QACF,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5B,OAAO,QAAQ,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACR,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC3B,OAAO,OAAO,CAAC;IAChB,CAAC;AACF,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC"}

package/packages/privilege-broker/dist/audit.d.ts

@@ -0,0 +1,38 @@
+import type { AuditEntry, AuditLogger } from "./types.js";
+/** No-op logger — discards all events. */
+export declare class NoOpAuditLogger implements AuditLogger {
+    log(_entry: AuditEntry): void;
+}
+/** Console logger — writes human-readable lines to stdout/stderr. */
+export declare class ConsoleAuditLogger implements AuditLogger {
+    log(entry: AuditEntry): void;
+}
+/**
+ * JSON Lines file logger — appends one JSON object per event.
+ * Auto-creates parent directory. Auto-rotates when file exceeds maxSizeBytes.
+ */
+export declare class FileAuditLogger implements AuditLogger {
+    private readonly logPath;
+    private readonly maxSizeBytes;
+    private readonly maxRotations;
+    constructor(options?: {
+        logPath?: string;
+        maxSizeBytes?: number;
+        maxRotations?: number;
+    });
+    log(entry: AuditEntry): void;
+    private _ensureDir;
+    private _rotateIfNeeded;
+    /**
+     * Read recent audit entries.
+     * Returns newest entries last.
+     */
+    query(options?: {
+        workerId?: string;
+        taskId?: string;
+        capability?: string;
+        success?: boolean;
+        limit?: number;
+    }): AuditEntry[];
+}
+//# sourceMappingURL=audit.d.ts.map

package/packages/privilege-broker/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D,0CAA0C;AAC1C,qBAAa,eAAgB,YAAW,WAAW;IAClD,GAAG,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAE5B;CACD;AAED,qEAAqE;AACrE,qBAAa,kBAAmB,YAAW,WAAW;IACrD,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAsB3B;CACD;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,WAAW;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,YACC,OAAO,GAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;KACjB,EAQN;IAED,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAI3B;IAED,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,eAAe;IAqBvB;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,UAAU,EAAE,CAqBf;CACD"}

package/packages/privilege-broker/dist/audit.js

@@ -0,0 +1,125 @@
+/**
+ * Audit Logger — RFC-0101 §7
+ *
+ * Logs every capability grant/denial with actor, target, reason, and outcome.
+ * Built-in implementations: Console, File, NoOp.
+ * Replace with your preferred audit backend (syslog, PostgreSQL, Loki, etc.)
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/** No-op logger — discards all events. */
+export class NoOpAuditLogger {
+    log(_entry) {
+        // no-op
+    }
+}
+/** Console logger — writes human-readable lines to stdout/stderr. */
+export class ConsoleAuditLogger {
+    log(entry) {
+        const prefix = entry.outcome === "granted"
+            ? "✅"
+            : entry.outcome === "denied"
+                ? "❌"
+                : "⚠️";
+        const line = [
+            prefix,
+            `${entry.outcome.toUpperCase()}`,
+            `actor=${entry.actor}`,
+            `capability=${entry.capability}`,
+            `reason=${entry.reason}`,
+            entry.error ? `error=${entry.error}` : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        if (entry.outcome === "error") {
+            console.error(`[AUDIT] ${line}`);
+        }
+        else {
+            console.log(`[AUDIT] ${line}`);
+        }
+    }
+}
+/**
+ * JSON Lines file logger — appends one JSON object per event.
+ * Auto-creates parent directory. Auto-rotates when file exceeds maxSizeBytes.
+ */
+export class FileAuditLogger {
+    logPath;
+    maxSizeBytes;
+    maxRotations;
+    constructor(options = {}) {
+        const home = process.env["HOME"] ?? "/tmp";
+        this.logPath =
+            options.logPath ?? join(home, ".pi", "harness", "broker-audit.logl");
+        this.maxSizeBytes = options.maxSizeBytes ?? 10 * 1024 * 1024; // 10 MB
+        this.maxRotations = options.maxRotations ?? 5;
+        this._ensureDir();
+    }
+    log(entry) {
+        this._rotateIfNeeded();
+        const line = JSON.stringify(entry) + "\n";
+        writeFileSync(this.logPath, line, { flag: "a" });
+    }
+    _ensureDir() {
+        const dir = dirname(this.logPath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    _rotateIfNeeded() {
+        if (!existsSync(this.logPath))
+            return;
+        try {
+            const { statSync } = require("node:fs");
+            const stat = statSync(this.logPath);
+            if (stat.size < this.maxSizeBytes)
+                return;
+            // Rotate: broker-audit.log → broker-audit.log.1 → ...
+            const { renameSync, existsSync: exists } = require("node:fs");
+            for (let i = this.maxRotations - 1; i >= 1; i--) {
+                const from = `${this.logPath}.${i}`;
+                const to = `${this.logPath}.${i + 1}`;
+                if (exists(to))
+                    unlinkSync(to);
+                if (exists(from))
+                    renameSync(from, to);
+            }
+            renameSync(this.logPath, `${this.logPath}.1`);
+        }
+        catch {
+            // If rotation fails, continue writing to the existing file
+        }
+    }
+    /**
+     * Read recent audit entries.
+     * Returns newest entries last.
+     */
+    query(options) {
+        if (!existsSync(this.logPath))
+            return [];
+        const raw = readFileSync(this.logPath, "utf8");
+        const entries = [];
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const e = JSON.parse(line);
+                if (options?.workerId && e.workerId !== options.workerId)
+                    continue;
+                if (options?.taskId && e.taskId !== options.taskId)
+                    continue;
+                if (options?.capability && e.capability !== options.capability)
+                    continue;
+                if (options?.success !== undefined && e.success !== options.success)
+                    continue;
+                entries.push(e);
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        const result = options?.limit ? entries.slice(-options.limit) : entries;
+        return result;
+    }
+}
+//# sourceMappingURL=audit.js.map

package/packages/privilege-broker/dist/audit.js.map

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

package/packages/privilege-broker/dist/executor.d.ts

@@ -0,0 +1,25 @@
+import type { AuditLogger } from "./types.js";
+/** The BrokerExecutor resolves and executes capability grants. */
+export declare class BrokerExecutor {
+    private readonly audit;
+    constructor(audit: AuditLogger);
+    /**
+     * Execute a command as the configured service account.
+     * Throws on timeout or spawn error.
+     */
+    execute(options: {
+        command: string;
+        args: string[];
+        envWhitelist?: string[];
+        allowedCwd?: string;
+        timeoutMs?: number;
+        actor: string;
+        capability: string;
+        reason: string;
+    }): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/packages/privilege-broker/dist/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../src/executor.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,kEAAkE;AAClE,qBAAa,cAAc;IACd,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAlC,YAA6B,KAAK,EAAE,WAAW,EAAI;IAEnD;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CA4EhE;CACD"}

package/packages/privilege-broker/dist/executor.js

@@ -0,0 +1,83 @@
+/**
+ * Broker Executor — RFC-0101 §7
+ *
+ * Executes a resolved CapabilityGrant using execve(2) (no shell).
+ * The service account must exist and have minimal permissions.
+ *
+ * Safety properties:
+ * - No shell interpolation — argv is passed directly to execve
+ * - Env whitelist enforced — only approved env vars are forwarded
+ * - Working directory constrained via chdir
+ * - Timeout enforced — process is killed if it exceeds timeoutMs
+ */
+import { spawn } from "node:child_process";
+/** The BrokerExecutor resolves and executes capability grants. */
+export class BrokerExecutor {
+    audit;
+    constructor(audit) {
+        this.audit = audit;
+    }
+    /**
+     * Execute a command as the configured service account.
+     * Throws on timeout or spawn error.
+     */
+    async execute(options) {
+        const { command, args, envWhitelist, allowedCwd, timeoutMs = 30_000, actor, capability, reason, } = options;
+        // Build minimal env
+        const env = {};
+        if (envWhitelist) {
+            for (const key of envWhitelist) {
+                if (process.env[key] !== undefined) {
+                    env[key] = process.env[key];
+                }
+            }
+        }
+        env.PI_HARNESS_ACTOR = actor;
+        env.PI_HARNESS_CAPABILITY = capability;
+        const child = spawn(command, args, {
+            env,
+            cwd: allowedCwd ?? process.cwd(),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                reject(new Error(`command timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            child.on("exit", (code) => {
+                clearTimeout(timer);
+                const exitCode = code ?? 0;
+                this.audit.log({
+                    timestamp: new Date().toISOString(),
+                    actor,
+                    capability: capability,
+                    reason,
+                    outcome: exitCode === 0 ? "granted" : "error",
+                    error: exitCode !== 0 ? `exit ${exitCode}` : undefined,
+                });
+                resolve({ exitCode, stdout, stderr });
+            });
+            child.on("error", (err) => {
+                clearTimeout(timer);
+                this.audit.log({
+                    timestamp: new Date().toISOString(),
+                    actor,
+                    capability: capability,
+                    reason,
+                    outcome: "error",
+                    error: err.message,
+                });
+                reject(err);
+            });
+        });
+    }
+}
+//# sourceMappingURL=executor.js.map

package/packages/privilege-broker/dist/executor.js.map

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

package/packages/privilege-broker/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Privilege Broker — RFC-0101 §7
+ *
+ * Provides safe privilege escalation for autonomous tasks:
+ * - Lists available capabilities
+ * - Checks human approval
+ * - Executes privileged operations safely
+ *
+ * Usage:
+ * ```ts
+ * import { PrivilegeBroker } from "@pi-harness/privilege-broker";
+ *
+ * const broker = new PrivilegeBroker({
+ *   registry: defaultCapabilityRegistry(),
+ *   audit: new ConsoleAuditLogger(),
+ * });
+ *
+ * const ok = await broker.check(
+ *   "run_command",
+ *   { command: "npm test" },
+ *   "pi-runtime-agent",
+ * );
+ * ```
+ */
+export type { PrivilegeEntry, PrivilegeRegistry, CapabilityName, CapabilityGrant, AuditEntry, AuditLogger, ApprovalClass, } from "./types.js";
+export { loadRegistry, type PrivilegeRegistryError } from "./registry.js";
+export { type ApprovalResult, registerApprovalClass, checkApproval, clearApprovalCache, } from "./approval.js";
+export { NoOpAuditLogger, ConsoleAuditLogger, FileAuditLogger, } from "./audit.js";
+export { BrokerExecutor } from "./executor.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/privilege-broker/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,YAAY,EACX,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,UAAU,EACV,WAAW,EACX,aAAa,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,KAAK,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EACN,KAAK,cAAc,EACnB,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,eAAe,EACf,kBAAkB,EAClB,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/packages/privilege-broker/dist/index.js

@@ -0,0 +1,5 @@
+export { loadRegistry } from "./registry.js";
+export { registerApprovalClass, checkApproval, clearApprovalCache, } from "./approval.js";
+export { NoOpAuditLogger, ConsoleAuditLogger, FileAuditLogger, } from "./audit.js";
+export { BrokerExecutor } from "./executor.js";
+//# sourceMappingURL=index.js.map

package/packages/privilege-broker/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiCA,OAAO,EAAE,YAAY,EAA+B,MAAM,eAAe,CAAC;AAC1E,OAAO,EAEN,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,eAAe,EACf,kBAAkB,EAClB,eAAe,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/packages/privilege-broker/dist/registry.d.ts

@@ -0,0 +1,15 @@
+import type { PrivilegeRegistry } from "./types.js";
+export declare class PrivilegeRegistryError extends Error {
+    constructor(msg: string);
+}
+/** Default location relative to the package root. */
+export declare const DEFAULT_PRIVILEGES_PATH: string;
+/**
+ * Load and validate the privilege registry from a YAML file.
+ *
+ * @throws {PrivilegeRegistryError} if the file is missing or invalid
+ */
+export declare function loadRegistry(path?: string): PrivilegeRegistry;
+/** Lightweight validation — check required fields. */
+export declare function validate(registry: PrivilegeRegistry): string[];
+//# sourceMappingURL=registry.d.ts.map

package/packages/privilege-broker/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAEX,iBAAiB,EAEjB,MAAM,YAAY,CAAC;AAEpB,qBAAa,sBAAuB,SAAQ,KAAK;IAChD,YAAY,GAAG,EAAE,MAAM,EAGtB;CACD;AAED,qDAAqD;AACrD,eAAO,MAAM,uBAAuB,QAKnC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,iBAAiB,CA6B7D;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,EAAE,CA4B9D"}

package/packages/privilege-broker/dist/registry.js

@@ -0,0 +1,76 @@
+/**
+ * Privilege Registry — RFC-0101 §7
+ *
+ * Loads config/privileges.yaml at startup and provides:
+ * - lookup(capability) → PrivilegeEntry | null
+ * - knownCapabilities() → CapabilityName[]
+ * - validate() → { valid: boolean; errors: string[] }
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { parse as parseYaml } from "yaml";
+export class PrivilegeRegistryError extends Error {
+    constructor(msg) {
+        super(`[PrivilegeRegistryError] ${msg}`);
+        this.name = "PrivilegeRegistryError";
+    }
+}
+/** Default location relative to the package root. */
+export const DEFAULT_PRIVILEGES_PATH = join(dirname(new URL(".", import.meta.url).pathname), "..", "config", "privileges.yaml");
+/**
+ * Load and validate the privilege registry from a YAML file.
+ *
+ * @throws {PrivilegeRegistryError} if the file is missing or invalid
+ */
+export function loadRegistry(path) {
+    const filePath = path ?? DEFAULT_PRIVILEGES_PATH;
+    if (!existsSync(filePath)) {
+        throw new PrivilegeRegistryError(`privileges file not found at ${filePath}. Copy config/privileges.yaml.example to config/privileges.yaml and edit it.`);
+    }
+    let raw;
+    try {
+        const content = readFileSync(filePath, "utf8");
+        raw = parseYaml(content);
+    }
+    catch (err) {
+        throw new PrivilegeRegistryError(`failed to parse ${filePath}: ${err.message}`);
+    }
+    const registry = raw;
+    // Validate
+    const errors = validate(registry);
+    if (errors.length > 0) {
+        throw new PrivilegeRegistryError(`validation errors in ${filePath}:\n  ${errors.join("\n  ")}`);
+    }
+    return registry;
+}
+/** Lightweight validation — check required fields. */
+export function validate(registry) {
+    const errors = [];
+    if (!registry || typeof registry !== "object") {
+        errors.push("registry must be an object");
+        return errors;
+    }
+    if (typeof registry.version !== "number") {
+        errors.push("registry.version is required and must be a number");
+    }
+    if (!Array.isArray(registry.capabilities)) {
+        errors.push("registry.capabilities must be an array");
+        return errors;
+    }
+    for (const cap of registry.capabilities) {
+        if (!cap.capability) {
+            errors.push("each capability must have a 'capability' field");
+        }
+        if (!cap.description) {
+            errors.push(`capability ${cap.capability} missing 'description'`);
+        }
+        if (!cap.approval_class) {
+            errors.push(`capability ${cap.capability} missing 'approval_class'`);
+        }
+        if (!cap.actors || typeof cap.actors !== "object") {
+            errors.push(`capability ${cap.capability} missing 'actors' object`);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=registry.js.map