@vellumai/assistant 0.5.1 → 0.5.3

package/src/skills/inline-command-runner.ts

@@ -0,0 +1,242 @@
+/**
+ * Sandbox-only runner for inline command expansions (`!\`command\``).
+ *
+ * Executes the literal command string in the sandbox without going through the
+ * general `bash` tool's permission path. Security constraints:
+ *
+ * - Network mode forced off (no outbound connections)
+ * - Sanitized environment variables only (no API keys, tokens, credentials)
+ * - No credential proxy, no CES client, no host fallback
+ * - Uses the conversation working directory as `cwd` so repo-local commands
+ *   remain interoperable with externally authored skills that expect project
+ *   context.
+ *
+ * Output handling:
+ * - Captures stdout only (stderr is discarded)
+ * - Strips ANSI escape sequences
+ * - Rejects binary-ish output
+ * - Clamps output to a fixed cap
+ * - Returns deterministic sanitized error results for timeout, non-zero exit,
+ *   or spawn failures (no raw stderr dumps)
+ */
+
+import { spawn } from "node:child_process";
+
+import { getConfig } from "../config/loader.js";
+import { buildSanitizedEnv } from "../tools/terminal/safe-env.js";
+import { wrapCommand } from "../tools/terminal/sandbox.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("inline-command-runner");
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/** Maximum wall-clock time for an inline command before it is killed. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/** Maximum output characters before truncation. */
+const MAX_OUTPUT_CHARS = 20_000;
+
+/**
+ * ANSI escape sequence pattern (covers SGR, cursor movement, erase, etc.).
+ * Matches: ESC[ ... final_byte  and  ESC] ... ST  (OSC sequences).
+ */
+const ANSI_RE = /\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07]*(?:\x07|\x1b\\)/g;
+
+/**
+ * Heuristic for binary output: if more than 10% of the characters are
+ * non-printable (control chars excluding \t, \n, \r) then reject.
+ */
+const BINARY_THRESHOLD = 0.1;
+
+// ─── Result type ─────────────────────────────────────────────────────────────
+
+/** Deterministic result shape returned by the inline command runner. */
+export interface InlineCommandResult {
+  /** The sanitized stdout output, or a human-readable error description. */
+  output: string;
+  /** Whether the command completed successfully. */
+  ok: boolean;
+  /**
+   * Machine-readable failure reason.
+   * - `"timeout"` — command exceeded the wall-clock limit
+   * - `"non_zero_exit"` — command exited with a non-zero code
+   * - `"binary_output"` — stdout contained binary-ish data
+   * - `"spawn_failure"` — the subprocess could not be spawned
+   * - `undefined` — success
+   */
+  failureReason?:
+    | "timeout"
+    | "non_zero_exit"
+    | "binary_output"
+    | "spawn_failure";
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export interface InlineCommandRunnerOptions {
+  /** Override the default timeout (ms). */
+  timeoutMs?: number;
+  /** Override the default output cap (chars). */
+  maxOutputChars?: number;
+}
+
+/**
+ * Run an inline command expansion in the sandbox.
+ *
+ * @param command  The literal command string from the `!\`...\`` token.
+ * @param workingDir  The conversation's working directory (repo root).
+ * @param options  Optional overrides for timeout and output cap.
+ */
+export async function runInlineCommand(
+  command: string,
+  workingDir: string,
+  options?: InlineCommandRunnerOptions,
+): Promise<InlineCommandResult> {
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxChars = options?.maxOutputChars ?? MAX_OUTPUT_CHARS;
+
+  // Build sandbox-wrapped command. Always use the sandbox config with
+  // network forced off — inline commands never need network access.
+  const config = getConfig();
+  const sandboxConfig = { ...config.sandbox, enabled: true };
+
+  const wrapped = wrapCommand(command, workingDir, sandboxConfig, {
+    networkMode: "off",
+  });
+
+  // Build a minimal, sanitized environment. Explicitly exclude gateway URL,
+  // workspace dir, and data dir since inline commands have no business calling
+  // internal APIs, mutating workspace state, or accessing instance-scoped data.
+  const env = buildSanitizedEnv();
+  delete env.INTERNAL_GATEWAY_BASE_URL;
+  delete env.VELLUM_WORKSPACE_DIR;
+  delete env.VELLUM_DATA_DIR;
+
+  return new Promise<InlineCommandResult>((resolve) => {
+    let timedOut = false;
+    const stdoutChunks: Buffer[] = [];
+
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(wrapped.command, wrapped.args, {
+        cwd: workingDir,
+        env,
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn({ command, error: message }, "Failed to spawn inline command");
+      resolve({
+        output: "Inline command could not be started.",
+        ok: false,
+        failureReason: "spawn_failure",
+      });
+      return;
+    }
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+
+    child.stdout!.on("data", (data: Buffer) => stdoutChunks.push(data));
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+
+      // ── Timeout ──────────────────────────────────────────────────────
+      if (timedOut) {
+        log.debug({ command, timeoutMs }, "Inline command timed out");
+        resolve({
+          output: `Inline command timed out after ${timeoutMs}ms.`,
+          ok: false,
+          failureReason: "timeout",
+        });
+        return;
+      }
+
+      // ── Non-zero exit ────────────────────────────────────────────────
+      if (code !== 0) {
+        log.debug(
+          { command, exitCode: code },
+          "Inline command exited with non-zero code",
+        );
+        resolve({
+          output: `Inline command failed (exit code ${code}).`,
+          ok: false,
+          failureReason: "non_zero_exit",
+        });
+        return;
+      }
+
+      // ── Process stdout ───────────────────────────────────────────────
+      const raw = Buffer.concat(stdoutChunks).toString("utf-8");
+
+      // Strip ANSI sequences first — these are terminal artifacts, not
+      // binary data. Stripping before the binary check prevents legitimate
+      // color-coded tool output from being rejected.
+      let cleaned = raw.replace(ANSI_RE, "");
+
+      // Reject binary-ish output (after ANSI stripping)
+      if (isBinaryish(cleaned)) {
+        log.debug({ command }, "Inline command produced binary-ish output");
+        resolve({
+          output: "Inline command produced binary output.",
+          ok: false,
+          failureReason: "binary_output",
+        });
+        return;
+      }
+
+      // Clamp to max output
+      if (cleaned.length > maxChars) {
+        cleaned = cleaned.slice(0, maxChars) + "\n[output truncated]";
+      }
+
+      // Trim trailing whitespace
+      cleaned = cleaned.trimEnd();
+
+      resolve({
+        output: cleaned,
+        ok: true,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      log.warn({ command, error: err.message }, "Inline command spawn error");
+      resolve({
+        output: "Inline command could not be started.",
+        ok: false,
+        failureReason: "spawn_failure",
+      });
+    });
+  });
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Heuristic check for binary output. Returns true if more than
+ * {@link BINARY_THRESHOLD} of the characters are non-printable control
+ * characters (excluding tab, newline, carriage return).
+ */
+function isBinaryish(text: string): boolean {
+  if (text.length === 0) return false;
+
+  let controlCount = 0;
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    // Control characters: 0x00-0x1F (excluding \t=0x09, \n=0x0A, \r=0x0D)
+    // and 0x7F (DEL)
+    if (
+      (code <= 0x1f && code !== 0x09 && code !== 0x0a && code !== 0x0d) ||
+      code === 0x7f
+    ) {
+      controlCount++;
+    }
+  }
+
+  return controlCount / text.length > BINARY_THRESHOLD;
+}

package/src/skills/transitive-version-hash.ts

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+
+import type { SkillSummary } from "../config/skills.js";
+import { validateIncludes } from "./include-graph.js";
+import { computeSkillVersionHash } from "./version-hash.js";
+
+/**
+ * Error thrown when the include graph is invalid (missing nodes or cycles).
+ * The permission layer depends on exact approval candidates, so we fail closed
+ * rather than returning a partial or potentially misleading hash.
+ */
+export class TransitiveHashError extends Error {
+  constructor(
+    message: string,
+    public readonly code: "missing" | "cycle",
+  ) {
+    super(message);
+    this.name = "TransitiveHashError";
+  }
+}
+
+/**
+ * Compute a transitive version hash for a skill and all its included children.
+ *
+ * The hash covers:
+ * 1. The DFS-ordered list of visited skill IDs (so the graph structure matters)
+ * 2. Each visited skill's directory hash (via `computeSkillVersionHash`)
+ *
+ * This means editing any included child skill invalidates the parent's
+ * transitive hash, which is required for version-pinned inline-command
+ * approval.
+ *
+ * Fails closed (throws `TransitiveHashError`) when:
+ * - A child referenced in `includes` is missing from the catalog index
+ * - The include graph contains a cycle
+ *
+ * @param rootSkillId  The skill ID to start traversal from.
+ * @param catalogIndex A `Map<skillId, SkillSummary>` built via `indexCatalogById`.
+ * @returns A canonical hash string in the format `tv1:<hex-sha256>`.
+ */
+export function computeTransitiveSkillVersionHash(
+  rootSkillId: string,
+  catalogIndex: Map<string, SkillSummary>,
+): string {
+  // Validate the include graph first — fail closed on any issue.
+  const validation = validateIncludes(rootSkillId, catalogIndex);
+
+  if (!validation.ok) {
+    if (validation.error === "cycle") {
+      throw new TransitiveHashError(
+        `Cycle detected in include graph: ${validation.cyclePath.join(" -> ")}`,
+        "cycle",
+      );
+    }
+    // validation.error === "missing"
+    throw new TransitiveHashError(
+      `Missing child skill "${validation.missingChildId}" referenced by "${validation.parentId}" (path: ${validation.path.join(" -> ")})`,
+      "missing",
+    );
+  }
+
+  // validation.ok === true, so visited contains all skill IDs in DFS pre-order.
+  const { visited } = validation;
+
+  const hash = createHash("sha256");
+
+  for (const skillId of visited) {
+    // Fold the skill ID into the digest so graph structure matters.
+    hash.update(skillId);
+    hash.update("\0");
+
+    const skill = catalogIndex.get(skillId);
+    if (!skill) {
+      // Should be unreachable after validateIncludes succeeds, but fail closed.
+      throw new TransitiveHashError(
+        `Skill "${skillId}" disappeared from catalog index after validation`,
+        "missing",
+      );
+    }
+
+    // Fold the per-directory content hash so file changes propagate.
+    const dirHash = computeSkillVersionHash(skill.directoryPath);
+    hash.update(dirHash);
+    hash.update("\n");
+  }
+
+  return `tv1:${hash.digest("hex")}`;
+}

package/src/swarm/backend-claude-code.ts

@@ -7,7 +7,7 @@
 
 import { resolveModelIntent } from "../providers/model-intents.js";
 import type { ModelIntent } from "../providers/types.js";
-import { getSecureKeyAsync } from "../security/secure-keys.js";
+import { getProviderKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
 import type {
   SwarmWorkerBackend,
@@ -29,8 +29,7 @@ export function createClaudeCodeBackend(): SwarmWorkerBackend {
     name: "claude_code",
 
     async isAvailable(): Promise<boolean> {
-      const apiKey =
-        (await getSecureKeyAsync("anthropic")) ?? process.env.ANTHROPIC_API_KEY;
+      const apiKey = await getProviderKeyAsync("anthropic");
       return !!apiKey;
     },
 
@@ -39,9 +38,7 @@ export function createClaudeCodeBackend(): SwarmWorkerBackend {
       const stderrLines: string[] = [];
       try {
         const { query } = await import("@anthropic-ai/claude-agent-sdk");
-        const apiKey =
-          (await getSecureKeyAsync("anthropic")) ??
-          process.env.ANTHROPIC_API_KEY;
+        const apiKey = await getProviderKeyAsync("anthropic");
         if (!apiKey) {
           return {
             success: false,

package/src/tasks/task-store.ts

@@ -1,4 +1,4 @@
-import { desc, eq, inArray } from "drizzle-orm";
+import { asc, desc, eq, inArray, or } from "drizzle-orm";
 
 import { getDb } from "../memory/db.js";
 import { taskRuns, tasks, workItems } from "../memory/schema.js";
@@ -139,3 +139,45 @@ export function getTaskRun(id: string): TaskRun | undefined {
   const db = getDb();
   return db.select().from(taskRuns).where(eq(taskRuns.id, id)).get();
 }
+
+// ── Brief Helpers ─────────────────────────────────────────────────────
+
+/**
+ * Lightweight read-only projection of a work item used by the brief compiler.
+ * Avoids pulling the full WorkItem type with all its tool/approval fields.
+ */
+export interface ActionableWorkItem {
+  id: string;
+  taskId: string;
+  title: string;
+  status: string;
+  priorityTier: number;
+  updatedAt: number;
+}
+
+/**
+ * Return actionable work items — those that are queued, running, or
+ * awaiting review. Ordered by priority (high first) then most-recently-updated.
+ */
+export function getActionableWorkItems(): ActionableWorkItem[] {
+  const db = getDb();
+  return db
+    .select({
+      id: workItems.id,
+      taskId: workItems.taskId,
+      title: workItems.title,
+      status: workItems.status,
+      priorityTier: workItems.priorityTier,
+      updatedAt: workItems.updatedAt,
+    })
+    .from(workItems)
+    .where(
+      or(
+        eq(workItems.status, "queued"),
+        eq(workItems.status, "running"),
+        eq(workItems.status, "awaiting_review"),
+      ),
+    )
+    .orderBy(asc(workItems.priorityTier), desc(workItems.updatedAt))
+    .all();
+}

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -97,6 +97,7 @@ mock.module("../version.js", () => ({
 // Production import (after mocks)
 // ---------------------------------------------------------------------------
 
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import type { UsageEvent } from "../usage/types.js";
 import { UsageTelemetryReporter } from "./usage-telemetry-reporter.js";
 
@@ -434,7 +435,7 @@ describe("UsageTelemetryReporter", () => {
     expect(body.user_id).toBeUndefined();
   });
 
-  test("assistant_id falls back to 'self' when getExternalAssistantId returns undefined", async () => {
+  test("assistant_id falls back to DAEMON_INTERNAL_ASSISTANT_ID when getExternalAssistantId returns undefined", async () => {
     mockGetExternalAssistantId.mockReturnValue(undefined);
     const events = [makeUsageEvent()];
     mockQueryUnreportedUsageEvents.mockReturnValue(events);
@@ -450,7 +451,7 @@ describe("UsageTelemetryReporter", () => {
       (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
     );
     expect(body.installation_id).toBe("test-device-id");
-    expect(body.assistant_id).toBe("self");
+    expect(body.assistant_id).toBe(DAEMON_INTERNAL_ASSISTANT_ID);
   });
 
   test("turn events are included in the events array with type discriminator", async () => {

package/src/telemetry/usage-telemetry-reporter.ts

@@ -23,6 +23,7 @@ import { queryUnreportedLifecycleEvents } from "../memory/lifecycle-events-store
 import { queryUnreportedUsageEvents } from "../memory/llm-usage-store.js";
 import { queryUnreportedTurnEvents } from "../memory/turn-events-store.js";
 import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import { getExternalAssistantId } from "../runtime/auth/external-assistant-id.js";
 import { getDeviceId } from "../util/device-id.js";
 import { getLogger } from "../util/logger.js";
@@ -187,7 +188,8 @@ export class UsageTelemetryReporter {
         ),
       ];
 
-      const assistantId = getExternalAssistantId() ?? "self";
+      const assistantId =
+        getExternalAssistantId() ?? DAEMON_INTERNAL_ASSISTANT_ID;
       const organizationId = getPlatformOrganizationId() || undefined;
       const userId = getPlatformUserId() || undefined;
       const payload = {

package/src/tools/AGENTS.md

@@ -1,18 +1,14 @@
 # Tools - Agent Instructions
 
-## No New Tools Policy
+## New Non-Skill Tools Are Strongly Discouraged
 
-**New tool registrations require approval from Team Jarvis.**
+**Prefer skills over new non-skill tool registrations.** Non-skill tools require approval from Team Jarvis.
 
-The tool registration system (`class ... implements Tool` + `registerTool()`) is being phased out in favor of skill-based approaches. Before adding a new tool, contact Team Jarvis for approval.
+Skills are the preferred approach for adding new capabilities — they are progressively disclosed into context, more portable, and can be iterated on independently. New non-skill tool registrations (`class ... implements Tool` + `registerTool()`) carry additional costs:
 
-## Why This Policy Exists
+1. **Context overhead** — Each registered tool adds to the system prompt and increases token usage for every conversation.
 
-1. **Skills are preferred** - The project direction is to teach the assistant CLI tools via skills rather than hardcoding tool implementations. Skills are progressively disclosed into context, are more portable, and are often self-contained.
-
-2. **Context overhead** - Each registered tool adds to the system prompt and increases token usage for every conversation.
-
-3. **Maintenance burden** - Tools require ongoing maintenance, testing, and security review. Skills can be iterated on independently.
+2. **Maintenance burden** — Tools require ongoing maintenance, testing, and security review.
 
 ## What To Do Instead
 
@@ -26,7 +22,7 @@ Instead of creating a new tool, consider:
 
 ## Approved Exception: Credential Execution Service (CES) Tools
 
-The following three CES tools are the only approved exception to the no-new-tools policy:
+The following three CES tools are approved exceptions that justify tool registrations over skills:
 
 | Tool                         | Purpose                                                                                                                                                    |
 | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |