@kilnai/core 0.1.0

package/dist/sandbox/policies.d.ts

@@ -0,0 +1,38 @@
+import type { SandboxConfig } from "./index.js";
+/** Predefined sandbox configs per agent role. */
+export declare const ROLE_PRESETS: Record<string, SandboxConfig>;
+export declare class SandboxPolicy {
+    private readonly _config;
+    private readonly _projectPath;
+    private readonly _resolvedAllowedPaths;
+    private readonly _resolvedDeniedPaths;
+    constructor({ config, projectPath, }: {
+        config: SandboxConfig;
+        projectPath: string;
+    });
+    canRead(filePath: string): boolean;
+    canWrite(filePath: string): boolean;
+    private resolvePathAccess;
+    canAccess(domain: string): boolean;
+    get config(): SandboxConfig;
+    get projectPath(): string;
+    toJSON(): {
+        config: SandboxConfig;
+        projectPath: string;
+        resolvedAllowedPaths: readonly string[];
+        resolvedDeniedPaths: readonly string[];
+    };
+}
+export declare function createPolicy(role: string, projectPath: string, overrides?: Partial<SandboxConfig>): SandboxPolicy;
+/**
+ * Create a tenant-scoped filesystem jail.
+ * The tenant is allowed read-write access only within `<basePath>/tenants/<tenantId>`.
+ * Access to other tenant directories is blocked because only the tenant's own dir is in allowedPaths.
+ * The parent `<basePath>/tenants` is explicitly denied to block directory listing of all tenants.
+ * Note: allowedPaths is checked after deniedPaths in SandboxPolicy -- so the tenant dir is placed in
+ * allowedPaths and the parent-deny ensures other tenants are unreachable even if allowedPaths
+ * matching were to fail. The tenant's own dir does NOT start-with a different tenant's allowed path,
+ * so cross-tenant access is blocked by the allowedPaths whitelist.
+ */
+export declare function createTenantSandbox(tenantId: string, basePath: string, basePolicy?: SandboxConfig): SandboxConfig;
+//# sourceMappingURL=policies.d.ts.map

package/dist/sandbox/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../../src/sandbox/policies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,iDAAiD;AACjD,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CA2CtD,CAAC;AAEF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAoB;IAC1D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAoB;gBAE7C,EACV,MAAM,EACN,WAAW,GACZ,EAAE;QACD,MAAM,EAAE,aAAa,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;KACrB;IAcD,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKlC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKnC,OAAO,CAAC,iBAAiB;IAsBzB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAUlC,IAAI,MAAM,IAAI,aAAa,CAE1B;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,MAAM,IAAI;QACR,MAAM,EAAE,aAAa,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;KACxC;CAQF;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GACjC,aAAa,CAUf;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,aAAa,GACzB,aAAa,CAUf"}

package/dist/sandbox/policies.js

