@vellumai/assistant 0.6.5 → 0.6.6

package/src/daemon/external-plugins-bootstrap.ts

@@ -0,0 +1,478 @@
+/**
+ * Plugin bootstrap — runs every registered plugin's `init()` hook once during
+ * daemon startup.
+ *
+ * Plugins register themselves via side-effect imports elsewhere in the boot
+ * sequence (first-party) or at runtime (hot-reload). By the time
+ * {@link bootstrapPlugins} runs, the registry has been fully populated for
+ * this boot cycle. This function:
+ *
+ * 1. Registers the canonical first-party default plugins via
+ *    {@link registerDefaultPlugins} (one per pipeline). Registration is
+ *    idempotent so repeat calls (e.g. during integration tests) do not throw.
+ * 2. Walks {@link getRegisteredPlugins} in registration order.
+ * 3. For each plugin, consults `manifest.requiresFlag` against
+ *    {@link isAssistantFeatureFlagEnabled}. If any listed flag is disabled,
+ *    the plugin is skipped wholesale — no `init()`, no tool/route/skill
+ *    contributions, and no entry in the shutdown hook. This is the primary
+ *    mechanism for shipping experimental plugins behind a feature flag.
+ * 4. Resolves the plugin's `manifest.requiresCredential` entries via the
+ *    credential store helper ({@link getSecureKeyAsync}). In Docker mode
+ *    that helper goes through the CES HTTP API transparently; in local mode
+ *    it hits the encrypted file store / CES RPC backend.
+ * 5. Validates the config block under `plugins.<name>` against
+ *    `manifest.config` if the manifest supplies a parser-like validator
+ *    (Zod schemas with `.parse()` are supported; anything else is passed
+ *    through untouched).
+ * 6. Creates `~/.vellum/plugins-data/<plugin>/` on demand for per-plugin
+ *    writable state and exposes it via {@link PluginInitContext.pluginStorageDir}.
+ * 7. Awaits `plugin.init(ctx)` sequentially. One init failure surfaces as a
+ *    {@link PluginExecutionError} naming the offending plugin and aborts
+ *    bootstrap — later plugins' `init()` never runs and the daemon fails
+ *    startup cleanly rather than coming up in a half-wired state.
+ * 8. After a plugin's `init()` succeeds, registers any tools declared on
+ *    `plugin.tools` with the global tool registry via
+ *    {@link registerPluginTools}. Tool contributions land after `init()` so
+ *    a plugin that fails mid-init never leaves partial tool registrations
+ *    behind.
+ *
+ * A single shutdown hook is registered via
+ * {@link registerShutdownHook} that walks the plugin list in **reverse
+ * registration order**. Only plugins that actually initialized (i.e. were
+ * not skipped by the feature-flag gate) appear in that walk. For each such
+ * plugin it first unregisters the contributed tools (so `onShutdown()`
+ * observes a clean model-visible surface) and then awaits the optional
+ * `onShutdown()`. Per-plugin shutdown failures are logged and swallowed —
+ * the hook registry already swallows hook-level throws, but we log at the
+ * plugin level so the plugin name is attributed.
+ */
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../config/schema.js";
+import { registerDefaultPlugins } from "../plugins/defaults/index.js";
+import {
+  registerPluginSkills,
+  unregisterPluginSkills,
+} from "../plugins/plugin-skill-contributions.js";
+import {
+  ASSISTANT_API_VERSIONS,
+  getRegisteredPlugins,
+} from "../plugins/registry.js";
+import {
+  type Plugin,
+  PluginExecutionError,
+  type PluginInitContext,
+  type PluginSkillRegistration,
+} from "../plugins/types.js";
+import {
+  registerSkillRoute,
+  type SkillRouteHandle,
+  unregisterSkillRoute,
+} from "../runtime/skill-route-registry.js";
+import { getSecureKeyAsync } from "../security/secure-keys.js";
+import {
+  registerPluginTools,
+  unregisterPluginTools,
+} from "../tools/registry.js";
+import { getLogger } from "../util/logger.js";
+import { vellumRoot } from "../util/platform.js";
+import { registerShutdownHook } from "./shutdown-registry.js";
+
+const log = getLogger("plugins-bootstrap");
+
+/**
+ * Minimal context required to bootstrap the plugin layer. Kept intentionally
+ * small so the call site in `lifecycle.ts` can construct it from whatever
+ * state is already available at that point in startup.
+ */
+export interface DaemonContext {
+  config: AssistantConfig;
+  assistantVersion: string;
+}
+
+/**
+ * Resolve one credential value. Returns the raw secret string or throws a
+ * {@link PluginExecutionError} tagged with the plugin name so the caller can
+ * fail startup with clear attribution.
+ */
+async function resolveCredentialOrThrow(
+  pluginName: string,
+  credentialKey: string,
+): Promise<string> {
+  const value = await getSecureKeyAsync(credentialKey);
+  if (value === undefined || value === "") {
+    throw new PluginExecutionError(
+      `plugin ${pluginName} requires credential "${credentialKey}" but the credential store returned no value`,
+      pluginName,
+    );
+  }
+  return value;
+}
+
+/**
+ * Validate a plugin config block. If the manifest supplies a parser-like
+ * validator (Zod schemas expose `.parse()`), use it. Otherwise pass the
+ * config through untouched.
+ */
+function validatePluginConfig(
+  pluginName: string,
+  validator: unknown,
+  raw: unknown,
+): unknown {
+  if (
+    validator != null &&
+    typeof validator === "object" &&
+    "parse" in validator &&
+    typeof (validator as { parse: unknown }).parse === "function"
+  ) {
+    try {
+      return (validator as { parse: (input: unknown) => unknown }).parse(raw);
+    } catch (err) {
+      throw new PluginExecutionError(
+        `plugin ${pluginName} config validation failed: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+        pluginName,
+        { cause: err },
+      );
+    }
+  }
+  return raw;
+}
+
+/**
+ * Read `config.plugins.<name>`. `AssistantConfigSchema` declares `plugins` as
+ * an optional `Record<string, unknown>`, so the field is type-safe at the
+ * schema boundary; per-plugin validation happens downstream via
+ * `plugin.manifest.config` in `validatePluginConfig`.
+ */
+function getPluginConfigRaw(
+  config: AssistantConfig,
+  pluginName: string,
+): unknown {
+  return config.plugins?.[pluginName];
+}
+
+/**
+ * Ensure `~/.vellum/plugins-data/<name>/` exists and return its absolute path.
+ */
+function ensurePluginStorageDir(pluginName: string): string {
+  const dir = join(vellumRoot(), "plugins-data", pluginName);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Run every registered plugin's `init()` hook sequentially and install a
+ * reverse-order shutdown hook. See the module docstring for full semantics.
+ *
+ * Returns once every plugin has finished initialising successfully. Throws a
+ * {@link PluginExecutionError} on the first failure — the error message names
+ * the offending plugin so operators see which `init()` bailed.
+ *
+ * Must be called after any custom/third-party plugin registrations have run
+ * and before the first conversation is served. First-party defaults are
+ * registered inline via {@link registerDefaultPlugins}.
+ */
+export async function bootstrapPlugins(ctx: DaemonContext): Promise<void> {
+  // Register first-party default plugins. Each default wraps one of the
+  // assistant's canonical pipelines (`toolExecute`, `llmCall`, ...) with a
+  // passthrough so the pipeline shape is explicit at boot even when no
+  // third-party plugins are loaded. Registration is idempotent via the
+  // already-registered guard so repeated calls (e.g. during integration
+  // tests) do not throw.
+  registerDefaultPlugins();
+
+  const plugins = getRegisteredPlugins();
+  if (plugins.length === 0) {
+    // No-op fast path. The default injectors normally populate the registry,
+    // so this branch is primarily for tests that call
+    // `resetPluginRegistryForTests()` and stub the default registration.
+    log.debug("bootstrapPlugins: registry empty — skipping");
+    return;
+  }
+
+  log.info({ count: plugins.length }, "bootstrapPlugins: initializing plugins");
+
+  // Plugins that passed `requiresFlag` gating and therefore need the full
+  // init → contribute → shutdown lifecycle. Plugins skipped by the flag gate
+  // are omitted from this list so the shutdown hook below never tears down
+  // capabilities that were never wired up in the first place. Each entry
+  // carries the opaque route handles returned by `registerSkillRoute` so
+  // teardown can key on identity rather than regex-pattern text — two plugins
+  // registering the same pattern would otherwise step on each other's routes
+  // during shutdown, violating the "no traffic hits a plugin handler during
+  // onShutdown" invariant.
+  const activePlugins: ActivePlugin[] = [];
+
+  // If one plugin's init or contribution phase throws, tear down any plugins
+  // that already fully initialized (in reverse registration order) before
+  // re-throwing. Without this, a mid-loop failure would leave earlier plugins
+  // with live tools/routes/skills and no `onShutdown()` call — the shutdown
+  // hook is only registered once the loop completes successfully.
+  async function teardownPartialInit(): Promise<void> {
+    for (let i = activePlugins.length - 1; i >= 0; i--) {
+      await teardownPlugin(activePlugins[i]!, "bootstrap-failed");
+    }
+  }
+
+  for (const plugin of plugins) {
+    const name = plugin.manifest.name;
+
+    // Feature-flag gating — if any key in `manifest.requiresFlag` is
+    // disabled, skip this plugin entirely. Skipping means: no `init()`, no
+    // tool / route / skill contributions, and no shutdown hook entry. A
+    // later boot with the flag flipped ON picks up the plugin cleanly.
+    const requiredFlags = plugin.manifest.requiresFlag ?? [];
+    let disabledFlag: string | undefined;
+    for (const flagKey of requiredFlags) {
+      if (!isAssistantFeatureFlagEnabled(flagKey, ctx.config)) {
+        disabledFlag = flagKey;
+        break;
+      }
+    }
+    if (disabledFlag !== undefined) {
+      log.info(
+        { plugin: name, flag: disabledFlag },
+        `skipping plugin ${name}: feature flag ${disabledFlag} is disabled`,
+      );
+      continue;
+    }
+
+    try {
+      // Credential resolution — gather every entry in `requiresCredential`
+      // before calling `init()` so the plugin receives a fully-populated map.
+      const credentials: Record<string, string> = {};
+      const required = plugin.manifest.requiresCredential ?? [];
+      for (const key of required) {
+        credentials[key] = await resolveCredentialOrThrow(name, key);
+      }
+
+      // Per-plugin config block, validated against the manifest's parser-like
+      // validator when one is declared.
+      const rawConfig = getPluginConfigRaw(ctx.config, name);
+      const config = validatePluginConfig(
+        name,
+        plugin.manifest.config,
+        rawConfig,
+      );
+
+      // Per-plugin writable data directory. Created lazily during bootstrap
+      // rather than at registration time so the side effect is isolated to
+      // the boot path.
+      const pluginStorageDir = ensurePluginStorageDir(name);
+
+      const initContext: PluginInitContext = {
+        config,
+        credentials,
+        logger: log.child({ plugin: name }),
+        pluginStorageDir,
+        assistantVersion: ctx.assistantVersion,
+        apiVersions: ASSISTANT_API_VERSIONS,
+      };
+
+      if (plugin.init) {
+        try {
+          await plugin.init(initContext);
+        } catch (err) {
+          throw new PluginExecutionError(
+            `plugin ${name} init() failed: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+            name,
+            { cause: err },
+          );
+        }
+      }
+
+      // After init succeeds, wire in the plugin's model-visible capabilities.
+      // Tool contributions (PR 31) register only after `init()` succeeds so a
+      // plugin that fails mid-init never leaves partially-wired tools behind.
+      // Tool registration failures are wrapped in a PluginExecutionError so
+      // the offending plugin name surfaces in the abort — matching the
+      // strict-fail semantics of `init()` errors.
+      if (plugin.tools && plugin.tools.length > 0) {
+        try {
+          const accepted = registerPluginTools(name, plugin.tools);
+          log.info(
+            { plugin: name, count: accepted.length },
+            "plugin tools registered",
+          );
+        } catch (err) {
+          throw new PluginExecutionError(
+            `plugin ${name} tool registration failed: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+            name,
+            { cause: err },
+          );
+        }
+      }
+
+      // Route contributions (PR 32) — registered after init() succeeds so a
+      // plugin that fails to initialize never exposes a half-wired HTTP
+      // surface. Mirrors the skill-route registry shape; see
+      // {@link PluginRouteRegistration}. Retain every returned handle so the
+      // teardown path unregisters by identity rather than pattern text — two
+      // plugins (or a plugin and a skill) that happen to register the same
+      // regex must not evict each other's routes during shutdown.
+      const routeHandles: SkillRouteHandle[] = [];
+      if (plugin.routes && plugin.routes.length > 0) {
+        for (const route of plugin.routes) {
+          routeHandles.push(registerSkillRoute(route));
+        }
+        log.info(
+          { plugin: name, count: plugin.routes.length },
+          "plugin routes registered",
+        );
+      }
+
+      // Skills register into the in-memory plugin-skill catalog so
+      // `skill_load` / `skill_execute` can resolve them alongside filesystem
+      // skills. A registration failure aborts bootstrap with the plugin named
+      // — same strict-fail posture as init() throws.
+      if (plugin.skills && plugin.skills.length > 0) {
+        try {
+          // `plugin.skills` is typed as `PluginSkillRegistration[]` at the
+          // Plugin interface — the type assertion here is a narrowing from
+          // that generic slot into the concrete shape the registry expects.
+          registerPluginSkills(
+            name,
+            plugin.skills as readonly PluginSkillRegistration[],
+          );
+        } catch (err) {
+          throw new PluginExecutionError(
+            `plugin ${name} skill registration failed: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+            name,
+            { cause: err },
+          );
+        }
+      }
+
+      activePlugins.push({ plugin, routeHandles });
+
+      log.info({ plugin: name }, "plugin initialized");
+    } catch (err) {
+      // Tear down every plugin that already made it through its full init +
+      // contribution phase, in reverse order, before propagating the error.
+      // Without this, the caller would see a partially-wired registry (tools,
+      // routes, skills all live) with no shutdown hook to clean them up, since
+      // `registerShutdownHook` is only called after the loop completes.
+      await teardownPartialInit();
+      throw err;
+    }
+  }
+
+  // Shutdown hook — walks plugins in REVERSE registration order. We snapshot
+  // only the plugins that actually initialized so later registrations (if
+  // any) don't end up being torn down by this hook, and plugins skipped by
+  // `requiresFlag` gating do not appear in the tear-down list. Subsequent
+  // bootstraps (hot-reload) would register their own hook.
+  //
+  // For each plugin we:
+  //   1. Unregister contributed HTTP routes so incoming requests stop hitting
+  //      the plugin's handlers before its state is torn down.
+  //   2. Unregister contributed tools so the model-visible tool surface is
+  //      cleared before `onShutdown()` runs.
+  //   3. Call `onShutdown()` (if defined) so the plugin can release resources
+  //      (background tasks, timers, connections) with its tools and routes
+  //      already removed.
+  //   4. Unregister contributed skills via the ref-counted helper. Skills tear
+  //      down last so `onShutdown()` can still invoke skill-resolving code
+  //      (e.g. to flush pending skill work) before the catalog is emptied.
+  //      This mirrors the symmetry of registerPluginSkills() — every
+  //      successful registration must get a matching unregister call,
+  //      regardless of whether onShutdown throws.
+  const shutdownSnapshot: ActivePlugin[] = [...activePlugins];
+  registerShutdownHook("plugins", async (reason) => {
+    for (let i = shutdownSnapshot.length - 1; i >= 0; i--) {
+      await teardownPlugin(shutdownSnapshot[i]!, reason);
+    }
+  });
+}
+
+/**
+ * One plugin that made it through the full init + contribution phase. Holds
+ * every opaque {@link SkillRouteHandle} issued by `registerSkillRoute` so
+ * teardown can revoke exactly the routes this plugin contributed, even when
+ * the regex pattern text collides with another owner's registration.
+ */
+interface ActivePlugin {
+  readonly plugin: Plugin;
+  readonly routeHandles: readonly SkillRouteHandle[];
+}
+
+/**
+ * Tear down a single fully-initialized plugin: unregister routes, unregister
+ * tools, invoke `onShutdown()` if present, then unregister skills. Every step
+ * swallows errors and logs with plugin attribution so one bad plugin can't
+ * block teardown of the rest.
+ *
+ * Shared between the normal shutdown hook and the bootstrap error path; both
+ * consume plugins that already cleared every contribution step.
+ */
+async function teardownPlugin(
+  active: ActivePlugin,
+  reason: string,
+): Promise<void> {
+  const { plugin, routeHandles } = active;
+  const name = plugin.manifest.name;
+
+  // Unregister model-visible surfaces before invoking `onShutdown()` so the
+  // plugin's onShutdown hook observes a registry state where its tools and
+  // routes are already gone. `unregisterPluginTools` is a no-op when the
+  // plugin never contributed tools, so we don't need to guard on
+  // `plugin.tools` here. Route unregistration keys on the opaque handles
+  // retained at registration time — pattern text is not a stable key because
+  // two owners can legitimately register the same regex.
+  for (const handle of routeHandles) {
+    try {
+      unregisterSkillRoute(handle);
+    } catch (err) {
+      log.warn(
+        { err, plugin: name },
+        "plugin route unregister failed (continuing)",
+      );
+    }
+  }
+
+  try {
+    unregisterPluginTools(name);
+  } catch (err) {
+    log.warn(
+      { err, plugin: name, reason },
+      "plugin tool unregister failed (continuing with remaining plugins)",
+    );
+  }
+
+  if (plugin.onShutdown) {
+    try {
+      await plugin.onShutdown();
+    } catch (err) {
+      // Swallow — we want every plugin's onShutdown to get a chance to run
+      // even when an earlier one throws. The outer runShutdownHooks already
+      // logs at hook level, but the plugin-name attribution here is what
+      // operators read first.
+      log.warn(
+        { err, plugin: name, reason },
+        "plugin onShutdown failed (continuing with remaining plugins)",
+      );
+    }
+  }
+
+  if (plugin.skills && plugin.skills.length > 0) {
+    try {
+      unregisterPluginSkills(name);
+    } catch (err) {
+      log.warn(
+        { err, plugin: name, reason },
+        "plugin skill unregistration failed (continuing with remaining plugins)",
+      );
+    }
+  }
+}

