kcp-harness 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/audit.d.ts

@@ -0,0 +1,73 @@
+import type { Classification } from "./classifier.js";
+import type { GovernanceDecision } from "./governor.js";
+import type { LedgerSnapshot } from "./budget-ledger.js";
+import type { DriftResult } from "./temporal-watch.js";
+/** Event types for structured audit logging. */
+export type AuditEventType = "tool_call" | "session_start" | "session_end" | "budget_spend" | "budget_exceeded" | "temporal_drift" | "plan_invalidated";
+/** A single audit event. */
+export interface AuditEvent {
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** Session ID for correlation. */
+    sessionId: string;
+    /** Monotonic sequence number within the session. */
+    sequence: number;
+    /** Event type for structured filtering. */
+    type: AuditEventType;
+    /** The tool call that was intercepted (for tool_call events). */
+    toolCall?: {
+        name: string;
+        /** Sanitized arguments (sensitive values redacted). */
+        args: Record<string, unknown>;
+    };
+    /** Classification result (for tool_call events). */
+    classification?: Classification;
+    /** Governance decision (only for governed calls). */
+    governance?: GovernanceDecision;
+    /** Final outcome. */
+    outcome: "approved" | "blocked" | "pass-through" | "error";
+    /** Processing time in milliseconds. */
+    durationMs: number;
+    /** Error message if the call failed. */
+    error?: string;
+    /** Budget snapshot at time of event (for spend events). */
+    budget?: LedgerSnapshot;
+    /** Temporal drift details (for drift events). */
+    drift?: {
+        manifest: string;
+        summary: string;
+        movedUnits?: number;
+        newPlanAsOf?: string;
+    };
+}
+/** Append-only audit log writer. */
+export declare class AuditLog {
+    private readonly path;
+    private initialized;
+    constructor(path: string);
+    /** Emit an audit event to the log. */
+    emit(event: AuditEvent): void;
+    /** Get the log file path. */
+    getPath(): string;
+    private ensureDir;
+}
+/** Create an in-memory audit log for testing. */
+export declare class InMemoryAuditLog {
+    readonly events: AuditEvent[];
+    emit(event: AuditEvent): void;
+    getPath(): string;
+}
+export type AuditWriter = AuditLog | InMemoryAuditLog;
+/** Build a tool_call audit event from the processing pipeline. */
+export declare function buildEvent(sessionId: string, sequence: number, toolName: string, args: Record<string, unknown>, classification: Classification, governance: GovernanceDecision | undefined, outcome: AuditEvent["outcome"], durationMs: number, error?: string): AuditEvent;
+/** Build a session lifecycle event. */
+export declare function buildLifecycleEvent(sessionId: string, sequence: number, type: "session_start" | "session_end", details?: Record<string, unknown>): AuditEvent;
+/** Build a budget spend event. */
+export declare function buildBudgetEvent(sessionId: string, sequence: number, accepted: boolean, snapshot: LedgerSnapshot, details?: {
+    manifest?: string;
+    unitId?: string;
+    amount?: number;
+    currency?: string;
+}): AuditEvent;
+/** Build a temporal drift event. */
+export declare function buildDriftEvent(sessionId: string, sequence: number, drift: DriftResult): AuditEvent;

package/dist/audit.js