@@ -0,0 +1,145 @@
+import { resolve } from "node:path";
+/** Predefined sandbox configs per agent role. */
+export const ROLE_PRESETS = {
+    architect: {
+        fsPolicy: "read-only",
+        netPolicy: "documentation",
+        allowedPaths: [],
+        deniedPaths: [],
+        allowedDomains: ["*"],
+    },
+    worker: {
+        fsPolicy: "read-write",
+        netPolicy: "package-managers",
+        allowedPaths: [],
+        deniedPaths: [
+            "/etc",
+            "/usr",
+            "/bin",
+            "/sbin",
+            "/var",
+            "C:\\Windows",
+            "C:\\Program Files",
+        ],
+        allowedDomains: [
+            "registry.npmjs.org",
+            "pypi.org",
+            "proxy.golang.org",
+            "plugins.gradle.org",
+            "repo.maven.apache.org",
+        ],
+    },
+    optimizer: {
+        fsPolicy: "read-only",
+        netPolicy: "none",
+        allowedPaths: [],
+        deniedPaths: [],
+        allowedDomains: [],
+    },
+    researcher: {
+        fsPolicy: "read-only",
+        netPolicy: "full",
+        allowedPaths: [],
+        deniedPaths: [],
+        allowedDomains: ["*"],
+    },
+};
+export class SandboxPolicy {
+    _config;
+    _projectPath;
+    _resolvedAllowedPaths;
+    _resolvedDeniedPaths;
+    constructor({ config, projectPath, }) {
+        this._config = config;
+        this._projectPath = projectPath;
+        // Default allowedPaths to project dir for read-write policies
+        const allowed = config.allowedPaths.length === 0 && config.fsPolicy === "read-write"
+            ? [resolve(projectPath)]
+            : config.allowedPaths.map((p) => resolve(p));
+        this._resolvedAllowedPaths = allowed;
+        this._resolvedDeniedPaths = config.deniedPaths.map((p) => resolve(p));
+    }
+    canRead(filePath) {
+        if (this._config.fsPolicy === "none")
+            return false;
+        return this.resolvePathAccess(resolve(filePath));
+    }
+    canWrite(filePath) {
+        if (this._config.fsPolicy !== "read-write")
+            return false;
+        return this.resolvePathAccess(resolve(filePath));
+    }
+    resolvePathAccess(resolvedPath) {
+        const matchedAllow = this._resolvedAllowedPaths
+            .filter((a) => resolvedPath.startsWith(a))
+            .reduce((best, a) => (best === null || a.length > best.length ? a : best), null);
+        const matchedDeny = this._resolvedDeniedPaths
+            .filter((d) => resolvedPath.startsWith(d))
+            .reduce((best, d) => (best === null || d.length > best.length ? d : best), null);
+        if (matchedAllow !== null && matchedDeny !== null) {
+            return matchedAllow.length >= matchedDeny.length;
+        }
+        if (matchedDeny !== null)
+            return false;
+        if (this._resolvedAllowedPaths.length > 0) {
+            return matchedAllow !== null;
+        }
+        return true;
+    }
+    canAccess(domain) {
+        if (this._config.netPolicy === "none")
+            return false;
+        if (this._config.netPolicy === "full")
+            return true;
+        if (this._config.allowedDomains.includes("*"))
+            return true;
+        return this._config.allowedDomains.some((allowed) => domain === allowed || domain.endsWith(`.${allowed}`));
+    }
+    get config() {
+        return this._config;
+    }
+    get projectPath() {
+        return this._projectPath;
+    }
+    toJSON() {
+        return {
+            config: this._config,
+            projectPath: this._projectPath,
+            resolvedAllowedPaths: this._resolvedAllowedPaths,
+            resolvedDeniedPaths: this._resolvedDeniedPaths,
+        };
+    }
+}
+export function createPolicy(role, projectPath, overrides) {
+    const preset = ROLE_PRESETS[role] ?? ROLE_PRESETS["worker"];
+    const config = {
+        fsPolicy: overrides?.fsPolicy ?? preset.fsPolicy,
+        netPolicy: overrides?.netPolicy ?? preset.netPolicy,
+        allowedPaths: overrides?.allowedPaths ?? preset.allowedPaths,
+        deniedPaths: overrides?.deniedPaths ?? preset.deniedPaths,
+        allowedDomains: overrides?.allowedDomains ?? preset.allowedDomains,
+    };
+    return new SandboxPolicy({ config, projectPath });
+}
+/**
+ * Create a tenant-scoped filesystem jail.
+ * The tenant is allowed read-write access only within `<basePath>/tenants/<tenantId>`.
+ * Access to other tenant directories is blocked because only the tenant's own dir is in allowedPaths.
+ * The parent `<basePath>/tenants` is explicitly denied to block directory listing of all tenants.
+ * Note: allowedPaths is checked after deniedPaths in SandboxPolicy -- so the tenant dir is placed in
+ * allowedPaths and the parent-deny ensures other tenants are unreachable even if allowedPaths
+ * matching were to fail. The tenant's own dir does NOT start-with a different tenant's allowed path,
+ * so cross-tenant access is blocked by the allowedPaths whitelist.
+ */
+export function createTenantSandbox(tenantId, basePath, basePolicy) {
+    const tenantDir = resolve(basePath, "tenants", tenantId);
+    const tenantsRoot = resolve(basePath, "tenants");
+    return {
+        fsPolicy: "read-write",
+        allowedPaths: [tenantDir],
+        deniedPaths: [tenantsRoot],
+        netPolicy: basePolicy?.netPolicy ?? "none",
+        allowedDomains: basePolicy?.allowedDomains ?? [],
+    };
+}
+//# sourceMappingURL=policies.js.map

