@getfamiliar/shared 0.1.12 → 0.1.15

package/build/AgentRun.d.ts

@@ -40,18 +40,19 @@ export interface AgentRunRow {
      */
     readonly parentAgentrunId: string | null;
     /**
-     * Topic copied from the originating event at queue time. Combined
-     * with {@link handler} to resolve a workspace markdown file.
+     * The handler's address. Root agentruns copy the event's topic;
+     * spawned children carry the topic the spawning tool named. For
+     * topic `chat:whatsapp` the handler file is
+     * `workspace/chat/whatsapp.md` (or `workspace/chat/whatsapp/index.md`).
      */
     readonly topic: string;
     /**
-     * Basename of the handler file in the workspace (e.g. `index`,
-     * `analyze`). Resolution rules — for topic `chat:whatsapp` and
-     * handler `analyze`:
-     *   1. `workspace/chat/whatsapp/analyze.md`
-     *   2. fallback `workspace/chat/analyze.md`
+     * `true` when the topic must resolve to its own handler file;
+     * `false` when resolution may fall back up the topic chain
+     * (`chat:whatsapp` → `chat`). Root agentruns copy the event's
+     * {@link EventRow.isExactTopic}; spawned children are always exact.
      */
-    readonly handler: string;
+    readonly isExactTopic: boolean;
     /**
      * Resolved model id actually used for this run, of the form
      * `<provider>/<modelId>` (e.g. `featherless/zai-org/GLM-5.1`).
@@ -147,10 +148,14 @@ export interface NewAgentRun {
     readonly eventId: string;
     /** FK to the parent agentrun, or omitted/null for the root agentrun. */
     readonly parentAgentrunId?: string | null;
-    /** Topic copied from the event. Required. */
+    /** Handler address — the event's topic for roots, the named topic for children. Required. */
     readonly topic: string;
-    /** Handler basename (e.g. `index`). Required. */
-    readonly handler: string;
+    /**
+     * Whether handler resolution must match the topic exactly. Default
+     * `true` (the column default) — only the input-event watcher passes
+     * `false`, for events whose topic may fall back up the chain.
+     */
+    readonly isExactTopic?: boolean;
     /** Defaults to 50; usually inherited from the event. */
     readonly priority?: number;
     /** Initial state; default `"pending"`. */

package/build/AgentRunBus.js

@@ -44,13 +44,13 @@ export class AgentRunBus {
      */
     async add(run) {
         const result = await this.connection.getPool().query(`INSERT INTO agentruns
-                (event_id, parent_agentrun_id, topic, handler, priority, state, prompt, payload, privileged, calltype)
+                (event_id, parent_agentrun_id, topic, is_exact_topic, priority, state, prompt, payload, privileged, calltype)
              VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9, $10)
              RETURNING *`, [
             run.eventId,
             run.parentAgentrunId ?? null,
             run.topic,
-            run.handler,
+            run.isExactTopic ?? true,
             run.priority ?? 50,
             run.state ?? "pending",
             run.prompt ?? null,
@@ -339,7 +339,7 @@ function mapRow(raw) {
         eventId: raw.event_id,
         parentAgentrunId: raw.parent_agentrun_id,
         topic: raw.topic,
-        handler: raw.handler,
+        isExactTopic: raw.is_exact_topic,
         priority: raw.priority,
         state: raw.state,
         prompt: raw.prompt,

package/build/Config.d.ts

@@ -19,6 +19,11 @@
  * boot. Plugin-side keys are not policed by the platform — plugins own
  * the validation of their own subtrees.
  */
+/**
+ * Fallback for `core.writablePaths` when `config.yml` doesn't set it:
+ * the workspace globs the agent may write to, which are never handlers.
+ */
+export declare const DEFAULT_WRITABLE_PATHS: readonly string[];
 export interface ConfigService {
     /**
      * Read a string under a dotted path. Throws when the key is

package/build/Config.js

@@ -1 +1,26 @@
-export {};
+/**
+ * Plugin-agnostic configuration surface exposed by the host.
+ *
+ * Plugins reach configuration through `HostContext.config` rather than
+ * touching `process.env` or reading the YAML file themselves. The
+ * service intentionally has no plugin-specific types; everything is
+ * keyed by dotted path strings (e.g. `"core.postgresPassword"`,
+ * `"telegram.botToken"`) and validated to a primitive shape at the
+ * call site.
+ *
+ * Required-vs-optional semantics live in the call signature, not in
+ * the schema: omitting `defaultValue` makes the read throw on missing
+ * or wrong-shaped data, while supplying one widens the return type to
+ * include the default (so plugins can pass `null` for fields they
+ * tolerate being absent).
+ *
+ * The platform-level minimum (the keys without which the daemon can't
+ * start) is enforced by a separate `ConfigLinter` on the host side at
+ * boot. Plugin-side keys are not policed by the platform — plugins own
+ * the validation of their own subtrees.
+ */
+/**
+ * Fallback for `core.writablePaths` when `config.yml` doesn't set it:
+ * the workspace globs the agent may write to, which are never handlers.
+ */
+export const DEFAULT_WRITABLE_PATHS = ["wiki/**", "files/**"];

package/build/DockerTools.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared bridge network all Familiar containers join. Owned
+ * by the daemon (see `commands/Start.ts`); created once via
+ * {@link ensureNetwork} before any container is started.
+ */
+export declare const SHARED_NETWORK_NAME = "familiar-net";
+/**
+ * Internal (egress-less) bridge network the locked-down agent container
+ * joins. Created with `--internal` so the agent has no route to the
+ * internet; it reaches postgres (dual-homed onto this net) and the host
+ * bastion (via the `familiar-bastion-bridge` socat sidecar, also on this
+ * net) by container name. Owned by the daemon, created via
+ * {@link ensureNetwork} with `{ internal: true }`.
+ */
+export declare const ISOLATED_NETWORK_NAME = "familiar-isolated";
+/** Options shared by {@link dockerExec}. */
+export interface DockerExecOptions {
+    /** If true, non-zero exit codes resolve instead of throwing. */
+    readonly allowFailure?: boolean;
+}
+/** Output of {@link dockerCapture}. */
+export interface DockerCaptureResult {
+    readonly code: number | null;
+    readonly stdout: string;
+}
+/**
+ * Run a docker CLI command and discard its stdio. Resolves on exit
+ * code 0 (or always when `allowFailure` is set); rejects otherwise.
+ */
+export declare function dockerExec(args: readonly string[], options?: DockerExecOptions): Promise<void>;
+/**
+ * Run a docker CLI command and capture stdout. Never throws on non-zero
+ * exit; callers inspect the returned `code`.
+ */
+export declare function dockerCapture(args: readonly string[]): Promise<DockerCaptureResult>;
+/** Whether a container with the given name is currently running. */
+export declare function isContainerRunning(name: string): Promise<boolean>;
+/** Whether a Docker network with the given name already exists. */
+export declare function isNetworkPresent(name: string): Promise<boolean>;
+/**
+ * Whether a Docker image with the given reference is present in the
+ * local image store. Used by the pull-mode image lifecycle to avoid
+ * re-pulling a version-pinned image that's already local.
+ *
+ * @param ref Image reference (tag or registry-qualified `name:tag`).
+ * @returns true if `docker image inspect` succeeds.
+ */
+export declare function isImagePresent(ref: string): Promise<boolean>;
+/** Options for {@link buildNetworkCreateArgs} / {@link ensureNetwork}. */
+export interface NetworkCreateOptions {
+    /**
+     * Create the network with `--internal` so containers on it have no
+     * egress to the host or the internet — only to other containers on
+     * the same network. Used for the agent's `familiar-isolated` net.
+     */
+    readonly internal?: boolean;
+}
+/**
+ * Build the `docker network create` argument vector. Pure (no side
+ * effects) so it can be unit-tested without a daemon.
+ *
+ * @param name Network name to create.
+ * @param options Network creation flags (e.g. `internal`).
+ * @returns The full docker CLI argv, e.g. `["network", "create", "--internal", "familiar-isolated"]`.
+ */
+export declare function buildNetworkCreateArgs(name: string, options?: NetworkCreateOptions): string[];
+/**
+ * Create the named bridge network if it doesn't already exist. Idempotent.
+ *
+ * @param name Network name to ensure.
+ * @param options Network creation flags applied only on first creation
+ *   (an existing network is left as-is).
+ */
+export declare function ensureNetwork(name: string, options?: NetworkCreateOptions): Promise<void>;
+/**
+ * Attach an already-running container to an additional network by name.
+ * Callers recreate their container on every `start()` (via
+ * {@link removeContainer} first), so the attachment is always fresh —
+ * this throws on failure rather than swallowing it, so a genuine
+ * problem (missing network, missing container) surfaces instead of
+ * silently leaving the container unable to reach its peer.
+ *
+ * @param network Network to connect the container to.
+ * @param container Name of the running container to attach.
+ * @throws If the docker command fails (network/container missing, etc.).
+ */
+export declare function connectNetwork(network: string, container: string): Promise<void>;
+/**
+ * Force-remove a container by name. Default `allowFailure: true` because
+ * "remove if it exists" is the common idempotent-cleanup intent.
+ */
+export declare function removeContainer(name: string, options?: DockerExecOptions): Promise<void>;
+/** Send `docker stop` to a container. Ignores already-stopped/missing containers. */
+export declare function stopContainer(name: string): Promise<void>;
+/**
+ * Run a docker CLI command with the parent process's stdin/stdout/
+ * stderr inherited, blocking until the child exits. Used by
+ * subcommands that hand the user's terminal to a foreground docker
+ * process (`familiar psql`'s psql shell, `familiar mcp call`'s
+ * one-shot CLI invocations against an MCP runtime container).
+ *
+ * Returns the child's exit status — `null`-on-signal collapses to
+ * 1 so the caller's `process.exit(...)` always sees a usable
+ * number. A failure to launch docker itself (e.g. binary missing)
+ * surfaces as a thrown {@link Error} the caller can format.
+ *
+ * @throws If the docker binary couldn't be spawned at all.
+ */
+export declare function dockerInteractive(args: readonly string[]): number;
+/**
+ * On Linux, `host.docker.internal` isn't built-in and must be mapped to
+ * the host gateway explicitly. macOS and Windows resolve it natively.
+ *
+ * Used by sidecars that dial a host-side listener (the bastion bridge,
+ * the tailscale plugin's serve proxy to the webserver).
+ *
+ * @returns Extra `docker run` args, or an empty array on macOS/Windows.
+ */
+export declare function hostGatewayArgs(): string[];

package/build/DockerTools.js

@@ -0,0 +1,175 @@
+import { spawn, spawnSync } from "node:child_process";
+import os from "node:os";
+/**
+ * Shared bridge network all Familiar containers join. Owned
+ * by the daemon (see `commands/Start.ts`); created once via
+ * {@link ensureNetwork} before any container is started.
+ */
+export const SHARED_NETWORK_NAME = "familiar-net";
+/**
+ * Internal (egress-less) bridge network the locked-down agent container
+ * joins. Created with `--internal` so the agent has no route to the
+ * internet; it reaches postgres (dual-homed onto this net) and the host
+ * bastion (via the `familiar-bastion-bridge` socat sidecar, also on this
+ * net) by container name. Owned by the daemon, created via
+ * {@link ensureNetwork} with `{ internal: true }`.
+ */
+export const ISOLATED_NETWORK_NAME = "familiar-isolated";
+/**
+ * Run a docker CLI command and discard its stdio. Resolves on exit
+ * code 0 (or always when `allowFailure` is set); rejects otherwise.
+ */
+export function dockerExec(args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("docker", [...args], { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        proc.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on("close", (code) => {
+            if (code === 0 || options.allowFailure) {
+                resolve();
+                return;
+            }
+            const trimmed = stderr.trim();
+            const suffix = trimmed.length > 0 ? `: ${trimmed}` : "";
+            reject(new Error(`docker ${args.join(" ")} exited with code ${code}${suffix}`));
+        });
+        proc.on("error", reject);
+    });
+}
+/**
+ * Run a docker CLI command and capture stdout. Never throws on non-zero
+ * exit; callers inspect the returned `code`.
+ */
+export function dockerCapture(args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("docker", [...args], { stdio: ["ignore", "pipe", "ignore"] });
+        let stdout = "";
+        proc.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        proc.on("close", (code) => {
+            resolve({ code, stdout });
+        });
+        proc.on("error", reject);
+    });
+}
+/** Whether a container with the given name is currently running. */
+export async function isContainerRunning(name) {
+    const { code, stdout } = await dockerCapture([
+        "container",
+        "inspect",
+        "-f",
+        "{{.State.Running}}",
+        name,
+    ]);
+    return code === 0 && stdout.trim() === "true";
+}
+/** Whether a Docker network with the given name already exists. */
+export async function isNetworkPresent(name) {
+    const { code } = await dockerCapture(["network", "inspect", name]);
+    return code === 0;
+}
+/**
+ * Whether a Docker image with the given reference is present in the
+ * local image store. Used by the pull-mode image lifecycle to avoid
+ * re-pulling a version-pinned image that's already local.
+ *
+ * @param ref Image reference (tag or registry-qualified `name:tag`).
+ * @returns true if `docker image inspect` succeeds.
+ */
+export async function isImagePresent(ref) {
+    const { code } = await dockerCapture(["image", "inspect", ref]);
+    return code === 0;
+}
+/**
+ * Build the `docker network create` argument vector. Pure (no side
+ * effects) so it can be unit-tested without a daemon.
+ *
+ * @param name Network name to create.
+ * @param options Network creation flags (e.g. `internal`).
+ * @returns The full docker CLI argv, e.g. `["network", "create", "--internal", "familiar-isolated"]`.
+ */
+export function buildNetworkCreateArgs(name, options = {}) {
+    const args = ["network", "create"];
+    if (options.internal) {
+        args.push("--internal");
+    }
+    args.push(name);
+    return args;
+}
+/**
+ * Create the named bridge network if it doesn't already exist. Idempotent.
+ *
+ * @param name Network name to ensure.
+ * @param options Network creation flags applied only on first creation
+ *   (an existing network is left as-is).
+ */
+export async function ensureNetwork(name, options = {}) {
+    if (!(await isNetworkPresent(name))) {
+        await dockerExec(buildNetworkCreateArgs(name, options));
+    }
+}
+/**
+ * Attach an already-running container to an additional network by name.
+ * Callers recreate their container on every `start()` (via
+ * {@link removeContainer} first), so the attachment is always fresh —
+ * this throws on failure rather than swallowing it, so a genuine
+ * problem (missing network, missing container) surfaces instead of
+ * silently leaving the container unable to reach its peer.
+ *
+ * @param network Network to connect the container to.
+ * @param container Name of the running container to attach.
+ * @throws If the docker command fails (network/container missing, etc.).
+ */
+export function connectNetwork(network, container) {
+    return dockerExec(["network", "connect", network, container]);
+}
+/**
+ * Force-remove a container by name. Default `allowFailure: true` because
+ * "remove if it exists" is the common idempotent-cleanup intent.
+ */
+export function removeContainer(name, options = { allowFailure: true }) {
+    return dockerExec(["rm", "-f", name], options);
+}
+/** Send `docker stop` to a container. Ignores already-stopped/missing containers. */
+export function stopContainer(name) {
+    return dockerExec(["stop", name], { allowFailure: true });
+}
+/**
+ * Run a docker CLI command with the parent process's stdin/stdout/
+ * stderr inherited, blocking until the child exits. Used by
+ * subcommands that hand the user's terminal to a foreground docker
+ * process (`familiar psql`'s psql shell, `familiar mcp call`'s
+ * one-shot CLI invocations against an MCP runtime container).
+ *
+ * Returns the child's exit status — `null`-on-signal collapses to
+ * 1 so the caller's `process.exit(...)` always sees a usable
+ * number. A failure to launch docker itself (e.g. binary missing)
+ * surfaces as a thrown {@link Error} the caller can format.
+ *
+ * @throws If the docker binary couldn't be spawned at all.
+ */
+export function dockerInteractive(args) {
+    const result = spawnSync("docker", [...args], { stdio: "inherit" });
+    if (result.error) {
+        throw new Error(`failed to launch docker: ${result.error.message}`);
+    }
+    return result.status ?? 1;
+}
+/**
+ * On Linux, `host.docker.internal` isn't built-in and must be mapped to
+ * the host gateway explicitly. macOS and Windows resolve it natively.
+ *
+ * Used by sidecars that dial a host-side listener (the bastion bridge,
+ * the tailscale plugin's serve proxy to the webserver).
+ *
+ * @returns Extra `docker run` args, or an empty array on macOS/Windows.
+ */
+export function hostGatewayArgs() {
+    if (os.platform() === "linux") {
+        return ["--add-host=host.docker.internal:host-gateway"];
+    }
+    return [];
+}

package/build/Event.d.ts

@@ -41,9 +41,9 @@ export interface EventRow {
      */
     readonly id: string;
     /**
-     * Event topic, matching `\w+(:\w+)*` (e.g. `mail`, `chat:whatsapp`,
-     * `chat:telegram:group:reaction`). Each `:`-separated segment maps
-     * to a folder when the container resolves the handler markdown.
+     * Event topic, matching `TOPIC_PATTERN` (e.g. `mail`, `chat:whatsapp`,
+     * `chat:telegram:group:reaction`). The topic is the handler's whole
+     * address: `a:b:c` resolves to `a/b/c.md` (or `a/b/c/index.md`).
      */
     readonly topic: string;
     /**
@@ -94,12 +94,12 @@ export interface EventRow {
      */
     readonly prompt: string;
     /**
-     * Override for the root agentrun's handler. `null` means the
-     * input-event watcher uses `'index'` (i.e. resolves
-     * `<topic>/index.md`). Set by the emitter via
-     * {@link NewEvent.startHandler}; never mutated after insert.
+     * `true` when the topic must name an existing handler file exactly;
+     * `false` when handler resolution may fall back up the topic chain.
+     * Set by the emitter via {@link NewEvent.isExactTopic}; never
+     * mutated after insert.
      */
-    readonly startHandler: string | null;
+    readonly isExactTopic: boolean;
     /**
      * `true` when this event was emitted by a trusted user-input source
      * (the operator at the local terminal via cli-chat, the operator on
@@ -236,24 +236,24 @@ export interface NewEvent {
      *
      * Use this for plugin emitters that want a chatmessage text
      * different from `prompt` (e.g. cli-chat persists the slash-
-     * prefixed `/topic/handler …` line while the handler sees only
+     * prefixed `/topic/sub …` line while the handler sees only
      * the trailing prompt text). When unset and `isChat: true`, the
      * existing path inserts `prompt` itself.
      */
     readonly userChatMessage?: string;
     /**
-     * Override which handler markdown the root agentrun runs. When
-     * omitted, the input-event watcher uses `'index'` (i.e. resolves
-     * `<topic>/index.md`). Useful when an emitter wants to skip the
-     * triage `index.md` and invoke a specific handler directly.
+     * When `true`, the topic addresses one handler file exactly
+     * (`a:b:c` → `a/b/c.md` or `a/b/c/index.md`) and the run fails if
+     * it is missing. Default `false`: world events fall back up the
+     * topic chain (`a:b`, then `a`) to the most specific existing
+     * handler. Set it for emissions that name a handler rather than
+     * report a world change — cron firings, scheduled wake-ups,
+     * memory's `skills:memory:save`, cli-chat slash commands.
      *
-     * Pass the basename without `.md` (e.g. `'analyze'` resolves to
-     * `<topic>/analyze.md`). The agentrun fails loud at handler-load
-     * time if no such file exists — there is no shape validation
-     * here, mirroring how `topic` is only regex-checked, not
-     * existence-checked, at emit time.
+     * Like `topic` itself, existence is not checked at emit time; the
+     * agentrun fails loud at handler-load time.
      */
-    readonly startHandler?: string;
+    readonly isExactTopic?: boolean;
     /**
      * Auxiliary files to stage at `/scratch/<event-id>/<name>` for this
      * event. Visible to the agent and to every MCP container under the

package/build/EventBus.d.ts

@@ -116,7 +116,7 @@ export declare class EventBus {
      */
     listLatest(limit: number): Promise<EventRow[]>;
     /**
-     * Fetch the most recently created N event rows whose topic, start_handler,
+     * Fetch the most recently created N event rows whose topic,
      * prompt, or payload (cast to text) case-insensitively contains `needle`.
      * Used by `familiar events list <search>` so the operator can grep the
      * recent bus without piping through `grep`.
@@ -138,7 +138,7 @@ export declare class EventBus {
      * pair can't express. Both of those stay as the CLI's call sites.
      *
      * Substring match (when `search` is set) is the same ILIKE-against-
-     * `(topic, start_handler, prompt, payload::text)` predicate
+     * `(topic, prompt, payload::text)` predicate
      * {@link searchLatest} uses. `dateFrom` is inclusive, `dateTo` is
      * exclusive (`created_at >= $from AND created_at < $to`), so the
      * agent can pass two midnights to get a single local day without

package/build/EventBus.js

@@ -139,7 +139,7 @@ export class EventBus {
             const result = await client.query(`INSERT INTO events
                    (topic, payload, priority, state, idempotency_key,
                     is_chat, preferred_chat_channel_id, prompt, privileged,
-                    start_handler, output_chat_on_failure)
+                    is_exact_topic, output_chat_on_failure)
                  VALUES ($1, $2::jsonb, $3, $4, $5, $6, $7, $8, $9, $10, $11)
                  RETURNING *`, [
                 event.topic,
@@ -151,7 +151,7 @@ export class EventBus {
                 event.preferredChatChannelId ?? null,
                 prompt,
                 event.privileged ?? false,
-                event.startHandler ?? null,
+                event.isExactTopic ?? false,
                 event.outputChatOnFailure ?? false,
             ]);
             const row = mapRow(result.rows[0]);
@@ -242,7 +242,7 @@ export class EventBus {
         return result.rows.map(mapRow);
     }
     /**
-     * Fetch the most recently created N event rows whose topic, start_handler,
+     * Fetch the most recently created N event rows whose topic,
      * prompt, or payload (cast to text) case-insensitively contains `needle`.
      * Used by `familiar events list <search>` so the operator can grep the
      * recent bus without piping through `grep`.
@@ -259,7 +259,6 @@ export class EventBus {
         const pattern = `%${needle.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
         const result = await this.connection.getPool().query(`SELECT * FROM events
                  WHERE topic                          ILIKE $2
-                    OR coalesce(start_handler, '')    ILIKE $2
                     OR coalesce(prompt, '')           ILIKE $2
                     OR payload::text                  ILIKE $2
                  ORDER BY created_at DESC, id DESC
@@ -274,7 +273,7 @@ export class EventBus {
      * pair can't express. Both of those stay as the CLI's call sites.
      *
      * Substring match (when `search` is set) is the same ILIKE-against-
-     * `(topic, start_handler, prompt, payload::text)` predicate
+     * `(topic, prompt, payload::text)` predicate
      * {@link searchLatest} uses. `dateFrom` is inclusive, `dateTo` is
      * exclusive (`created_at >= $from AND created_at < $to`), so the
      * agent can pass two midnights to get a single local day without
@@ -286,8 +285,7 @@ export class EventBus {
         let n = 1;
         if (filter.search !== undefined && filter.search.length > 0) {
             const pattern = `%${filter.search.replace(/[\\%_]/g, (c) => `\\${c}`)}%`;
-            conditions.push(`(topic ILIKE $${n} OR coalesce(start_handler, '') ILIKE $${n} ` +
-                `OR coalesce(prompt, '') ILIKE $${n} OR payload::text ILIKE $${n})`);
+            conditions.push(`(topic ILIKE $${n} OR coalesce(prompt, '') ILIKE $${n} OR payload::text ILIKE $${n})`);
             values.push(pattern);
             n++;
         }
@@ -473,7 +471,7 @@ function mapRow(raw) {
         isChat: raw.is_chat,
         preferredChatChannelId: raw.preferred_chat_channel_id,
         prompt: raw.prompt ?? "",
-        startHandler: raw.start_handler,
+        isExactTopic: raw.is_exact_topic,
         privileged: raw.privileged,
         outputChatOnFailure: raw.output_chat_on_failure,
         createdAt: raw.created_at,

package/build/HandlerCatalog.d.ts

@@ -1,31 +1,35 @@
+import { type HandlerResolution, type HandlerResolutionOptions } from "./HandlerResolution.js";
 /**
  * One handler entry surfaced by {@link HandlerCatalog.list}.
  *
- * Encodes the same notion as the container's `HandlerFile`: a topic
- * (one or more `:`-separated segments) plus a basename. `slashPath`
- * is the user-facing form the cli-chat prompt accepts as a direct
- * handler call (e.g. `/grocery/fruits/order`).
+ * The topic is the handler's whole address (`chat:telegram` for both
+ * `chat/telegram.md` and `chat/telegram/index.md`). `slashPath` is the
+ * user-facing form the cli-chat prompt accepts as a direct handler call
+ * (e.g. `/grocery/fruits/order`).
  */
 export interface HandlerPath {
     /** Colon-separated topic, e.g. `chat:telegram`. */
     readonly topic: string;
-    /** Handler basename without `.md`, e.g. `index`, `analyze`. */
-    readonly handler: string;
     /** Absolute path on disk of the handler file. */
     readonly absolutePath: string;
-    /** Workspace-relative posix path, e.g. `chat/telegram/index.md`. */
+    /** Workspace-relative posix path, e.g. `chat/telegram.md`. */
     readonly relativePath: string;
-    /** User-facing slash form, e.g. `/chat/telegram/index`. */
+    /** User-facing slash form of the topic, e.g. `/chat/telegram`. */
     readonly slashPath: string;
 }
+/** A {@link HandlerResolution} plus the winning file's absolute path. */
+export interface ResolvedHandler extends HandlerResolution {
+    /** Absolute path on disk of the winning handler file. */
+    readonly absolutePath: string;
+}
 /**
  * Read-only view over the `workspace/` directory's handler files.
  *
- * Mirrors the resolution semantics implemented by
- * `container/src/HandlerFile.ts` so host-side code (CLI, cron
+ * Shares the resolution rules of `container/src/HandlerFile.ts` (both
+ * build on `HandlerResolution.ts`) so host-side code (CLI, cron
  * scheduler introspection, tab-completion) can answer "does this
  * handler exist?" and "list every handler" without depending on
- * container internals or reimplementing the topic-walk inheritance.
+ * container internals.
  *
  * The catalog is stateless on the disk — every method re-scans —
  * so live workspace edits are reflected without a daemon restart.
@@ -46,12 +50,14 @@ export declare class HandlerCatalog {
     constructor(workspaceDir: string, writablePathGlobs?: readonly string[]);
     /**
      * Walk `workspace/` and return one {@link HandlerPath} per
-     * candidate handler file. Excludes every file at the workspace root
-     * (`PROMPT.md`, `SOUL.md`, … — root files have no topic, so they are
-     * never handlers) and the `skills/` subtree. Every other `.md` file under a topic
-     * directory is included, even if it's a knowledge file (e.g.
-     * `people/anna.md`) — `HandlerCatalog` does not police what is or
-     * isn't a "proper" handler; that's a handler-loading concern.
+     * addressable handler file. Excludes every file at the workspace
+     * root (`PROMPT.md`, `SOUL.md`, … — root files have no topic, so they
+     * are never handlers), the `skills/` subtree, writable paths, file
+     * names that don't form a valid topic, and a folder-form
+     * `x/index.md` shadowed by its `x.md` twin. Every other `.md` file
+     * under a topic directory is included, even if it's a knowledge file
+     * (e.g. `people/anna.md`) — `HandlerCatalog` does not police what is
+     * or isn't a "proper" handler; that's a handler-loading concern.
      *
      * Sorted by `slashPath` for stable display ordering in
      * tab-completion. Returns an empty array when the workspace
@@ -59,17 +65,16 @@ export declare class HandlerCatalog {
      */
     list(): Promise<readonly HandlerPath[]>;
     /**
-     * Resolve a handler call: given a topic (e.g. `chat:telegram`)
-     * and a basename (e.g. `index`), return the absolute path of the
-     * deepest existing handler file, mirroring the container's
-     * inheritance walk.
+     * Resolve a topic to the one handler file that runs for it, with
+     * the same rules as the container's `HandlerFile.load`: file form
+     * `a/b/c.md` before folder form `a/b/c/index.md`, and — unless
+     * `isExactTopic` — falling back up the topic chain.
      *
-     * For topic `a:b:c` and basename `x` the resolution tries, in
-     * order: `a/b/c/x.md`, `a/b/x.md`, `a/x.md`. Returns the first
-     * existing path or `null` if none exist. The deepest existing
-     * file is what `HandlerFile.load` would treat as the leaf — for
-     * cli-chat existence checks, that's exactly the question we
-     * want answered.
+     * @param topic Colon-separated topic, e.g. `chat:telegram`.
+     * @param options See {@link HandlerResolutionOptions}.
+     * @returns The resolution, or `null` when nothing matches or the
+     *   winning file lives under a writable path (the container refuses
+     *   to run it, so it does not resolve).
      */
-    resolve(topic: string, handler: string): Promise<string | null>;
+    resolve(topic: string, options: HandlerResolutionOptions): Promise<ResolvedHandler | null>;
 }