@vellumai/assistant 0.8.0 → 0.8.1

package/src/notifications/home-feed-side-effect.ts

@@ -0,0 +1,111 @@
+/**
+ * Home-feed side effect for the notification pipeline.
+ *
+ * Writes a `FeedItem` into the home activity feed when a notification
+ * signal originates from a non-interactive (background or scheduled)
+ * conversation, or carries the `isAsyncBackground` attention hint.
+ *
+ * Producer flows like the scheduler, watchers, and background activity
+ * jobs already emit through `emitNotificationSignal()` — this helper
+ * mirrors the high-signal subset of that traffic into the home feed so
+ * the macOS Home page surfaces them alongside other activity.
+ */
+import {
+  type FeedItem,
+  feedItemSchema,
+  type FeedItemUrgency,
+} from "../home/feed-types.js";
+import { appendFeedItem } from "../home/feed-writer.js";
+import { getConversation } from "../memory/conversation-crud.js";
+import { isBackgroundConversationType } from "../memory/conversation-types.js";
+import { getLogger } from "../util/logger.js";
+import type { NotificationSignal } from "./signal.js";
+import type {
+  NotificationDecision,
+  NotificationDeliveryResult,
+} from "./types.js";
+
+const log = getLogger("home-feed-side-effect");
+
+const FEED_ITEM_URGENCIES: ReadonlySet<string> = new Set<FeedItemUrgency>([
+  "low",
+  "medium",
+  "high",
+  "critical",
+]);
+
+/**
+ * Append a `FeedItem` for the given notification signal when the
+ * filter criteria pass.
+ *
+ * Returns the persisted `FeedItem`, or `null` if the signal does not
+ * qualify for home-feed mirroring (non-background origin AND no
+ * `isAsyncBackground` hint) or if schema validation fails.
+ */
+export async function writeHomeFeedItemForSignal(
+  signal: NotificationSignal,
+  decision: NotificationDecision,
+  deliveryResults: NotificationDeliveryResult[],
+): Promise<FeedItem | null> {
+  if (!shouldMirrorToHomeFeed(signal)) return null;
+
+  const renderedCopy = decision.renderedCopy.vellum;
+  const payloadTitle = readPayloadString(signal.contextPayload, "title");
+  const payloadBody = readPayloadString(signal.contextPayload, "body");
+
+  const conversationId = deliveryResults.find(
+    (r) => r.channel === "vellum",
+  )?.conversationId;
+  const urgency = FEED_ITEM_URGENCIES.has(signal.attentionHints.urgency)
+    ? (signal.attentionHints.urgency as FeedItemUrgency)
+    : undefined;
+  const now = new Date().toISOString();
+
+  const item: FeedItem = {
+    id: `notif:${signal.signalId}`,
+    type: "notification",
+    priority: 50,
+    title: renderedCopy?.title ?? payloadTitle ?? signal.sourceEventName,
+    summary: renderedCopy?.body ?? payloadBody ?? signal.sourceEventName,
+    timestamp: now,
+    createdAt: now,
+    status: "new",
+    ...(urgency ? { urgency } : {}),
+    ...(conversationId ? { conversationId } : {}),
+  };
+
+  try {
+    feedItemSchema.parse(item);
+  } catch (err) {
+    log.warn(
+      { err, signalId: signal.signalId },
+      "FeedItem failed schema validation; skipping home-feed write",
+    );
+    return null;
+  }
+
+  await appendFeedItem(item);
+  return item;
+}
+
+/**
+ * `sourceContextId` is best-effort — it may not be a conversation id
+ * (e.g. scheduler job id, watcher event id), so a lookup failure
+ * falls through to "not a background conversation" rather than throwing.
+ */
+function shouldMirrorToHomeFeed(signal: NotificationSignal): boolean {
+  if (signal.attentionHints.isAsyncBackground) return true;
+  if (!signal.sourceContextId) return false;
+  try {
+    const row = getConversation(signal.sourceContextId);
+    return isBackgroundConversationType(row?.conversationType);
+  } catch {
+    return false;
+  }
+}
+
+function readPayloadString(payload: unknown, key: string): string | undefined {
+  if (!payload || typeof payload !== "object") return undefined;
+  const value = (payload as Record<string, unknown>)[key];
+  return typeof value === "string" ? value : undefined;
+}

package/src/notifications/signal.ts

@@ -88,6 +88,11 @@ export const NOTIFICATION_SOURCE_EVENT_NAMES = [
     description: "Tool requires user confirmation before executing",
   },
   { id: "activity.complete", description: "Background activity finished" },