package/dist/sandbox/policies.js.map

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

package/dist/security/audit-log.d.ts

@@ -0,0 +1,17 @@
+import type { AuditEntry, AuditFilter, AuditChainResult, AuditLog } from "./types.js";
+export declare class JsonlAuditLog implements AuditLog {
+    private readonly logPath;
+    private readonly hashChaining;
+    private lastHash;
+    private entryCount;
+    constructor(logPath: string, options?: {
+        hashChaining?: boolean;
+    });
+    append(entry: Omit<AuditEntry, "id" | "hash" | "previousHash">): AuditEntry;
+    query(filter: AuditFilter): readonly AuditEntry[];
+    verifyChain(fromIndex?: number, toIndex?: number): AuditChainResult;
+    count(): number;
+    private readAllEntries;
+    private loadState;
+}
+//# sourceMappingURL=audit-log.d.ts.map

package/dist/security/audit-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.d.ts","sourceRoot":"","sources":["../../src/security/audit-log.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAgEtF,qBAAa,aAAc,YAAW,QAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE;IAoBjE,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,MAAM,GAAG,cAAc,CAAC,GAAG,UAAU;IAuC3E,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,UAAU,EAAE;IA+BjD,WAAW,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB;IAwCnE,KAAK,IAAI,MAAM;IAIf,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,SAAS;CAWlB"}

package/dist/security/audit-log.js

