@vellumai/assistant 0.7.3 → 0.8.1

package/src/memory/v2/prompts/router.ts

@@ -0,0 +1,192 @@
+/**
+ * Memory v2 — router prompt template.
+ *
+ * The router runs once per assistant turn and decides which concept pages (if
+ * any) should be injected on top of the always-on essentials/threads/recent
+ * block. The body lives here (under `prompts/`) so it is reviewable on its
+ * own, mirroring the convention established in `sweep.ts`.
+ *
+ * Three placeholders are substituted at runtime:
+ *
+ *   - `{{ASSISTANT_NAME}}` — assistant display name (from IDENTITY.md when
+ *     available, else the neutral fallback "the assistant").
+ *   - `{{USER_NAME}}` — guardian display name (from the guardian persona when
+ *     available, else "the user").
+ *   - `{{PAGE_INDEX}}` — pre-rendered page index. Each line has the shape
+ *     `[id] slug — summary (edges: a, b, c)` where edges are numeric IDs into
+ *     the same list. The caller renders this so the prompt module stays
+ *     stateless.
+ *
+ * Operators may replace the bundled body via
+ * `memory.v2.router.router_prompt_path` and {@link resolveRouterPrompt} — the
+ * same placeholder substitution applies to overrides.
+ */
+
+import { lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+import { getLogger } from "../../../util/logger.js";
+import { getWorkspaceDir } from "../../../util/platform.js";
+
+const log = getLogger("memory-v2-router-prompt");
+
+/**
+ * Hard upper bound on the override file size. The bundled prompt is well
+ * under 4 KiB; 1 MiB is generous-enough for any reasonable hand-edit while
+ * still preventing pathological inputs from being slurped into memory on
+ * every router call.
+ */
+const MAX_PROMPT_BYTES = 1 * 1024 * 1024;
+
+/** Sentinel substituted with the assistant's display name at runtime. */
+const ASSISTANT_NAME_PLACEHOLDER = "{{ASSISTANT_NAME}}";
+
+/** Sentinel substituted with the guardian's display name at runtime. */
+const USER_NAME_PLACEHOLDER = "{{USER_NAME}}";
+
+/** Sentinel substituted with the rendered page index block at runtime. */
+const PAGE_INDEX_PLACEHOLDER = "{{PAGE_INDEX}}";
+
+/**
+ * Router prompt — picks at most a handful of concept pages to inject for the
+ * next assistant turn. The model emits a `select_pages_to_inject` tool call
+ * with a `page_ids` array; the runtime parses the response via the tool
+ * definition declared in the router job module.
+ *
+ * Recent message context and `<now>` / `<already_injected_ids>` blocks are
+ * appended at the call site so we don't inadvertently expand `{{` inside
+ * dynamic content.
+ */
+const ROUTER_PROMPT = `You are a background helper for ${ASSISTANT_NAME_PLACEHOLDER}. Your job is to route memory pages for the next assistant turn between ${ASSISTANT_NAME_PLACEHOLDER} and ${USER_NAME_PLACEHOLDER}.
+
+You will be shown the recent conversation, a \`<now>\` marker for the current time, an \`<already_injected_ids>\` block listing pages picked on the previous turn, and a \`# Concept Page Index\` listing every routable page on this workspace.
+
+Pick the concept pages whose contents would help ${ASSISTANT_NAME_PLACEHOLDER} respond well on this turn. Lean toward inclusion when in doubt — missing a relevant page is a worse error than surfacing a few unused ones, because the assistant can ignore extras but can't summon context that wasn't loaded. Abstain (return an empty list) only when nothing in the index plausibly bears on the turn.
+
+Index format. Each line of the index has the shape:
+
+    [id] slug — summary (edges: a, b, c)
+
+\`id\` is a small integer used to refer to this page. \`edges\` are numeric IDs into the same list, pointing at related pages; you may follow them when one page strongly implies another.
+
+Already-injected pages. Pages whose IDs appear in \`<already_injected_ids>\` were picked on the previous turn. Do not pick them again unless ${ASSISTANT_NAME_PLACEHOLDER} should re-anchor on that material — e.g., the topic genuinely returns after drifting away. Routine continuity does not require re-picking; the prior turn's pages are already in the assistant's working context.
+
+Time. Bias toward pages that match the current state implied by \`<now>\` and the active conversational threads (what is happening today, what was just decided, who is being discussed). Stale pages with no bearing on the live conversation should be skipped even if their summaries look superficially relevant.
+
+Emit your selection by calling \`select_pages_to_inject\` with the chosen \`page_ids\`. Return an empty array to abstain.
+
+# Concept Page Index
+
+${PAGE_INDEX_PLACEHOLDER}`;
+
+interface RenderRouterPromptOpts {
+  assistantName: string | null;
+  userName: string | null;
+  pageIndexBlock: string;
+}
+
+/**
+ * Resolve `ROUTER_PROMPT` with assistant name, user name, and the rendered
+ * page index substituted in. Falls back to neutral defaults so the prompt
+ * still produces well-formed English when either name is unavailable on this
+ * workspace. The page index is substituted verbatim — callers are responsible
+ * for trimming/formatting it.
+ */
+export function renderRouterPrompt(opts: RenderRouterPromptOpts): string {
+  return substitutePlaceholders(ROUTER_PROMPT, opts);
+}
+
+/**
+ * Load the router prompt template, optionally overridden from the file
+ * referenced by `memory.v2.router.router_prompt_path`, then substitute the
+ * standard placeholders. Path-resolution rules mirror the consolidation
+ * prompt override: absolute paths used as-is, leading `~/` expanded to home,
+ * relative paths resolved under the workspace root.
+ *
+ * Failure handling is intentionally permissive — missing file, read error,
+ * oversized file, or empty/whitespace-only body all log a warning and fall
+ * back to the bundled prompt. Router selection must never break because of
+ * a bad override.
+ */
+export function resolveRouterPrompt(
+  overridePath: string | null,
+  opts: RenderRouterPromptOpts,
+): string {
+  if (overridePath === null) return renderRouterPrompt(opts);
+
+  const resolvedPath = resolveOverridePath(overridePath);
+  let contents: string;
+  try {
+    const stat = lstatSync(resolvedPath);
+    if (!stat.isFile()) {
+      log.warn(
+        {
+          configuredPath: overridePath,
+          resolvedPath,
+          reason: "not_regular_file",
+          fallback: "bundled",
+        },
+        "router prompt override is not a regular file; using bundled prompt",
+      );
+      return renderRouterPrompt(opts);
+    }
+    if (stat.size > MAX_PROMPT_BYTES) {
+      log.warn(
+        {
+          configuredPath: overridePath,
+          resolvedPath,
+          size: stat.size,
+          limit: MAX_PROMPT_BYTES,
+          reason: "oversized_override",
+          fallback: "bundled",
+        },
+        "router prompt override exceeds size limit; using bundled prompt",
+      );
+      return renderRouterPrompt(opts);
+    }
+    contents = readFileSync(resolvedPath, "utf-8");
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    log.warn(
+      { configuredPath: overridePath, resolvedPath, code, fallback: "bundled" },
+      "router prompt override unreadable; using bundled prompt",
+    );
+    return renderRouterPrompt(opts);
+  }
+
+  if (contents.trim().length === 0) {
+    log.warn(
+      {
+        configuredPath: overridePath,
+        resolvedPath,
+        reason: "empty_override",
+        fallback: "bundled",
+      },
+      "router prompt override is empty; using bundled prompt",
+    );
+    return renderRouterPrompt(opts);
+  }
+
+  return substitutePlaceholders(contents, opts);
+}
+
+function substitutePlaceholders(
+  template: string,
+  opts: RenderRouterPromptOpts,
+): string {
+  const assistant = opts.assistantName?.trim() || "the assistant";
+  const user = opts.userName?.trim() || "the user";
+  return template
+    .replaceAll(ASSISTANT_NAME_PLACEHOLDER, assistant)
+    .replaceAll(USER_NAME_PLACEHOLDER, user)
+    .replaceAll(PAGE_INDEX_PLACEHOLDER, opts.pageIndexBlock);
+}
+
+function resolveOverridePath(overridePath: string): string {
+  if (overridePath.startsWith("~/")) {
+    return join(homedir(), overridePath.slice(2));
+  }
+  if (isAbsolute(overridePath)) return overridePath;
+  return join(getWorkspaceDir(), overridePath);
+}