@@ -0,0 +1,142 @@
+// Audit log — append-only compliance log for every governance decision.
+//
+// Every tool call processed by the harness produces an audit event — even
+// pass-throughs (logged as "ungoverned"). The audit log is a JSONL file:
+// one JSON object per line, append-only, never truncated or rotated by
+// the harness itself. External log management handles rotation.
+//
+// The log is compliance-grade:
+// - Every event has a session ID, sequence number, and ISO timestamp
+// - Classification, governance decision, and outcome are recorded
+// - Events are atomic (one write per line, fsync'd)
+// - The log can be replayed to reconstruct the session's governance history
+// - Session lifecycle events mark boundaries (start, end, drift)
+// - Budget snapshots recorded on every spend event
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+/** Append-only audit log writer. */
+export class AuditLog {
+    path;
+    initialized = false;
+    constructor(path) {
+        this.path = path;
+    }
+    /** Emit an audit event to the log. */
+    emit(event) {
+        this.ensureDir();
+        const line = JSON.stringify(event) + "\n";
+        appendFileSync(this.path, line, "utf-8");
+    }
+    /** Get the log file path. */
+    getPath() {
+        return this.path;
+    }
+    ensureDir() {
+        if (this.initialized)
+            return;
+        mkdirSync(dirname(this.path), { recursive: true });
+        this.initialized = true;
+    }
+}
+/** Create an in-memory audit log for testing. */
+export class InMemoryAuditLog {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+    }
+    getPath() {
+        return ":memory:";
+    }
+}
+/** Build a tool_call audit event from the processing pipeline. */
+export function buildEvent(sessionId, sequence, toolName, args, classification, governance, outcome, durationMs, error) {
+    return {
+        timestamp: new Date().toISOString(),
+        sessionId,
+        sequence,
+        type: "tool_call",
+        toolCall: { name: toolName, args: sanitizeArgs(toolName, args) },
+        classification,
+        governance: governance ? sanitizeDecision(governance) : undefined,
+        outcome,
+        durationMs,
+        error,
+    };
+}
+/** Build a session lifecycle event. */
+export function buildLifecycleEvent(sessionId, sequence, type, details) {
+    return {
+        timestamp: new Date().toISOString(),
+        sessionId,
+        sequence,
+        type,
+        outcome: "approved",
+        durationMs: 0,
+        ...(details ? { toolCall: { name: type, args: details } } : {}),
+    };
+}
+/** Build a budget spend event. */
+export function buildBudgetEvent(sessionId, sequence, accepted, snapshot, details) {
+    return {
+        timestamp: new Date().toISOString(),
+        sessionId,
+        sequence,
+        type: accepted ? "budget_spend" : "budget_exceeded",
+        outcome: accepted ? "approved" : "blocked",
+        durationMs: 0,
+        budget: snapshot,
+        ...(details ? { toolCall: { name: accepted ? "budget_spend" : "budget_exceeded", args: details } } : {}),
+    };
+}
+/** Build a temporal drift event. */
+export function buildDriftEvent(sessionId, sequence, drift) {
+    return {
+        timestamp: new Date().toISOString(),
+        sessionId,
+        sequence,
+        type: "temporal_drift",
+        outcome: "blocked",
+        durationMs: 0,
+        drift: {
+            manifest: drift.manifest,
+            summary: drift.summary,
+            movedUnits: drift.diff?.moves.length,
+            newPlanAsOf: drift.diff?.b.asOf,
+        },
+    };
+}
+/** Redact sensitive values from tool arguments for audit logging. */
+function sanitizeArgs(toolName, args) {
+    const sanitized = { ...args };
+    // Redact content from Write calls (could be large/sensitive)
+    if (toolName === "Write" && sanitized["content"]) {
+        const content = String(sanitized["content"]);
+        sanitized["content"] = `[${content.length} chars redacted]`;
+    }
+    // Redact Bash commands that might contain secrets
+    if (toolName === "Bash" && sanitized["command"]) {
+        const cmd = String(sanitized["command"]);
+        // Redact values after common secret-passing patterns
+        sanitized["command"] = cmd.replace(/(?:password|secret|token|key|api[_-]?key)\s*[=:]\s*\S+/gi, (match) => match.replace(/[=:]\s*\S+/, "=[REDACTED]"));
+    }
+    return sanitized;
+}
+/** Strip the full plan from governance decisions to keep logs compact. */
+function sanitizeDecision(decision) {
+    const { plan, trace, ...rest } = decision;
+    return {
+        ...rest,
+        // Keep plan metadata but strip unit content
+        plan: plan
+            ? {
+                ...plan,
+                selected: plan.selected.map((u) => ({
+                    ...u,
+                    // Keep everything — PlannedUnit doesn't contain content
+                })),
+            }
+            : undefined,
+        // Omit full trace from audit (it's large); the trace is available via kcp_trace
+        trace: undefined,
+    };
+}

package/dist/budget-ledger.d.ts

