@getfamiliar/shared 0.1.12 → 0.1.15

package/build/HandlerCatalog.js

@@ -1,5 +1,6 @@
-import { promises as fs } from "node:fs";
+import { promises as fs, statSync } from "node:fs";
 import path from "node:path";
+import { resolveHandlerPath, topicFromHandlerPath, twinHandlerPath, } from "./HandlerResolution.js";
 import { matchesAnyGlob } from "./PathGlob.js";
 /**
  * Workspace subtrees excluded from {@link HandlerCatalog.list} (cli-chat
@@ -13,11 +14,11 @@ const RESERVED_TOP_DIRS = new Set(["skills"]);
 /**
  * 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.
@@ -41,12 +42,14 @@ export class HandlerCatalog {
     }
     /**
      * 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
@@ -57,50 +60,66 @@ export class HandlerCatalog {
         if (!exists) {
             return [];
         }
+        const relativePaths = [];
+        await walkMarkdown(this.workspaceDir, [], relativePaths);
+        const present = new Set(relativePaths);
         const results = [];
-        await walkMarkdown(this.workspaceDir, [], results, this.workspaceDir, this.writablePathGlobs);
+        for (const relativePath of relativePaths) {
+            // Files under `core.writablePaths` (e.g. `wiki/**`) are writable by
+            // non-privileged runs and are never handlers — never propose them.
+            if (matchesAnyGlob(this.writablePathGlobs, relativePath)) {
+                continue;
+            }
+            const topic = topicFromHandlerPath(relativePath);
+            if (topic === null) {
+                continue;
+            }
+            const twin = twinHandlerPath(relativePath);
+            if (relativePath.endsWith("/index.md") && twin !== null && present.has(twin)) {
+                continue;
+            }
+            results.push({
+                topic,
+                absolutePath: path.join(this.workspaceDir, relativePath),
+                relativePath,
+                slashPath: `/${topic.split(":").join("/")}`,
+            });
+        }
         results.sort((a, b) => a.slashPath.localeCompare(b.slashPath));
         return results;
     }
     /**
-     * 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).
      */
