@archmax-ai/harness 0.0.0

package/dist/core/events.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Workflow lifecycle diagnostics the harness emits during assembly and while a
+ * machine-governed workflow runs. Every runtime diagnostic flows through this
+ * single typed stream; callers subscribe via `onEvent` on
+ * `CreateWorkflowAgentOptions`. With no subscriber, the harness installs
+ * {@link consoleEventHandler} (`[workflow]` / `[interpreter]` / `[rubrics]`
+ * console output).
+ *
+ * Two visual tiers: **node-change** events (`state-enter`, `state-leave`) render
+ * at the outer level; **action** events (`hook-*`, `advance`, `agent-text`)
+ * happen within a node and render indented beneath it.
+ *
+ * `callId` pairing rule: every event a tool call causes carries that call's
+ * `callId` — its own `tool-called`/`tool-result` pair and the effects it produced
+ * (`advance`, `parked`, `variables-set`, the sub-workflow pair). An event no call
+ * caused (a turn's opening arrival, a human-node park, run-start seeding) omits
+ * the field rather than carrying a synthetic id, so the set of events one call
+ * produced is derivable from ids alone. No governed call is exempt,
+ * `archmax_advance` included.
+ */
+export type WorkflowEventLevel = "info" | "warn" | "error";
+/**
+ * The `advance.from` marker for a turn's opening arrival at its state: a
+ * transition with no prior state. Mirrors LangGraph's `START` constant, kept as
+ * a local literal so this module stays free of a LangGraph dependency.
+ */
+export declare const SESSION_ORIGIN = "__start__";
+/**
+ * Where a tool call came from, on the tool events. Absent means the model called
+ * the tool directly; a value marks a programmatic call from inside a sandbox
+ * script (`script`) or a lifecycle hook (`lifecycle`).
+ */
+export type ToolEventOrigin = "script" | "lifecycle";
+/** How a programmatic tool call's origin reads in human-facing output. */
+export declare function originLabel(origin: ToolEventOrigin): string;
+/**
+ * Event payloads, without the severity level (added by the emitter). Every
+ * `state` field carries a **state slug** — never a `title`, so a retitled node
+ * emits byte-identical events.
+ */
+export type WorkflowEventPayload = {
+    type: "interpreter-enabled";
+} | {
+    type: "skills-loaded";
+    names: string[];
+} | {
+    type: "hooks-summary";
+    summary: string;
+} | {
+    type: "graph-topology";
+    topology: string;
+} | {
+    type: "warning";
+    scope: string;
+    message: string;
+} | {
+    type: "workflow-reset";
+    entry: string;
+} | {
+    type: "state-enter";
+    state: string;
+} | {
+    type: "state-leave";
+    state: string;
+    next: string;
+} | {
+    type: "state-error-routed";
+    state: string;
+    to: string;
+    reason: string;
+} | {
+    type: "hook-start";
+    state: string;
+    phase: "before" | "after";
+    label: string;
+} | {
+    type: "hook-output";
+    state: string;
+    line: string;
+} | {
+    type: "hook-passed";
+    state: string;
+    phase: "before" | "after";
+} | {
+    type: "hook-verdict";
+    state: string;
+    phase: "before" | "after";
+    label: string;
+    /** The hook's verdict, kept as the exact kernel vocabulary (never widened). */
+    verdict: "ok" | "correct" | "veto";
+    reason: string;
+    missing?: string[];
+} | {
+    type: "hook-rejected";
+    state: string;
+    phase: "before" | "after";
+    reason: string;
+} | {
+    type: "advance";
+    from: string;
+    to: string;
+    reason?: string;
+    /**
+     * The `archmax_advance` call that drove this transition, matching its
+     * `tool-called`/`tool-result` pair. Absent for the turn's opening arrival
+     * (`from` is {@link SESSION_ORIGIN}), which the turn boundary commits
+     * rather than a call.
+     */
+    callId?: string;
+} | {
+    type: "parked";
+    /** @deprecated Older spelling of {@link state}; emitted for one release. */
+    node: string;
+    /** The state the session parked at: a human state, or the state that waits. */
+    state?: string;
+    sessionId: string;
+    /**
+     * Which channel the session awaits: a human's decision, or an external
+     * event delivered as a trigger — so a subscriber can tell a waiting run
+     * from an ended one without reading checkpoints.
+     */
+    awaiting: "decision" | "input";
+    /**
+     * For an agent park, why the agent is waiting — its own `archmax_wait`
+     * reason. This is what a surface shows: an in-place park declares no
+     * awaited trigger ids, since any delivered firing resumes it.
+     */
+    reason?: string;
+    /**
+     * Absolute time the park asked to be resumed at, when the wait declared
+     * an `until`. A hint for whoever schedules the wake-up — the runtime holds
+     * no timer.
+     */
+    resumeAt?: string;
+    /**
+     * The `archmax_wait` call that asked for this park, matching that call's
+     * `tool-called`/`tool-result` pair. Absent for a human-node park: the run
+     * routed there, and no call asked for it.
+     */
+    callId?: string;
+} | {
+    type: "decided";
+    node: string;
+    state?: string;
+    to: string;
+    sessionId: string;
+} | {
+    type: "park-message";
+    node: string;
+    state?: string;
+    sessionId: string;
+    direction: "inbound" | "outbound";
+    text: string;
+} | {
+    type: "delivered";
+    node: string;
+    state?: string;
+    /** The trigger id that resumed the park. */
+    trigger: string;
+    /**
+     * The state the run continues in — the parked node itself, since a
+     * delivery resumes in place rather than routing an edge.
+     */
+    to: string;
+    sessionId: string;
+} | {
+    type: "agent-text";
+    state: string;
+    text: string;
+    messageId?: string;
+    partial?: boolean;
+} | {
+    type: "agent-text-delta";
+    state: string;
+    text: string;
+    messageId?: string;
+} | {
+    type: "tool-called";
+    state: string;
+    tool: string;
+    callId?: string;
+    args?: Record<string, unknown>;
+    detail?: string;
+    origin?: ToolEventOrigin;
+} | {
+    type: "tool-result";
+    state: string;
+    tool: string;
+    callId: string;
+    status: "ok" | "error";
+    durationMs: number;
+    output: string;
+    truncated: boolean;
+    origin?: ToolEventOrigin;
+} | {
+    type: "variables-set";
+    /** State the write was made from, or absent for run-start seeding. */
+    state?: string;
+    names: string[];
+    locked: boolean;
+    /**
+     * The `archmax_set_variables` call that wrote them, matching that call's
+     * `tool-called`/`tool-result` pair. Absent for run-start seeding, which no
+     * call made.
+     */
+    callId?: string;
+} | {
+    type: "title-set";
+    /** The stored (trimmed) value. */
+    title: string;
+    /** State the write was made from, or absent for run-start seeding. */
+    state?: string;
+    /**
+     * The `archmax_set_variables` call that wrote it, matching that call's
+     * `tool-called`/`tool-result` pair. Absent when no call made the write.
+     */
+    callId?: string;
+} | {
+    type: "tool-blocked";
+    state: string;
+    tool: string;
+    reason: string;
+    callId?: string;
+    args?: Record<string, unknown>;
+    origin?: ToolEventOrigin;
+} | {
+    type: "rubric-start";
+    state: string;
+    name: string;
+    dispatchId: string;
+} | {
+    type: "rubric-result";
+    state: string;
+    name: string;
+    dispatchId: string;
+    status: "ok" | "error";
+    durationMs: number;
+} | {
+    type: "sub-workflow-start";
+    /** The state the call was made from. */
+    state: string;
+    /** The child workflow slug. */
+    workflow: string;
+    dispatchId: string;
+    /**
+     * The tool call that started it, when one did. Concurrent sub-runs differ
+     * in both this and `dispatchId`.
+     */
+    toolCallId?: string;
+    /** How many delegations deep this sub-run is; `1` directly under a root run. */
+    depth: number;
+    /** The ancestor chain above it, when there is one. */
+    chain?: string[];
+} | {
+    type: "sub-workflow-result";
+    state: string;
+    workflow: string;
+    dispatchId: string;
+    /** The tool call this answers, matching its `sub-workflow-start`. */
+    toolCallId?: string;
+    /**
+     * How the dispatch settled. `parked` is not an outcome but a suspension:
+     * the child reached a human node (or waited), so the *parent* suspended
+     * with it and the dispatch resumes when the decision arrives.
+     */
+    status: "ok" | "error" | "parked";
+    durationMs: number;
+    /** Why it failed; absent on success. */
+    reason?: string;
+    /**
+     * The variables the sub-run returned, by **name** — absent when its target
+     * declares no `returns`. Names only, never values (this is a diagnostic
+     * channel); the values reach the parent as its `result:` variable.
+     */
+    returns?: string[];
+} | {
+    type: "model-usage";
+    state: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    model?: string;
+    costUsd?: number;
+} | {
+    type: "prompt-shaping";
+    cache: string;
+    withheld: string[];
+};
+/**
+ * Metadata stamped on every delivered event: emission time, a sequence number
+ * that is strictly increasing across all events delivered to the same handler
+ * (i.e. the same assembled agent), and — when a session context is bound — the
+ * session the event belongs to, so one handler can demultiplex concurrent runs.
+ */
+export interface WorkflowEventEnvelope {
+    ts: number;
+    seq: number;
+    sessionId?: string;
+    /**
+     * The sub-workflow dispatch this event was emitted inside, when it was. A
+     * sub-run has its own session but shares its caller's event handler, so
+     * without this a child's `state-enter` would read as the parent moving to
+     * that state. Absent for everything a run does on its own behalf.
+     */
+    subWorkflowDispatchId?: string;
+}
+/** A lifecycle event as delivered to subscribers: payload, severity, envelope. */
+export type WorkflowLifecycleEvent = WorkflowEventPayload & {
+    level: WorkflowEventLevel;
+} & WorkflowEventEnvelope;
+/** Callback signature for {@link WorkflowLifecycleEvent} subscribers. */
+export type WorkflowEventHandler = (event: WorkflowLifecycleEvent) => void;
+/** Payload with an optional explicit level override (else derived per type). */
+export type WorkflowEventInput = WorkflowEventPayload & {
+    level?: WorkflowEventLevel;
+};
+/** Internal emitter shape: accepts payloads, fills in the level, delivers. */
+export type WorkflowEventEmitter = (event: WorkflowEventInput) => void;
+/** What the ambient binding contributes to every event's envelope. */
+export interface EventContext {
+    sessionId: string;
+    /** Set while a sub-run executes, so its events can be told from its parent's. */
+    subWorkflowDispatchId?: string;
+}
+/**
+ * Run `fn` with the ambient event-envelope context bound. Nested calls
+ * **inherit** what they do not override: a sub-run binds its dispatch id without
+ * having to restate the session id it is running on.
+ */
+export declare function withEventContext<T>(context: Partial<EventContext> & {
+    sessionId?: string;
+}, fn: () => T): T;
+/**
+ * Build the runtime's event emitter: fills in each event's severity level and
+ * envelope (`ts`, `seq`, ambient `sessionId`) and delivers it to `handler`,
+ * defaulting to {@link consoleEventHandler} so diagnostics are never silently
+ * dropped.
+ */
+export declare function createWorkflowEventEmitter(handler?: WorkflowEventHandler): WorkflowEventEmitter;
+/**
+ * The default console line for an event, or `null` for events the console
+ * output does not show (`tool-called`, `agent-text`).
+ */
+export declare function renderEventLine(event: WorkflowLifecycleEvent): string | null;
+/**
+ * Default subscriber: renders events with the established console prefixes.
+ * Installed by the harness when the caller supplies no `onEvent` handler.
+ */
+export declare const consoleEventHandler: WorkflowEventHandler;

package/dist/core/events.js

@@ -0,0 +1,205 @@
+/**
+ * Workflow lifecycle diagnostics the harness emits during assembly and while a
+ * machine-governed workflow runs. Every runtime diagnostic flows through this
+ * single typed stream; callers subscribe via `onEvent` on
+ * `CreateWorkflowAgentOptions`. With no subscriber, the harness installs
+ * {@link consoleEventHandler} (`[workflow]` / `[interpreter]` / `[rubrics]`
+ * console output).
+ *
+ * Two visual tiers: **node-change** events (`state-enter`, `state-leave`) render
+ * at the outer level; **action** events (`hook-*`, `advance`, `agent-text`)
+ * happen within a node and render indented beneath it.
+ *
+ * `callId` pairing rule: every event a tool call causes carries that call's
+ * `callId` — its own `tool-called`/`tool-result` pair and the effects it produced
+ * (`advance`, `parked`, `variables-set`, the sub-workflow pair). An event no call
+ * caused (a turn's opening arrival, a human-node park, run-start seeding) omits
+ * the field rather than carrying a synthetic id, so the set of events one call
+ * produced is derivable from ids alone. No governed call is exempt,
+ * `archmax_advance` included.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * The `advance.from` marker for a turn's opening arrival at its state: a
+ * transition with no prior state. Mirrors LangGraph's `START` constant, kept as
+ * a local literal so this module stays free of a LangGraph dependency.
+ */
+export const SESSION_ORIGIN = "__start__";
+/** How a programmatic tool call's origin reads in human-facing output. */
+export function originLabel(origin) {
+    return origin === "script" ? "script" : "lifecycle hook";
+}
+function defaultLevel(event) {
+    switch (event.type) {
+        case "warning":
+        case "tool-blocked":
+        case "hook-rejected":
+            return "warn";
+        case "tool-result":
+        case "rubric-result":
+        case "sub-workflow-result":
+            return event.status === "error" ? "warn" : "info";
+        default:
+            return "info";
+    }
+}
+/**
+ * Ambient session binding for the event envelope. The turn runner binds it
+ * around each invoke so every event emitted while a session executes — from any
+ * emitter instance — carries that session's id without threading it through
+ * every emit call site.
+ */
+const eventContext = new AsyncLocalStorage();
+/**
+ * Run `fn` with the ambient event-envelope context bound. Nested calls
+ * **inherit** what they do not override: a sub-run binds its dispatch id without
+ * having to restate the session id it is running on.
+ */
+export function withEventContext(context, fn) {
+    const current = eventContext.getStore();
+    const merged = {
+        sessionId: context.sessionId ?? current?.sessionId ?? "",
+        ...(context.subWorkflowDispatchId ?? current?.subWorkflowDispatchId
+            ? {
+                subWorkflowDispatchId: context.subWorkflowDispatchId ?? current?.subWorkflowDispatchId,
+            }
+            : {}),
+    };
+    return eventContext.run(merged, fn);
+}
+/**
+ * Per-handler sequence counters. Many emitter instances deliver to one
+ * handler (one assembled agent), so the counter is keyed by the handler to
+ * keep `seq` strictly increasing across everything that agent observes.
+ */
+const seqByHandler = new WeakMap();
+function nextSeq(handler) {
+    let counter = seqByHandler.get(handler);
+    if (!counter) {
+        counter = { n: 0 };
+        seqByHandler.set(handler, counter);
+    }
+    return ++counter.n;
+}
+/**
+ * Build the runtime's event emitter: fills in each event's severity level and
+ * envelope (`ts`, `seq`, ambient `sessionId`) and delivers it to `handler`,
+ * defaulting to {@link consoleEventHandler} so diagnostics are never silently
+ * dropped.
+ */
+export function createWorkflowEventEmitter(handler) {
+    const deliver = handler ?? consoleEventHandler;
+    return (event) => {
+        const { level, ...payload } = event;
+        const sessionId = payload.sessionId ?? eventContext.getStore()?.sessionId;
+        const dispatchId = eventContext.getStore()?.subWorkflowDispatchId;
+        deliver({
+            ...payload,
+            level: level ?? defaultLevel(payload),
+            ts: Date.now(),
+            seq: nextSeq(deliver),
+            ...(sessionId ? { sessionId } : {}),
+            ...(dispatchId ? { subWorkflowDispatchId: dispatchId } : {}),
+        });
+    };
+}
+/**
+ * The default console line for an event, or `null` for events the console
+ * output does not show (`tool-called`, `agent-text`).
+ */
+export function renderEventLine(event) {
+    switch (event.type) {
+        case "interpreter-enabled":
+            return "[interpreter] enabled (ptc: all agent tools)";
+        case "skills-loaded":
+            return `[skills] loaded: ${event.names.join(", ")}`;
+        case "hooks-summary":
+            return `[workflow] lifecycle: ${event.summary}`;
+        case "graph-topology":
+            return `[workflow] LangGraph graph:\n  ${event.topology}`;
+        case "warning":
+            return `[${event.scope}] ${event.message}`;
+        case "workflow-reset":
+            return `[workflow] reset to entry '${event.entry}'`;
+        case "state-enter":
+            return `[workflow] entering node '${event.state}'`;
+        case "state-leave":
+            return `[workflow] leaving node '${event.state}' -> workflowState=${event.next}`;
+        case "state-error-routed":
+            return `[workflow] '${event.state}' failed -> routing to on_error '${event.to}': ${event.reason}`;
+        case "hook-start":
+            return `[workflow] ${event.phase} '${event.state}': running ${event.label}`;
+        case "hook-output":
+            return `[workflow:${event.state}] ${event.line}`;
+        case "hook-passed":
+            return `[workflow] '${event.state}' ${event.phase}-script passed`;
+        case "hook-verdict": {
+            const missing = event.missing?.length ? ` (missing: ${event.missing.join(", ")})` : "";
+            return `[workflow:${event.state}] ${event.label}: ${event.verdict.toUpperCase()} — ${event.reason}${missing}`;
+        }
+        case "hook-rejected":
+            return `[workflow] '${event.state}' ${event.phase} REJECTED: ${event.reason}`;
+        case "advance":
+            return event.from === SESSION_ORIGIN
+                ? `[workflow] entering start state '${event.to}'`
+                : `[workflow] advanced '${event.from}' -> '${event.to}'${event.reason ? `: ${event.reason}` : ""}`;
+        case "parked":
+            return event.awaiting === "input"
+                ? `[workflow] parked in '${event.node}' awaiting an event${event.reason ? `: ${event.reason}` : ""}${event.resumeAt ? ` (due ${event.resumeAt})` : ""} (session ${event.sessionId})`
+                : `[workflow] parked at human node '${event.node}' awaiting a decision (session ${event.sessionId})`;
+        case "decided":
+            return `[workflow] decision at '${event.node}' routed to '${event.to}' (session ${event.sessionId})`;
+        case "park-message":
+            return (`[workflow] ${event.direction === "inbound" ? "message to" : "reply from"} the run parked ` +
+                `at '${event.node}' (session ${event.sessionId})`);
+        case "delivered":
+            return `[workflow] '${event.trigger}' delivered to '${event.node}', resuming it (session ${event.sessionId})`;
+        case "variables-set":
+            return `[workflow] variables set${event.state ? ` in ${event.state}` : ""}: ${event.names.join(", ")}${event.locked ? " (locked)" : ""}`;
+        case "title-set":
+            // Printed in full: the write check bounds a title to one short line, so
+            // there is nothing here to cap or elide.
+            return `[workflow] title set${event.state ? ` in ${event.state}` : ""}: ${event.title}`;
+        case "tool-blocked":
+            // A refused programmatic call says so: the reason names a tool and a
+            // state, and without this an author would look for the call in the
+            // model's transcript, where it never appears.
+            return event.origin ? `${event.reason} (called from a ${originLabel(event.origin)})` : event.reason;
+        case "prompt-shaping":
+            return (`[workflow] prompt cache ${event.cache}` +
+                (event.withheld.length ? ` (withheld: ${event.withheld.join(", ")})` : ""));
+        case "sub-workflow-start":
+            return `[workflow] running sub-workflow '${event.workflow}' from '${event.state}'`;
+        case "sub-workflow-result":
+            if (event.status === "parked") {
+                return `[workflow] sub-workflow '${event.workflow}' parked, suspending the run with it`;
+            }
+            return event.status === "ok"
+                ? `[workflow] sub-workflow '${event.workflow}' completed (${event.durationMs}ms)`
+                : `[workflow] sub-workflow '${event.workflow}' failed: ${event.reason ?? "unknown error"}`;
+        case "tool-called":
+        case "agent-text":
+        case "agent-text-delta":
+        case "tool-result":
+        case "rubric-start":
+        case "rubric-result":
+        case "model-usage":
+            // Accounting is not console output: the CLI renders its own usage footer
+            // from its own subscriber, so a line here would duplicate it.
+            return null;
+    }
+}
+/**
+ * Default subscriber: renders events with the established console prefixes.
+ * Installed by the harness when the caller supplies no `onEvent` handler.
+ */
+export const consoleEventHandler = (event) => {
+    const line = renderEventLine(event);
+    if (line == null)
+        return;
+    if (event.level === "info")
+        console.log(line);
+    else
+        console.warn(line);
+};
+//# sourceMappingURL=events.js.map

package/dist/core/events.js.map

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

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,15 @@
+export interface ParsedFrontmatter {
+    /** Parsed YAML frontmatter block (whatever shape the caller expects). */
+    data: unknown;
+    /** Markdown content after the closing `---` delimiter. */
+    body: string;
+}
+/**
+ * Parse a `---`-delimited YAML frontmatter block followed by a Markdown body,
+ * the convention shared by `SUBAGENT.md` and `WORKFLOW.md`. Returns `null` when
+ * the input has no frontmatter delimiters or the YAML block fails to parse.
+ *
+ * Delegates delimiter handling (CRLF/LF, trailing-newline, BOM) to gray-matter
+ * while parsing the YAML with the project's `yaml` engine.
+ */
+export declare function parseFrontmatter(raw: string): ParsedFrontmatter | null;

package/dist/core/frontmatter.js

@@ -0,0 +1,32 @@
+import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
+/**
+ * gray-matter engine that reuses this project's `yaml` package (YAML 1.2)
+ * instead of gray-matter's bundled `js-yaml` (YAML 1.1), so frontmatter parses
+ * with the same semantics as the rest of the runtime. gray-matter hands the
+ * block over with CRLF line endings intact, and a trailing `\r` would otherwise
+ * end up inside parsed string values, so normalize before parsing.
+ */
+const YAML_ENGINE = {
+    yaml: (input) => (parseYaml(input.replace(/\r(?=\n|$)/g, "")) ?? {}),
+};
+/**
+ * Parse a `---`-delimited YAML frontmatter block followed by a Markdown body,
+ * the convention shared by `SUBAGENT.md` and `WORKFLOW.md`. Returns `null` when
+ * the input has no frontmatter delimiters or the YAML block fails to parse.
+ *
+ * Delegates delimiter handling (CRLF/LF, trailing-newline, BOM) to gray-matter
+ * while parsing the YAML with the project's `yaml` engine.
+ */
+export function parseFrontmatter(raw) {
+    if (!matter.test(raw))
+        return null;
+    try {
+        const parsed = matter(raw, { engines: YAML_ENGINE });
+        return { data: parsed.data, body: parsed.content };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/core/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../../src/core/frontmatter.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,CAAC,KAAa,EAAU,EAAE,CAC9B,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAW;CAChE,CAAC;AASF;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QACrD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/core/listing-redact.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The line-oriented listing filter both governed-capability redactions run on.
+ *
+ * The kernel refuses a path the state may not reach, which is enforcement — but
+ * a scoped tool asks about a *directory*, not a file: `ls skills/`, `glob
+ * catalogs/**\/*.csv`, and `grep` over the root all name a scope the state may
+ * legitimately reach and would hand back everything in it. Blocking those calls
+ * outright is the wrong trade (a state with one enabled capability could then
+ * not list it), so the result is filtered instead.
+ *
+ * This is the only place governance touches a tool **result** rather than a
+ * call, and it exists because invisibility is a requirement of governance in its
+ * own right: a name the model never sees is a capability it never tries.
+ *
+ * Filtering is line-oriented because the upstream filesystem tools render
+ * line-oriented text: `ls` one entry per line, `glob` one path per line, `grep`
+ * a `<path>:` header followed by indented `  <line>: <text>` matches. A header
+ * for a hidden owner therefore suppresses its continuation lines too —
+ * otherwise the matched *content* would survive its filename.
+ */
+/**
+ * Drop from `text` every line about an owner `isHidden` refuses.
+ *
+ * `ownerOf` maps a result line's path to the governed thing that owns it (a
+ * skill slug, a mount name) or `null` when it owns none — a line no owner claims
+ * is always kept, since the state's other rules govern it.
+ *
+ * Returns the text unchanged when nothing was hidden, so a result the filter has
+ * no opinion about is passed through by identity rather than rebuilt.
+ */
+export declare function redactListing(text: string, ownerOf: (path: string) => string | null, isHidden: (owner: string) => boolean): string;
+/**
+ * The scoped file tools whose results are filtered. `read_file` is absent on
+ * purpose: it names one path, which the kernel already refuses, and filtering a
+ * file's *contents* would hand the model a silently truncated document.
+ */
+export declare const REDACTED_TOOLS: ReadonlySet<string>;