@vellumai/assistant 0.8.0 → 0.8.2

package/src/cli/utils/__tests__/parse-duration.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseDuration } from "../parse-duration.js";
+
+describe("parseDuration", () => {
+  test('"30s" → 30', () => {
+    expect(parseDuration("30s")).toBe(30);
+  });
+
+  test('"5m" → 300', () => {
+    expect(parseDuration("5m")).toBe(300);
+  });
+
+  test('"1h" → 3600', () => {
+    expect(parseDuration("1h")).toBe(3600);
+  });
+
+  test('"1h30m" → 5400', () => {
+    expect(parseDuration("1h30m")).toBe(5400);
+  });
+
+  test('"90m" → 5400', () => {
+    expect(parseDuration("90m")).toBe(5400);
+  });
+
+  test('"60" (bare number) → 60', () => {
+    expect(parseDuration("60")).toBe(60);
+  });
+
+  test("invalid string → throws Error", () => {
+    expect(() => parseDuration("abc")).toThrow('Invalid duration: "abc"');
+  });
+
+  test("empty string → throws Error", () => {
+    expect(() => parseDuration("")).toThrow();
+  });
+
+  test('"1hxyz" (partial parse) → throws with "Invalid duration"', () => {
+    expect(() => parseDuration("1hxyz")).toThrow("Invalid duration");
+  });
+
+  test('"1h-30m" (partial parse with dash) → throws with "Invalid duration"', () => {
+    expect(() => parseDuration("1h-30m")).toThrow("Invalid duration");
+  });
+
+  test('"30mxyz" (partial parse) → throws with "Invalid duration"', () => {
+    expect(() => parseDuration("30mxyz")).toThrow("Invalid duration");
+  });
+});

package/src/cli/utils/conversation-id.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolve the conversation ID by precedence:
+ *   1. Explicit value provided in `opts.explicit`
+ *   2. `__SKILL_CONTEXT_JSON` env var (set by skill sandbox runner)
+ *   3. `__CONVERSATION_ID` env var (set by bash tool subprocess)
+ *   4. Throw with the provided `failureHelp` message
+ */
+export function resolveConversationId(opts: {
+  explicit?: string;
+  failureHelp: string;
+}): string {
+  if (opts.explicit) return opts.explicit;
+
+  const contextJson = process.env.__SKILL_CONTEXT_JSON;
+  if (contextJson) {
+    try {
+      const parsed = JSON.parse(contextJson) as Record<string, unknown>;
+      if (typeof parsed.conversationId === "string" && parsed.conversationId) {
+        return parsed.conversationId;
+      }
+    } catch {
+      // ignore malformed JSON
+    }
+  }
+
+  const envConvId = process.env.__CONVERSATION_ID;
+  if (envConvId && typeof envConvId === "string") return envConvId;
+
+  throw new Error(opts.failureHelp);
+}

package/src/cli/utils/parse-duration.ts

@@ -0,0 +1,41 @@
+/**
+ * Parse a human-friendly duration string into seconds.
+ *
+ * Accepted formats:
+ *   "60"     → 60   (bare number = seconds)
+ *   "60s"    → 60
+ *   "5m"     → 300
+ *   "1h"     → 3600
+ *   "1h30m"  → 5400
+ *   "90s"    → 90
+ *
+ * Note: `--ttl never` is handled at the call site (mapped to ttlSeconds: null);
+ * do NOT pass "never" to this function.
+ */
+export function parseDuration(input: string): number {
+  if (/^\d+$/.test(input)) return parseInt(input, 10);
+  // Validate the whole string is composed entirely of <digits><unit> groups
+  if (!/^(\d+[hms])+$/.test(input)) {
+    throw new Error(`Invalid duration: "${input}"`);
+  }
+
+  let total = 0;
+  const re = /(\d+)(h|m|s)/g;
+  let match;
+  while ((match = re.exec(input)) !== null) {
+    const val = parseInt(match[1], 10);
+    switch (match[2]) {
+      case "h":
+        total += val * 3600;
+        break;
+      case "m":
+        total += val * 60;
+        break;
+      case "s":
+        total += val;
+        break;
+    }
+  }
+  if (total === 0) throw new Error(`Invalid duration: "${input}"`);
+  return total;
+}

package/src/config/acp-defaults.test.ts

@@ -29,10 +29,14 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     });
   });
 
-  test("is frozen at runtime so mutation throws in strict mode", () => {
+  test("is deeply frozen so mutation throws in strict mode", () => {
     expect(Object.isFrozen(DEFAULT_ACP_AGENT_PROFILES)).toBe(true);
     for (const profile of Object.values(DEFAULT_ACP_AGENT_PROFILES)) {
       expect(Object.isFrozen(profile)).toBe(true);
+      // `args` arrays must also be frozen — `Object.freeze` is shallow, so
+      // an unfrozen `args` would let one caller silently corrupt every other
+      // read of the shared default via `.push(...)` / `.splice(...)`.
+      expect(Object.isFrozen(profile.args)).toBe(true);
     }
   });
 });

