@vellumai/assistant 0.10.9-staging.1 → 0.10.9

package/src/apps/app-store.ts

@@ -35,10 +35,11 @@ import {
 } from "node:path";
 
 import { rawAll } from "../persistence/raw-query.js";
+import { isPluginDisabled } from "../plugins/disabled-state.js";
 import type { EditEngineResult } from "../tools/shared/filesystem/edit-engine.js";
 import { applyEdit } from "../tools/shared/filesystem/edit-engine.js";
 import { getLogger } from "../util/logger.js";
-import { getDataDir } from "../util/platform.js";
+import { getDataDir, getWorkspacePluginsDir } from "../util/platform.js";
 
 export interface AppDefinition {
   id: string;
@@ -85,6 +86,28 @@ export function resolveEffectiveAppHtml(app: AppDefinition): string {
   return `<p>App compilation failed. Edit a source file to trigger a rebuild.</p>`;
 }
 
+/**
+ * Resolve the effective, self-contained HTML for an app given its source
+ * directory and format, without needing a loaded {@link AppDefinition}. Used
+ * to render apps addressed by path (e.g. plugin-bundled apps). Single-file
+ * apps serve their root index.html; multi-file apps serve the compiled
+ * dist/index.html with JS/CSS inlined.
+ */
+export function resolveEffectiveAppHtmlFromDir(
+  sourceDir: string,
+  formatVersion: number,
+): string {
+  if (formatVersion !== 2) {
+    const indexPath = join(sourceDir, "index.html");
+    return existsSync(indexPath) ? readFileSync(indexPath, "utf-8") : "";
+  }
+  const distIndex = join(sourceDir, "dist", "index.html");
+  if (existsSync(distIndex)) {
+    return inlineDistAssets(sourceDir, readFileSync(distIndex, "utf-8"));
+  }
+  return `<p>App compilation failed. Edit a source file to trigger a rebuild.</p>`;
+}
+
 /**
  * Inline dist assets (main.js, main.css) into the compiled HTML so it can be
  * delivered as a self-contained string via loadHTMLString/SSE without needing
@@ -377,6 +400,16 @@ function invalidateDirNameCache(appId?: string): void {
  * Returns the resolved absolute path.
  */
 function validateFilePath(appId: string, path: string): string {
+  return validateFilePathInDir(getAppDirPath(appId), path);
+}
+
+/**
+ * Validate a relative file path within a known app directory (absolute path).
+ * Prevents path traversal and access to protected directories. Used when the
+ * app directory is already resolved (e.g. plugin-bundled apps addressed by
+ * path rather than by a workspace app id).
+ */
+function validateFilePathInDir(appDir: string, path: string): string {
   if (!path || path.trim() === "") {
     throw new Error(`Invalid file path: path is empty`);
   }
@@ -391,7 +424,6 @@ function validateFilePath(appId: string, path: string): string {
   if (normalized === "records" || normalized.startsWith("records/")) {
     throw new Error(`Invalid file path: 'records/' directory is protected`);
   }
-  const appDir = getAppDirPath(appId);
   const resolved = resolve(appDir, path);
   // Ensure the resolved path is still within the app directory
   if (!resolved.startsWith(appDir + "/") && resolved !== appDir) {
@@ -624,6 +656,257 @@ export function listApps(): AppDefinition[] {
   return apps;
 }
 
+// ---------------------------------------------------------------------------
+// Cross-source enumeration (workspace + plugin-bundled apps)
+// ---------------------------------------------------------------------------
+
+/**
+ * Where an app is provided from. Workspace apps are user-created and live under
+ * `<workspace>/data/apps/`; plugin apps are bundled by an installed plugin
+ * under `<workspace>/plugins/<name>/apps/`.
+ */
+export type AppOrigin =
+  | { readonly kind: "workspace" }
+  | { readonly kind: "plugin"; readonly pluginName: string };
+
+/**
+ * Id prefix marking a plugin-bundled app. A plugin app's id encodes its
+ * location: `plugins~<pluginName>~<appDir>`, which maps to
+ * `<workspace>/plugins/<pluginName>/apps/<appDir>` (the `apps/` segment is
+ * implied). Unlike workspace apps — whose id is an opaque UUID looked up by
+ * scanning — a plugin app is resolved by a direct path build.
+ *
+ * The delimiter is `~` (a URL-unreserved character), not `/`, so the id is a
+ * single URL path segment: it survives `:id` route params and proxies without
+ * percent-encoding (`%2F` in a path is widely mishandled).
+ */
+const PLUGIN_APP_ID_PREFIX = "plugins~";
+const PLUGIN_APP_ID_SEP = "~";
+
+/** Build the addressable id for a plugin-bundled app. */
+function pluginAppId(pluginName: string, appDir: string): string {
+  return `${PLUGIN_APP_ID_PREFIX}${pluginName}${PLUGIN_APP_ID_SEP}${appDir}`;
+}
+
+/** True when an app id addresses a plugin-bundled app (vs a workspace app). */
+export function isPluginAppId(id: string): boolean {
+  return id.startsWith(PLUGIN_APP_ID_PREFIX);
+}
+
+/** An app paired with the absolute path to its source and its origin. */
+export interface EnumeratedApp {
+  /**
+   * Addressable app id: an opaque UUID for workspace apps, or
+   * `plugins~<name>~<app>` for plugin-bundled apps.
+   */
+  readonly id: string;
+  /** Human-readable app name. */
+  readonly name: string;
+  /** Absolute path to the app's source directory. */
+  readonly sourcePath: string;
+  /** Where the app is provided from. */
+  readonly origin: AppOrigin;
+}
+
+/**
+ * Enumerate apps bundled under a single plugin's `apps/` directory. Each
+ * immediate subdirectory is one app: its directory name is the app name and
+ * its path is the source.
+ */
+function listAppsForPlugin(
+  pluginName: string,
+  pluginDir: string,
+): EnumeratedApp[] {
+  const appsDir = join(pluginDir, "apps");
+  let entries: string[];
+  try {
+    entries = readdirSync(appsDir);
+  } catch {
+    // No apps/ directory (or unreadable) — this plugin bundles no apps.
+    return [];
+  }
+  const apps: EnumeratedApp[] = [];
+  for (const entry of entries) {
+    const appDir = join(appsDir, entry);
+    try {
+      // statSync follows symlinks so a symlinked app directory still counts.
+      if (!statSync(appDir).isDirectory()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    apps.push({
+      id: pluginAppId(pluginName, entry),
+      name: entry,
+      sourcePath: appDir,
+      origin: { kind: "plugin", pluginName },
+    });
+  }
+  return apps;
+}
+
+/**
+ * Enumerate apps bundled by installed, enabled plugins under
+ * `<workspace>/plugins/<name>/apps/`.
+ *
+ * Plugin discovery mirrors the plugin loader's `scanPlugins`: a plugin is an
+ * entry that resolves to a directory (following symlinks) and carries a
+ * `package.json` manifest. Stray directories without a manifest are ignored,
+ * and disabled plugins (those with a `.disabled` sentinel) contribute nothing,
+ * matching how their other surfaces (tools, hooks, routes) are gated.
+ */
+export function listPluginApps(): EnumeratedApp[] {
+  const pluginsRoot = getWorkspacePluginsDir();
+  if (!existsSync(pluginsRoot)) {
+    return [];
+  }
+  let entries: string[];
+  try {
+    entries = readdirSync(pluginsRoot);
+  } catch {
+    return [];
+  }
+  const apps: EnumeratedApp[] = [];
+  for (const name of entries) {
+    const pluginDir = join(pluginsRoot, name);
+    try {
+      if (!statSync(pluginDir).isDirectory()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    if (!existsSync(join(pluginDir, "package.json"))) {
+      continue;
+    }
+    if (isPluginDisabled(name)) {
+      continue;
+    }
+    apps.push(...listAppsForPlugin(name, pluginDir));
+  }
+  return apps;
+}
+
+/**
+ * Enumerate every app the assistant can surface, tagged with its origin:
+ * workspace apps (user-created) followed by apps bundled by installed plugins.
+ */
+export function listAllApps(): EnumeratedApp[] {
+  const workspaceApps: EnumeratedApp[] = listApps().map((definition) => ({
+    id: definition.id,
+    name: definition.name,
+    sourcePath: getAppDirPath(definition.id),
+    origin: { kind: "workspace" as const },
+  }));
+  return [...workspaceApps, ...listPluginApps()];
+}
+
+/** An app id resolved to its on-disk source and metadata. */
+export interface ResolvedAppSource {
+  /** The id that was resolved (echoed back for the caller). */
+  readonly id: string;
+  /** Human-readable app name. */
+  readonly name: string;
+  /** Filesystem directory stem — the workspace slug or the plugin app dir. */
+  readonly dirName: string;
+  /** Absolute path to the app's source directory. */
+  readonly sourceDir: string;
+  /** Where the app is provided from. */
+  readonly origin: AppOrigin;
+  /** 1 = single-file (index.html at root); 2 = multi-file (compiled dist/). */
+  readonly formatVersion: number;
+}
+
+/**
+ * Validate a single plugin-app id path segment (plugin name or app directory).
+ * Rejects empty, traversal, separators, and untrimmed values so an id can be
+ * mapped to a filesystem path without escaping the plugins root.
+ */
+function isSafeIdSegment(segment: string): boolean {
+  return (
+    segment.length > 0 &&
+    segment === segment.trim() &&
+    !segment.includes("/") &&
+    !segment.includes("\\") &&
+    !segment.includes("..") &&
+    segment !== "."
+  );
+}
+
+/**
+ * Resolve an app id to its on-disk source, for both workspace apps (opaque
+ * UUID, looked up via {@link getApp}) and plugin-bundled apps
+ * (`plugins~<name>~<app>`, resolved by direct path build). Returns null when
+ * the app does not exist, or when a plugin id fails the same installed-plugin
+ * gates as discovery (directory, `package.json` manifest, not disabled).
+ */
+export function resolveAppSource(id: string): ResolvedAppSource | null {
+  if (id.startsWith(PLUGIN_APP_ID_PREFIX)) {
+    const rest = id.slice(PLUGIN_APP_ID_PREFIX.length);
+    // Split on the first delimiter: the plugin name is kebab-case (no `~`), so
+    // everything after it is the app directory (which may itself contain `~`).
+    const sep = rest.indexOf(PLUGIN_APP_ID_SEP);
+    if (sep === -1) {
+      return null;
+    }
+    const pluginName = rest.slice(0, sep);
+    const appDirName = rest.slice(sep + PLUGIN_APP_ID_SEP.length);
+    // Both must be safe single path components — the app segment, used as a
+    // directory name, must not smuggle in separators or traversal.
+    if (!isSafeIdSegment(pluginName) || !isSafeIdSegment(appDirName)) {
+      return null;
+    }
+    const pluginDir = join(getWorkspacePluginsDir(), pluginName);
+    try {
+      if (!statSync(pluginDir).isDirectory()) {
+        return null;
+      }
+    } catch {
+      return null;
+    }
+    if (!existsSync(join(pluginDir, "package.json"))) {
+      return null;
+    }
+    if (isPluginDisabled(pluginName)) {
+      return null;
+    }
+    const sourceDir = join(pluginDir, "apps", appDirName);
+    try {
+      if (!statSync(sourceDir).isDirectory()) {
+        return null;
+      }
+    } catch {
+      return null;
+    }
+    // Single-file apps ship index.html at the root; anything else is treated
+    // as multi-file (served from a compiled dist/).
+    const formatVersion = existsSync(join(sourceDir, "index.html")) ? 1 : 2;
+    return {
+      id,
+      name: appDirName,
+      dirName: appDirName,
+      sourceDir,
+      origin: { kind: "plugin", pluginName },
+      formatVersion,
+    };
+  }
+
+  const app = getApp(id);
+  if (!app) {
+    return null;
+  }
+  const { dirName } = resolveAppDir(id);
+  return {
+    id,
+    name: app.name,
+    dirName,
+    sourceDir: getAppDirPath(id),
+    origin: { kind: "workspace" },
+    formatVersion: app.formatVersion ?? 1,
+  };
+}
+
 export function updateApp(
   id: string,
   updates: Partial<
@@ -880,6 +1163,23 @@ export function readAppFileBytes(appId: string, path: string): Buffer {
   return readFileSync(resolved);
 }
 
+/**
+ * Read a file as raw bytes from an app directory addressed by its absolute
+ * path (rather than by a workspace app id). Path is validated to prevent
+ * traversal. Used to serve assets for plugin-bundled apps, whose source dir is
+ * resolved via {@link resolveAppSource}.
+ */
+export function readAppFileBytesFromDir(
+  sourceDir: string,
+  path: string,
+): Buffer {
+  const resolved = validateFilePathInDir(sourceDir, path);
+  if (!existsSync(resolved)) {
+    throw new Error(`File not found: ${path}`);
+  }
+  return readFileSync(resolved);
+}
+
 /**
  * Write a file to the app directory.
  * Auto-creates intermediate directories. Path is validated to prevent traversal.

package/src/cli/AGENTS.md

@@ -154,6 +154,23 @@ registerFooCommand(program);
    `console.log` results directly; that bypasses the convention and
    breaks downstream scripting.
 
+   **`--json` is global.** `registerGlobalJsonOption` (called once in
+   `program.ts` after every command is registered) attaches `--json` to
+   every **leaf** command in the tree, so a caller can append `--json` to
+   any command it actually invokes without hitting "unknown option". Only
+   leaves get it: Commander consumes a recognized option at the outermost
+   command that declares it, even when the flag appears after the
+   subcommand name, so a group-level `--json` would swallow
+   `clients list --json` before the `list` action reads `opts.json`. You
+   therefore do **not** need to declare `--json` yourself — but a command
+   only _honors_ it when its action routes output through
+   `writeOutput`/`shouldOutputJson` (or reads `opts.json`). When a command
+   emits bespoke human-readable text, branch on `shouldOutputJson(cmd)` and
+   emit a JSON object in the `--json` case (see `commands/status.ts`).
+   Declare `--json` explicitly in the command's `.help` module only when
+   you want a more specific description than the generic one; the global
+   registration skips any leaf that already declares it.
+
 ### Anti-patterns
 
 - ❌ Hoisting a daemon import — `import { x } from "../../runtime/foo.js"`

package/src/cli/commands/__tests__/gateway.test.ts

@@ -33,6 +33,7 @@ let mockResponses: Array<{
   ok: boolean;
   result?: unknown;
   error?: string;
+  statusCode?: number;
 }> = [];
 
 // ---------------------------------------------------------------------------
@@ -44,6 +45,10 @@ mock.module("../../../ipc/cli-client.js", () => ({
     ipcCalls.push({ method, params });
     return mockResponses.shift() ?? { ok: true, result: null };
   },
+  exitFromIpcResult: (r: { error?: string }) => {
+    process.exitCode = 1;
+    if (r.error) process.stderr.write(r.error);
+  },
 }));
 
 mock.module("../../../util/logger.js", () => ({
@@ -179,6 +184,56 @@ describe("gateway logs tail — IPC params", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// gateway status
+// ---------------------------------------------------------------------------
+
+describe("gateway status", () => {
+  test("--json passes through the connected tunnel payload", async () => {
+    mockResponses.push({
+      ok: true,
+      result: { tunnel: "https://abc123.vellum.ai" },
+    });
+
+    const { stdout, exitCode } = await runCommand([
+      "gateway",
+      "status",
+      "--json",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls[0].method).toBe("gateway_status");
+    expect(JSON.parse(stdout.trim())).toEqual({
+      tunnel: "https://abc123.vellum.ai",
+    });
+  });
+
+  test("--json emits {} when no tunnel is connected", async () => {
+    mockResponses.push({ ok: true, result: {} });
+
+    const { stdout, exitCode } = await runCommand([
+      "gateway",
+      "status",
+      "--json",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(JSON.parse(stdout.trim())).toEqual({});
+  });
+
+  test("exits non-zero when the gateway is not running", async () => {
+    mockResponses.push({
+      ok: false,
+      error: "Gateway is not running or is unreachable over IPC.",
+      statusCode: 503,
+    });
+
+    const { exitCode } = await runCommand(["gateway", "status"]);
+
+    expect(exitCode).not.toBe(0);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Pretty-print output
 // ---------------------------------------------------------------------------

package/src/cli/commands/apps.help.ts

@@ -4,15 +4,21 @@ import type { CliCommandHelp } from "../lib/cli-command-help.js";
 
 export const appsHelp: CliCommandHelp = {
   name: "apps",
-  description: "Inspect user-defined apps and their on-disk source",
+  description: "Inspect apps and their on-disk source",
   helpText: `
-Apps are user-defined mini-applications stored under the workspace apps
-directory (~/.vellum/apps/<slug>/). Each app has a human-readable name and a
+Apps are mini-applications the assistant can surface. Each has a name and a
 source directory holding its HTML/TSX definition, pages, and records.
 
-This surface is read-only. Apps are created, edited, and deleted through the
-app-builder skill and its tools (app-create, app-update, app-delete) — there is
-no CLI create/update/delete verb by design.
+Apps come from two places, distinguished by their source path:
+  workspace   User-created apps under the workspace apps directory
+              (~/.vellum/apps/<slug>/).
+  plugin      Apps bundled by an installed plugin, each a directory under
+              ~/.vellum/plugins/<name>/apps/<app>/. Stray directories without
+              a plugin package.json, and disabled plugins, contribute nothing.
+
+This surface is read-only. Workspace apps are created, edited, and deleted
+through the app-builder skill and its tools (app-create, app-update,
+app-delete); plugin apps are owned by their plugin.
 
 Examples:
   $ assistant apps list
@@ -25,12 +31,12 @@ Examples:
         { flags: "--json", description: "Machine-readable JSON output" },
       ],
       helpText: `
-Lists every app with its name and the absolute path to its source directory.
-The source path is the app's directory under the workspace apps directory; it
-holds index.html (single-file apps) or the TSX source tree (multi-file apps).
+Lists every app with its name and the absolute path to its source directory —
+the path itself shows whether the app is a workspace app or bundled by a plugin
+(~/.vellum/plugins/<name>/apps/...). Workspace apps are listed first, then
+plugin-bundled apps; both are sorted by name.
 
-Pass --json for the full record, including the app ID, format version, and
-last-updated time.
+Pass --json for machine-readable output.
 
 Examples:
   $ assistant apps list

package/src/cli/commands/apps.ts

@@ -8,9 +8,6 @@ import { appsHelp } from "./apps.help.js";
 interface AppListEntry {
   name: string;
   source: string;
-  id: string;
-  formatVersion: number;
-  updatedAt: number;
 }
 
 export function registerAppsCommand(program: Command): void {
@@ -24,17 +21,10 @@ export function registerAppsCommand(program: Command): void {
       subcommand(apps, "list").action(async (opts: { json?: boolean }) => {
         // Lazy-import the app store so the daemon module graph loads only when
         // this command runs (cli/no-daemon-internals).
-        const { getAppDirPath, listApps } =
-          await import("../../apps/app-store.js");
-
-        const entries: AppListEntry[] = listApps()
-          .map((app) => ({
-            name: app.name,
-            source: getAppDirPath(app.id),
-            id: app.id,
-            formatVersion: app.formatVersion ?? 1,
-            updatedAt: app.updatedAt,
-          }))
+        const { listAllApps } = await import("../../apps/app-store.js");
+
+        const entries: AppListEntry[] = listAllApps()
+          .map(({ name, sourcePath }) => ({ name, source: sourcePath }))
           .sort((a, b) => a.name.localeCompare(b.name));
 
         if (opts.json) {
@@ -48,7 +38,7 @@ export function registerAppsCommand(program: Command): void {
         }
 
         // Name and source lead; align the name into a column so the source
-        // path is scannable across rows.
+        // path (which also identifies the app's origin) stays scannable.
         const nameWidth = Math.max(4, ...entries.map((e) => e.name.length));
         log.info(`Apps (${entries.length}):\n`);
         log.info(`  ${"NAME".padEnd(nameWidth)}  SOURCE`);

package/src/cli/commands/gateway.help.ts

@@ -11,11 +11,41 @@ manages trust rules, routes traffic to the assistant, and records
 structured logs for all inbound activity.
 
 Examples:
+  $ assistant gateway status
   $ assistant gateway logs tail
   $ assistant gateway logs tail -n 50
   $ assistant gateway logs tail --level warn
   $ assistant gateway logs tail --module cors`,
   subcommands: [
+    {
+      name: "status",
+      description: "Show gateway status (public tunnel state)",
+      options: [
+        {
+          flags: "--json",
+          description: "Machine-readable compact JSON output",
+        },
+      ],
+      helpText: `
+Reports the live status of the gateway's public tunnel — the outbound
+public-ingress transport (currently Velay).
+
+The tunnel is ONLY used to route inbound Twilio webhooks and live voice/audio
+WebSockets through to this assistant. It has nothing to do with platform
+credentials, the managed LLM proxy, or text channels. If you are not using
+Twilio voice or live audio, a "not connected" tunnel is expected and harmless.
+
+JSON output (--json):
+  { "tunnel": "<public-url>" }   when a tunnel is connected
+  { }                            when the gateway is running but no tunnel is up
+
+If the gateway itself is not running, the command exits non-zero with an error
+rather than reporting an empty tunnel.
+
+Examples:
+  $ assistant gateway status
+  $ assistant gateway status --json`,
+    },
     {
       name: "logs",
       description: "Gateway log operations",

package/src/cli/commands/gateway.ts

@@ -2,15 +2,17 @@
  * `assistant gateway` CLI namespace.
  *
  * Subcommands:
+ *   status   — Show the gateway's public tunnel status via the daemon IPC proxy.
  *   logs tail — Show the last N gateway log entries via the daemon IPC proxy.
  */
 
 import type { Command } from "commander";
 
-import { cliIpcCall } from "../../ipc/cli-client.js";
+import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
+import { shouldOutputJson, writeOutput } from "../output.js";
 import { gatewayHelp } from "./gateway.help.js";
 
 // -- Types --------------------------------------------------------------------
@@ -23,6 +25,10 @@ interface PinoEntry {
   [key: string]: unknown;
 }
 
+interface GatewayStatusResult {
+  tunnel?: string;
+}
+
 // -- Helpers ------------------------------------------------------------------
 
 function formatTime(ms: number): string {
@@ -66,6 +72,39 @@ export function registerGatewayCommand(program: Command): void {
     build: (gateway) => {
       applyCommandHelp(gateway, gatewayHelp);
 
+      // -----------------------------------------------------------------------
+      // status
+      // -----------------------------------------------------------------------
+
+      subcommand(gateway, "status").action(async (_opts, cmd: Command) => {
+        const r = await cliIpcCall<GatewayStatusResult>("gateway_status", {});
+        if (!r.ok)
+          return exitFromIpcResult(
+            { ok: false, error: r.error, statusCode: r.statusCode },
+            cmd,
+          );
+
+        const result = r.result!;
+
+        if (shouldOutputJson(cmd)) {
+          writeOutput(cmd, result);
+          return;
+        }
+
+        if (result.tunnel) {
+          log.info(`Tunnel: connected (${result.tunnel})`);
+        } else {
+          log.info("Tunnel: not connected");
+        }
+        log.info(
+          "  The public tunnel is only used to route inbound Twilio webhooks and",
+        );
+        log.info(
+          "  live voice/audio WebSockets. It is not needed for text channels or",
+        );
+        log.info("  the managed LLM proxy.");
+      });
+
       const logs = subcommand(gateway, "logs");
 
       subcommand(logs, "tail").action(async (opts) => {