@vellumai/assistant 0.8.0 → 0.8.1

package/AGENTS.md

@@ -34,6 +34,17 @@ Routes in `src/runtime/routes/` are being migrated to a **shared `ROUTES` array*
 - **Dual exposure is intentional.** Every route in the shared `ROUTES` array is served over both HTTP and IPC. This is by design — it enables the gateway to call the daemon over IPC instead of HTTP, eliminating JWT token exchange on those paths (ATL-309 → ATL-311). Do not flag IPC exposure of shared routes as unintentional surface area.
 - **`RouteDefinition` carries everything:** `operationId`, `endpoint`, `method`, `handler`, `policyKey?`, `summary?`, `description?`, `tags?`, `responseBody?`. The HTTP adapter reads all fields; the IPC adapter only needs `operationId` and `handler`.
 
+### CLI ↔ daemon communication protocol
+
+The CLI and daemon communicate over a Unix domain socket using **length-prefixed binary framing**: each frame is a 4-byte big-endian length followed by a payload. Messages use a JSON envelope `{ id, method, params?, headers? }` for requests and `{ id, result?, error?, headers? }` for responses.
+
+Three response shapes are supported:
+- **JSON-only**: a single JSON frame (no `content-length` or `transfer-encoding` header).
+- **Binary**: a JSON envelope with `headers: { "content-length": "<n>" }` followed by one binary frame of exactly `n` bytes.
+- **Chunked streaming**: a JSON envelope with `headers: { "transfer-encoding": "chunked" }` followed by one or more binary frames, terminated by a zero-length frame.
+
+The server auto-detects legacy newline-delimited JSON from old CLI clients and handles it transparently. New code must use length-prefixed framing via `writeMessage()` / `IpcFrameReader` in `src/ipc/ipc-framing.ts`.
+
 ### CLI ↔ daemon version skew
 
 The CLI and daemon are always shipped and upgraded together — there is no version skew between them. When migrating a route to the shared `ROUTES` array and updating the CLI to send structured params, backward compatibility with older CLI versions is **not required**. Do not add compat shims for flat-param callers that no longer exist.

package/Dockerfile

@@ -27,12 +27,13 @@ COPY packages/skill-host-contracts ./packages/skill-host-contracts
 COPY packages/slack-text ./packages/slack-text
 COPY packages/twilio-client ./packages/twilio-client
 
-# Install deps for shared packages that have their own file: dependencies.
-# Without this, bun's module resolution at runtime walks up from e.g.
-# packages/ces-client/src/ and never finds the transitive dependency
-# (ces-contracts) because only assistant/node_modules gets populated.
+# Install deps for shared packages whose source is loaded at runtime.
+# Without this, bun's module resolution walks up from packages/<name>/src/
+# and can't find the package's own deps (zod, transitive file: refs)
+# because only assistant/node_modules gets populated.
 RUN cd /app/packages/ces-client && bun install --frozen-lockfile
 RUN cd /app/packages/gateway-client && bun install --frozen-lockfile
+RUN cd /app/packages/service-contracts && bun install --frozen-lockfile
 
 # Install assistant dependencies first for cache reuse
 COPY assistant/package.json assistant/bun.lock ./assistant/

package/README.md

@@ -47,9 +47,9 @@ cp .env.example .env
 
 ## Update Bulletin
 
-Release notes are surfaced via a background conversation dispatched at daemon startup. Workspace migrations write release notes to `<workspace>/UPDATES.md`; `runUpdateBulletinJobIfNeeded()` then spawns a `conversationType: "background"` conversation (via `wakeAgentForOpportunity()`) whenever the file's content hash changes. The agent uses judgment to surface updates to the user when relevant, and deletes the file when done.
+Release notes are surfaced via a background conversation dispatched at daemon startup. Workspace migrations write release notes to `<workspace>/UPDATES.md`; `runUpdateBulletinJobIfNeeded()` then spawns a `conversationType: "background"` conversation via `runBackgroundJob()` (see `runtime/background-job-runner.ts`) whenever the file's content hash changes. The agent uses judgment to surface updates to the user when relevant, and deletes the file when done.
 