package/src/daemon/first-greeting.ts

@@ -2,14 +2,19 @@ import { existsSync } from "node:fs";
 
 import { getWorkspacePromptPath } from "../util/platform.js";
 
-/**
- * The canned assistant response for the wake-up greeting on a fresh workspace.
- * Warm, non-presumptuous greeting that communicates "I'm new," "I improve over
- * time," and invites the user to lead with whatever they want — a task, a
- * question, or getting to know each other.
- */
-export const CANNED_FIRST_GREETING =
-  "Hey — I'm brand new. No name, no memories, no idea who you are yet. I'll get sharper the more we work together. What can I do for you?";
+export interface OnboardingGreetingContext {
+  tools: string[];
+  tasks: string[];
+  tone: string;
+  userName?: string;
+  assistantName?: string;
+}
+
+export const CANNED_FIRST_GREETING = [
+  "Hey — brand new, no name, no memories, no idea who you are yet. I'll get sharper the more we work together.",
+  "",
+  "What can I do for you? Or I can ask you some questions to get started.",
+].join("\n");
 
 /**
  * Returns `true` when all of the following are true:
@@ -31,11 +36,183 @@ export function isWakeUpGreeting(
   );
 }
 
-/**
- * Returns the canned first-greeting string. Simple getter that exists to keep
- * the call site consistent and allow future flexibility (e.g., locale-aware
- * greetings) without changing the API.
- */
-export function getCannedFirstGreeting(): string {
+export function getCannedFirstGreeting(
+  onboarding?: OnboardingGreetingContext,
+): string {
+  if (onboarding) {
+    return buildPersonalizedGreeting(onboarding);
+  }
   return CANNED_FIRST_GREETING;
 }
+
+const TOOL_LABELS: Record<string, string> = {
+  gmail: "Gmail",
+  outlook: "Outlook",
+  "google-calendar": "Google Calendar",
+  slack: "Slack",
+  notion: "Notion",
+  linear: "Linear",
+  jira: "Jira",
+  github: "GitHub",
+  figma: "Figma",
+  "google-drive": "Google Drive",
+  excel: "Excel",
+  "apple-notes": "Apple Notes",
+};
+
+const TASK_PRIORITY: string[] = [
+  "code-building",
+  "project-management",
+  "writing",
+  "research",
+  "scheduling",
+  "personal",
+];
+
+interface Guess {
+  text: string;
+  preferredTools: string[];
+}
+
+const SINGLE_GUESSES: Record<string, Guess> = {
+  "code-building": {
+    text: "shipping something or debugging",
+    preferredTools: ["github", "linear", "jira"],
+  },
+  writing: {
+    text: "drafting something or cleaning up docs",
+    preferredTools: ["notion", "google-drive", "apple-notes"],
+  },
+  research: {
+    text: "digging into a topic or making sense of something",
+    preferredTools: ["notion", "google-drive"],
+  },
+  "project-management": {
+    text: "planning the week, writing a spec, or pushing something forward",
+    preferredTools: ["notion", "linear", "google-drive"],
+  },
+  scheduling: {
+    text: "planning the week or prepping for meetings",
+    preferredTools: ["google-calendar", "outlook", "linear"],
+  },
+  personal: {
+    text: "juggling travel, bills, or household stuff",
+    preferredTools: ["gmail", "google-calendar", "apple-notes"],
+  },
+};
+
+const COMBO_GUESSES: Record<string, Guess> = {
+  "code-building+project-management": {
+    text: "shipping code or figuring out what to ship next",
+    preferredTools: ["github", "linear", "jira"],
+  },
+  "code-building+writing": {
+    text: "shipping code or writing something up",
+    preferredTools: ["github", "linear", "jira"],
+  },
+  "project-management+writing": {
+    text: "writing a spec or pushing something forward",
+    preferredTools: ["notion", "linear", "google-drive"],
+  },
+  "research+writing": {
+    text: "drafting something or digging into a topic",
+    preferredTools: ["notion", "google-drive"],
+  },
+  "project-management+scheduling": {
+    text: "planning the week or prepping for something",
+    preferredTools: ["google-calendar", "outlook", "linear"],
+  },
+};
+
+function comboKey(a: string, b: string): string {
+  return [a, b].sort().join("+");
+}
+
+function highestPriorityTask(tasks: string[]): string | undefined {
+  for (const t of TASK_PRIORITY) {
+    if (tasks.includes(t)) return t;
+  }
+  return tasks[0];
+}
+
+function buildIntroLine(userName?: string, assistantName?: string): string {
+  const namepart = userName ? `Hey ${userName},` : "Hey,";
+  const who = assistantName
+    ? `I'm ${assistantName}. Brand new, and I'll get sharper the more we work together.`
+    : "brand new, and I'll get sharper the more we work together.";
+  return `${namepart} ${who}`;
+}
+
+function pickRelevantTools(
+  preferredTools: string[],
+  userTools: string[],
+): string[] {
+  const userSet = new Set(userTools);
+  const matched: string[] = [];
+  for (const t of preferredTools) {
+    if (userSet.has(t)) {
+      matched.push(TOOL_LABELS[t] ?? t);
+      if (matched.length === 2) break;
+    }
+  }
+  return matched;
+}
+
+function buildSpecificGuess(tasks: string[], tools: string[]): string {
+  let guess: Guess | undefined;
+
+  if (tasks.length === 2) {
+    guess = COMBO_GUESSES[comboKey(tasks[0], tasks[1])];
+  }
+
+  if (!guess) {
+    const top = highestPriorityTask(tasks);
+    guess = top ? SINGLE_GUESSES[top] : undefined;
+  }
+
+  if (!guess) return "";
+
+  const relevant = pickRelevantTools(guess.preferredTools, tools);
+
+  if (relevant.length === 2) {
+    return `You mentioned using ${relevant[0]} and ${relevant[1]} — probably ${guess.text}? Am I on the right track, or something else on your mind?`;
+  }
+  if (relevant.length === 1) {
+    return `You mentioned using ${relevant[0]} — probably ${guess.text}? Am I on the right track, or something else on your mind?`;
+  }
+
+  return `Probably ${guess.text}? Am I on the right track, or something else on your mind?`;
+}
+
+function buildPersonalizedGreeting(ctx: OnboardingGreetingContext): string {
+  const userName = ctx.userName?.trim();
+  const assistantName = ctx.assistantName?.trim();
+
+  const hasName = userName && userName.length > 0;
+  const hasTasks = ctx.tasks.length > 0;
+  const hasTools = ctx.tools.length > 0;
+
+  const hasAssistantName = assistantName && assistantName.length > 0;
+
+  if (!hasName && !hasTasks && !hasTools && !hasAssistantName) {
+    return CANNED_FIRST_GREETING;
+  }
+
+  const intro = buildIntroLine(hasName ? userName : undefined, assistantName);
+
+  let secondParagraph: string;
+
+  if (ctx.tasks.length >= 4) {
+    secondParagraph =
+      "Looks like you wear a lot of hats. Where should we start?";
+  } else if (ctx.tasks.length === 0) {
+    secondParagraph =
+      "What's on your plate? Or if it's easier, I can ask you a few questions to get oriented.";
+  } else {
+    secondParagraph =
+      buildSpecificGuess(ctx.tasks, ctx.tools) ||
+      "What's on your plate? Or if it's easier, I can ask you a few questions to get oriented.";
+  }
+
+  return [intro, "", secondParagraph].join("\n");
+}