-    async resolve(topic, handler) {
-        const segments = topic.split(":");
-        for (let depth = segments.length; depth >= 1; depth--) {
-            const rel = path.join(...segments.slice(0, depth), `${handler}.md`);
-            const relPosix = rel.split(path.sep).join("/");
-            const absolute = path.join(this.workspaceDir, rel);
-            if (await fileExists(absolute)) {
-                // A file under `core.writablePaths` is never a handler, even
-                // when it exists — mirror the container's `HandlerFile.load`
-                // guard so host-side callers agree it does not resolve.
-                if (matchesAnyGlob(this.writablePathGlobs, relPosix)) {
-                    return null;
-                }
-                return absolute;
-            }
+    async resolve(topic, options) {
+        const resolution = resolveHandlerPath(topic, options, (relativePath) => isFileSync(path.join(this.workspaceDir, relativePath)));
+        if (resolution === null ||
+            matchesAnyGlob(this.writablePathGlobs, resolution.relativePath)) {
+            return null;
         }
-        return null;
+        return {
+            ...resolution,
+            absolutePath: path.join(this.workspaceDir, resolution.relativePath),
+        };
     }
 }
 /**
- * Recursively walk `dir`, accumulating one {@link HandlerPath} per
- * `.md` file. `segments` tracks the topic path from the workspace
- * root; an empty array means we're at the root, whose files are
- * skipped (no topic, never a handler).
+ * Recursively walk `dir`, accumulating the workspace-relative posix
+ * path of every `.md` file below a topic folder. `segments` tracks the
+ * folder path from the workspace root; files at the root itself are
+ * skipped (no topic, never a handler), and so is the reserved
+ * `skills/` subtree.
  */
-async function walkMarkdown(dir, segments, out, workspaceDir, writablePathGlobs) {
+async function walkMarkdown(dir, segments, out) {
     let entries;
     try {
         entries = await fs.readdir(dir, { withFileTypes: true });
@@ -113,35 +132,22 @@ async function walkMarkdown(dir, segments, out, workspaceDir, writablePathGlobs)
             if (segments.length === 0 && RESERVED_TOP_DIRS.has(entry.name)) {
                 continue;
             }
-            await walkMarkdown(path.join(dir, entry.name), [...segments, entry.name], out, workspaceDir, writablePathGlobs);
+            await walkMarkdown(path.join(dir, entry.name), [...segments, entry.name], out);
             continue;
         }
-        if (!entry.isFile() || !entry.name.endsWith(".md")) {
+        if (!entry.isFile() || !entry.name.endsWith(".md") || segments.length === 0) {
             continue;
         }
-        if (segments.length === 0) {
-            // `.md` at the workspace root (PROMPT.md, SOUL.md, …) has no
-            // topic folder — never a handler. Skip silently rather than
-            // reporting an empty topic.
-            continue;
-        }
-        const handlerBase = entry.name.slice(0, -".md".length);
-        const topic = segments.join(":");
-        const absolutePath = path.join(dir, entry.name);
-        const relativePath = path.relative(workspaceDir, absolutePath).split(path.sep).join("/");
-        // Files under `core.writablePaths` (e.g. `wiki/**`) are writable by
-        // non-privileged runs and are never handlers — never propose them.
-        if (matchesAnyGlob(writablePathGlobs, relativePath)) {
-            continue;
-        }
-        const slashPath = `/${[...segments, handlerBase].join("/")}`;
-        out.push({ topic, handler: handlerBase, absolutePath, relativePath, slashPath });
+        out.push([...segments, entry.name].join("/"));
     }
 }
-async function fileExists(absolute) {
+/**
+ * Synchronous regular-file probe, used as the existence callback of
+ * {@link resolveHandlerPath}.
+ */
+function isFileSync(absolute) {
     try {
-        const stat = await fs.stat(absolute);
-        return stat.isFile();
+        return statSync(absolute).isFile();
     }
     catch {
         return false;

package/build/HandlerResolution.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Outcome of {@link resolveHandlerPath}: the one handler file a topic
+ * resolves to.
+ */
+export interface HandlerResolution {
+    /** Workspace-relative posix path of the winning file, e.g. `mail/new/ms365.md`. */
+    readonly relativePath: string;
+    /**
+     * Workspace-relative path of the twin that lost against
+     * {@link relativePath} on the same level (`mail/new/ms365/index.md`
+     * when `mail/new/ms365.md` also exists), or `null` when the level
+     * held only one file. Only one of the two forms is allowed; callers
+     * warn when this is set.
+     */
+    readonly shadowedPath: string | null;
+}
+/**
+ * Options for {@link handlerCandidateLevels} / {@link resolveHandlerPath}.
+ */
+export interface HandlerResolutionOptions {
+    /**
+     * `true` ⇒ only the topic's own level is tried (cron, subagents,
+     * scheduled wake-ups, addressed emissions). `false` ⇒ the resolver
+     * walks up the topic chain (`a:b:c → a:b → a`), which is what
+     * world events get.
+     */
+    readonly isExactTopic: boolean;
+}
+/**
+ * Build the candidate handler files for a topic, one entry per topic
+ * level (most specific first). Each level lists its candidates in
+ * precedence order: the file form `a/b/c.md` before the folder form
+ * `a/b/c/index.md`. A single-segment topic `a` has only `a/index.md`
+ * — workspace-root files are never handlers.
+ *
+ * For topic `mail:new:ms365` without `isExactTopic`:
+ *
+ *   1. `mail/new/ms365.md`, `mail/new/ms365/index.md`
+ *   2. `mail/new.md`, `mail/new/index.md`
+ *   3. `mail/index.md`
+ *
+ * @param topic Colon-separated topic, e.g. `mail:new:ms365`.
+ * @param options See {@link HandlerResolutionOptions}.
+ * @returns The candidate levels, most specific first.
+ */
+export declare function handlerCandidateLevels(topic: string, options: HandlerResolutionOptions): readonly (readonly string[])[];
+/**
+ * Resolve a topic to the single handler file that runs for it. The
+ * first level of {@link handlerCandidateLevels} holding any existing
+ * file wins; within a level the file form beats the folder form and
+ * the loser is reported as {@link HandlerResolution.shadowedPath}.
+ * Nothing is merged — exactly one file is the handler.
+ *
+ * @param topic Colon-separated topic, e.g. `mail:new:ms365`.
+ * @param options See {@link HandlerResolutionOptions}.
+ * @param isFile Existence probe for a workspace-relative path.
+ * @returns The resolution, or `null` when no candidate exists.
+ */
+export declare function resolveHandlerPath(topic: string, options: HandlerResolutionOptions, isFile: (relativePath: string) => boolean): HandlerResolution | null;
+/**
+ * Derive the topic a handler file answers to. The inverse of
+ * {@link handlerCandidateLevels}' own level:
+ *
+ * - `mail/important/digest.md` → `mail:important:digest`
+ * - `mail/new/index.md` → `mail:new`
+ * - `mail/index.md` → `mail`
+ *
+ * @param relativePath Workspace-relative posix path ending in `.md`.
+ * @returns The topic, or `null` for workspace-root files, non-`.md`
+ *   files and paths whose segments don't form a valid topic (e.g. a
+ *   file name containing a dot or a space).
+ */
+export declare function topicFromHandlerPath(relativePath: string): string | null;
+/**
+ * The other form of the same handler: `a/b/c.md` ↔ `a/b/c/index.md`.
+ * Only one of the two may exist; seeding and the cron scheduler use
+ * this to detect the conflict.
+ *
+ * @param relativePath Workspace-relative posix path ending in `.md`.
+ * @returns The twin's path, or `null` when the twin would be a
+ *   workspace-root file (`a/index.md` ↔ `a.md`) or the path is a root
+ *   file / not markdown.
+ */
+export declare function twinHandlerPath(relativePath: string): string | null;

package/build/HandlerResolution.js

@@ -0,0 +1,105 @@
+import { TOPIC_PATTERN } from "./Schema.js";
+const TOPIC_REGEXP = new RegExp(TOPIC_PATTERN);
+/** File name of the folder form of a handler (`a/b/c/index.md`). */
+const INDEX_FILE = "index.md";
+/**
+ * Build the candidate handler files for a topic, one entry per topic
+ * level (most specific first). Each level lists its candidates in
+ * precedence order: the file form `a/b/c.md` before the folder form
+ * `a/b/c/index.md`. A single-segment topic `a` has only `a/index.md`
+ * — workspace-root files are never handlers.
+ *
+ * For topic `mail:new:ms365` without `isExactTopic`:
+ *
+ *   1. `mail/new/ms365.md`, `mail/new/ms365/index.md`
+ *   2. `mail/new.md`, `mail/new/index.md`
+ *   3. `mail/index.md`
+ *
+ * @param topic Colon-separated topic, e.g. `mail:new:ms365`.
+ * @param options See {@link HandlerResolutionOptions}.
+ * @returns The candidate levels, most specific first.
+ */
+export function handlerCandidateLevels(topic, options) {
+    const segments = topic.split(":");
+    const shallowestDepth = options.isExactTopic ? segments.length : 1;
+    const levels = [];
+    for (let depth = segments.length; depth >= shallowestDepth; depth--) {
+        const folder = segments.slice(0, depth).join("/");
+        const level = depth === 1 ? [] : [`${folder}.md`];
+        level.push(`${folder}/${INDEX_FILE}`);
+        levels.push(level);
+    }
+    return levels;
+}
+/**
+ * Resolve a topic to the single handler file that runs for it. The
+ * first level of {@link handlerCandidateLevels} holding any existing
+ * file wins; within a level the file form beats the folder form and
+ * the loser is reported as {@link HandlerResolution.shadowedPath}.
+ * Nothing is merged — exactly one file is the handler.
+ *
+ * @param topic Colon-separated topic, e.g. `mail:new:ms365`.
+ * @param options See {@link HandlerResolutionOptions}.
+ * @param isFile Existence probe for a workspace-relative path.
+ * @returns The resolution, or `null` when no candidate exists.
+ */
+export function resolveHandlerPath(topic, options, isFile) {
+    for (const level of handlerCandidateLevels(topic, options)) {
+        const existing = level.filter((candidate) => isFile(candidate));
+        if (existing.length > 0) {
+            return { relativePath: existing[0], shadowedPath: existing[1] ?? null };
+        }
+    }
+    return null;
+}
+/**
+ * Derive the topic a handler file answers to. The inverse of
+ * {@link handlerCandidateLevels}' own level:
+ *
+ * - `mail/important/digest.md` → `mail:important:digest`
+ * - `mail/new/index.md` → `mail:new`
+ * - `mail/index.md` → `mail`
+ *
+ * @param relativePath Workspace-relative posix path ending in `.md`.
+ * @returns The topic, or `null` for workspace-root files, non-`.md`
+ *   files and paths whose segments don't form a valid topic (e.g. a
+ *   file name containing a dot or a space).
+ */
+export function topicFromHandlerPath(relativePath) {
+    if (!relativePath.endsWith(".md")) {
+        return null;
+    }
+    const segments = relativePath.split("/");
+    if (segments.length < 2) {
+        return null;
+    }
+    const fileName = segments[segments.length - 1];
+    const folders = segments.slice(0, -1);
+    const topicSegments = fileName === INDEX_FILE ? folders : [...folders, fileName.slice(0, -".md".length)];
+    const topic = topicSegments.join(":");
+    return TOPIC_REGEXP.test(topic) ? topic : null;
+}
+/**
+ * The other form of the same handler: `a/b/c.md` ↔ `a/b/c/index.md`.
+ * Only one of the two may exist; seeding and the cron scheduler use
+ * this to detect the conflict.
+ *
+ * @param relativePath Workspace-relative posix path ending in `.md`.
+ * @returns The twin's path, or `null` when the twin would be a
+ *   workspace-root file (`a/index.md` ↔ `a.md`) or the path is a root
+ *   file / not markdown.
+ */
+export function twinHandlerPath(relativePath) {
+    if (!relativePath.endsWith(".md")) {
+        return null;
+    }
+    const segments = relativePath.split("/");
+    if (segments.length < 2) {
+        return null;
+    }
+    const fileName = segments[segments.length - 1];
+    if (fileName === INDEX_FILE) {
+        return segments.length < 3 ? null : `${segments.slice(0, -1).join("/")}.md`;
+    }
+    return `${relativePath.slice(0, -".md".length)}/${INDEX_FILE}`;
+}

package/build/Plugin.d.ts

@@ -282,6 +282,13 @@ export interface HostContext {
      * `dataDir` is for plugin-private host-only state.
      */
     readonly dataDir: string;
+    /**
+     * Absolute host path of the project's `workspace/` directory — the
+     * assistant's markdown workspace (handlers, PROMPT.md, SOUL.md,
+     * knowledge files), bind-mounted into the agent container as
+     * `/workspace`.
+     */
+    readonly workspaceDir: string;
     /**
      * Absolute host path of the project's `tmp/` directory — the
      * gitignored, safe-to-wipe scratch root (it also holds the daemon
@@ -579,6 +586,24 @@ export interface PluginToolCallContext {
      */
     readonly toolRunContext: ToolRunContext;
 }
+/**
+ * One kind of event a plugin emits onto the bus, as returned by
+ * {@link PluginHostManifest.getEmittedEvents}. Describes a topic, not an
+ * individual event — `familiar events list-topics` lists these.
+ */
+export interface EmittedEventDescriptor {
+    /** Event topic, matching `TOPIC_PATTERN` (e.g. `mail:new:ms365`). */
+    readonly topic: string;
+    /** One-line, human-readable description of when the event fires. */
+    readonly description: string;
+    /**
+     * `true` when the plugin emits this topic with `isExactTopic` (it
+     * addresses one handler file, e.g. memory's `skills:memory:save`),
+     * so `familiar events list-topics` resolves it without falling back up
+     * the topic chain. Omit for world events.
+     */
+    readonly isExactTopic?: boolean;
+}
 /**
  * Host-side surface a plugin may declare. All fields optional; a
  * plugin that's pure workspace template (no host code) leaves `host`
@@ -589,9 +614,18 @@ export interface PluginToolCallContext {
  */
 export interface PluginHostManifest {
     /**
-     * Synchronous, side-effect-light setup. Runs once per process,
-     * **before any plugin's `start`** and before any plugin one-shot
-     * CLI command's `run`. Use this for module-level state that other
+     * Config subtrees outside the plugin's own `<plugin.id>.*` group
+     * whose change restarts the plugin on a config reload (dotted paths,
+     * e.g. `["inference.apiKeys.openai"]`). The own group is always
+     * watched; list a foreign key here only when the plugin captures it
+     * in `prepare` / `start` instead of reading it per use.
+     */
+    restartOnConfigChange?: readonly string[];
+    /**
+     * Synchronous, side-effect-light setup. Runs once per process start
+     * and again on every plugin restart (config reload, after
+     * {@link stop}), **before the plugin's `start`** and before any plugin
+     * one-shot CLI command's `run`. Use this for module-level state that other
      * plugins consume — e.g. populating an API-key constant the
      * plugin's library exports — so the order in which siblings call
      * each other doesn't depend on `start` finishing first.
@@ -614,12 +648,22 @@ export interface PluginHostManifest {
      */
     start?(ctx: HostContext): Promise<void>;
     /**
-     * Drain hook called during daemon shutdown. Awaited in reverse
-     * registration order (LIFO of `start`), wrapped in a `safeStop`
-     * so a throw is logged but does not abort the rest of the drain.
-     *
-     * Use this for plugins that own dirty in-memory state which must
-     * be flushed to disk before the process exits — the memory
+     * Drain hook called during daemon shutdown and before a plugin
+     * restart (config reload changed the plugin's config group). On
+     * shutdown it is awaited in reverse registration order (LIFO of
+     * `start`), wrapped in a `safeStop` so a throw is logged but does
+     * not abort the rest of the drain.
+     *
+     * Must release everything `start` set up — timers, poll loops,
+     * sockets, chat / workspace subscriptions — and reset module state,
+     * because a restart runs `prepare` → `start` → `tools` again in the
+     * same process. Providers, prompt appenders / placeholders and tools
+     * the plugin registered are unregistered by the host. A plugin with
+     * a `start` but no `stop` cannot be restarted: a config reload that
+     * touches it reports "daemon restart required" instead.
+     *
+     * Use this also for plugins that own dirty in-memory state which
+     * must be flushed to disk before the process exits — the memory
      * plugin's Orama index is the motivating case.
      *
      * Hard rules: must resolve within the daemon-wide drain budget
@@ -634,8 +678,9 @@ export interface PluginHostManifest {
     stop?(ctx: HostContext): Promise<void>;
     /**
      * Declarative list of {@link PluginTool}s this plugin contributes
-     * to the agent. Collected once, **after** the plugin's `start`
-     * resolves, so closures over `start`-time state are safe.
+     * to the agent. Collected **after** the plugin's `start` resolves
+     * (at boot and after every restart), so closures over `start`-time
+     * state are safe.
      *
      * Hard rules: synchronous, side-effect-free — just build and
      * return the tool list. The host registers each tool under
@@ -681,6 +726,19 @@ export interface PluginHostManifest {
      * collision between two plugins, the first registered wins (logged).
      */
     getModelProviders?(ctx: HostContext): readonly ModelProviderDescriptor[];
+    /**
+     * Declare the event topics this plugin emits onto the bus under the
+     * current configuration — e.g. ms365 omits `mail:new:ms365` when its
+     * mail feature is disabled. Backs `familiar events list-topics`, so the
+     * operator can see which topics exist and which handler file each
+     * one resolves to.
+     *
+     * Hard rules: synchronous, side-effect-free — derive the list from
+     * constants and `ctx.config`, no network, no DB. Called after
+     * `prepare`, also from one-shot CLI runs without the daemon. Topics
+     * that don't match `TOPIC_PATTERN` are logged and dropped.
+     */
+    getEmittedEvents?(ctx: HostContext): readonly EmittedEventDescriptor[];
     /**
      * Default command for the plugin's CLI root. When set, invoking
      * the plugin id with no subcommand (e.g. `familiar cli-chat`) runs
@@ -723,7 +781,7 @@ export interface PluginManifest {
     readonly host?: PluginHostManifest;
     /**
      * Absolute path to a directory of files copied into
-     * `data/workspace/` on first install. Existing files are left
+     * the workspace (`<home>/workspace/`) on first install. Existing files are left
      * alone — diff/merge on plugin updates is a separate concern.
      * Plugins typically derive this with
      * `path.join(__dirname, "..", "workspace-template")` (or the ESM

package/build/PromptPlaceholders.js

@@ -30,7 +30,7 @@ export const CORE_PROMPT_PLACEHOLDERS = [
     },
     {
         name: "HANDLER_CONTENT",
-        description: "Body of the resolved handler file (merged with its parents). Placeholders inside it are expanded too.",
+        description: "Body of the resolved handler file. Placeholders inside it are expanded too.",
         kind: "static",
     },
     {
@@ -40,12 +40,7 @@ export const CORE_PROMPT_PLACEHOLDERS = [
     },
     {
         name: "HANDLER_PATH",
-        description: "Workspace-relative path of the handler file, e.g. `chat/telegram/index.md`.",
-        kind: "static",
-    },
-    {
-        name: "HANDLER_INHERITS",
-        description: "Parent handler files this handler is merged with, as `a ← b`, or `(none)`.",
+        description: "Workspace-relative path of the handler file, e.g. `chat/telegram.md`.",
         kind: "static",
     },
     {
@@ -70,7 +65,7 @@ export const CORE_PROMPT_PLACEHOLDERS = [
     },
     {
         name: "RUNTIME_LIST",
-        description: "Bullet list of run facts: current time, event topic, handler file, inheritance, outputChat, privileged.",
+        description: "Bullet list of run facts: current time, event topic, handler file, outputChat, privileged.",
         kind: "dynamic",
     },
     {

package/build/ScheduledSubagent.d.ts

@@ -12,7 +12,7 @@
  *    `scheduled_subagents_changed` NOTIFY and installs a Croner job for
  *    `fireAt` with `maxRuns: 1`.
  * 3. When the job fires, the host atomically claims-and-deletes the
- *    row, then emits a fresh event with the row's topic / handler /
+ *    row, then emits a fresh exact-topic event with the row's topic /
  *    prompt / payload / priority / privileged.
  *
  * `prompt` is optional at the table level so the agent can schedule
@@ -25,8 +25,8 @@ export interface ScheduledSubagentRow {
     readonly key: string;
     /** UTC ISO-8601 firing time (e.g. `2026-05-21T13:00:00Z`). */
     readonly fireAt: string;
+    /** Handler address; must resolve exactly (no fallback up the topic chain). */
     readonly topic: string;
-    readonly handler: string;
     readonly prompt: string | null;
     readonly payload: unknown;
     readonly priority: number;
@@ -41,7 +41,6 @@ export interface NewScheduledSubagent {
     readonly key: string;
     readonly fireAt: string;
     readonly topic: string;
-    readonly handler: string;
     readonly prompt?: string | null;
     readonly payload?: unknown;
     readonly priority?: number;

package/build/ScheduledSubagentBus.d.ts

@@ -43,7 +43,7 @@ export declare class ScheduledSubagentBus {
      * old row is overwritten in one statement so the host scheduler
      * sees exactly one NOTIFY and installs exactly one job.
      *
-     * @throws If `topic` does not match `\w+(:\w+)*` (CHECK constraint).
+     * @throws If `topic` does not match `TOPIC_PATTERN` (CHECK constraint).
      */
     upsert(row: NewScheduledSubagent): Promise<ScheduledSubagentRow>;
     /**

package/build/ScheduledSubagentBus.js

@@ -37,16 +37,15 @@ export class ScheduledSubagentBus {
      * old row is overwritten in one statement so the host scheduler
      * sees exactly one NOTIFY and installs exactly one job.
      *
-     * @throws If `topic` does not match `\w+(:\w+)*` (CHECK constraint).
+     * @throws If `topic` does not match `TOPIC_PATTERN` (CHECK constraint).
      */
     async upsert(row) {
         const result = await this.connection.getPool().query(`INSERT INTO scheduled_subagents
-                (key, fire_at, topic, handler, prompt, payload, priority, privileged)
-             VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8)
+                (key, fire_at, topic, prompt, payload, priority, privileged)
+             VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7)
              ON CONFLICT (key) DO UPDATE SET
                 fire_at = EXCLUDED.fire_at,
                 topic = EXCLUDED.topic,
-                handler = EXCLUDED.handler,
                 prompt = EXCLUDED.prompt,
                 payload = EXCLUDED.payload,
                 priority = EXCLUDED.priority,
@@ -55,7 +54,6 @@ export class ScheduledSubagentBus {
             row.key,
             row.fireAt,
             row.topic,
-            row.handler,
             row.prompt ?? null,
             JSON.stringify(row.payload ?? {}),
             row.priority ?? 50,
@@ -177,7 +175,6 @@ function mapRow(raw) {
         key: raw.key,
         fireAt: raw.fire_at.toISOString(),
         topic: raw.topic,
-        handler: raw.handler,
         prompt: raw.prompt,
         payload: raw.payload,
         priority: raw.priority,