package/src/config/acp-defaults.ts

@@ -1,5 +1,11 @@
 import type { AcpAgentConfig } from "./acp-schema.js";
 
+// Shared frozen empty args array — these defaults are read by every ACP spawn,
+// so a single accidental `args.push(...)` from one caller would corrupt every
+// subsequent read. Cast through `unknown` because `AcpAgentConfig.args` is
+// `string[]` (Zod-inferred) but the value is genuinely immutable at runtime.
+const FROZEN_EMPTY_ARGS = Object.freeze([] as string[]) as unknown as string[];
+
 /**
  * Default ACP agent profiles that ship with the assistant.
  *
@@ -7,20 +13,21 @@ import type { AcpAgentConfig } from "./acp-schema.js";
  * agent id, the resolver falls back to this map so common agents like `claude`
  * and `codex` Just Work without requiring per-user config.
  *
- * Keyed by agent id. Frozen so accidental runtime mutation throws in strict
- * mode and the readonly type matches actual runtime behavior.
+ * Keyed by agent id. Deeply frozen — the outer object, each profile, and the
+ * `args` arrays — so mutation throws in strict mode rather than silently
+ * corrupting the shared defaults.
  */
 export const DEFAULT_ACP_AGENT_PROFILES: Readonly<
   Record<string, AcpAgentConfig>
 > = Object.freeze({
   claude: Object.freeze({
     command: "claude-agent-acp",
-    args: [],
+    args: FROZEN_EMPTY_ARGS,
     description: "Claude Code (via @agentclientprotocol/claude-agent-acp)",
   }),
   codex: Object.freeze({
     command: "codex-acp",
-    args: [],
+    args: FROZEN_EMPTY_ARGS,
     description: "OpenAI Codex CLI (via @zed-industries/codex-acp)",
   }),
 });

package/src/config/bundled-skills/acp/TOOLS.json