-**For release maintainers:** Add a new migration under `assistant/src/workspace/migrations/0XX-release-notes-<slug>.ts` with the release notes inline as a string literal, and append the export to `WORKSPACE_MIGRATIONS` in `assistant/src/workspace/migrations/registry.ts`. Migrations are append-only. Idempotency is handled by the workspace-migration runner — `runWorkspaceMigrations()` records each migration's `WorkspaceMigration.id` in `<workspace>/data/.workspace-migrations.json` and never re-runs an ID that is already in the `applied` set, so release-notes migrations do not need an in-file guard. Skip the migration entirely for releases with no user/assistant-facing changes.
+**For release maintainers:** Add a new migration under `assistant/src/workspace/migrations/0XX-release-notes-<slug>.ts` with the release notes inline as a string literal, and append the export to `WORKSPACE_MIGRATIONS` in `assistant/src/workspace/migrations/registry.ts`. Migrations are append-only. Idempotency requires both the workspace-migration runner AND an in-file marker: `runWorkspaceMigrations()` records each migration's `WorkspaceMigration.id` in `<workspace>/data/.workspace-migrations.json` and skips IDs already in the `applied` set, but a crash between `UPDATES.md` append and checkpoint finalize can cause a duplicate append on next boot. Embed an HTML marker like `<!-- release-note-id:<migration-id> -->` in the appended block, and short-circuit when the marker is already present. See the root `AGENTS.md` "Release Update Hygiene" section for the full rationale. Skip the migration entirely for releases with no user/assistant-facing changes.
 
 ## Usage
 

package/docker-entrypoint.sh

@@ -1,11 +1,27 @@
 #!/usr/bin/env sh
 set -eu
 
+# Ensure /tmp has the standard sticky-bit world-writable mode so non-root
+# processes (the `assistant` user, bun's tmpdir, scratch writes) can use it.
+chmod 1777 /tmp 2>/dev/null || true
+
 if [ "$(id -u)" = "0" ] && [ "${VELLUM_WORKSPACE_DIR:-}" = "/workspace" ] && [ -d /workspace ]; then
   git config --global --add safe.directory /workspace >/dev/null 2>&1 || true
   git config --global --add safe.directory '/workspace/*' >/dev/null 2>&1 || true
 fi
 