@@ -0,0 +1,85 @@
+/** A single spend event. */
+export interface LedgerEntry {
+    /** Monotonic sequence within the ledger. */
+    seq: number;
+    /** ISO 8601 timestamp. */
+    timestamp: string;
+    /** What triggered the spend. */
+    source: LedgerSource;
+    /** The cost. */
+    cost: LedgerCost;
+    /** Running total after this entry (per currency). */
+    runningTotal: Record<string, number>;
+}
+/** What triggered a spend event. */
+export interface LedgerSource {
+    /** The manifest that produced the plan. */
+    manifest: string;
+    /** The unit that incurred the cost (if unit-level). */
+    unitId?: string;
+    /** The task that prompted the plan. */
+    task: string;
+    /** Audit sequence number for correlation. */
+    auditSequence?: number;
+}
+/** The cost of a spend event. */
+export interface LedgerCost {
+    /** Amount spent. */
+    amount: number;
+    /** Currency (default: USDC). */
+    currency: string;
+    /** Payment method used. */
+    method: string;
+    /** Human-readable note. */
+    note?: string;
+}
+/** Budget ceiling configuration. */
+export interface BudgetCeiling {
+    amount: number;
+    currency: string;
+}
+/** Result of attempting to record a spend. */
+export interface SpendResult {
+    /** Whether the spend was recorded (false if it would exceed ceiling). */
+    accepted: boolean;
+    /** The ledger entry (if accepted). */
+    entry?: LedgerEntry;
+    /** Running total after this entry. */
+    total: number;
+    /** Remaining budget (if ceiling is set). */
+    remaining?: number;
+    /** Reason for rejection (if not accepted). */
+    reason?: string;
+}
+/** Budget ledger — append-only spend tracking for a session. */
+export declare class BudgetLedger {
+    private entries;
+    private totals;
+    private ceiling?;
+    private nextSeq;
+    constructor(ceiling?: BudgetCeiling);
+    /** Record a spend event. Returns whether it was accepted. */
+    record(source: LedgerSource, cost: LedgerCost): SpendResult;
+    /** Record spend from a plan's projected costs (convenience). */
+    recordPlanSpend(manifest: string, task: string, projectedSpend: number, currency: string, auditSequence?: number): SpendResult;
+    /** Record spend for a specific unit (fine-grained). */
+    recordUnitSpend(manifest: string, unitId: string, task: string, amount: number, currency: string, method: string, auditSequence?: number): SpendResult;
+    /** Get the current total for a currency. */
+    getTotal(currency?: string): number;
+    /** Get remaining budget (if ceiling is set). */
+    getRemaining(): number | undefined;
+    /** Get all entries. */
+    getEntries(): readonly LedgerEntry[];
+    /** Get the ceiling configuration. */
+    getCeiling(): BudgetCeiling | undefined;
+    /** Get a summary snapshot. */
+    snapshot(): LedgerSnapshot;
+}
+/** A point-in-time snapshot of the ledger. */
+export interface LedgerSnapshot {
+    ceiling?: BudgetCeiling;
+    totals: Record<string, number>;
+    remaining?: number;
+    entryCount: number;
+    lastEntry?: LedgerEntry;
+}

package/dist/budget-ledger.js

