@vellumai/assistant 0.12.2-staging.5 → 0.12.2-staging.7

package/Dockerfile

@@ -130,13 +130,13 @@ RUN bun run scripts/smoke-container-workspace-dependencies.ts
 # The repo-root .dockerignore decides which skills (and files) ship.
 COPY skills /app/skills
 
-# Materialize the git-ignored offline plugin manifest from its canonical source.
-# `assistant/src/cli/lib/plugin-catalog-local.ts` statically imports this JSON
-# (loaded even when platform features are enabled), so it must exist in the image
-# — the build installs with --ignore-scripts, so the postinstall sync that
-# regenerates it in dev never runs here. Mirrors how CI materializes the
-# feature-flag registry before building.
-COPY plugins/marketplace.json /app/assistant/src/cli/lib/bundled-marketplace.json
+# Materialize the git-ignored offline marketplace and reviewed local packages.
+# The build installs with --ignore-scripts, so the postinstall sync that creates
+# these static imports in development never runs here.
+COPY plugins /app/plugins
+COPY meta/sync-bundled-copies.ts /app/meta/
+RUN cd /app && bun run meta/sync-bundled-copies.ts --plugins-only && \
+    bun run assistant/scripts/generate-bundled-plugin-packages.ts
 
 # Install assistant CLI launcher backed by the bundled assistant package
 RUN printf '#!/usr/bin/env sh\nexec bun run /app/assistant/src/index.ts "$@"\n' > /usr/local/bin/assistant && \

package/docs/architecture/memory.md

@@ -87,8 +87,17 @@ graph LR
   nesting existed still parse, since an unindented body line that is not itself
   entry-shaped is read as a continuation.
 - **Consolidation** (`substrate/consolidation-job.ts`) is a background
-  agent conversation that files buffer entries into concept pages, rewrites
-  the aggregate views, and trims the buffer. Scheduling
+  agent conversation that files buffer entries into concept pages and
+  rewrites the aggregate views. The agent never writes the buffer: the job
+  snapshots `buffer.md`, hands the run its pass's entries verbatim in the
+  prompt, and after the run removes exactly those entries itself through
+  `buffer-file.ts` (the module that also owns the append path, so the two
+  writers of the buffer share one protocol). Removal happens only when the
+  run's persisted messages hold a page-writing tool call with a non-error
+  result, the same evidence bar the retrospective's cursor advance uses; a
+  run that wrote nothing, failed, or timed out leaves the buffer intact for
+  the next pass. Entries deferred past the per-run cap and entries appended
+  while the run was in flight are therefore never lost. Scheduling
   (`maybeEnqueueGraphMaintenanceJobs` in `jobs-worker.ts`):
   - interval-based (`memory.v2.consolidation_interval_hours`, default 8h),
     skipped below `MIN_BUFFER_LINES_FOR_CONSOLIDATION` (10) **unless** the

package/docs/desktop-browser-cli.md

@@ -18,7 +18,7 @@ flowchart LR
 
 Chrome and its dock launcher share the managed profile and loopback debug port. For Chrome reopened from the dock, the profile singleton lock identifies a candidate PID, validated against the installed executable, profile and loopback debug arguments. Discovery checks `/proc` socket ownership against that browser PID, refuses redirects and validates the returned browser WebSocket endpoint. The connection stays within the container. No CDP endpoint or token is exposed to the renderer.
 