+  {
+    id: "activity.failed",
+    description:
+      "Background job execution failed (model_provider, exception, or timeout)",
+  },
   {
     id: "quick_chat.response_ready",
     description: "Quick chat response ready for review",

package/src/permissions/checker.ts

@@ -289,6 +289,17 @@ function buildClassifyRiskParams(
 ): ClassifyRiskParams {
   // ── Bash/host_bash ──
   if (toolName === "bash" || toolName === "host_bash") {
+    // Count credential references attached to this invocation.
+    let credentialRefCount: number | undefined;
+    if (Array.isArray(input.credential_ids)) {
+      const validIds = (input.credential_ids as unknown[]).filter(
+        (id) => typeof id === "string" && id.length > 0,
+      );
+      if (validIds.length > 0) {
+        credentialRefCount = validIds.length;
+      }
+    }
+
     return {
       tool: toolName,
       command: getStringField(input, "command"),
@@ -297,6 +308,7 @@ function buildClassifyRiskParams(
       isContainerized: getIsContainerized(),
       networkMode:
         typeof input.network_mode === "string" ? input.network_mode : undefined,
+      credentialRefCount,
     };
   }
 

package/src/permissions/ipc-risk-types.ts

@@ -92,4 +92,6 @@ export interface ClassifyRiskParams {
   skillMetadata?: SkillMetadata;
   /** Tool registry default risk level for unknown tools. */
   registryDefaultRisk?: string;
+  /** Number of credential references attached to this tool invocation. */
+  credentialRefCount?: number;
 }

package/src/plugin-api/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Public entry point for the `@vellumai/plugin-api` package.
+ *
+ * Plugin authors import from `"@vellumai/plugin-api"`; this file is what
+ * their import lands on (directly via the published npm package, or via a
+ * boot-time shim that re-exports from the assistant binary's embedded
+ * bundle).
+ *
+ * Keep this file's surface stable across minor/patch releases. Anything
+ * exported here is part of the public contract.
+ */
+
+export type { PluginInitContext, PluginShutdownContext } from "./types.js";

package/src/plugin-api/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@vellumai/plugin-api",
+  "version": "0.0.0-source",
+  "description": "Public API surface for Vellum assistant plugins. Source-of-truth lives here; the bundled artifact is what gets published to npm and embedded into the assistant binary.",
+  "type": "module",
+  "private": true,
+  "main": "./index.ts",
+  "types": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  }
+}

package/src/plugin-api/types.ts

@@ -0,0 +1,62 @@
+/**
+ * Public plugin-API types.
+ *
+ * This module is the source-of-truth for types that plugin authors depend on.
+ * The rest of the assistant imports from here via relative paths
+ * (`../plugin-api/types.js`). At publish time, this file's contents are
+ * bundled into the `@vellumai/plugin-api` npm package; at runtime in the
+ * assistant binary, the same source is reachable to user plugins via a
+ * boot-time shim that re-exports from the embedded bundle.
+ *
+ * Today this module is intentionally narrow — only `PluginInitContext` and
+ * `PluginShutdownContext`. Additional public types migrate over in
+ * follow-up PRs as the surface stabilizes.
+ *
+ * Internal-only types (pipeline shapes, middleware, manifest validation,
+ * etc.) stay in `assistant/src/plugins/types.ts` until they're ready to
+ * become public.
+ */
+
+// ─── Init context ────────────────────────────────────────────────────────────
+
+/**
+ * Context passed to `Plugin.init()` during bootstrap. Carries resolved
+ * config/credentials, a pino-compatible logger scoped to the plugin, a
+ * per-plugin writable data directory, and the assistant's version metadata.
+ */
+export interface PluginInitContext {
+  /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
+  config: unknown;
+  /** Resolved credential values keyed by the entries of `manifest.requiresCredential`. */
+  credentials: Record<string, string>;
+  /**
+   * Pino-compatible child logger bound to `{ plugin: <name> }`. Untyped here
+   * to avoid pulling pino into the types module.
+   */
+  logger: unknown;
+  /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
+  pluginStorageDir: string;
+  /** Assistant semver for compatibility checks inside the plugin. */
+  assistantVersion: string;
+  /** Capability → version-list map (`ASSISTANT_API_VERSIONS`) for defensive runtime checks. */
+  apiVersions: Record<string, string[]>;
+}
+
+// ─── Shutdown context ────────────────────────────────────────────────────────
+
+/**
+ * Context passed to the `shutdown` hook during daemon teardown. Kept
+ * intentionally narrower than {@link PluginInitContext} — most teardown
+ * paths only need to know which assistant version they're shutting
+ * down against (e.g. for version-conditional cleanup of state files
+ * written by a previous boot).
+ *
+ * Additional fields may be added as concrete plugin needs surface; the
+ * `assistantVersion` field mirrors the init context's so plugins that
+ * stash a version stamp at init can compare against the same name on
+ * tear-down without keeping their own copy.
+ */
+export interface PluginShutdownContext {
+  /** Assistant semver for compatibility checks inside the plugin. */
+  assistantVersion: string;
+}

package/src/plugins/defaults/injectors.ts

@@ -251,9 +251,24 @@ const pkbReminderInjector: Injector = {
     const mode = inputs.mode ?? "full";
     if (mode !== "full") return null;
     if (!inputs.pkbActive) return null;
+    // The `memory-retrospective` feature flag enables a focused background
+    // retrospective pass that catches what the in-conversation `remember`
+    // calls miss. When that backstop is on, the per-turn pressure to call
+    // `remember` softens to a judgment framing. When it's off, the original
+    // high-pressure BODY is used so users without the retrospective still
+    // get aggressive capture in-conversation.
+    let relaxed = false;
+    try {
+      relaxed = isAssistantFeatureFlagEnabled(
+        "memory-retrospective",
+        getConfig(),
+      );
+    } catch {
+      // Best-effort — fall back to the default (non-relaxed) BODY.
+    }
     const reminder = isPkbInjectionSilencedByV2()
-      ? buildPkbReminder([])
-      : await buildPkbReminderWithHints(inputs);
+      ? buildPkbReminder([], relaxed)
+      : await buildPkbReminderWithHints(inputs, relaxed);
     return {
       id: "pkb-reminder",
       text: reminder,
@@ -283,6 +298,7 @@ function buildPkbContextBlock(content: string): string {
  */
 async function buildPkbReminderWithHints(
   inputs: TurnInjectionInputs,
+  relaxed: boolean,
 ): Promise<string> {
   let hints: string[] = [];
   const queryVector = inputs.pkbQueryVector;
@@ -343,7 +359,7 @@ async function buildPkbReminderWithHints(
       hints = [];
     }
   }
-  return buildPkbReminder(hints);
+  return buildPkbReminder(hints, relaxed);
 }
 
 /**

package/src/plugins/external-plugin-loader.ts

@@ -0,0 +1,294 @@
+/**
+ * External plugin loader — builds a {@link Plugin} from a directory and
+ * registers it with the runtime.
+ *
+ * The convention this loader walks is currently **experimental**: surface
+ * set, manifest fields, and discovery shape may all change before the
+ * framework stabilizes. We keep this module's identifiers harness-neutral
+ * ("external") so the stable call path through the harness —
+ * `loadUserPlugins → loadExternalPlugin → registerPlugin` — does not
+ * need to be renamed when the convention shifts.
+ *
+ *     <pluginDir>/
+ *       package.json              ← manifest.name comes from `name`
+ *                                   (npm scope stripped); manifest.requires
+ *                                   comes from `vellum.requires` if present
+ *       hooks/
+ *         <name>.ts               ← default export → plugin.hooks[<name>]
+ *                                   (today the runtime invokes "init" at
+ *                                    bootstrap and "shutdown" at teardown;
+ *                                    other filenames sit in the map for
+ *                                    forward compatibility)
+ *       tools/
+ *         *.ts                    ← each file's default export → plugin.tools[]
+ *       src/                      ← internal helpers, ignored by the loader
+ *
+ * Per-surface, `.js` is preferred over `.ts` (compiled-binary semantics).
+ * Missing surface files are silently omitted (the harness treats absent
+ * fields as "this plugin contributes nothing here"). Surface files
+ * present without a usable default export are a hard failure: the
+ * loader logs with attribution and skips the plugin.
+ *
+ * This function owns the per-plugin isolation contract: it never throws,
+ * times out after `importTimeoutMs`, catches any error from the build or
+ * `registerPlugin` call, and logs an attributed entry. Callers can
+ * `await loadExternalPlugin(...)` in a loop with no per-iteration guard.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { z } from "zod";
+
+import { getLogger } from "../util/logger.js";
+import { registerPlugin } from "./registry.js";
+import type {
+  Plugin,
+  PluginHookFn,
+  PluginHooks,
+  PluginManifest,
+  PluginToolRegistration,
+} from "./types.js";
+
+const log = getLogger("external-plugin-loader");
+
+/** Default upper bound on how long a single plugin load may take. */
+const DEFAULT_IMPORT_TIMEOUT_MS = 10_000;
+
+/**
+ * Zod schema for the subset of `package.json` the external loader reads.
+ *
+ * - `name` is the only required field; everything else is best-effort.
+ * - `vellum.requires` is forwarded to {@link PluginManifest.requires}
+ *   verbatim (no merge with defaults) — empty objects propagate so the
+ *   registry can reject under-specified plugins.
+ * - Unknown fields pass through (`passthrough`) so the loader does not
+ *   destructively reshape the file when the rest of the npm ecosystem
+ *   writes to it.
+ */
+const PluginPackageJsonSchema = z
+  .object({
+    name: z.string().min(1, "package.json `name` must be a non-empty string"),
+    version: z.string().optional(),
+    vellum: z
+      .object({
+        requires: z.record(z.string(), z.string()).optional(),
+      })
+      .passthrough()
+      .optional(),
+  })
+  .passthrough();
+
+type PluginPackageJson = z.infer<typeof PluginPackageJsonSchema>;
+
+export interface LoadExternalPluginOptions {
+  /**
+   * Maximum time to spend building the `Plugin` from disk before bailing.
+   * The build runs to completion in the background if it eventually
+   * resolves, but the loader has already moved on. Defaults to
+   * {@link DEFAULT_IMPORT_TIMEOUT_MS}.
+   */
+  readonly importTimeoutMs?: number;
+}
+
+/**
+ * Strip the npm scope from a package name. `@vellumai/simple-memory` →
+ * `simple-memory`; an unscoped name passes through unchanged.
+ */
+function stripScope(name: string): string {
+  const match = /^@[^/]+\/(.+)$/.exec(name);
+  return match ? match[1]! : name;
+}
+
+/**
+ * Dynamic-import `absolutePath` and return its default export. Throws when
+ * the module has no default export — callers attribute the error.
+ */
+async function importDefault<T>(absolutePath: string): Promise<T> {
+  const url = pathToFileURL(absolutePath).href;
+  const mod = (await import(url)) as { default?: T };
+  if (mod.default === undefined) {
+    throw new Error(
+      `module ${absolutePath} has no default export — external plugins must default-export their interface surfaces`,
+    );
+  }
+  return mod.default;
+}
+
+interface SurfaceFile {
+  /** Basename without `.js`/`.ts` extension. */
+  readonly name: string;
+  /** Absolute path on disk. */
+  readonly path: string;
+}
+
+/**
+ * List every `.js`/`.ts` file directly under `dir`, deduplicating `.js`
+ * over `.ts` when both are present for the same basename. Returns entries
+ * sorted by basename so plugin authors get a deterministic per-plugin
+ * registration sequence; cross-plugin order remains the registry's job.
+ *
+ * Used to walk both `hooks/` and `tools/` — neither surface needs
+ * subdirectory recursion today, so this stays flat on purpose.
+ */
+function listSurfaceDir(dir: string): SurfaceFile[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const entries = readdirSync(dir);
+  const byBase = new Map<string, string>();
+  for (const entry of entries) {
+    // `.d.ts` declaration files are TypeScript type-only artifacts shipped
+    // alongside compiled `.js`. They have no default-exported runtime
+    // function and would crash `importDefault`, so the walker filters
+    // them out before the `.js`/`.ts` extension check.
+    if (entry.endsWith(".d.ts")) continue;
+    const base =
+      entry.endsWith(".js") || entry.endsWith(".ts")
+        ? entry.slice(0, -3)
+        : null;
+    if (base === null) continue;
+    const existing = byBase.get(base);
+    if (
+      existing === undefined ||
+      (existing.endsWith(".ts") && entry.endsWith(".js"))
+    ) {
+      byBase.set(base, entry);
+    }
+  }
+  return [...byBase.keys()]
+    .sort()
+    .map((name) => ({ name, path: join(dir, byBase.get(name)!) }));
+}
+
+/**
+ * Walk every file under `<pluginDir>/hooks/` and import each as a
+ * lifecycle hook keyed by filename basename. The runtime today invokes
+ * `init` at bootstrap and `shutdown` at teardown; other filenames are
+ * loaded into the map for forward compatibility with future lifecycle
+ * events but stay inert.
+ */
+async function loadHooks(
+  pluginDir: string,
+  pluginName: string,
+): Promise<PluginHooks | undefined> {
+  const files = listSurfaceDir(join(pluginDir, "hooks"));
+  if (files.length === 0) return undefined;
+  const hooks: PluginHooks = {};
+  for (const { name, path } of files) {
+    const fn = await importDefault<PluginHookFn>(path);
+    if (typeof fn !== "function") {
+      throw new Error(
+        `external plugin ${pluginName}: hooks/${name} default export must be a function (got ${typeof fn})`,
+      );
+    }
+    hooks[name] = fn;
+  }
+  return hooks;
+}
+
+/**
+ * Build a `Plugin` object from the directory layout. Internal — the
+ * public entry point ({@link loadExternalPlugin}) wraps this in the
+ * timeout/try-catch/register triple.
+ */
+async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
+  const pkgPath = join(pluginDir, "package.json");
+  let rawPkg: unknown;
+  try {
+    rawPkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `package.json at ${pluginDir} could not be read or parsed: ${reason}`,
+    );
+  }
+  const parsed = PluginPackageJsonSchema.safeParse(rawPkg);
+  if (!parsed.success) {
+    throw new Error(
+      `package.json at ${pluginDir} failed schema validation: ${parsed.error.message}`,
+    );
+  }
+  const pkg: PluginPackageJson = parsed.data;
+  const name = stripScope(pkg.name);
+  const version = pkg.version && pkg.version.length > 0 ? pkg.version : "0.0.0";
+
+  // Default `requires` keeps the existing v1 negotiation working for
+  // plugins that have not yet opted into `vellum.requires`. Plugins that
+  // set `vellum.requires` get exactly what they declared — no merge.
+  const requires = pkg.vellum?.requires ?? { pluginRuntime: "v1" };
+
+  const manifest: PluginManifest = { name, version, requires };
+  const plugin: Plugin = { manifest };
+
+  const hooks = await loadHooks(pluginDir, name);
+  if (hooks !== undefined) plugin.hooks = hooks;
+
+  const tools: PluginToolRegistration[] = [];
+  for (const { path: toolPath } of listSurfaceDir(join(pluginDir, "tools"))) {
+    const tool = await importDefault<PluginToolRegistration>(toolPath);
+    if (
+      tool === null ||
+      typeof tool !== "object" ||
+      typeof (tool as { name?: unknown }).name !== "string"
+    ) {
+      throw new Error(
+        `external plugin ${name}: ${toolPath} default export must be a Tool object with a string "name"`,
+      );
+    }
+    tools.push(tool);
+  }
+  if (tools.length > 0) plugin.tools = tools;
+
+  return plugin;
+}
+
+/**
+ * Load the external plugin at `pluginDir` and register it.
+ */
+export async function loadExternalPlugin(
+  pluginDir: string,
+  opts: LoadExternalPluginOptions = {},
+): Promise<void> {
+  const timeoutMs = opts.importTimeoutMs ?? DEFAULT_IMPORT_TIMEOUT_MS;
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timeoutSentinel = Symbol("external-plugin-load-timeout");
+    const buildPromise = buildPluginFromDir(pluginDir);
+    const timeoutPromise = new Promise<typeof timeoutSentinel>((resolve) => {
+      timeoutHandle = setTimeout(() => resolve(timeoutSentinel), timeoutMs);
+    });
+    const result = await Promise.race([buildPromise, timeoutPromise]);
+    if (result === timeoutSentinel) {
+      // Abandoned build — surface imports may still be running. Attach a
+      // terminal `.catch` so a late rejection does not surface as an
+      // unhandled-rejection crash. The closed-registration latch in
+      // `registry.ts` rejects any late `registerPlugin()` call from a
+      // surface module that finishes evaluating after this loader has
+      // moved on.
+      buildPromise.catch(() => {
+        /* swallow — see comment above */
+      });
+      log.warn(
+        { pluginDir, timeoutMs },
+        `Timed out loading external plugin ${pluginDir} after ${timeoutMs}ms — skipping`,
+      );
+      return;
+    }
+    registerPlugin(result);
+    log.info(
+      { pluginDir, name: result.manifest.name },
+      "loaded external plugin",
+    );
+  } catch (err) {
+    // Per-plugin isolation: one bad external plugin must not crash the
+    // daemon. Surface the failure with attribution and move on.
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(
+      { err, pluginDir },
+      `Failed to load external plugin ${pluginDir}: ${message}`,
+    );
+  } finally {
+    if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+  }
+}