@@ -11,7 +11,7 @@
         "properties": {
           "agent": {
             "type": "string",
-            "description": "Which agent to spawn (e.g. 'claude', 'codex', 'gemini'). Defaults to 'claude'."
+            "description": "Which agent to spawn (e.g. 'claude', 'codex'). Defaults to 'claude'."
           },
           "task": {
             "type": "string",
@@ -67,7 +67,7 @@
       "name": "acp_steer",
       "description": "**Interrupts** the in-flight prompt of a running ACP session and replaces it with `instruction`. Use to redirect the agent (e.g., 'stop, do X instead'). For follow-up work that should happen *after* the current task, do NOT use this — wait for `acp_session_completed` and `acp_spawn` again.",
       "category": "orchestration",
-      "risk": "medium",
+      "risk": "high",
       "input_schema": {
         "type": "object",
         "properties": {

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -177,27 +177,31 @@ useEffect(() => {
 }, []);
 ```
 
-**File workflow:** Call `app_create` first to create the app record and scaffold, use `file_write` for each source file under `src/`, then call `app_refresh` once to compile and refresh the UI.
+**File workflow:** Pass all source files inline via the `source_files` parameter of `app_create`. This writes and compiles the real app in a single call — no scaffold placeholder, no separate `file_write` or `app_refresh` needed for initial creation. For subsequent edits, use `file_edit`/`file_write` then call `app_refresh` once.
 
 **Allowed third-party packages:** `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`, `lucide`. Import them directly - esbuild resolves them at build time. No CDN imports. Note: `lucide` is the vanilla JS icon library (not `lucide-react`). Use its `createElement` or `createIcons` API, or manually inline SVG - do not import JSX icon components.
 
-**Example - creating a multi-file project** (assuming app slug is `project-tracker`):
+**Example - creating a multi-file project:**
 
 ```
-file_write("{workspaceDir}/data/apps/project-tracker/src/index.html", `<!DOCTYPE html>
+app_create({
+  name: "Project Tracker",
+  description: "Track projects with status and priority",
+  schema_json: '{"type":"object","properties":{"title":{"type":"string"},"status":{"type":"string"}},"required":["title"]}',
+  preview: { title: "Project Tracker", icon: "📋" },
+  source_files: {
+    "src/index.html": `<!DOCTYPE html>
 <html lang="en">
 <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Project Tracker</title></head>
 <body><div id="app"></div></body>
-</html>`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/main.tsx", `import { render } from 'preact';
+</html>`,
+    "src/main.tsx": `import { render } from 'preact';
 import { App } from './components/App';
 import './styles.css';
 
-render(<App />, document.getElementById('app')!);`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/components/App.tsx", `import { FunctionComponent } from 'preact';
+render(<App />, document.getElementById('app')!);`,
+    "src/components/App.tsx": `import { FunctionComponent } from 'preact';
 import { useState, useEffect } from 'preact/hooks';
 import { Header } from './Header';
 
@@ -217,9 +221,8 @@ export const App: FunctionComponent = () => {
       {/* ... */}
     </div>
   );
-};`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/components/Header.tsx", `import { FunctionComponent } from 'preact';
+};`,
+    "src/components/Header.tsx": `import { FunctionComponent } from 'preact';
 
 interface HeaderProps {
   title: string;
@@ -231,14 +234,12 @@ export const Header: FunctionComponent<HeaderProps> = ({ title, count }) => (
     <h1>{title}</h1>
     <span className="badge">{count} items</span>
   </header>
-);`)
-
-file_write("{workspaceDir}/data/apps/project-tracker/src/styles.css", `.app { padding: var(--v-spacing-lg); }
+);`,
+    "src/styles.css": `.app { padding: var(--v-spacing-lg); }
 .header { display: flex; justify-content: space-between; align-items: center; }
-.badge { background: var(--v-accent); color: var(--v-aux-white); padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`)
-
-# After all files are written, compile and refresh:
-app_refresh(app_id)
+.badge { background: var(--v-accent); color: var(--v-aux-white); padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`
+  }
+})
 ```
 
 **Technical constraints (multi-file):**
@@ -329,10 +330,11 @@ Call `app_create` with:
 - `name`: Short descriptive name
 - `description`: One-sentence summary
 - `schema_json`: JSON schema as string
-- `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat
+- `source_files`: Map of relative file paths to contents (e.g. `{"src/main.tsx": "...", "src/styles.css": "..."}`). **Always include this** with the complete app source — it writes, compiles, and opens the real app in a single call.
+- `auto_open`: (optional, defaults to `true`) Shows an inline preview card in chat after the app is built. Only fires when real source files are provided (not for scaffold-only apps).
 - `preview`: Always include - `title` (required), `subtitle`, `description`, `icon` (image URL preferred, emoji fallback), `metrics` (up to 3 key-value pills)
 
-Do not pass `html` or `pages` to `app_create`; those single-file shortcuts are retired. After `app_create` returns the app ID, write the real app source under `src/` and call `app_refresh`.
+Do not pass `html` or `pages` to `app_create`; those single-file shortcuts are retired.
 
 The app is NOT opened in a workspace panel automatically - users open it via the 'Open App' button on the inline card.
 

package/src/config/bundled-skills/app-builder/TOOLS.json

@@ -64,6 +64,13 @@
             },
             "required": ["title"]
           },