@@ -0,0 +1,214 @@
+// Append-only JSONL audit log with SHA-256 hash chaining for tamper detection
+import { createHash } from "node:crypto";
+import { appendFileSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { KilnError } from "../engine/errors.js";
+const GENESIS_HASH = "genesis";
+/** Deterministic JSON serialization with sorted keys */
+function canonicalJson(obj) {
+    return JSON.stringify(obj, Object.keys(obj).sort());
+}
+/** Compute SHA-256 hash of entry content + previous hash */
+function computeHash(entry, previousHash) {
+    const payload = {
+        id: entry.id,
+        timestamp: entry.timestamp instanceof Date ? entry.timestamp.toISOString() : entry.timestamp,
+        action: entry.action,
+        actor: entry.actor,
+        resource: entry.resource,
+        outcome: entry.outcome,
+        previousHash,
+    };
+    if (entry.metadata !== undefined)
+        payload["metadata"] = entry.metadata;
+    if (entry.tenantId !== undefined)
+        payload["tenantId"] = entry.tenantId;
+    if (entry.sessionId !== undefined)
+        payload["sessionId"] = entry.sessionId;
+    const content = canonicalJson(payload);
+    return createHash("sha256").update(content).digest("hex");
+}
+/** Serialize an AuditEntry to a JSON line for file storage */
+function serializeEntry(entry) {
+    const obj = {
+        id: entry.id,
+        timestamp: entry.timestamp instanceof Date ? entry.timestamp.toISOString() : entry.timestamp,
+        action: entry.action,
+        actor: entry.actor,
+        resource: entry.resource,
+        outcome: entry.outcome,
+    };
+    if (entry.metadata !== undefined)
+        obj["metadata"] = entry.metadata;
+    if (entry.tenantId !== undefined)
+        obj["tenantId"] = entry.tenantId;
+    if (entry.sessionId !== undefined)
+        obj["sessionId"] = entry.sessionId;
+    if (entry.hash !== undefined)
+        obj["hash"] = entry.hash;
+    if (entry.previousHash !== undefined)
+        obj["previousHash"] = entry.previousHash;
+    return JSON.stringify(obj);
+}
+/** Deserialize a JSON line back to an AuditEntry */
+function deserializeEntry(line) {
+    const obj = JSON.parse(line);
+    return {
+        id: obj["id"],
+        timestamp: new Date(obj["timestamp"]),
+        action: obj["action"],
+        actor: obj["actor"],
+        resource: obj["resource"],
+        outcome: obj["outcome"],
+        metadata: obj["metadata"],
+        tenantId: obj["tenantId"],
+        sessionId: obj["sessionId"],
+        hash: obj["hash"],
+        previousHash: obj["previousHash"],
+    };
+}
+export class JsonlAuditLog {
+    logPath;
+    hashChaining;
+    lastHash;
+    entryCount;
+    constructor(logPath, options) {
+        this.logPath = logPath;
+        this.hashChaining = options?.hashChaining ?? true;
+        // Ensure directory exists
+        const dir = dirname(logPath);
+        mkdirSync(dir, { recursive: true });
+        // Initialize from existing file or create empty
+        if (existsSync(logPath)) {
+            const { count, lastHash } = this.loadState();
+            this.entryCount = count;
+            this.lastHash = lastHash;
+        }
+        else {
+            writeFileSync(logPath, "", "utf-8");
+            this.entryCount = 0;
+            this.lastHash = GENESIS_HASH;
+        }
+    }
+    append(entry) {
+        const id = crypto.randomUUID();
+        const previousHash = this.lastHash;
+        const fullEntry = {
+            ...entry,
+            id,
+            timestamp: entry.timestamp instanceof Date ? entry.timestamp : new Date(entry.timestamp),
+            previousHash: this.hashChaining ? previousHash : undefined,
+            hash: undefined,
+        };
+        const hash = this.hashChaining
+            ? computeHash(fullEntry, previousHash)
+            : undefined;
+        const finalEntry = {
+            ...fullEntry,
+            hash,
+        };
+        try {
+            const line = serializeEntry(finalEntry) + "\n";
+            appendFileSync(this.logPath, line, "utf-8");
+        }
+        catch (err) {
+            throw new KilnError("AUDIT_WRITE_FAILED", "Failed to write audit log entry", {
+                context: { id, action: entry.action },
+                cause: err,
+            });
+        }
+        if (this.hashChaining && hash) {
+            this.lastHash = hash;
+        }
+        this.entryCount++;
+        return finalEntry;
+    }
+    query(filter) {
+        const entries = this.readAllEntries();
+        let filtered = entries;
+        if (filter.action) {
+            filtered = filtered.filter((e) => e.action === filter.action);
+        }
+        if (filter.actor) {
+            filtered = filtered.filter((e) => e.actor === filter.actor);
+        }
+        if (filter.tenantId) {
+            filtered = filtered.filter((e) => e.tenantId === filter.tenantId);
+        }
+        if (filter.outcome) {
+            filtered = filtered.filter((e) => e.outcome === filter.outcome);
+        }
+        if (filter.since) {
+            const since = filter.since.getTime();
+            filtered = filtered.filter((e) => e.timestamp.getTime() >= since);
+        }
+        if (filter.until) {
+            const until = filter.until.getTime();
+            filtered = filtered.filter((e) => e.timestamp.getTime() <= until);
+        }
+        if (filter.limit !== undefined && filter.limit > 0) {
+            filtered = filtered.slice(0, filter.limit);
+        }
+        return filtered;
+    }
+    verifyChain(fromIndex, toIndex) {
+        if (!this.hashChaining) {
+            return { valid: true, entriesChecked: 0 };
+        }
+        const entries = this.readAllEntries();
+        const start = fromIndex ?? 0;
+        const end = toIndex !== undefined ? Math.min(toIndex + 1, entries.length) : entries.length;
+        if (entries.length === 0) {
+            return { valid: true, entriesChecked: 0 };
+        }
+        for (let i = start; i < end; i++) {
+            const entry = entries[i];
+            const expectedPreviousHash = i === 0 ? GENESIS_HASH : entries[i - 1].hash;
+            if (entry.previousHash !== expectedPreviousHash) {
+                return {
+                    valid: false,
+                    entriesChecked: i - start + 1,
+                    brokenAt: i,
+                    error: `Chain broken at index ${i}: previousHash mismatch`,
+                };
+            }
+            const recomputedHash = computeHash(entry, expectedPreviousHash);
+            if (entry.hash !== recomputedHash) {
+                return {
+                    valid: false,
+                    entriesChecked: i - start + 1,
+                    brokenAt: i,
+                    error: `Chain broken at index ${i}: hash mismatch (tampered entry)`,
+                };
+            }
+        }
+        return { valid: true, entriesChecked: end - start };
+    }
+    count() {
+        return this.entryCount;
+    }
+    readAllEntries() {
+        if (!existsSync(this.logPath))
+            return [];
+        const content = readFileSync(this.logPath, "utf-8").trim();
+        if (content.length === 0)
+            return [];
+        return content
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map(deserializeEntry);
+    }
+    loadState() {
+        const entries = this.readAllEntries();
+        if (entries.length === 0) {
+            return { count: 0, lastHash: GENESIS_HASH };
+        }
+        const lastEntry = entries[entries.length - 1];
+        return {
+            count: entries.length,
+            lastHash: lastEntry.hash ?? GENESIS_HASH,
+        };
+    }
+}
+//# sourceMappingURL=audit-log.js.map

package/dist/security/audit-log.js.map

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

package/dist/security/guardian.d.ts

@@ -0,0 +1,24 @@
+import type { EventBus } from "../events/index.js";
+import type { Capability } from "../engine/domain/capability.js";
+import type { ProviderAdapter } from "../agents/index.js";
+import type { AuditLog, GuardianConfig, GuardianReviewResult } from "./types.js";
+export interface GuardianRequest {
+    readonly capability: Capability;
+    readonly agentName: string;
+    readonly arguments: Record<string, unknown>;
+    readonly context?: string;
+    readonly sessionId?: string;
+    readonly tenantId?: string;
+}
+export declare class Guardian {
+    private readonly config;
+    private readonly provider;
+    private readonly eventBus?;
+    private readonly auditLog?;
+    constructor(config: GuardianConfig, provider: ProviderAdapter, eventBus?: EventBus, auditLog?: AuditLog);
+    /** Check if a capability needs Guardian review */
+    needsReview(capability: Capability): boolean;
+    /** Review a capability execution request */
+    review(request: GuardianRequest): Promise<GuardianReviewResult>;
+}
+//# sourceMappingURL=guardian.d.ts.map

package/dist/security/guardian.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardian.d.ts","sourceRoot":"","sources":["../../src/security/guardian.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAyB,MAAM,oBAAoB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAsED,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAW;gBAGnC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,QAAQ,EACnB,QAAQ,CAAC,EAAE,QAAQ;IAQrB,kDAAkD;IAClD,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO;IAY5C,4CAA4C;IACtC,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAiGtE"}

package/dist/security/guardian.js

@@ -0,0 +1,177 @@
+// Guardian: secondary LLM review for destructive capability execution
+import { textParts, extractText } from "../engine/domain/content.js";
+function buildReviewPrompt(request) {
+    const { capability, agentName, arguments: args, context } = request;
+    return `You are a security reviewer. Evaluate whether this action should be allowed.
+
+Action: ${capability.name} - ${capability.description}
+Requested by: ${agentName}
+Arguments: ${JSON.stringify(args)}
+Context: ${context ?? "none"}
+
+Safety annotations:
+- Destructive: ${capability.annotations?.destructive}
+- Idempotent: ${capability.annotations?.idempotent}
+
+Respond with JSON only:
+{"approved": boolean, "reason": "explanation", "riskLevel": "low" | "medium" | "high" | "critical"}
+
+Deny if:
+- Arguments contain paths outside expected scope
+- Arguments contain shell injection patterns
+- The action could cause irreversible data loss
+- The action modifies system-level configuration
+- The arguments seem crafted to bypass safety
+
+Approve if:
+- The action is within expected scope
+- Arguments are well-formed and within normal ranges
+- The action is reversible or has safeguards`;
+}
+function parseReviewerResponse(content) {
+    try {
+        // Strip markdown code fences if present
+        const cleaned = content.replace(/```(?:json)?\n?/g, "").trim();
+        const parsed = JSON.parse(cleaned);
+        if (parsed !== null &&
+            typeof parsed === "object" &&
+            "approved" in parsed &&
+            typeof parsed["approved"] === "boolean" &&
+            "reason" in parsed &&
+            typeof parsed["reason"] === "string" &&
+            "riskLevel" in parsed &&
+            typeof parsed["riskLevel"] === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function truncateArgValues(args) {
+    const result = {};
+    for (const [key, value] of Object.entries(args)) {
+        const str = typeof value === "string" ? value : JSON.stringify(value);
+        result[key] = str.length > 100 ? str.slice(0, 100) + "..." : str;
+    }
+    return result;
+}
+export class Guardian {
+    config;
+    provider;
+    eventBus;
+    auditLog;
+    constructor(config, provider, eventBus, auditLog) {
+        this.config = config;
+        this.provider = provider;
+        this.eventBus = eventBus;
+        this.auditLog = auditLog;
+    }
+    /** Check if a capability needs Guardian review */
+    needsReview(capability) {
+        if (!this.config.enabled)
+            return false;
+        if (capability.annotations?.readOnly === true &&
+            this.config.bypassForReadOnly === true) {
+            return false;
+        }
+        if (capability.annotations?.destructive === true)
+            return true;
+        return false;
+    }
+    /** Review a capability execution request */
+    async review(request) {
+        const startedAt = Date.now();
+        const sessionId = request.sessionId ?? "unknown";
+        let approved;
+        let reason;
+        let riskLevel;
+        try {
+            const prompt = buildReviewPrompt(request);
+            const response = await this.provider.createMessage({
+                system: "You are a security reviewer that evaluates capability execution requests.",
+                messages: [{ role: "user", parts: textParts(prompt) }],
+            });
+            const parsed = parseReviewerResponse(extractText(response.parts));
+            if (parsed === null) {
+                // Malformed response -- treat as blockOnError
+                if (this.config.blockOnError) {
+                    approved = false;
+                    reason = "Guardian reviewer returned malformed response";
+                    riskLevel = "critical";
+                }
+                else {
+                    approved = true;
+                    reason = "Guardian reviewer returned malformed response, proceeding";
+                    riskLevel = "high";
+                }
+            }
+            else {
+                approved = parsed.approved;
+                reason = parsed.reason;
+                const validLevels = ["low", "medium", "high", "critical"];
+                riskLevel = validLevels.includes(parsed.riskLevel)
+                    ? parsed.riskLevel
+                    : "high";
+            }
+        }
+        catch {
+            if (this.config.blockOnError) {
+                approved = false;
+                reason = "Guardian reviewer unavailable";
+                riskLevel = "critical";
+            }
+            else {
+                approved = true;
+                reason = "Guardian reviewer unavailable, proceeding";
+                riskLevel = "high";
+            }
+        }
+        const reviewDurationMs = Date.now() - startedAt;
+        const result = {
+            approved,
+            reason,
+            reviewedBy: this.provider.name,
+            reviewDurationMs,
+            riskLevel,
+            capabilityName: request.capability.name,
+            agentName: request.agentName,
+        };
+        // Emit event
+        if (this.eventBus) {
+            const event = {
+                type: "guardian_reviewed",
+                timestamp: new Date(),
+                sessionId,
+                approved,
+                capabilityName: request.capability.name,
+                agentName: request.agentName,
+                riskLevel,
+                reason,
+            };
+            this.eventBus.emit(event);
+        }
+        // Audit log
+        if (this.auditLog) {
+            this.auditLog.append({
+                timestamp: new Date(),
+                action: approved ? "destructive_approved" : "destructive_blocked",
+                actor: request.agentName,
+                resource: request.capability.name,
+                outcome: approved ? "allowed" : "denied",
+                metadata: {
+                    riskLevel,
+                    reason,
+                    reviewedBy: this.provider.name,
+                    reviewDurationMs,
+                    arguments: truncateArgValues(request.arguments),
+                },
+                tenantId: request.tenantId,
+                sessionId: request.sessionId,
+            });
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=guardian.js.map

package/dist/security/guardian.js.map

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