package/src/plugins/types.ts

@@ -93,30 +93,14 @@ export interface PluginManifest {
   config?: unknown;
 }
 
-// ─── Init context ────────────────────────────────────────────────────────────
-
-/**
- * Context passed to `Plugin.init()` during bootstrap. Carries resolved
- * config/credentials, a pino-compatible logger scoped to the plugin, a
- * per-plugin writable data directory, and the assistant's version metadata.
- */
-export interface PluginInitContext {
-  /** Parsed config for this plugin (may be `unknown` until the manifest validates). */
-  config: unknown;
-  /** Resolved credential values keyed by the entries of `manifest.requiresCredential`. */
-  credentials: Record<string, string>;
-  /**
-   * Pino-compatible child logger bound to `{ plugin: <name> }`. Untyped here
-   * to avoid pulling pino into the types module.
-   */
-  logger: unknown;
-  /** Absolute path to `<workspaceDir>/plugins-data/<plugin>/` (created by bootstrap). */
-  pluginStorageDir: string;
-  /** Assistant semver for compatibility checks inside the plugin. */
-  assistantVersion: string;
-  /** Capability → version-list map (`ASSISTANT_API_VERSIONS`) for defensive runtime checks. */
-  apiVersions: Record<string, string[]>;
-}
+// ─── Init / Shutdown context ─────────────────────────────────────────────────
+// Public types — defined in `assistant/src/plugin-api/types.ts` and re-exported
+// here so existing internal call sites keep working. Plugin authors will
+// import these from `@vellumai/plugin-api` once that package is published.
+export type {
+  PluginInitContext,
+  PluginShutdownContext,
+} from "../plugin-api/types.js";
 
 // ─── Middleware ──────────────────────────────────────────────────────────────
 