+          "source_files": {
+            "type": "object",
+            "description": "Map of file paths to file contents to write under the app directory. Supply the real app source here instead of making separate file_write calls. Paths are relative to the app directory (e.g. 'src/main.tsx', 'src/components/App.tsx', 'src/styles.css'). When src/main.tsx is included, no scaffold placeholder is created and the app compiles immediately with real content.",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
           "change_summary": {
             "type": "string",
             "description": "Short summary of what changed, using git conventional commit format (e.g. 'feat: add coin flip app', 'fix: correct button alignment'). Used as the version history entry."

package/src/config/bundled-skills/app-control/TOOLS.json

@@ -21,6 +21,10 @@
           "reasoning": {
             "type": "string",
             "description": "Explanation of why you are starting this app"
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app", "reasoning"]
@@ -43,6 +47,10 @@
           "settle_ms": {
             "type": "integer",
             "description": "Milliseconds to wait before capturing so the target app and the WindowServer can flush pending input + composite a fresh frame. Default ~200ms (sized for emulator-class apps at 60fps). Pass 0 for static UIs; raise for slow-feedback apps."
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app"]
@@ -78,6 +86,10 @@
           "reasoning": {
             "type": "string",
             "description": "Explanation of why you are pressing this key"
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app", "key", "reasoning"]
@@ -109,6 +121,10 @@
           "reasoning": {
             "type": "string",
             "description": "Explanation of why you are pressing this combo"
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app", "keys", "reasoning"]
@@ -158,6 +174,10 @@
           "reasoning": {
             "type": "string",
             "description": "Explanation of what this sequence does and why"
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app", "steps", "reasoning"]
@@ -184,6 +204,10 @@
           "reasoning": {
             "type": "string",
             "description": "Explanation of what you are typing and why"
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app", "text", "reasoning"]
@@ -223,6 +247,10 @@
           "reasoning": {
             "type": "string",
             "description": "Explanation of what you see and why you are clicking here"
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app", "x", "y", "reasoning"]
@@ -266,6 +294,10 @@
           "reasoning": {
             "type": "string",
             "description": "Explanation of what you are dragging and why"
+          },
+          "target_client_id": {
+            "type": "string",
+            "description": "ID of the specific client to target. Required when multiple clients support host_app_control; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_app_control`."
           }
         },
         "required": ["app", "from_x", "from_y", "to_x", "to_y", "reasoning"]

package/src/config/bundled-skills/computer-use/TOOLS.json

@@ -24,11 +24,7 @@
         "properties": {
           "click_type": {
             "type": "string",
-            "enum": [
-              "single",
-              "double",
-              "right"
-            ],
+            "enum": ["single", "double", "right"],
             "description": "Type of click to perform (default: \"single\")"
           },
           "element_id": {
@@ -52,9 +48,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "reasoning"
-        ]
+        "required": ["reasoning"]
       },
       "executor": "tools/computer-use-click.ts",
       "execution_target": "host"
@@ -80,10 +74,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "text",
-          "reasoning"
-        ]
+        "required": ["text", "reasoning"]
       },
       "executor": "tools/computer-use-type-text.ts",
       "execution_target": "host"
@@ -109,10 +100,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "key",
-          "reasoning"
-        ]
+        "required": ["key", "reasoning"]
       },
       "executor": "tools/computer-use-key.ts",
       "execution_target": "host"
@@ -139,12 +127,7 @@
           },
           "direction": {
             "type": "string",
-            "enum": [
-              "up",
-              "down",
-              "left",
-              "right"
-            ],
+            "enum": ["up", "down", "left", "right"],
             "description": "Scroll direction"
           },
           "amount": {
@@ -160,11 +143,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "direction",
-          "amount",
-          "reasoning"
-        ]
+        "required": ["direction", "amount", "reasoning"]
       },
       "executor": "tools/computer-use-scroll.ts",
       "execution_target": "host"
@@ -210,9 +189,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "reasoning"
-        ]
+        "required": ["reasoning"]
       },
       "executor": "tools/computer-use-drag.ts",
       "execution_target": "host"
@@ -238,10 +215,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "duration_ms",
-          "reasoning"
-        ]
+        "required": ["duration_ms", "reasoning"]
       },
       "executor": "tools/computer-use-wait.ts",
       "execution_target": "host"
@@ -267,17 +241,14 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "app_name",
-          "reasoning"
-        ]
+        "required": ["app_name", "reasoning"]
       },
       "executor": "tools/computer-use-open-app.ts",
       "execution_target": "host"
     },
     {
       "name": "computer_use_run_applescript",
-      "description": "Run an AppleScript command. Prefer this over click/type when possible - it doesn't move the cursor or interrupt the user. Never use 'do shell script' inside AppleScript (blocked for security).",
+      "description": "Run an AppleScript command. Prefer this over click/type when possible - it doesn't move the cursor or interrupt foreground activity. Never use 'do shell script' inside AppleScript (blocked for security).",
       "category": "computer-use",
       "risk": "medium",
       "input_schema": {
@@ -296,10 +267,7 @@
             "description": "ID of the specific client to target. Required when multiple clients support host_cu; omit when only one is connected. Obtain IDs from `assistant clients list --capability host_cu`."
           }
         },
-        "required": [
-          "script",
-          "reasoning"
-        ]
+        "required": ["script", "reasoning"]
       },
       "executor": "tools/computer-use-run-applescript.ts",
       "execution_target": "host"
@@ -317,16 +285,14 @@
             "description": "Human-readable summary of what was accomplished"
           }
         },
-        "required": [
-          "summary"
-        ]
+        "required": ["summary"]
       },
       "executor": "tools/computer-use-done.ts",
       "execution_target": "host"
     },
     {
       "name": "computer_use_respond",
-      "description": "Respond to the user with a text answer instead of performing computer actions. Use this when you can answer directly without interacting with the screen.",
+      "description": "Reply with a text answer instead of performing computer actions. Use this when you can answer directly without interacting with the screen.",
       "category": "computer-use",
       "risk": "low",
       "input_schema": {
@@ -334,17 +300,14 @@
         "properties": {
           "answer": {
             "type": "string",
-            "description": "The text answer to display to the user"
+            "description": "The text answer to display"
           },
           "reasoning": {
             "type": "string",
             "description": "Explanation of how you determined the answer"
           }
         },
-        "required": [
-          "answer",
-          "reasoning"
-        ]
+        "required": ["answer", "reasoning"]
       },
       "executor": "tools/computer-use-respond.ts",
       "execution_target": "host"