-The desktop client bypasses personal-browser discovery, extension reconnect waits and backend fallback. It reuses the existing AX snapshot, DOM element resolution, mouse, keyboard, extraction and credential-fill implementations. Operation-scoped clients borrow the lease's connection; disposing one does not release the lease. `detach`, `close`, cancellation, errors and idle expiry release control. Only `tabs close` closes a Chrome tab.
+The desktop client bypasses personal-browser discovery, extension reconnect waits and backend fallback. It reuses the existing AX snapshot, DOM element resolution, mouse, keyboard, extraction and credential-fill implementations. Operation-scoped clients borrow the lease's connection; disposing one does not release the lease. `detach`, `close`, turn completion, cancellation, errors and idle expiry release control. Turn completion clears the activity indicator immediately and queues browser cleanup before the next automation session; it leaves Chrome and the current page open for the user. Only `tabs close` closes a Chrome tab.
 
 `assistant browser --virtual-desktop screenshot --output /tmp/desktop-page.jpg` captures a color page image through CDP `Page.captureScreenshot`. It excludes the browser toolbar and desktop dock. `snapshot` returns semantic page structure. Agents should use these interfaces and let the manager start the desktop, including when older memory notes describe manual Xvnc, `xdotool` or scratch XWD conversion scripts.
 
@@ -26,8 +26,10 @@ Tab IDs are ephemeral numeric aliases for this managed browser's CDP target IDs.
 
 CDP mouse events use page viewport CSS coordinates. Before dispatching them, the client animates a purple arrow overlay to the same point. The overlay is excluded from accessibility and hit testing. It appears in the existing desktop stream and is removed on release. It does not move the OS pointer, appear in browser toolbar UI or visualize every programmatic DOM operation. Native dialogs and other applications are outside the browser CLI; users can interact with them directly in the expanded desktop. The picture-in-picture preview is view-only. Direct user interaction does not pause automation.
 
-The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
+The client records key and mouse presses before dispatch. On release it opens a fresh bounded cleanup connection, attaches to the same live targets, releases uncertain held input and removes overlays. A failed cleanup preserves state and the automation slot for retry. Turn-triggered cancellation retries cleanup automatically until it succeeds or ownership changes. Dispatched actions are never automatically retried. Closed targets need no input cleanup. Browser-process loss disposes the client, and later requests discover the replacement process.
 
 `--use-active-tab` and personal browser targeting are rejected with `--virtual-desktop`. Download waiting is unsupported. Browser operations are bounded to two minutes and share the desktop lease's action budget and idle expiry.
 
 Validation: focused client tests exercise shared snapshot/click behavior, namespace isolation, stale references, target changes, cancellation and uncertain-input cleanup. Lease tests cover browser ownership, cancellation and cleanup independently of native input. The Linux smoke script exercises real Chrome, the CLI and visible pointer feedback.
+
+The desktop header icon pulses in the assistant's avatar accent color while a browser automation lease is active, including between browser commands. It shares the progress indicator's accent and neutral fallback. Reduced-motion clients show a solid accent. Setup status exposes the optional `automationActive` field; `desktop_activity_changed` events refresh it on acquisition and cancellation or release. Installation progress retains its `assistant:self:desktop` sync invalidations. The indicator reads status without starting installation, and reconnects refetch the current lease state.

package/node_modules/@vellumai/environments/src/shell.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   pathListDelimiter,
   prependUniquePathEntries,
 } from "./shell.js";
@@ -38,6 +39,26 @@ describe("buildShellInvocation", () => {
   });
 });
 
