@getfamiliar/shared 0.1.2

package/build/StepResultBus.d.ts

@@ -0,0 +1,64 @@
+import type { Logger } from "./logging/Logger.js";
+import type { PostgresConnection } from "./PostgresConnection.js";
+import type { NewStepResult, StepResultRow } from "./StepResult.js";
+/**
+ * Disposer returned by {@link StepResultBus.listen}. Calling it
+ * unsubscribes the handler from the underlying NOTIFY channel.
+ * Idempotent: calling more than once is safe.
+ */
+export type StepResultUnsubscribe = () => Promise<void>;
+/**
+ * Domain client for the `stepresults` audit table.
+ *
+ * INSERT-only — steps are immutable, with no claim / update semantics.
+ * The container's {@link import("./AgentRunBus").AgentRunBus} runner
+ * `add`s a row from inside `ToolLoopAgent.generate`'s `onStepFinish`;
+ * the host's `HostContextImpl` `listen`s for them inside `events.emit`
+ * to surface live step events to plugins.
+ */
+export declare class StepResultBus {
+    private readonly connection;
+    private readonly log;
+    constructor(connection: PostgresConnection, log?: Logger);
+    /**
+     * Insert a step row and return the persisted shape. The derived
+     * columns `total_tokens` (sum of input+output when both present)
+     * and `tool_call_count` (length of toolCalls array) are filled
+     * here so callers don't have to.
+     */
+    add(step: NewStepResult): Promise<StepResultRow>;
+    /**
+     * Subscribe to {@link STEPRESULTS_NEW_CHANNEL}. The notification
+     * payload (`<event_id>:<agent_run_id>:<id>`) is parsed, the row
+     * is fetched by id, and `handler` is invoked with it.
+     *
+     * Errors thrown by `handler` are caught and logged so one bad
+     * subscriber doesn't break others on the same channel.
+     *
+     * Returns a disposer; call it to unlisten. Idempotent.
+     */
+    listen(handler: (row: StepResultRow) => void | Promise<void>): Promise<StepResultUnsubscribe>;
+    /**
+     * Fetch a step by id. Useful when a notification handler has the
+     * id from the channel payload but wants the full typed row.
+     */
+    getById(id: string): Promise<StepResultRow | undefined>;
+    /**
+     * Fetch all step rows whose `created_at` is `>= since`, ordered by
+     * id. Steps are immutable so `created_at` is sufficient — no
+     * separate `updated_at` to consider.
+     */
+    listSince(since: Date): Promise<StepResultRow[]>;
+    /**
+     * Fetch every step belonging to one agentrun, ordered by step
+     * number. Used by the report layer to render an agentrun's full
+     * step list and to sum its token usage at finalization time.
+     */
+    listByAgentRunId(agentRunId: string): Promise<readonly StepResultRow[]>;
+    /**
+     * Inner notification dispatcher. Parses the channel payload,
+     * fetches the row, and invokes the handler — catching and
+     * logging any error from the handler itself.
+     */
+    private dispatchNotification;
+}

package/build/StepResultBus.js