@@ -1077,19 +1061,51 @@ export interface PluginSkillRegistration {
 
 // ─── Plugin ──────────────────────────────────────────────────────────────────
 
+/**
+ * A plugin lifecycle hook. Receives a per-lifecycle context shape and
+ * may return either a transformed context or `void`. Today's runtime
+ * consumes only the resolved-or-rejected nature of the promise; the
+ * `TCtx` return is reserved for future hooks that fan a transformed
+ * context out to downstream plugins.
+ *
+ * Each known hook key has a documented context shape:
+ *   - `init` — {@link PluginInitContext}
+ *   - `shutdown` — {@link PluginShutdownContext}
+ *
+ * Unknown keys are populated by the loader for forward compatibility
+ * but are not invoked by today's runtime.
+ */
+export type PluginHookFn<TCtx = unknown> = (
+  ctx: TCtx,
+) => Promise<TCtx | void>;
+
+/**
+ * Map of lifecycle hooks contributed by a plugin. Keys match file
+ * basenames under `<plugin>/hooks/` — the external loader populates one
+ * entry per `hooks/<name>.{ts,js}` it finds. The runtime invokes
+ * known keys (`init`, `shutdown`) at the matching lifecycle event;
+ * unknown keys are forward-compat scaffolding.
+ *
+ * See `assistant/src/daemon/external-plugins-bootstrap.ts` for the
+ * full lifecycle, and {@link PluginHookFn} for the per-entry signature.
+ */
+// The map stores hooks for arbitrary keys with arbitrary context shapes.
+// `any` (rather than `unknown`) is required so concrete plugin signatures
+// like `(ctx: PluginInitContext) => Promise<void>` and `() => Promise<void>`
+// both assign in/out of slot entries under strict-function-types contravariance.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PluginHooks = Record<string, PluginHookFn<any>>;
+
 /**
  * A registered plugin. Every field besides `manifest` is optional — a plugin
  * may contribute any combination of middleware, injectors, and model-visible
- * capabilities. Lifecycle hooks (`init`, `onShutdown`) run sequentially
- * during daemon startup/shutdown.
+ * capabilities. Lifecycle hooks live under `hooks`.
  */
 export interface Plugin {
   /** Static manifest validated by the registry. */
   manifest: PluginManifest;
-  /** Optional async initializer. Runs once during bootstrap, before traffic. */
-  init?(ctx: PluginInitContext): Promise<void>;
-  /** Optional shutdown hook. Runs during daemon shutdown in reverse-registration order. */
-  onShutdown?(): Promise<void>;
+  /** Lifecycle hooks (init, shutdown). See {@link PluginHooks}. */
+  hooks?: PluginHooks;
   /** Tool registrations visible to the model. */
   tools?: PluginToolRegistration[];
   /** HTTP route registrations served by the assistant. */