@vellumai/assistant 0.12.1-dev.202609141913.5e16607 → 0.12.1-staging.2

package/src/config/__tests__/platform-rehydration.test.ts

@@ -27,8 +27,6 @@ const {
   setPlatformOrganizationId,
   setPlatformUserId,
 } = await import("../env.js");
-const { _resetPlatformIdentityEnsureForTests } =
-  await import("../platform-identity.js");
 const { rehydratePlatformCredentials } =
   await import("../platform-rehydration.js");
 
@@ -41,44 +39,23 @@ describe("rehydratePlatformCredentials", () => {
   const originalPlatformUrlEnv = process.env.VELLUM_PLATFORM_URL;
   const originalOrgEnv = process.env.PLATFORM_ORGANIZATION_ID;
   const originalUserEnv = process.env.PLATFORM_USER_ID;
-  const originalAssistantApiKeyEnv = process.env.ASSISTANT_API_KEY;
-  const originalFetch = globalThis.fetch;
-  const fetchCalls: Array<{ url: string; init?: RequestInit }> = [];
-  let fetchImpl: (
-    input: RequestInfo | URL,
-    init?: RequestInit,
-  ) => Promise<Response> = async () =>
-    new Response("not found", { status: 404 });
 
   beforeEach(() => {
     mockSecureKeys = {};
     throwForKey = undefined;
-    fetchCalls.length = 0;
-    fetchImpl = async () => new Response("not found", { status: 404 });
-    globalThis.fetch = (async (
-      input: RequestInfo | URL,
-      init?: RequestInit,
-    ) => {
-      const url = typeof input === "string" ? input : input.toString();
-      fetchCalls.push({ url, init });
-      return fetchImpl(input, init);
-    }) as unknown as typeof fetch;
     // Env vars take precedence over the rehydrated overrides for some fields;
     // clear them so the credential-store values are what we observe.
     delete process.env.VELLUM_PLATFORM_URL;
     delete process.env.PLATFORM_ORGANIZATION_ID;
     delete process.env.PLATFORM_USER_ID;
-    delete process.env.ASSISTANT_API_KEY;
     // Reset in-memory overrides between tests.
     setPlatformBaseUrl(undefined);
     setPlatformAssistantId(undefined);
     setPlatformOrganizationId(undefined);
     setPlatformUserId(undefined);
-    _resetPlatformIdentityEnsureForTests();
   });
 
   afterEach(() => {
-    globalThis.fetch = originalFetch;
     if (originalPlatformUrlEnv === undefined) {
       delete process.env.VELLUM_PLATFORM_URL;
     } else {
@@ -94,18 +71,13 @@ describe("rehydratePlatformCredentials", () => {
     } else {
       process.env.PLATFORM_USER_ID = originalUserEnv;
     }
-    if (originalAssistantApiKeyEnv === undefined) {
-      delete process.env.ASSISTANT_API_KEY;
-    } else {
-      process.env.ASSISTANT_API_KEY = originalAssistantApiKeyEnv;
-    }
     setPlatformBaseUrl(undefined);
     setPlatformAssistantId(undefined);
     setPlatformOrganizationId(undefined);
     setPlatformUserId(undefined);
   });
 
-  test("rehydrates the platform base URL from the credential store", async () => {
+  test("rehydrates base URL and all platform IDs from the credential store", async () => {
     mockSecureKeys[credentialKey("vellum", "platform_base_url")] = PROD_URL;
     mockSecureKeys[credentialKey("vellum", "platform_assistant_id")] =
       ASSISTANT_ID;
@@ -116,18 +88,21 @@ describe("rehydratePlatformCredentials", () => {
     await rehydratePlatformCredentials();
 
     expect(getPlatformBaseUrl()).toBe(PROD_URL);
-    expect(getPlatformAssistantId()).toBe("");
-    expect(getPlatformOrganizationId()).toBe("");
-    expect(getPlatformUserId()).toBe("");
+    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
+    expect(getPlatformOrganizationId()).toBe(ORG_ID);
+    expect(getPlatformUserId()).toBe(USER_ID);
   });
 
   test("trims stored values before applying them", async () => {
     mockSecureKeys[credentialKey("vellum", "platform_base_url")] =
       `  ${PROD_URL}  `;
+    mockSecureKeys[credentialKey("vellum", "platform_assistant_id")] =
+      `\n${ASSISTANT_ID}\n`;
 
     await rehydratePlatformCredentials();
 
     expect(getPlatformBaseUrl()).toBe(PROD_URL);
+    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
   });
 
   test("leaves overrides untouched when nothing is stored", async () => {
@@ -138,78 +113,13 @@ describe("rehydratePlatformCredentials", () => {
     expect(getPlatformUserId()).toBe("");
   });
 
-  test("a credential-store read failure does not throw", async () => {
+  test("a per-field read failure does not block the remaining fields", async () => {
     throwForKey = credentialKey("vellum", "platform_base_url");
-
-    await expect(rehydratePlatformCredentials()).resolves.toBeUndefined();
-    expect(getPlatformAssistantId()).toBe("");
-  });
-
-  test("trades the assistant API key for ids via platform validate", async () => {
-    mockSecureKeys[credentialKey("vellum", "platform_base_url")] = PROD_URL;
-    mockSecureKeys[credentialKey("vellum", "assistant_api_key")] =
-      "assistant-key";
-    fetchImpl = async () =>
-      new Response(
-        JSON.stringify({
-          assistant_id: ASSISTANT_ID,
-          organization_id: ORG_ID,
-          user_id: USER_ID,
-        }),
-        { status: 200 },
-      );
-
-    await rehydratePlatformCredentials();
-
-    expect(fetchCalls).toHaveLength(1);
-    expect(fetchCalls[0]?.url).toBe(
-      `${PROD_URL}/v1/internal/assistants/validate/`,
-    );
-    const headers = new Headers(fetchCalls[0]?.init?.headers);
-    expect(headers.get("Authorization")).toBe("Api-Key assistant-key");
-    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
-    expect(getPlatformOrganizationId()).toBe(ORG_ID);
-    expect(getPlatformUserId()).toBe(USER_ID);
-  });
-
-  test("validate ids are used when the vault also has a copy", async () => {
-    mockSecureKeys[credentialKey("vellum", "platform_base_url")] = PROD_URL;
-    mockSecureKeys[credentialKey("vellum", "assistant_api_key")] =
-      "assistant-key";
-    mockSecureKeys[credentialKey("vellum", "platform_assistant_id")] =
-      "asst-from-vault";
-    fetchImpl = async () =>
-      new Response(
-        JSON.stringify({
-          assistant_id: ASSISTANT_ID,
-          organization_id: ORG_ID,
-          user_id: USER_ID,
-        }),
-        { status: 200 },
-      );
-
-    await rehydratePlatformCredentials();
-
-    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
-  });
-
-  test("does not populate ids from the vault when validate is unreachable", async () => {
-    mockSecureKeys[credentialKey("vellum", "platform_base_url")] = PROD_URL;
-    mockSecureKeys[credentialKey("vellum", "assistant_api_key")] =
-      "assistant-key";
     mockSecureKeys[credentialKey("vellum", "platform_assistant_id")] =
       ASSISTANT_ID;
-    mockSecureKeys[credentialKey("vellum", "platform_organization_id")] =
-      ORG_ID;
-    mockSecureKeys[credentialKey("vellum", "platform_user_id")] = USER_ID;
-    fetchImpl = async () => {
-      throw new Error("network down");
-    };
 
     await rehydratePlatformCredentials();
 
-    expect(getPlatformAssistantId()).toBe("");
-    expect(getPlatformOrganizationId()).toBe("");
-    expect(getPlatformUserId()).toBe("");
+    expect(getPlatformAssistantId()).toBe(ASSISTANT_ID);
   });
 });

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

@@ -13,17 +13,15 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     ]);
   });
 
-  test("claude profile uses the @agentclientprotocol adapter binary on opus", () => {
+  test("claude profile uses the @agentclientprotocol adapter binary", () => {
     expect(DEFAULT_ACP_AGENT_PROFILES.claude).toEqual({
       command: "claude-agent-acp",
       args: [],
       description: "Claude Code (via @agentclientprotocol/claude-agent-acp)",
-      model: "opus",
     });
   });
 
   test("codex profile uses the @agentclientprotocol adapter binary", () => {
-    // No model: Codex aliases are its own, so the adapter's default stands.
     expect(DEFAULT_ACP_AGENT_PROFILES.codex).toEqual({
       command: "codex-acp",
       args: [],
@@ -46,19 +44,11 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
 describe("DEFAULT_AGENT_NPM_PACKAGES", () => {
   test("is keyed by command name with the canonical npm package", () => {
     expect(DEFAULT_AGENT_NPM_PACKAGES).toEqual({
-      "claude-agent-acp": "@agentclientprotocol/claude-agent-acp@0.75.1",
-      "codex-acp": "@agentclientprotocol/codex-acp@1.10.0",
+      "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
+      "codex-acp": "@agentclientprotocol/codex-acp",
     });
   });
 
-  test("every package spec pins an exact version", () => {
-    // A bare name would let a clean install resolve whatever npm calls
-    // latest, which is what the repo's pinning rule exists to prevent.
-    for (const spec of Object.values(DEFAULT_AGENT_NPM_PACKAGES)) {
-      expect(spec).toMatch(/^@?[^@]+@\d+\.\d+\.\d+$/);
-    }
-  });
-
   test("every default profile's command has a matching npm package", () => {
     for (const profile of Object.values(DEFAULT_ACP_AGENT_PROFILES)) {
       expect(DEFAULT_AGENT_NPM_PACKAGES[profile.command]).toBeDefined();

package/src/config/acp-defaults.ts

@@ -1,11 +1,5 @@
 import type { AcpAgentConfig } from "./acp-schema.js";
 
-/**
- * A bundled profile always names its command; a user entry for the same id
- * may omit `command` and inherit this one.
- */
-export type AcpAgentProfile = AcpAgentConfig & { command: string };
-
 // 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
@@ -19,22 +13,17 @@ const FROZEN_EMPTY_ARGS = Object.freeze([] as string[]) as unknown as string[];
  * falls back to this map so common agents like `claude` and `codex` Just Work
  * without requiring per-user config.
  *
- * A profile's `model` is the model a session of that agent starts on when the
- * ask names none, and is the rung `acp.agents.<id>.model` fills: a user config
- * entry that names a model overrides it, one that omits it inherits it.
- *
- * Keyed by agent id. Deeply frozen: the outer object, each profile, and the
- * `args` arrays, so mutation throws in strict mode rather than silently
+ * 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, AcpAgentProfile>
+  Record<string, AcpAgentConfig>
 > = Object.freeze({
   claude: Object.freeze({
     command: "claude-agent-acp",
     args: FROZEN_EMPTY_ARGS,
     description: "Claude Code (via @agentclientprotocol/claude-agent-acp)",
-    model: "opus",
   }),
   codex: Object.freeze({
     command: "codex-acp",
@@ -44,21 +33,15 @@ export const DEFAULT_ACP_AGENT_PROFILES: Readonly<
 });
 
 /**
- * Single source of truth for adapter binary → npm package spec. Automatic
+ * Single source of truth for adapter binary → npm package name. Automatic
  * installation and the resolver's install hints use this map, so a new
  * adapter only needs one entry here.
  *
  * Keyed by command name (not agent id) so the mapping follows the binary
  * regardless of how a user's config aliases an agent.
- *
- * Values carry an exact version, so a clean install lands the adapter version
- * the daemon was tested against instead of whatever npm calls latest today.
- * An adapter already on PATH is left alone: installation runs only when
- * preflight found no binary at all, so this never moves a version the user
- * installed themselves.
  */
 export const DEFAULT_AGENT_NPM_PACKAGES: Readonly<Record<string, string>> =
   Object.freeze({
-    "claude-agent-acp": "@agentclientprotocol/claude-agent-acp@0.75.1",
-    "codex-acp": "@agentclientprotocol/codex-acp@1.10.0",
+    "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
+    "codex-acp": "@agentclientprotocol/codex-acp",
   });

package/src/config/acp-schema.ts

@@ -1,15 +1,8 @@
 import { z } from "zod";
 
-import { DEFAULT_ACP_AGENT_PROFILES } from "./acp-defaults.js";
-
-export const AcpAgentConfigSchema = z
+const AcpAgentConfigSchema = z
   .object({
-    command: z
-      .string()
-      .optional()
-      .describe(
-        "Command to spawn the ACP agent process. Required unless the id has a bundled profile, whose command is inherited when this is unset",
-      ),
+    command: z.string().describe("Command to spawn the ACP agent process"),
     args: z
       .array(z.string())
       .default([])
@@ -22,12 +15,6 @@ export const AcpAgentConfigSchema = z
       .record(z.string(), z.string())
       .optional()
       .describe("Environment variables set for the agent process"),
-    model: z
-      .string()
-      .optional()
-      .describe(
-        "Model sessions of this agent start on when the ask names none (an adapter-reported alias such as 'opus' or 'sonnet' for Claude, not an Assistant catalog id). Overrides the bundled profile's value; unset inherits it.",
-      ),
   })
   .describe("Configuration for an individual ACP agent");
 
@@ -43,21 +30,6 @@ export const AcpConfigSchema = z
       ),
     agents: z
       .record(z.string(), AcpAgentConfigSchema)
-      .superRefine((agents, ctx) => {
-        for (const [id, agent] of Object.entries(agents)) {
-          if (
-            agent.command !== undefined ||
-            Object.hasOwn(DEFAULT_ACP_AGENT_PROFILES, id)
-          ) {
-            continue;
-          }
-          ctx.addIssue({
-            code: "custom",
-            path: [id, "command"],
-            message: `acp.agents.${id} needs a command: only the bundled ids (${Object.keys(DEFAULT_ACP_AGENT_PROFILES).join(", ")}) inherit one`,
-          });
-        }
-      })
       .default({})
       .describe("Map of agent names to their configurations"),
   })

package/src/config/bundled-skills/acp/SKILL.md

@@ -23,18 +23,6 @@ Use `acp_spawn` to delegate a coding task to an external agent. The agent runs a
 
 Users can refer to agents by natural names: "claude code", "codex cli", and "openai codex" all resolve to the canonical `claude` and `codex` ids (unless the user's config defines an agent literally keyed by that name, which always wins).
 
-## Choosing a model
-
-Claude runs on Opus unless the user names a model; every other agent starts on its own default.
-
-When the user does name one, pass it as `model` on `acp_spawn`. Model names are the agent's own vocabulary, not Assistant model ids: an alias such as `default`, `sonnet`, `opus`, `haiku`, `fable`, or `opusplan` for Claude, or a full model id. Pass what the user said and let the agent resolve it.
-
-The spawn result reports `requestedModel` and `effectiveModel`. Treat `effectiveModel` as authoritative for the top-level ACP session. Never infer that model from the task text or from a nested subagent. When `requestedModel` is non-null and differs from `effectiveModel`, state which model the session is actually running on and relay `modelWarning` when present.
-
-If the agent refuses the model, or advertises no model selector, the spawn result says so: relay it in one sentence and carry on, because the session is live on the agent's own model.
-
-A session runs on the model it started on, so a different model means a new `acp_spawn`. A standing default per agent lives in the config at `acp.agents.<id>.model`.
-
 ## When the user names Claude Code or Codex
 
 If they name Claude Code or Codex without asking you to run it here (for example they say that tool will do the work), offer once, in one short sentence, that you can connect and run it in this conversation. Then continue with whatever they were doing.
@@ -47,23 +35,21 @@ If they name Claude Code or Codex without asking you to run it here (for example
 
 ACP is always available - default profiles for `claude` and `codex` ship out-of-box, so no config edit is needed to start. First-time setup is just making the adapter binary available, then spawning:
 
-1. Install the adapter binary if it's missing. This happens automatically: when `acp_spawn` finds the agent's binary missing from PATH, the assistant installs the pinned version via a sandboxed bun global install and proceeds in the same call (see "Automatic adapter availability" below).
+1. Install the adapter binary if it's missing. This happens automatically: when `acp_spawn` finds the agent's binary missing from PATH, the assistant installs it once via a sandboxed bun global install and proceeds in the same call (see "Automatic adapter availability" below).
 
 2. Call `acp_spawn`. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
 
 ## Automatic adapter availability
 
-When an agent's binary is missing from PATH, the assistant installs the adapter version it was built against via a sandboxed bun global install and then runs the real installed binary. The install runs in a fresh empty temporary directory (never the task's project directory), with known secrets stripped from the installer environment and the registry pinned to the public npm registry, so a malicious project directory cannot hijack package resolution or capture a token.
-
-An adapter already on PATH is left alone, whoever installed it: the install runs only when preflight found no binary at all.
+When `acp_spawn` finds the agent's binary missing from PATH, the assistant installs it once via a sandboxed bun global install and then runs the real installed binary. The install runs in a fresh empty temporary directory (never the task's project directory), with known secrets stripped from the installer environment and the registry pinned to the public npm registry, so a malicious project directory cannot hijack package resolution or capture a token. After this one-time install, the adapter is a normal trusted binary on PATH and every later spawn (and resume) uses it directly.
 
 Only the allowlisted out-of-box packages are ever installed this way (`@agentclientprotocol/claude-agent-acp`, `@agentclientprotocol/codex-acp`); user-configured agents with custom commands are never installed automatically.
 
-Manual installation is fallback guidance for unusual setups: bun unavailable, restricted global installs, or an auto-install failure (the failure reason is surfaced in the tool result). Install the pinned version below rather than `@latest`, so the adapter matches what the assistant was built against.
+Manual installation is fallback guidance for unusual setups: bun unavailable, restricted global installs, or an auto-install failure (the failure reason is surfaced in the tool result).
 
 ```bash
-bun add -g @agentclientprotocol/claude-agent-acp@0.75.1   # claude
-bun add -g @agentclientprotocol/codex-acp@1.10.0          # codex
+bun add -g @agentclientprotocol/claude-agent-acp   # claude
+bun add -g @agentclientprotocol/codex-acp          # codex
 ```
 
 ## Claude setup
@@ -98,14 +84,20 @@ Do NOT put API keys (or any secret) in the workspace config file - secrets never
 
 - Two agents are supported out-of-box: `claude` (via the `claude-agent-acp` adapter) and `codex` (via the `codex-acp` adapter).
 - NEVER use `claude`, `claude -p`, `claude --acp`, or the bare `codex` CLI as the ACP `command`. Claude and Codex only speak the protocol through their dedicated `*-acp` adapters.
-- Default profiles for both ship out-of-box. Users only need an `agents.<id>` entry in config if they want to override the defaults (e.g. point to a custom binary path or pass extra args/env). An entry that still runs the bundled adapter, whether it omits `command` or names the same binary by name or full path, inherits the `command`, `description` and `model` it leaves out, so a single-field change such as `acp.agents.claude.model` is all it takes. An entry that points the id at a different binary stands on its own, so it must spell out everything it needs, `command` included.
+- Default profiles for both ship out-of-box. Users only need an `agents.<id>` entry in config if they want to override the defaults (e.g. point to a custom binary path or pass extra args/env). An `acp.agents.<id>` entry replaces the bundled default entirely (no field merge), so any override must spell out the full `command` and `args`, not just the field being changed.
 - NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp` or `codex-acp`, leave it alone.
 
 ## Updating an adapter
 
-Adapter upgrades ship with Assistant releases: the pinned version is what a missing adapter is installed at. An adapter already on PATH is never replaced, so a user who upgrades one themselves keeps that version.
+Adapters are installed automatically when missing. To update an installed adapter, ask the user first and use its owning package manager. For bun installations:
+
+```bash
+bun add -g @agentclientprotocol/claude-agent-acp@latest
+# or
+bun add -g @agentclientprotocol/codex-acp@latest
+```
 
-Codex uses the adapter's bundled dependency by default, within the version range declared by the adapter. If `CODEX_PATH` selects a separate CLI, update that installation separately.
+Codex uses the adapter's bundled dependency by default, within the version range declared by the adapter. If `CODEX_PATH` selects a separate CLI, update that installation separately. Verify the required model with a fresh `acp_spawn` call after updating.
 
 ## When to use acp_steer vs acp_spawn
 

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

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "acp_spawn",
-      "description": "Spawn an external coding agent (e.g. Claude Code, Codex) via ACP to work on a task. Default profiles ship for `claude` (`claude-agent-acp`) and `codex` (`codex-acp`); the assistant resolves the agent id to the right binary. The result reports `requestedModel` and the adapter-reported `effectiveModel`; treat `effectiveModel` as authoritative for the top-level ACP session. The agent runs as a subprocess and streams results back. Use this when you want to delegate a coding task to an external agent that has its own tools, file editing, and terminal access. If a default agent's binary is missing, the assistant installs it once via a sandboxed bun global install and proceeds in the same call; if that fails (e.g. bun unavailable), an actionable install hint is returned - do NOT alter `agents.<id>.command` to swap binaries.",
+      "description": "Spawn an external coding agent (e.g. Claude Code, Codex) via ACP to work on a task. Default profiles ship for `claude` (`claude-agent-acp`) and `codex` (`codex-acp`); the assistant resolves the agent id to the right binary. The agent runs as a subprocess and streams results back. Use this when you want to delegate a coding task to an external agent that has its own tools, file editing, and terminal access. If a default agent's binary is missing, the assistant installs it once via a sandboxed bun global install and proceeds in the same call; if that fails (e.g. bun unavailable), an actionable install hint is returned - do NOT alter `agents.<id>.command` to swap binaries.",
       "category": "orchestration",
       "risk": "high",
       "input_schema": {
@@ -20,10 +20,6 @@
           "cwd": {
             "type": "string",
             "description": "Working directory for the agent. This determines where the agent runs and where its session is stored. Set this to the project/repo root the user wants the agent to work in. Defaults to current conversation's working directory."
-          },
-          "model": {
-            "type": "string",
-            "description": "Model the agent should run on, passed ONLY when the user named one (e.g. 'opus' for Claude). Left off, a Claude session runs on Opus and every other agent on its own default. If the agent refuses the value, or advertises no model selector, the result says so and the session runs on its own model."
           }
         },
         "required": ["task"]

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

@@ -60,7 +60,7 @@ Apps live under `/workspace/data/apps/`:
   <slug>.json          # App metadata
   <slug>/
     src/               # Source files (TSX) — what you write
-    dist/              # Compiled output, generated by app_refresh or assistant apps refresh
+    dist/              # Compiled output — auto-generated by app_refresh
     records/           # Data records (one JSON file per record)
   <slug>.preview       # Preview image (auto-generated)
 ```
@@ -156,9 +156,9 @@ Calculators, single-page tools, landing pages, and slide decks skip this — pas
 
 ### 3 — Create the app (scaffold, then expand)
 
-⚠️ **`app_create` is ONE-SHOT per build.** Call it exactly once. After it returns an `app_id`, all further changes go through `file_write` / `file_edit` and a single compile (`assistant apps refresh` or `app_refresh`). To start over: `app_delete(app_id)` first, then a fresh `app_create`.
+⚠️ **`app_create` is ONE-SHOT per build.** Call it exactly once. After it returns an `app_id`, all further changes go through `file_write` / `file_edit` + `app_refresh`. To start over: `app_delete(app_id)` first, then a fresh `app_create`.
 
-Apps are multi-file Preact + TSX projects; esbuild bundles when you compile. Structure:
+Apps are multi-file Preact + TSX projects; esbuild bundles automatically. Structure:
 
 ```
 src/
@@ -179,9 +179,9 @@ render(<App />, document.getElementById("app")!);
 
 1. **`app_create`** with a **4-file scaffold**: `src/index.html`, `src/main.tsx`, a **placeholder** `src/components/App.tsx` (`<div>Loading...</div>`), and an **empty** `src/styles.css`. The placeholders make the first compile clean — a 2-file scaffold leaves broken imports.
 2. **`file_write`** each real file, one per tool call, overwriting the placeholders and adding components.
-3. Compile ONCE at the end. File edits do not compile on their own. Use `assistant apps inspect <name>` to see whether source drifted, then `assistant apps refresh <name>` (or `app_refresh`).
+3. **`app_refresh`** ONCE at the end to compile.
 
-**Actually write the files.** Source code in reasoning/thinking is invisible to the app sandbox and is not a file write. Put every real file body in an `app_create.source_files`, `file_write`, `file_edit`, or `app_update.source_files` tool call, then verify the files exist before compiling when there is any doubt.
+**Actually write the files.** Source code in reasoning/thinking is invisible to the app sandbox and is not a file write. Put every real file body in an `app_create.source_files`, `file_write`, `file_edit`, or `app_update.source_files` tool call, then verify the files exist before `app_refresh` when there is any doubt.
 
 **Allowed packages** (esbuild-resolved, no CDN): `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`. For icons, write inline `<svg>` markup directly — no icon package is bundled.
 
@@ -221,14 +221,11 @@ app_create({                         app_create({
 
 ### 4 — Compile
 
-File edits do not compile on their own. After ALL file writes, compile once:
-
 ```
-assistant apps inspect <name>
-assistant apps refresh <name>
+app_refresh(app_id)
 ```
 
-`assistant apps inspect` reports whether source changed since the last compile. `assistant apps refresh` compiles and refreshes open surfaces. `app_refresh(app_id)` also compiles. If compile fails, the response has error details; fix with `file_edit`, then compile again.
+Call it ONCE, after ALL file writes — batching is required. If it fails, the response has error details; fix with `file_edit`, then `app_refresh` again.
 
 ### 5 — Show the preview card
 
@@ -247,7 +244,7 @@ Editing an existing app means reusing its `app_id` — never `app_create`. Resol
 - **`app_update`** — rename or change description/schema, and/or rewrite files via `source_files`, in one call. It recompiles for you, so no separate `app_refresh` is needed. Use this instead of editing `<slug>.json` by hand.
 - **Full rebrand** — still iteration, edit the existing files.
 
-Then compile ONCE (`assistant apps refresh <name>` or `app_refresh(app_id)`) unless you used `app_update`, which already recompiled. If the change is substantial, `app_open(app_id, open_mode: "preview")` for a fresh card; for small tweaks the existing card stays valid.
+Then `app_refresh(app_id)` ONCE (unless you used `app_update`, which already recompiled). If the change is substantial, `app_open(app_id, open_mode: "preview")` for a fresh card; for small tweaks the existing card stays valid.
 
 > ⚠️ **`skill_load("app-builder")` is required before every `app_*` call** (including the first `app_create`). The skill can auto-unload between turns; without the reload, `app_refresh` / `app_open` error with "not currently active." It's idempotent — call it every time.
 
@@ -353,7 +350,7 @@ Slide decks are a different domain — skip app patterns (contextual headers, se
 ## SKILL COMPLETE WHEN
 
 - [ ] Request was scoped: personal build (sandbox) or complex/shippable (handed off to a project folder + coding agent)
-- [ ] **Sandbox path:** `app_create` returned an `app_id`; all files written via `file_write`; compile ran ONCE clean (`assistant apps refresh` or `app_refresh`); `app_open(open_mode: "preview")` rendered the card; user told what was built (3-6 bullets); iterations reflected live
+- [ ] **Sandbox path:** `app_create` returned an `app_id`; all files written via `file_write`; `app_refresh` ran ONCE clean; `app_open(open_mode: "preview")` rendered the card; user told what was built (3-6 bullets); iterations reflected live
 - [ ] **Handoff path:** project folder established; coding agent spawned via `acp_spawn({ task, cwd })`; user told work continues in the folder
 
 ---

package/src/config/bundled-skills/app-builder/references/CUSTOM_ROUTES.md

@@ -143,7 +143,7 @@ Older routes were written with a second `context` argument (`context.assistantEv
 
 ## Key rules
 
-- Always create the route handler files via `file_write` before compiling (`app_refresh` or `assistant apps refresh`)
+- Always create the route handler files via `file_write` before calling `app_refresh`
 - Export an optional `description` string for CLI discoverability (`assistant routes list`)
 - Handlers have full Node.js API access — `fs`, `path`, `crypto`, etc.
 - Handlers get a 30-second timeout per request

package/src/config/bundled-skills/messaging/SKILL.md

@@ -14,7 +14,7 @@ metadata:
 
 You are a unified messaging assistant with access to multiple platforms (Gmail, Outlook, Telegram, and more). Use the messaging tools to help users read, search, organize, draft, and send messages across all connected platforms.
 
-**On a channel, `messaging_send` posts through the channel's own transport.** Slack, Telegram, Discord, and WhatsApp all go out that way: threaded where you name a `thread_id`, rendered the way a reply is, and recorded in the chat's conversation once the channel acknowledges the post. Reading and searching Slack are not part of this skill; load the **slack** skill, which uses the Slack Web API for those.
+**Slack is not handled by this skill.** Slack messaging (send, read, search) is handled by the **slack** skill, which uses the Slack Web API directly via CLI. Do not use messaging tools with `platform: "slack"`.
 
 ## External Identity
 
@@ -34,7 +34,7 @@ When a platform is connected (auth test succeeds), always use the messaging API
 
 On Gmail and Outlook, `messaging_send` creates a real mailbox draft for review. It does not send. Recipients are optional on Outlook: if the user has not named a To address, still create the draft (use a non-email `conversation_id` such as `drafts`) and tell them only after the tool returns a draft ID. If draft creation fails or is interrupted, say so and offer the email copy in chat. Do not claim a draft exists until the tool succeeds.
 
-**On a channel, the send goes out as the assistant's own bot**, so `account` does not apply and is refused. It carries text only: attachments stay on Gmail and Outlook. The post is recorded in the chat's conversation, which is what lets `recall` find it later.
+**Exception: Slack.** Slack messaging should use the Slack Web API directly via CLI, not messaging tools. See the **slack** skill for details.
 
 ## Connection Setup
 
@@ -64,7 +64,7 @@ When the user asks to "connect my email", "set up email", "manage my email", or
 
 ### Slack
 
-For Slack setup, load the **slack-app-setup** skill directly. `messaging_send` posts to a Slack chat through the channel's transport. Reading, searching, reactions, and file upload live in the **slack** skill, which uses the Slack Web API.
+Slack is **not** handled by this skill. For Slack setup, load the **slack-app-setup** skill directly. For Slack messaging, use the **slack** skill which accesses the Slack Web API via CLI.
 
 ### Telegram
 

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

@@ -125,7 +125,7 @@
     },
     {
       "name": "messaging_send",
-      "description": "Send a message, reply to a thread, or create a draft. On Gmail and Outlook, always creates a real mailbox draft for review (recipients optional on Outlook). On a channel (Slack, Telegram, Discord, WhatsApp) the message goes out as the channel's own bot, threaded when thread_id names a thread. Supports replies (via thread_id) and attachments (via attachment_paths, Gmail and Outlook).",
+      "description": "Send a message, reply to a thread, or create a draft. On Gmail and Outlook, always creates a real mailbox draft for review (recipients optional on Outlook). Supports replies (via thread_id), attachments (via attachment_paths, Gmail and Outlook), and all messaging platforms.",
       "category": "messaging",
       "risk": "high",
       "input_schema": {
@@ -133,11 +133,11 @@
         "properties": {
           "platform": {
             "type": "string",
-            "description": "Platform (e.g. \"gmail\", \"slack\", \"telegram\", \"discord\"). Auto-detected if only one is connected."
+            "description": "Platform (e.g. \"gmail\"). Auto-detected if only one is connected. Slack is not supported — use the Slack Web API directly."
           },
           "account": {
             "type": "string",
-            "description": "Email address of the account to use. Required when multiple accounts are connected for the same email platform. If omitted, uses the most recently connected account. Does not apply to a channel: a channel send goes out as the channel's own bot."
+            "description": "Email address of the account to use. Required when multiple accounts are connected for the same platform. If omitted, uses the most recently connected account."
           },
           "conversation_id": {
             "type": "string",