@@ -0,0 +1,169 @@
+import { STEPRESULTS_NEW_CHANNEL } from "./Schema.js";
+/**
+ * Domain client for the `stepresults` audit table.
+ *
+ * INSERT-only — steps are immutable, with no claim / update semantics.
+ * The container's {@link import("./AgentRunBus").AgentRunBus} runner
+ * `add`s a row from inside `ToolLoopAgent.generate`'s `onStepFinish`;
+ * the host's `HostContextImpl` `listen`s for them inside `events.emit`
+ * to surface live step events to plugins.
+ */
+export class StepResultBus {
+    connection;
+    log;
+    constructor(connection, log) {
+        this.connection = connection;
+        this.log = log;
+    }
+    /**
+     * Insert a step row and return the persisted shape. The derived
+     * columns `total_tokens` (sum of input+output when both present)
+     * and `tool_call_count` (length of toolCalls array) are filled
+     * here so callers don't have to.
+     */
+    async add(step) {
+        const inputTokens = step.inputTokens ?? null;
+        const outputTokens = step.outputTokens ?? null;
+        const totalTokens = inputTokens !== null && outputTokens !== null ? inputTokens + outputTokens : null;
+        const toolCalls = step.toolCalls ?? [];
+        const toolResults = step.toolResults ?? [];
+        const toolCallCount = Array.isArray(toolCalls) ? toolCalls.length : 0;
+        const rawResultJson = step.rawResult === undefined || step.rawResult === null
+            ? null
+            : JSON.stringify(step.rawResult);
+        const result = await this.connection.getPool().query(`INSERT INTO stepresults
+                (agent_run_id, event_id, step_number, finish_reason,
+                 result_text, reasoning_text,
+                 input_tokens, output_tokens, total_tokens,
+                 input_tokens_no_cache, input_tokens_cache_read, input_tokens_cache_write,
+                 output_tokens_text, output_tokens_reasoning,
+                 tool_call_count, tool_calls, tool_results, raw_result)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15,
+                     $16::jsonb, $17::jsonb, $18::jsonb)
+             RETURNING *`, [
+            step.agentRunId,
+            step.eventId,
+            step.stepNumber,
+            step.finishReason,
+            step.resultText ?? null,
+            step.reasoningText ?? null,
+            inputTokens,
+            outputTokens,
+            totalTokens,
+            step.inputTokensNoCache ?? null,
+            step.inputTokensCacheRead ?? null,
+            step.inputTokensCacheWrite ?? null,
+            step.outputTokensText ?? null,
+            step.outputTokensReasoning ?? null,
+            toolCallCount,
+            JSON.stringify(toolCalls),
+            JSON.stringify(toolResults),
+            rawResultJson,
+        ]);
+        return mapRow(result.rows[0]);
+    }
+    /**
+     * Subscribe to {@link STEPRESULTS_NEW_CHANNEL}. The notification
+     * payload (`<event_id>:<agent_run_id>:<id>`) is parsed, the row
+     * is fetched by id, and `handler` is invoked with it.
+     *
+     * Errors thrown by `handler` are caught and logged so one bad
+     * subscriber doesn't break others on the same channel.
+     *
+     * Returns a disposer; call it to unlisten. Idempotent.
+     */
+    async listen(handler) {
+        const wrapper = (payload) => {
+            this.log?.debug({ channel: STEPRESULTS_NEW_CHANNEL, payload }, "NOTIFY stepresults_new");
+            void this.dispatchNotification(payload, handler);
+        };
+        await this.connection.listen(STEPRESULTS_NEW_CHANNEL, wrapper);
+        let disposed = false;
+        return async () => {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            await this.connection.unlisten(STEPRESULTS_NEW_CHANNEL, wrapper);
+        };
+    }
+    /**
+     * Fetch a step by id. Useful when a notification handler has the
+     * id from the channel payload but wants the full typed row.
+     */
+    async getById(id) {
+        const result = await this.connection
+            .getPool()
+            .query(`SELECT * FROM stepresults WHERE id = $1`, [id]);
+        return result.rows.length > 0 ? mapRow(result.rows[0]) : undefined;
+    }
+    /**
+     * Fetch all step rows whose `created_at` is `>= since`, ordered by
+     * id. Steps are immutable so `created_at` is sufficient — no
+     * separate `updated_at` to consider.
+     */
+    async listSince(since) {
+        const result = await this.connection.getPool().query(`SELECT * FROM stepresults
+             WHERE created_at >= $1
+             ORDER BY id`, [since]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Fetch every step belonging to one agentrun, ordered by step
+     * number. Used by the report layer to render an agentrun's full
+     * step list and to sum its token usage at finalization time.
+     */
+    async listByAgentRunId(agentRunId) {
+        const result = await this.connection.getPool().query(`SELECT * FROM stepresults
+             WHERE agent_run_id = $1
+             ORDER BY step_number`, [agentRunId]);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Inner notification dispatcher. Parses the channel payload,
+     * fetches the row, and invokes the handler — catching and
+     * logging any error from the handler itself.
+     */
+    async dispatchNotification(payload, handler) {
+        const parts = payload.split(":");
+        if (parts.length !== 3) {
+            return;
+        }
+        const [, , id] = parts;
+        try {
+            const row = await this.getById(id);
+            if (!row) {
+                return;
+            }
+            await handler(row);
+        }
+        catch (err) {
+            console.error(`StepResultBus listen handler error for id=${id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+/** Convert a snake_case raw row into the camelCase {@link StepResultRow}. */
+function mapRow(raw) {
+    return {
+        id: raw.id,
+        agentRunId: raw.agent_run_id,
+        eventId: raw.event_id,
+        stepNumber: raw.step_number,
+        finishReason: raw.finish_reason,
+        resultText: raw.result_text,
+        reasoningText: raw.reasoning_text,
+        inputTokens: raw.input_tokens,
+        outputTokens: raw.output_tokens,
+        totalTokens: raw.total_tokens,
+        inputTokensNoCache: raw.input_tokens_no_cache,
+        inputTokensCacheRead: raw.input_tokens_cache_read,
+        inputTokensCacheWrite: raw.input_tokens_cache_write,
+        outputTokensText: raw.output_tokens_text,
+        outputTokensReasoning: raw.output_tokens_reasoning,
+        toolCallCount: raw.tool_call_count,
+        toolCalls: raw.tool_calls,
+        toolResults: raw.tool_results,
+        rawResult: raw.raw_result,
+        createdAt: raw.created_at,
+    };
+}

package/build/Timezone.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Reformat a UTC ISO-8601 string as a wall-clock-with-offset string in
+ * `zone`. Used by every agent-facing surface that reads stored UTC
+ * timestamps — calendar events, scheduled handlers, etc. — so the
+ * agent always operates in `core.timezone`.
+ *
+ * Conversion failures (malformed UTC string, unknown zone) fall back
+ * to the input string unchanged so a single bad row never crashes an
+ * entire read/emit path. Handlers see the raw UTC and can flag the row.
+ *
+ * @param utcIso - UTC ISO-8601 timestamp (e.g. `2026-05-21T13:00:00Z`).
+ * @param zone   - IANA zone name (e.g. `Europe/Berlin`, `UTC`).
+ * @returns Wall-clock ISO with offset in `zone` (e.g. `2026-05-21T15:00:00+02:00`).
+ */
+export declare function renderInZone(utcIso: string, zone: string): string;
+/**
+ * Result of parsing an agent-supplied wall-clock ISO string. The
+ * caller cares about both the canonical UTC ISO (for DB storage) and
+ * the original input (for echo-back in tool responses). On failure
+ * `error` carries a one-line message.
+ */
+export type ParseInZoneResult = {
+    readonly ok: true;
+    readonly utcIso: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Parse an agent-supplied date string and return the matching UTC ISO.
+ *
+ * Naive ISO strings (no offset, e.g. `2026-05-22T13:55:00`) are
+ * interpreted as wall-clock time in `zone`. Strings with an explicit
+ * offset (`2026-05-22T13:55:00+02:00`, `…Z`) are honored verbatim and
+ * `zone` is ignored — luxon detects the offset and uses it. The result
+ * is always converted to UTC for storage.
+ *
+ * @param input - Agent-supplied date string.
+ * @param zone  - IANA zone name to apply to naive inputs.
+ */
+export declare function parseInZone(input: string, zone: string): ParseInZoneResult;
+/**
+ * Resolve the [start, endExclusive) UTC bounds of a calendar day in
+ * `zone`. The input is a date-only string (`YYYY-MM-DD`); the result
+ * gives the matching half-open UTC interval suitable for range
+ * queries on UTC-stored timestamps.
+ *
+ * @param day  - Date-only string `YYYY-MM-DD` interpreted in `zone`.
+ * @param zone - IANA zone the day boundaries are measured in.
+ */
+export declare function dayBoundsInZone(day: string, zone: string): {
+    readonly ok: true;
+    readonly fromUtc: string;
+    readonly toUtc: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};

package/build/Timezone.js

@@ -0,0 +1,84 @@
+import { DateTime } from "luxon";
+/**
+ * Reformat a UTC ISO-8601 string as a wall-clock-with-offset string in
+ * `zone`. Used by every agent-facing surface that reads stored UTC
+ * timestamps — calendar events, scheduled handlers, etc. — so the
+ * agent always operates in `core.timezone`.
+ *
+ * Conversion failures (malformed UTC string, unknown zone) fall back
+ * to the input string unchanged so a single bad row never crashes an
+ * entire read/emit path. Handlers see the raw UTC and can flag the row.
+ *
+ * @param utcIso - UTC ISO-8601 timestamp (e.g. `2026-05-21T13:00:00Z`).
+ * @param zone   - IANA zone name (e.g. `Europe/Berlin`, `UTC`).
+ * @returns Wall-clock ISO with offset in `zone` (e.g. `2026-05-21T15:00:00+02:00`).
+ */
+export function renderInZone(utcIso, zone) {
+    const dt = DateTime.fromISO(utcIso, { zone: "utc" });
+    if (!dt.isValid) {
+        return utcIso;
+    }
+    const local = dt.setZone(zone);
+    if (!local.isValid) {
+        return utcIso;
+    }
+    return local.toISO({ suppressMilliseconds: true }) ?? utcIso;
+}
+/**
+ * Parse an agent-supplied date string and return the matching UTC ISO.
+ *
+ * Naive ISO strings (no offset, e.g. `2026-05-22T13:55:00`) are
+ * interpreted as wall-clock time in `zone`. Strings with an explicit
+ * offset (`2026-05-22T13:55:00+02:00`, `…Z`) are honored verbatim and
+ * `zone` is ignored — luxon detects the offset and uses it. The result
+ * is always converted to UTC for storage.
+ *
+ * @param input - Agent-supplied date string.
+ * @param zone  - IANA zone name to apply to naive inputs.
+ */
+export function parseInZone(input, zone) {
+    if (typeof input !== "string" || input.trim().length === 0) {
+        return { ok: false, error: "date string is empty" };
+    }
+    // `setZone: false` keeps an explicit offset from the input (when
+    // present) instead of overriding with `zone`; naive inputs fall
+    // back to interpreting the wall-clock as `zone` local.
+    const parsed = DateTime.fromISO(input, { zone, setZone: false });
+    if (!parsed.isValid) {
+        return {
+            ok: false,
+            error: `invalid ISO-8601 date "${input}": ${parsed.invalidExplanation ?? parsed.invalidReason ?? "unknown reason"}`,
+        };
+    }
+    const utc = parsed.toUTC().toISO({ suppressMilliseconds: true });
+    if (utc === null) {
+        return { ok: false, error: `could not normalize "${input}" to UTC` };
+    }
+    return { ok: true, utcIso: utc };
+}
+/**
+ * Resolve the [start, endExclusive) UTC bounds of a calendar day in
+ * `zone`. The input is a date-only string (`YYYY-MM-DD`); the result
+ * gives the matching half-open UTC interval suitable for range
+ * queries on UTC-stored timestamps.
+ *
+ * @param day  - Date-only string `YYYY-MM-DD` interpreted in `zone`.
+ * @param zone - IANA zone the day boundaries are measured in.
+ */
+export function dayBoundsInZone(day, zone) {
+    const start = DateTime.fromISO(day, { zone });
+    if (!start.isValid) {
+        return {
+            ok: false,
+            error: `invalid day "${day}": ${start.invalidExplanation ?? start.invalidReason ?? "unknown reason"}`,
+        };
+    }
+    const dayStart = start.startOf("day");
+    const dayEnd = dayStart.plus({ days: 1 });
+    const fromUtc = dayStart.toUTC().toISO({ suppressMilliseconds: true });
+    const toUtc = dayEnd.toUTC().toISO({ suppressMilliseconds: true });
+    if (fromUtc === null || toUtc === null) {
+        return { ok: false, error: `could not normalize day "${day}" to UTC bounds` };
+    }
+    return { ok: true, fromUtc, toUtc };
+}

package/build/ToolCall.d.ts

@@ -0,0 +1,25 @@
+/** Persisted shape of a `tool_calls` row. */
+export interface ToolCallRow {
+    readonly id: string;
+    readonly agentRunId: string | null;
+    readonly handlerPath: string;
+    readonly toolName: string;
+    readonly successful: boolean;
+    readonly createdAt: Date;
+}
+/** Insert shape — `id` and `createdAt` are filled by the DB. */
+export interface NewToolCall {
+    readonly agentRunId?: string | null;
+    readonly handlerPath: string;
+    readonly toolName: string;
+    readonly successful: boolean;
+}
+/**
+ * One tool's usage count over a window of runs — the shape the
+ * heuristic tool-preloader consumes. Ordered most-used first by the
+ * query that produces it.
+ */
+export interface ToolUsageCount {
+    readonly toolName: string;
+    readonly count: number;
+}

package/build/ToolCall.js

@@ -0,0 +1 @@
+export {};

package/build/ToolCallBus.d.ts

@@ -0,0 +1,65 @@
+import type { PostgresConnection } from "./PostgresConnection.js";
+import type { NewToolCall, ToolUsageCount } from "./ToolCall.js";
+/**
+ * Domain client for the `tool_calls` table — one row per tool
+ * invocation an agentrun attempted, tagged with the resolved handler
+ * path and whether the call threw. Append-only: there is no update or
+ * delete outside the global retention sweep. Mirrors
+ * {@link import("./InferenceEventBus.js").InferenceEventBus} in its
+ * constructor + Pool access pattern; does not own connection lifecycle.
+ *
+ * Feeds the heuristic tool-preloader: {@link topToolsForHandler} ranks
+ * the tools a handler has successfully used across its recent non-error
+ * runs so those tools can be loaded up front on the next run.
+ */
+export declare class ToolCallBus {
+    private readonly connection;
+    constructor(connection: PostgresConnection);
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle every
+     * other bus client installs; calling any one is sufficient on
+     * daemon start.
+     */
+    installSchema(): Promise<void>;
+    /**
+     * Insert one tool-call record. Fire-and-forget from the tool
+     * wrapper; any thrown error is the caller's responsibility to log —
+     * an audit-table write error must never mask (or fault) the real
+     * tool result.
+     */
+    add(row: NewToolCall): Promise<void>;
+    /**
+     * Rank the tools this handler has successfully called across its
+     * most recent `runWindow` **non-error** agentruns (terminal state
+     * `done`), most-used first.
+     *
+     * The window is over distinct agentruns, not individual calls: we
+     * take the newest `runWindow` done runs for `handlerPath`, then
+     * count successful calls within them grouped by tool name. A tool
+     * that failed every time contributes nothing; a tool used across
+     * many runs ranks above one used heavily in a single run only if it
+     * has more successful calls overall.
+     *
+     * @param handlerPath Resolved handler markdown path the runs belong to.
+     * @param runWindow How many recent done runs to consider.
+     * @returns Tool usage counts, descending by count.
+     */
+    topToolsForHandler(handlerPath: string, runWindow: number): Promise<readonly ToolUsageCount[]>;
+    /**
+     * Delete rows older than `cutoff`. Returns the number of rows
+     * removed. Run from the same retention pass that prunes daemon log
+     * files and `inference_events` so the retention policies stay
+     * aligned with `core.logRetentionDays`.
+     */
+    pruneBefore(cutoff: Date): Promise<number>;
+    /**
+     * Keep only the newest `keepPerHandler` rows for each distinct
+     * `handler_path`, deleting the rest. Returns the number of rows
+     * removed. Bounds the table per handler: the heuristic only ever
+     * reads a small recent window, so older history is pure storage
+     * waste. Run from a periodic GC.
+     *
+     * @param keepPerHandler Rows retained per handler_path (newest first).
+     */
+    pruneKeepingPerHandler(keepPerHandler: number): Promise<number>;
+}

package/build/ToolCallBus.js

@@ -0,0 +1,110 @@
+import { SCHEMA_SQL } from "./Schema.js";
+/**
+ * Domain client for the `tool_calls` table — one row per tool
+ * invocation an agentrun attempted, tagged with the resolved handler
+ * path and whether the call threw. Append-only: there is no update or
+ * delete outside the global retention sweep. Mirrors
+ * {@link import("./InferenceEventBus.js").InferenceEventBus} in its
+ * constructor + Pool access pattern; does not own connection lifecycle.
+ *
+ * Feeds the heuristic tool-preloader: {@link topToolsForHandler} ranks
+ * the tools a handler has successfully used across its recent non-error
+ * runs so those tools can be loaded up front on the next run.
+ */
+export class ToolCallBus {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle every
+     * other bus client installs; calling any one is sufficient on
+     * daemon start.
+     */
+    async installSchema() {
+        await this.connection.getPool().query(SCHEMA_SQL);
+    }
+    /**
+     * Insert one tool-call record. Fire-and-forget from the tool
+     * wrapper; any thrown error is the caller's responsibility to log —
+     * an audit-table write error must never mask (or fault) the real
+     * tool result.
+     */
+    async add(row) {
+        await this.connection.getPool().query(`INSERT INTO tool_calls
+                (agent_run_id, handler_path, tool_name, successful)
+             VALUES ($1, $2, $3, $4)`, [row.agentRunId ?? null, row.handlerPath, row.toolName, row.successful]);
+    }
+    /**
+     * Rank the tools this handler has successfully called across its
+     * most recent `runWindow` **non-error** agentruns (terminal state
+     * `done`), most-used first.
+     *
+     * The window is over distinct agentruns, not individual calls: we
+     * take the newest `runWindow` done runs for `handlerPath`, then
+     * count successful calls within them grouped by tool name. A tool
+     * that failed every time contributes nothing; a tool used across
+     * many runs ranks above one used heavily in a single run only if it
+     * has more successful calls overall.
+     *
+     * @param handlerPath Resolved handler markdown path the runs belong to.
+     * @param runWindow How many recent done runs to consider.
+     * @returns Tool usage counts, descending by count.
+     */
+    async topToolsForHandler(handlerPath, runWindow) {
+        const result = await this.connection.getPool().query(`WITH recent_runs AS (
+                SELECT tc.agent_run_id
+                FROM tool_calls tc
+                JOIN agentruns a ON a.id = tc.agent_run_id
+                WHERE tc.handler_path = $1 AND a.state = 'done'
+                GROUP BY tc.agent_run_id
+                ORDER BY tc.agent_run_id DESC
+                LIMIT $2
+            )
+            SELECT tc.tool_name, COUNT(*) AS count
+            FROM tool_calls tc
+            WHERE tc.handler_path = $1
+              AND tc.successful = true
+              AND tc.agent_run_id IN (SELECT agent_run_id FROM recent_runs)
+            GROUP BY tc.tool_name
+            ORDER BY count DESC`, [handlerPath, runWindow]);
+        return result.rows.map((raw) => ({
+            toolName: raw.tool_name,
+            count: Number(raw.count),
+        }));
+    }
+    /**
+     * Delete rows older than `cutoff`. Returns the number of rows
+     * removed. Run from the same retention pass that prunes daemon log
+     * files and `inference_events` so the retention policies stay
+     * aligned with `core.logRetentionDays`.
+     */
+    async pruneBefore(cutoff) {
+        const result = await this.connection
+            .getPool()
+            .query(`DELETE FROM tool_calls WHERE created_at < $1`, [cutoff]);
+        return result.rowCount ?? 0;
+    }
+    /**
+     * Keep only the newest `keepPerHandler` rows for each distinct
+     * `handler_path`, deleting the rest. Returns the number of rows
+     * removed. Bounds the table per handler: the heuristic only ever
+     * reads a small recent window, so older history is pure storage
+     * waste. Run from a periodic GC.
+     *
+     * @param keepPerHandler Rows retained per handler_path (newest first).
+     */
+    async pruneKeepingPerHandler(keepPerHandler) {
+        const result = await this.connection.getPool().query(`DELETE FROM tool_calls
+             WHERE id IN (
+                 SELECT id FROM (
+                     SELECT id, row_number() OVER (
+                         PARTITION BY handler_path ORDER BY id DESC
+                     ) AS rn
+                     FROM tool_calls
+                 ) ranked
+                 WHERE ranked.rn > $1
+             )`, [keepPerHandler]);
+        return result.rowCount ?? 0;
+    }
+}

package/build/ToolLevel.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Security classification for a tool, controlling who may invoke it.
+ *
+ * - `default` — anyone may call it (read-only or low-risk tools).
+ * - `approval` — will require explicit user approval before running. The
+ *   approval gate is future work; until it exists, approval tools are
+ *   gated like `privileged` (refused in non-privileged runs).
+ * - `privileged` — only runs in a privileged agentrun (one descending
+ *   from trusted user input: the cli-chat REPL, an allowlisted Telegram
+ *   sender). In a non-privileged run the tool stays visible but its
+ *   execution is refused with a clear error.
+ *
+ * Enforced container-side in `ToolsFactory`'s tool wrapper, the single
+ * choke point every tool (built-in, plugin, and `tool_call`-proxied)
+ * passes through. An omitted level defaults to {@link DEFAULT_TOOL_LEVEL}.
+ * MCP tools are not classified and are treated as `default`.
+ */
+export type ToolLevel = "default" | "approval" | "privileged";
+/** Level applied when a tool declares none. */
+export declare const DEFAULT_TOOL_LEVEL: ToolLevel;

package/build/ToolLevel.js

@@ -0,0 +1,2 @@
+/** Level applied when a tool declares none. */
+export const DEFAULT_TOOL_LEVEL = "default";