+describe("buildShellSpawnFlags", () => {
+  test("creates a POSIX process group and hides Windows consoles", () => {
+    expect(buildShellSpawnFlags("linux")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+    expect(buildShellSpawnFlags("darwin")).toEqual({
+      detached: true,
+      windowsHide: true,
+    });
+  });
+
+  test("does not detach Windows children that use piped stdio", () => {
+    expect(buildShellSpawnFlags("win32")).toEqual({
+      detached: false,
+      windowsHide: true,
+    });
+  });
+});
+
 describe("path list handling", () => {
   test("uses the platform delimiter", () => {
     expect(pathListDelimiter("win32")).toBe(";");

package/node_modules/@vellumai/environments/src/shell.ts

@@ -5,6 +5,11 @@ export interface ShellInvocation {
   args: string[];
 }
 
+export interface ShellSpawnFlags {
+  detached: boolean;
+  windowsHide: true;
+}
+
 const WINDOWS_UTF8_PREAMBLE =
   "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}; " +
   "$OutputEncoding = [System.Text.Encoding]::UTF8; " +
@@ -43,6 +48,25 @@ export function buildShellInvocation(
   return { command: "bash", args: ["-c", "--", command] };
 }
 
+/**
+ * Spawn flags for assistant-owned shell children (sandbox bash, local
+ * host_bash fallback, sanitized CLI bash, skill runners, scheduled scripts).
+ *
+ * POSIX uses a new process group so timeout/abort can SIGKILL the tree via
+ * `-pid`. Windows process trees are torn down with `taskkill /T`, which does
+ * not need a detached process. Combining `DETACHED_PROCESS`,
+ * `CREATE_NO_WINDOW`, and piped stdio on Windows can emit `close` with exit
+ * 0 and empty pipes without running the encoded command.
+ */
+export function buildShellSpawnFlags(
+  hostPlatform: NodeJS.Platform = process.platform,
+): ShellSpawnFlags {
+  return {
+    detached: hostPlatform !== "win32",
+    windowsHide: true,
+  };
+}
+
 export function pathListDelimiter(
   hostPlatform: NodeJS.Platform = process.platform,
 ): string {

package/node_modules/@vellumai/gateway-client/src/inbound-contract.ts

@@ -83,8 +83,14 @@ export const SourceMetadataSchema = z
     clientTimezone: z.string().optional(),
     /** Channel command intent (e.g. Telegram /start). */
     commandIntent: CommandIntentSchema.optional(),
-    /** Slack-specific: whether the bot was @-mentioned. */
-    slackBotMentioned: z.boolean().optional(),
+    /**
+     * Whether the message addresses the assistant by name, an @-mention on
+     * the platforms that have one. Stated by the channel's normalizer only
+     * where it proved the answer; absent means "not established". Read to
+     * decide whether a reply is expected before any text exists, never to
+     * admit or deny: admission is the gate's job, upstream of this.
+     */
+    botMentioned: z.boolean().optional(),
     /**
      * Slack-specific: the `edited.ts` float-string from a `message_changed`
      * event. Used by the daemon to reject out-of-order edit deliveries whose

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.12.2
+  version: 0.12.1
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -5042,7 +5042,7 @@ paths:
                           type: string
                       required:
                         - type
-                    slackBotMentioned:
+                    botMentioned:
                       type: boolean
                     slackEditedTs:
                       type: string
@@ -11941,6 +11941,8 @@ paths:
                       - ready
                       - failed
                       - unsupported
+                  automationActive:
+                    type: boolean
                   stage:
                     type: string
                     enum:
@@ -11971,6 +11973,8 @@ paths:
                       - ready
                       - failed
                       - unsupported
+                  automationActive:
+                    type: boolean
                   stage:
                     type: string
                     enum:
@@ -26622,26 +26626,44 @@ paths:
                     description: Resolved version (installed copy first, then repo `package.json`).
                   source:
                     anyOf:
-                      - type: object
-                        properties:
-                          kind:
-                            type: string
-                            const: github
-                          repo:
-                            type: string
-                            description: "`owner/repo` of the external plugin repository."
-                          path:
-                            description: Directory within the repo, when the plugin is not at the root.
-                            type: string
-                          ref:
-                            type: string
-                            description: Pinned git ref the plugin is fetched from.
-                        required:
-                          - kind
-                          - repo
-                          - ref
-                        additionalProperties: false
-                        description: "Origin of the match: a whitelisted external plugin repository."
+                      - oneOf:
+                          - type: object
+                            properties:
+                              kind:
+                                type: string
+                                const: github
+                              repo:
+                                type: string
+                                description: "`owner/repo` of the external plugin repository."
+                              path:
+                                description: Directory within the repo, when the plugin is not at the root.
+                                type: string
+                              ref:
+                                type: string
+                                description: Pinned git ref the plugin is fetched from.
+                            required:
+                              - kind
+                              - repo
+                              - ref
+                            additionalProperties: false
+                          - type: object
+                            properties:
+                              kind:
+                                type: string
+                                const: local
+                              path:
+                                type: string
+                                description: Package key in the assistant bundle.
+                              version:
+                                type: string
+                                description: Bundled package version.
+                            required:
+                              - kind
+                              - path
+                              - version
+                            additionalProperties: false
+                        description: Reviewed source of the marketplace entry.
+                        type: object
                       - type: "null"
                     description: Pinned origin from the marketplace entry, or null when an installed copy has no catalog entry.
                   readme:
@@ -26996,28 +27018,42 @@ paths:
                             description: ISO-8601 install timestamp from the sidecar; null when absent.
                           source:
                             anyOf:
-                              - type: object
-                                properties:
-                                  kind:
-                                    type: string
-                                    description: Source kind. Only `github` is written today.
-                                  owner:
-                                    type: string
-                                  repo:
-                                    type: string
-                                  path:
-                                    description: Repo-relative directory holding the plugin root; absent = repo root.
-                                    type: string
-                                  ref:
-                                    type: string
-                                    description: Ref the install resolved through (the pinned commit SHA for marketplace installs).
-                                required:
-                                  - kind
-                                  - owner
-                                  - repo
-                                  - ref
-                                additionalProperties: false
+                              - oneOf:
+                                  - type: object
+                                    properties:
+                                      kind:
+                                        type: string
+                                        const: github
+                                      owner:
+                                        type: string
+                                      repo:
+                                        type: string
+                                      path:
+                                        type: string
+                                      ref:
+                                        type: string
+                                    required:
+                                      - kind
+                                      - owner
+                                      - repo
+                                      - ref
+                                    additionalProperties: false
+                                  - type: object
+                                    properties:
+                                      kind:
+                                        type: string
+                                        const: local
+                                      path:
+                                        type: string
+                                      version:
+                                        type: string
+                                    required:
+                                      - kind
+                                      - path
+                                      - version
+                                    additionalProperties: false
                                 description: Source coordinates recorded in the install-time provenance sidecar.
+                                type: object
                               - type: "null"
                             description: Source recorded at install time; null when no sidecar exists.
                           localChanges:
@@ -27076,6 +27112,9 @@ paths:
                     anyOf:
                       - type: object
                         properties:
+                          kind:
+                            type: string
+                            const: local
                           repo:
                             type: string
                             description: "`owner/repo` of the external plugin repository."
@@ -27111,6 +27150,9 @@ paths:
                           marketplaceRef:
                             type: string
                             description: Ref of the canonical repo the marketplace manifest was read from.
+                          version:
+                            description: Bundled package version.
+                            type: string
                         required:
                           - repo
                           - path
@@ -27547,7 +27589,7 @@ paths:
                           description: Install name. Matches `assistant plugins install <name>`.
                         path:
                           type: string
-                          description: "Human-readable origin: a `github:owner/repo@ref` locator for the external plugin."
+                          description: Human-readable catalog origin locator.
                         description:
                           description: Short description, when known (external entries only today).
                           type: string
@@ -27561,27 +27603,87 @@ paths:
                             - type: string
                             - type: "null"
                           description: Marketplace category slug (Skills taxonomy); null when the entry declares none.
-                        source:
+                        integration:
                           type: object
                           properties:
                             kind:
                               type: string
-                              const: github
-                            repo:
+                              const: mcp
+                            displayName:
+                              type: string
+                            documentationUrl:
                               type: string
-                              description: "`owner/repo` of the external plugin repository."
-                            path:
-                              description: Directory within the repo, when the plugin is not at the root.
+                            verifiedAt:
                               type: string
-                            ref:
+                            verification:
+                              type: string
+                              const: documentation-only
+                            setup:
+                              type: object
+                              properties:
+                                mode:
+                                  type: string
+                                  enum:
+                                    - oauth
+                                    - manual
+                                instructions:
+                                  type: string
+                              required:
+                                - mode
+                                - instructions
+                              additionalProperties: false
+                            logo:
+                              type: string
+                            oauthProvider:
                               type: string
-                              description: Pinned git ref the plugin is fetched from.
                           required:
                             - kind
-                            - repo
-                            - ref
+                            - displayName
+                            - documentationUrl
+                            - verifiedAt
+                            - verification
+                            - setup
+                            - logo
                           additionalProperties: false
-                          description: "Origin of the match: a whitelisted external plugin repository."
+                        source:
+                          oneOf:
+                            - type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  const: github
+                                repo:
+                                  type: string
+                                  description: "`owner/repo` of the external plugin repository."
+                                path:
+                                  description: Directory within the repo, when the plugin is not at the root.
+                                  type: string
+                                ref:
+                                  type: string
+                                  description: Pinned git ref the plugin is fetched from.
+                              required:
+                                - kind
+                                - repo
+                                - ref
+                              additionalProperties: false
+                            - type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  const: local
+                                path:
+                                  type: string
+                                  description: Package key in the assistant bundle.
+                                version:
+                                  type: string
+                                  description: Bundled package version.
+                              required:
+                                - kind
+                                - path
+                                - version
+                              additionalProperties: false
+                          description: Reviewed source of the marketplace entry.
+                          type: object
                       required:
                         - name
                         - path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-staging.5",
+  "version": "0.12.2-staging.7",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -24,16 +24,17 @@
     "lint:unused": "knip --include files,dependencies,unlisted",
     "lint:circular": "bun run scripts/check-circular-deps.ts",
     "lint:unused:production": "knip --production --include exports",
-    "pretypecheck": "cd .. && bun run meta/sync-bundled-copies.ts",
+    "sync:bundled-catalog": "cd .. && bun run meta/sync-bundled-copies.ts && bun run assistant/scripts/generate-bundled-plugin-packages.ts",
+    "pretypecheck": "bun run sync:bundled-catalog",
     "typecheck": "bunx tsc --noEmit",
-    "pretypecheck:fast": "cd .. && bun run meta/sync-bundled-copies.ts",
+    "pretypecheck:fast": "bun run sync:bundled-catalog",
     "typecheck:fast": "bunx tsgo --noEmit",
     "test": "bun run scripts/test.ts",
     "test:coverage": "COVERAGE=true bun run scripts/test.ts",
     "test:stable": "EXCLUDE_EXPERIMENTAL=true bun run scripts/test.ts",
     "test:bench": "find src -type f -name '*.benchmark.test.ts' -print0 | xargs -0 -P 1 -I {} bun test {}",
     "test:filesystem-tools": "bash scripts/test-filesystem-tools.sh",
-    "postinstall": "cd .. && (git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true) && ([ -f meta/sync-bundled-copies.ts ] && bun run meta/sync-bundled-copies.ts 2>/dev/null || true)"
+    "postinstall": "bun run scripts/postinstall.ts"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.25.0",

package/scripts/bundled-plugin-packages.ts

@@ -0,0 +1,154 @@
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+import {
+  AGENT_PLUGINS_MCP_SCHEMA_URL,
+  SpecMcpDocumentSchema,
+  SpecMcpServerSchema,
+} from "../src/mcp/spec-schema.js";
+import {
+  readPluginManifest,
+  STANDARD_PLUGIN_MANIFEST,
+} from "../src/util/plugin-manifest.js";
+
+export interface BundledPackageFile {
+  path: string;
+  contentBase64: string;
+}
+
+export interface BundledPackage {
+  version: string;
+  files: BundledPackageFile[];
+}
+
+/** Validate and embed every local source in the canonical marketplace. */
+export function buildBundledPluginPackages(
+  repoRoot: string,
+): Record<string, BundledPackage> {
+  const marketplacePath = join(repoRoot, "plugins", "marketplace.json");
+  const manifest = JSON.parse(readFileSync(marketplacePath, "utf8")) as {
+    plugins?: unknown;
+  };
+  if (!Array.isArray(manifest.plugins)) {
+    throw new Error("plugins/marketplace.json is missing its plugins array");
+  }
+
+  const pluginsRoot = realpathSync(join(repoRoot, "plugins"));
+  const packages: Record<string, BundledPackage> = {};
+  for (const rawEntry of manifest.plugins) {
+    if (typeof rawEntry !== "object" || rawEntry === null) {
+      continue;
+    }
+    const entry = rawEntry as Record<string, unknown>;
+    const rawSource = entry.source;
+    if (typeof rawSource !== "object" || rawSource === null) {
+      continue;
+    }
+    const source = rawSource as Record<string, unknown>;
+    if (source.source !== "local") {
+      continue;
+    }
+    if (
+      typeof entry.name !== "string" ||
+      typeof source.path !== "string" ||
+      typeof source.version !== "string"
+    ) {
+      throw new Error(
+        "local marketplace entries require name, path, and version",
+      );
+    }
+
+    const pathSegments = source.path.split("/");
+    if (
+      !source.path.startsWith("plugins/") ||
+      source.path.includes("\\") ||
+      pathSegments.some(
+        (segment) => segment === "" || segment === "." || segment === "..",
+      )
+    ) {
+      throw new Error(
+        `local marketplace package path is not canonical: ${source.path}`,
+      );
+    }
+    let packageRoot = resolve(repoRoot);
+    for (const segment of pathSegments) {
+      packageRoot = join(packageRoot, segment);
+      if (lstatSync(packageRoot).isSymbolicLink()) {
+        throw new Error(
+          `local marketplace package path may not contain symlinks: ${source.path}`,
+        );
+      }
+    }
+    const packageRealpath = realpathSync(packageRoot);
+    const relativeToPlugins = relative(pluginsRoot, packageRealpath);
+    if (
+      relativeToPlugins === "" ||
+      relativeToPlugins === ".." ||
+      relativeToPlugins.startsWith(`..${sep}`)
+    ) {
+      throw new Error(
+        `local marketplace package escapes plugins/: ${source.path}`,
+      );
+    }
+
+    const pluginManifest = readPluginManifest(packageRealpath);
+    if (
+      pluginManifest.source !== STANDARD_PLUGIN_MANIFEST ||
+      pluginManifest.name !== entry.name ||
+      pluginManifest.version !== source.version
+    ) {
+      throw new Error(
+        `local marketplace package ${source.path} must match entry name and version`,
+      );
+    }
+    const rawMcp = JSON.parse(
+      readFileSync(join(packageRealpath, "mcp.json"), "utf8"),
+    ) as unknown;
+    const mcp = SpecMcpDocumentSchema.parse(rawMcp);
+    if (mcp.$schema !== AGENT_PLUGINS_MCP_SCHEMA_URL) {
+      throw new Error(
+        `local marketplace package ${source.path} must use the Agent Plugins MCP schema`,
+      );
+    }
+    if (Object.keys(mcp.mcpServers).length === 0) {
+      throw new Error(
+        `local marketplace package ${source.path} must declare an MCP server`,
+      );
+    }
+    for (const server of Object.values(mcp.mcpServers)) {
+      SpecMcpServerSchema.parse(server);
+    }
+
+    const files: BundledPackageFile[] = [];
+    const visit = (directory: string): void => {
+      for (const child of readdirSync(directory, { withFileTypes: true })) {
+        const childPath = join(directory, child.name);
+        if (child.isSymbolicLink() || lstatSync(childPath).isSymbolicLink()) {
+          throw new Error(
+            `local marketplace packages may not contain symlinks: ${source.path}/${child.name}`,
+          );
+        }
+        if (child.isDirectory()) {
+          visit(childPath);
+          continue;
+        }
+        if (!child.isFile()) {
+          throw new Error(
+            `local marketplace package contains an unsupported entry: ${childPath}`,
+          );
+        }
+        files.push({
+          path: relative(packageRealpath, childPath).split(sep).join("/"),
+          contentBase64: readFileSync(childPath).toString("base64"),
+        });
+      }
+    };
+    visit(packageRealpath);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    if (packages[source.path]) {
+      throw new Error(`duplicate local marketplace package: ${source.path}`);
+    }
+    packages[source.path] = { version: source.version, files };
+  }
+  return packages;
+}