@@ -0,0 +1,100 @@
+// Budget ledger — itemized session spend tracking.
+//
+// The budget ledger records every cost event in the session: what was spent,
+// on which unit, from which manifest, and why. It maintains a running total
+// that the governor uses to enforce budget ceilings across calls.
+//
+// The ledger is the single source of truth for "how much did this session
+// cost?" — the audit log cites it, the governor consults it, and the
+// harness_budget tool exposes it.
+//
+// Design:
+// - Append-only: entries are never modified or removed
+// - Deterministic totals: running total is recomputed from entries (no drift)
+// - Currency-aware: tracks spend per currency
+// - Overflow-safe: rejects entries that would exceed the ceiling
+/** Budget ledger — append-only spend tracking for a session. */
+export class BudgetLedger {
+    entries = [];
+    totals = new Map();
+    ceiling;
+    nextSeq = 1;
+    constructor(ceiling) {
+        this.ceiling = ceiling;
+    }
+    /** Record a spend event. Returns whether it was accepted. */
+    record(source, cost) {
+        const currency = cost.currency || "USDC";
+        const currentTotal = this.totals.get(currency) ?? 0;
+        const newTotal = round6(currentTotal + cost.amount);
+        // Check ceiling
+        if (this.ceiling && currency === this.ceiling.currency) {
+            if (newTotal > this.ceiling.amount + 1e-9) {
+                return {
+                    accepted: false,
+                    total: currentTotal,
+                    remaining: round6(this.ceiling.amount - currentTotal),
+                    reason: `would exceed budget ceiling: ${newTotal} > ${this.ceiling.amount} ${currency}`,
+                };
+            }
+        }
+        // Accept
+        this.totals.set(currency, newTotal);
+        const runningTotal = Object.fromEntries(this.totals);
+        const entry = {
+            seq: this.nextSeq++,
+            timestamp: new Date().toISOString(),
+            source,
+            cost: { ...cost, currency },
+            runningTotal,
+        };
+        this.entries.push(entry);
+        return {
+            accepted: true,
+            entry,
+            total: newTotal,
+            remaining: this.ceiling && currency === this.ceiling.currency
+                ? round6(this.ceiling.amount - newTotal)
+                : undefined,
+        };
+    }
+    /** Record spend from a plan's projected costs (convenience). */
+    recordPlanSpend(manifest, task, projectedSpend, currency, auditSequence) {
+        return this.record({ manifest, task, auditSequence }, { amount: projectedSpend, currency, method: "plan-projected", note: "from plan budget projection" });
+    }
+    /** Record spend for a specific unit (fine-grained). */
+    recordUnitSpend(manifest, unitId, task, amount, currency, method, auditSequence) {
+        return this.record({ manifest, unitId, task, auditSequence }, { amount, currency, method });
+    }
+    /** Get the current total for a currency. */
+    getTotal(currency = "USDC") {
+        return this.totals.get(currency) ?? 0;
+    }
+    /** Get remaining budget (if ceiling is set). */
+    getRemaining() {
+        if (!this.ceiling)
+            return undefined;
+        return round6(this.ceiling.amount - this.getTotal(this.ceiling.currency));
+    }
+    /** Get all entries. */
+    getEntries() {
+        return this.entries;
+    }
+    /** Get the ceiling configuration. */
+    getCeiling() {
+        return this.ceiling;
+    }
+    /** Get a summary snapshot. */
+    snapshot() {
+        return {
+            ceiling: this.ceiling,
+            totals: Object.fromEntries(this.totals),
+            remaining: this.getRemaining(),
+            entryCount: this.entries.length,
+            lastEntry: this.entries.length > 0 ? this.entries[this.entries.length - 1] : undefined,
+        };
+    }
+}
+function round6(n) {
+    return Math.round(n * 1e6) / 1e6;
+}

package/dist/classifier.d.ts

@@ -0,0 +1,35 @@
+import type { GovernedDomain } from "./config.js";
+/** The result of classifying a tool call. */
+export interface Classification {
+    /** Whether this call targets a governed knowledge domain. */
+    governed: boolean;
+    /** Which governed domain matched (if any). */
+    domain?: GovernedDomain;
+    /** The path or URL that triggered the match. */
+    target?: string;
+    /** Human-readable reason for the classification. */
+    reason: string;
+}
+/**
+ * Classify a tool call: is it knowledge-navigation targeting a governed domain?
+ *
+ * Classification rules (in order):
+ * 1. KCP tools → always governed (route to kcp-agent directly)
+ * 2. Tool name in domain's `tools` list → governed by that domain
+ * 3. File path extracted from arguments → match against domain paths
+ * 4. URL extracted from arguments → match against domain URLs
+ * 5. Otherwise → pass-through (ungoverned)
+ */
+export declare function classify(toolName: string, args: Record<string, unknown>, domains: GovernedDomain[]): Classification;
+/**
+ * Extract known targets from any tool call arguments.
+ * Useful for audit logging even when not governed.
+ */
+export declare function extractTargets(toolName: string, args: Record<string, unknown>): {
+    paths: string[];
+    urls: string[];
+};
+/** Normalize a file path: strip leading ./ and trailing /, collapse //. */
+export declare function normalizePath(p: string): string;
+/** Check if a path starts with a prefix (directory-boundary-aware). */
+export declare function matchesPrefix(path: string, prefix: string): boolean;