+# Source executable scripts from /workspace/.entrypoint.d/ in lexicographic
+# order so an assistant can extend the daemon environment from its own
+# workspace volume — PATH additions, credential helpers, tooling symlinks.
+# Scripts are sourced so env mutations propagate to the daemon. Errors are
+# logged but non-fatal.
+if [ -d /workspace/.entrypoint.d ]; then
+  for hook in /workspace/.entrypoint.d/*.sh; do
+    [ -r "$hook" ] || continue
+    . "$hook" || echo "Warning: workspace hook $hook exited $?" >&2
+  done
+fi
+
 # ── Bun profiler bootstrap ──────────────────────────────────────────────
 # When VELLUM_PROFILER_RUN_ID and VELLUM_PROFILER_MODE are set, prepare the
 # run directory on the workspace volume and append the appropriate Bun

package/eslint-rules/__tests__/cli-no-daemon-internals.test.ts

@@ -0,0 +1,420 @@
+import tsParser from "@typescript-eslint/parser";
+import { RuleTester } from "eslint";
+
+import rule from "../cli-no-daemon-internals.js";
+
+const tester = new RuleTester({
+  languageOptions: {
+    ecmaVersion: 2022,
+    sourceType: "module",
+    parser: tsParser,
+  },
+});
+
+tester.run("cli/no-daemon-internals", rule, {
+  valid: [
+    // ipc-tagged file importing only allowed sources
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { log } from "../logger.js";
+        import { printTable } from "../output.js";
+
+        registerCommand(program, {
+          name: "example",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // local-tagged file importing allowed sources
+    {
+      code: `
+        import type { Command } from "commander";
+        import { loadRawConfig } from "../../config/loader.js";
+        import { getWorkspaceDir } from "../../util/platform.js";
+
+        registerCommand(program, {
+          name: "local-example",
+          transport: "local",
+          build: () => {},
+        });
+      `,
+    },
+    // bootstrap-tagged file importing allowed sources
+    {
+      code: `
+        import type { Command } from "commander";
+        import { AssistantConfigSchema } from "../../config/schema.js";
+
+        registerCommand(program, {
+          name: "bootstrap-example",
+          transport: "bootstrap",
+          build: () => {},
+        });
+      `,
+    },
+    // ipc-tagged file importing from ../lib/ prefix (shared lib)
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { readFileSync } from "../lib/daemon-credential-client.js";
+
+        registerCommand(program, {
+          name: "lib-example",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // File with zero imports and no registerCommand — utility file
+    {
+      code: `
+        function utilHelper() {
+          return 42;
+        }
+        export { utilHelper };
+      `,
+    },
+    // Helper module — has imports but does not call registerCommand directly.
+    // Helper modules under commands/ (e.g. oauth/shared.ts, lib/cache-fs.ts)
+    // are not command entries and the rule must not fire on them, even when
+    // they import from outside the registrar allowlists.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { getProvider } from "../../../oauth/oauth-store.js";
+
+        export function buildAuthFlow(program) {
+          // helper module — no registerCommand call here; the actual
+          // command file imports this and calls registerCommand itself.
+        }
+      `,
+    },
+    // local-tagged file importing ../logger and ../output — both must be on
+    // the local allowlist (regression test for the allowlist gap that
+    // false-positived autonomy/config/completions/keys/credential-execution).
+    {
+      code: `
+        import type { Command } from "commander";
+        import { log } from "../logger.js";
+        import { writeOutput } from "../output.js";
+
+        registerCommand(program, {
+          name: "local-with-output",
+          transport: "local",
+          build: () => {},
+        });
+      `,
+    },
+    // Type-only imports are erased at compile time and must not count as
+    // runtime boundary violations, even when the source path is outside the
+    // allowlist (e.g. `import type` from runtime/routes for response shapes).
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import type { MemoryV2Result } from "../../runtime/routes/memory-v2-routes.js";
+
+        registerCommand(program, {
+          name: "ipc-with-type-import",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // Inline `import { type X }` form: importKind is set per specifier,
+    // not on the declaration. When every specifier is type-only the import
+    // is erased and must not flag a forbidden-runtime-import violation.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { type MemoryV2Result, type ScoreBreakdown } from "../../runtime/routes/memory-v2-routes.js";
+
+        registerCommand(program, {
+          name: "ipc-with-inline-type-import",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // Chained registerCommand pattern: `registerCommand(...).command(...)`.
+    // The outer call's callee is a MemberExpression whose object is the
+    // inner registerCommand call. The AST walker must follow callee +
+    // MemberExpression.object so findTransport() locates the registerCommand
+    // call and applies the correct transport allowlist.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+
+        registerCommand(program, {
+          name: "ipc-chained",
+          transport: "ipc",
+          build: () => {},
+        }).command("subcmd").description("desc");
+      `,
+    },
+    // Sibling subcommand composition: an index file (e.g. oauth/index.ts)
+    // imports sibling subcommand files (./connect.js, ./disconnect.js) to
+    // attach them under a parent group. The imported file is itself a
+    // command and the rule checks its imports independently, so this can't
+    // smuggle daemon internals.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { registerCommand } from "../../lib/register-command.js";
+        import { setupConnect } from "./connect.js";
+        import { setupDisconnect } from "./disconnect.js";
+
+        registerCommand(program, {
+          name: "ipc-index-composition",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // Nested command file (commands/oauth/foo.ts) needs deeper relative
+    // paths to the IPC client, lib/, logger, and output. Without the
+    // depth-2 entries the rule would false-positive on every nested
+    // command (oauth/*, platform/*).
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../../ipc/cli-client.js";
+        import { registerCommand } from "../../lib/register-command.js";
+        import { log } from "../../logger.js";
+        import { writeOutput } from "../../output.js";
+
+        registerCommand(program, {
+          name: "ipc-nested",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // Shared CLI utils (src/cli/utils/*) — sibling utility directory used
+    // by task/ui/conversations-defer for ID resolution and parsing. Lives
+    // alongside lib/ but historically wasn't on the allowlist.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { resolveConversationId } from "../utils/conversation-id.js";
+        import { parseDuration } from "../utils/parse-duration.js";
+
+        registerCommand(program, {
+          name: "ipc-with-utils",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // status.ts pattern: when the daemon is unreachable, the command falls
+    // back to a local socket-path probe + platform helpers. Both imports
+    // are part of the documented daemon-down fallback contract (§3.7).
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { getSocketPath } from "../../ipc/socket-path.js";
+        import { getWorkspaceDir } from "../../util/platform.js";
+
+        registerCommand(program, {
+          name: "ipc-status",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+    },
+    // local-tagged keys.ts pattern: the secure-key helpers are designed to
+    // run in-process (not over IPC), so direct security/* imports are part
+    // of the contract.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { credentialKey } from "../../security/credential-key.js";
+        import { getSecureKeyAsync } from "../../security/secure-keys.js";
+
+        registerCommand(program, {
+          name: "local-keys",
+          transport: "local",
+          build: () => {},
+        });
+      `,
+    },
+    // local-tagged credential-execution.ts pattern: speaks to the CES
+    // sidecar via service-contracts RPC; the daemon is not involved.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { credentialRpc } from "@vellumai/service-contracts/credential-rpc";
+        import { connect } from "../../credential-execution/client.js";
+
+        registerCommand(program, {
+          name: "local-ces",
+          transport: "local",
+          build: () => {},
+        });
+      `,
+    },
+    // local-tagged config.ts uses zod for schema validation and reaches
+    // across to oauth/shared.ts for the managed-mode platform-connection
+    // check (documented cross-namespace helper).
+    {
+      code: `
+        import type { Command } from "commander";
+        import { z } from "zod";
+        import { loadRawConfig } from "../../config/loader.js";
+        import { requirePlatformConnection } from "./oauth/shared.js";
+
+        registerCommand(program, {
+          name: "local-config",
+          transport: "local",
+          build: () => {},
+        });
+      `,
+    },
+  ],
+
+  invalid: [
+    // registerCommand called without a string transport prop — the actual
+    // missingTransport case (command-entry file forgot to declare its class).
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+
+        registerCommand(program, {
+          name: "no-transport",
+          build: () => {},
+        });
+      `,
+      errors: [
+        {
+          messageId: "missingTransport",
+        },
+      ],
+    },
+    // ipc-tagged file importing a forbidden runtime route
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { healthRoutes } from "../../runtime/routes/health-routes.js";
+
+        registerCommand(program, {
+          name: "bad-ipc",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+      errors: [
+        {
+          messageId: "forbiddenImport",
+          data: {
+            transport: "ipc",
+            source: "../../runtime/routes/health-routes.js",
+          },
+        },
+      ],
+    },
+    // ipc-tagged file importing a skills catalog module
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { SkillsCatalog } from "../../skills/catalog.js";
+
+        registerCommand(program, {
+          name: "bad-ipc-skills",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+      errors: [
+        {
+          messageId: "forbiddenImport",
+          data: {
+            transport: "ipc",
+            source: "../../skills/catalog.js",
+          },
+        },
+      ],
+    },
+    // local-tagged file importing a forbidden runtime route
+    {
+      code: `
+        import type { Command } from "commander";
+        import { loadRawConfig } from "../../config/loader.js";
+        import { healthRoutes } from "../../runtime/routes/health-routes.js";
+
+        registerCommand(program, {
+          name: "bad-local",
+          transport: "local",
+          build: () => {},
+        });
+      `,
+      errors: [
+        {
+          messageId: "forbiddenImport",
+          data: {
+            transport: "local",
+            source: "../../runtime/routes/health-routes.js",
+          },
+        },
+      ],
+    },
+    // Nested command file (commands/oauth/foo.ts) STILL rejects runtime
+    // route imports. Locking in the boundary so the depth-2 allowlist
+    // additions don't accidentally open daemon-internal namespaces.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../../ipc/cli-client.js";
+        import { healthRoutes } from "../../../runtime/routes/health-routes.js";
+
+        registerCommand(program, {
+          name: "bad-ipc-nested",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+      errors: [
+        {
+          messageId: "forbiddenImport",
+          data: {
+            transport: "ipc",
+            source: "../../../runtime/routes/health-routes.js",
+          },
+        },
+      ],
+    },
+    // services/, agents/, llm/ namespaces remain forbidden for ipc commands.
+    {
+      code: `
+        import type { Command } from "commander";
+        import { cliIpcCall } from "../../ipc/cli-client.js";
+        import { dispatchAgent } from "../../agents/dispatcher.js";
+
+        registerCommand(program, {
+          name: "bad-ipc-agents",
+          transport: "ipc",
+          build: () => {},
+        });
+      `,
+      errors: [
+        {
+          messageId: "forbiddenImport",
+          data: {
+            transport: "ipc",
+            source: "../../agents/dispatcher.js",
+          },
+        },
+      ],
+    },
+  ],
+});