@vellumai/assistant 0.6.0 → 0.6.1

package/src/config/bundled-skills/settings/tools/avatar-update.ts

@@ -9,14 +9,17 @@ import type {
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 import { getLogger } from "../../../../util/logger.js";
-import { getWorkspaceDir } from "../../../../util/platform.js";
+import {
+  getAvatarImagePath,
+  getWorkspaceDir,
+} from "../../../../util/platform.js";
 import { updateIdentityAvatarSection } from "./identity-avatar.js";
 
 const log = getLogger("avatar-update");
 
 /** Canonical path where the custom avatar PNG is stored. */
 function getAvatarPath(): string {
-  return join(getWorkspaceDir(), "data", "avatar", "avatar-image.png");
+  return getAvatarImagePath();
 }
 
 export async function run(

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

@@ -68,6 +68,8 @@ When you need to send a DM or look up a Slack user by name, check contacts first
 
 1. **Before calling `users.list`**: Use `contact_search` with `query: "<name>"` and `channel_type: "slack"`. If a matching contact has `externalUserId` (Slack user ID) and `externalChatId` (DM channel ID), skip the API lookups and use those IDs directly with `chat.postMessage`.
 
+   When `contact_search` returns notes for the recipient, use them to inform the message's tone, formality, and content. Contact notes capture relationship context and communication preferences that should shape how you write to this person.
+
 2. **After resolving via API**: When you had to call `users.list` or `conversations.open` to resolve a user, save the contact with `contact_upsert` so you can find them by name next time. External Slack IDs (user ID, DM channel ID) are cached automatically by the messaging layer and should not be passed through `contact_upsert`.
 
 ## Privacy Rules

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

@@ -6,6 +6,9 @@ metadata:
   emoji: "🤖"
   vellum:
     display-name: "Subagent"
+    activation-hints:
+      - "Run tasks in parallel, delegate work to background agents, or do multiple things at once"
+      - "Spawn a researcher, coder, or planner agent for independent work"
 ---
 
 Subagent orchestration -- spawn background agents to work on tasks in parallel.
@@ -14,9 +17,43 @@ Subagent orchestration -- spawn background agents to work on tasks in parallel.
 
 Subagents follow this status flow: `pending` -> `running` -> `completed` / `failed` / `aborted`
 
-- **Spawn**: Use `subagent_spawn` with a label and objective. The subagent runs autonomously.
-- **Auto-notification**: The parent conversation is automatically notified when a subagent reaches a terminal status. Do NOT poll `subagent_status`.
-- **Read output**: Use `subagent_read` only after the subagent reaches a terminal status (completed/failed/aborted).
+- **Spawn**: Use `subagent_spawn` with a label, objective, and role. The subagent runs autonomously.
+- **Mid-run communication**: Subagents can send notifications to the parent via `notify_parent` while still running -- useful for sharing interim findings or signaling that they are blocked.
+- **Auto-notification**: The parent conversation is automatically notified when a subagent reaches a terminal status (completed/failed/aborted). Do NOT poll `subagent_status`.
+- **Read output**: Use `subagent_read` after the subagent reaches a terminal status to retrieve its full output.
+
+## Roles
+
+Each subagent is spawned with a role that determines its tool access. Choose the most restrictive role that can accomplish the task.
+
+| Role | Tools | When to use |
+|---|---|---|
+| `general` | Full tool access | Task genuinely needs unrestricted capabilities (rare -- prefer a specialized role) |
+| `researcher` | `web_search`, `web_fetch`, `file_read`, `file_list`, `recall`, `notify_parent` | Information gathering, web research, codebase exploration, reading documentation |
+| `coder` | `bash`, `file_read`, `file_write`, `file_edit`, `web_search`, `recall`, `notify_parent` | Code changes, file editing, running commands, build/test tasks |
+| `planner` | `file_read`, `file_list`, `web_search`, `web_fetch`, `recall`, `notify_parent` | Analysis, planning, synthesizing information, reviewing approaches |
+
+All specialized roles (`researcher`, `coder`, `planner`) include `notify_parent` for mid-run communication with the parent.
+
+## Parent Communication
+
+Subagents use `notify_parent` to send messages to the parent conversation while still running. Each notification has an urgency level:
+
+- **`info`** -- Progress updates, minor findings. The parent is informed but does not need to act.
+- **`important`** -- Key findings, significant results. The parent should review when convenient.
+- **`blocked`** -- The subagent needs guidance or a decision from the parent to continue.
+
+Use notifications judiciously -- one per major finding or milestone. Do not send a notification for every small step.
+
+## Naming
+
+Subagents can be referenced by label instead of UUID. The `label` parameter is accepted on `subagent_message`, `subagent_status`, `subagent_read`, and `subagent_abort` as an alternative to `subagent_id`. Label lookup is case-insensitive.
+
+Use descriptive labels when spawning subagents (e.g., "research-auth-libraries", "implement-login-form") so they are easy to reference later.
+
+## Reading Output
+
+`subagent_read` returns the subagent's assistant text output. Use the `last_n` parameter to retrieve only the most recent N assistant messages instead of the full history. This is useful for large outputs where you only need the final result.
 
 ## Ownership
 
@@ -29,5 +66,8 @@ Set `send_result_to_user: false` when spawning a subagent whose result is for in
 ## Tips
 
 - Do NOT poll `subagent_status` in a loop. You will be notified automatically when a subagent completes.
+- Use roles to scope tool access and minimize blast radius. Default to the most restrictive role that works.
+- Spawn a `researcher` and `coder` in parallel for research-then-implement workflows -- the researcher gathers context while the coder starts on the known parts.
+- Use `notify_parent` for interim findings instead of waiting for completion. This lets the parent act on partial results early.
 - Use `subagent_message` to send follow-up instructions to a running subagent.
 - Use `subagent_abort` to cancel a subagent that is no longer needed.

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

@@ -25,6 +25,11 @@
             "type": "boolean",
             "description": "Whether to present the subagent's result to the user when it completes. Defaults to true. Set to false for internal/silent processing."
           },
+          "role": {
+            "type": "string",
+            "enum": ["general", "researcher", "coder", "planner"],
+            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'general': full access (default)."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -47,6 +52,10 @@
             "type": "string",
             "description": "Optional subagent ID to query. If omitted, returns all subagents for this conversation."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -59,7 +68,7 @@
     },
     {
       "name": "subagent_abort",
-      "description": "Abort a running subagent by ID.",
+      "description": "Abort a running subagent by ID or label.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -69,12 +78,16 @@
             "type": "string",
             "description": "The ID of the subagent to abort."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["subagent_id"]
+        "required": []
       },
       "executor": "tools/subagent-abort.ts",
       "execution_target": "host"
@@ -91,6 +104,10 @@
             "type": "string",
             "description": "The ID of the subagent to send a message to."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
           "content": {
             "type": "string",
             "description": "The message content to send to the subagent."
@@ -100,7 +117,7 @@
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["subagent_id", "content"]
+        "required": ["content"]
       },
       "executor": "tools/subagent-message.ts",
       "execution_target": "host"
@@ -117,12 +134,20 @@
             "type": "string",
             "description": "The ID of the subagent whose output to read."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
+          "last_n": {
+            "type": "integer",
+            "description": "Number of recent assistant messages to return. Omit to return all messages (current behavior)."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["subagent_id"]
+        "required": []
       },
       "executor": "tools/subagent-read.ts",
       "execution_target": "host"

package/src/config/env-registry.ts

@@ -24,6 +24,13 @@ function flag(name: string): boolean {
   return raw === "true" || raw === "1";
 }
 
+function int(name: string): number | undefined {
+  const raw = str(name);
+  if (raw === undefined) return undefined;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
 // ── Registry ─────────────────────────────────────────────────────────────────
 // Each entry documents the env var name, type, default, and purpose.
 
@@ -74,6 +81,57 @@ export function getWorkspaceDirOverride(): string | undefined {
   return str("VELLUM_WORKSPACE_DIR");
 }
 
+// ── Profiler env vars ───────────────────────────────────────────────────
+// These are injected by the platform when running a managed assistant in
+// profiler mode. The runtime uses them to locate, scope, and budget-limit
+// profiler output on the workspace volume.
+
+/**
+ * VELLUM_PROFILER_RUN_ID — string, default: undefined
+ * Unique identifier for the current profiler run. When set, the profiler
+ * run store treats this run as "active" and will never prune its directory.
+ */
+export function getProfilerRunId(): string | undefined {
+  return str("VELLUM_PROFILER_RUN_ID");
+}
+
+/**
+ * VELLUM_PROFILER_MODE — string, default: undefined
+ * The profiling mode to activate (e.g. "cpu", "heap", "cpu+heap").
+ * When unset, profiling is disabled.
+ */
+export function getProfilerMode(): string | undefined {
+  return str("VELLUM_PROFILER_MODE");
+}
+
+/**
+ * VELLUM_PROFILER_MAX_BYTES — integer, default: undefined
+ * Maximum total bytes retained across all profiler runs (including active).
+ * The startup sweep prunes oldest completed runs to stay within budget.
+ */
+export function getProfilerMaxBytes(): number | undefined {
+  return int("VELLUM_PROFILER_MAX_BYTES");
+}
+
+/**
+ * VELLUM_PROFILER_MAX_RUNS — integer, default: undefined
+ * Maximum number of completed profiler runs retained on disk.
+ * The startup sweep prunes oldest completed runs to stay within budget.
+ */
+export function getProfilerMaxRuns(): number | undefined {
+  return int("VELLUM_PROFILER_MAX_RUNS");
+}
+
+/**
+ * VELLUM_PROFILER_MIN_FREE_MB — integer, default: undefined
+ * Minimum free disk space (in megabytes) that must remain after profiler
+ * runs are accounted for. The startup sweep prunes oldest completed runs
+ * until at least this much free space is available.
+ */
+export function getProfilerMinFreeMb(): number | undefined {
+  return int("VELLUM_PROFILER_MIN_FREE_MB");
+}
+
 // ── Known env var names ──────────────────────────────────────────────────────
 
 /**
@@ -97,6 +155,11 @@ const KNOWN_VELLUM_VARS = new Set([
   "VELLUM_HOOK_SETTINGS",
   "VELLUM_LOCKFILE_DIR",
   "VELLUM_PLATFORM_URL",
+  "VELLUM_PROFILER_MAX_BYTES",
+  "VELLUM_PROFILER_MAX_RUNS",
+  "VELLUM_PROFILER_MIN_FREE_MB",
+  "VELLUM_PROFILER_MODE",
+  "VELLUM_PROFILER_RUN_ID",
   "VELLUM_ROOT_DIR",
   "VELLUM_SSH_USER",
   "VELLUM_UNSAFE_AUTH_BYPASS",

package/src/config/feature-flag-registry.json

@@ -121,6 +121,14 @@
       "description": "Show the Billing tab in Settings when signed in, displaying credits balance and top-up",
       "defaultEnabled": true
     },
+    {
+      "id": "referral-codes",
+      "scope": "macos",
+      "key": "referral-codes",
+      "label": "Referral Codes",
+      "description": "Show the referral invite link and stats panel on the Billing tab in Settings",
+      "defaultEnabled": false
+    },
     {
       "id": "managed-sign-in",
       "scope": "macos",
@@ -199,7 +207,7 @@
       "key": "show-thinking-blocks",
       "label": "Show Thinking Blocks",
       "description": "Display the assistant's thinking/reasoning inline in chat messages as collapsible blocks",
-      "defaultEnabled": false
+      "defaultEnabled": true
     },
     {
       "id": "inline-skill-commands",
@@ -272,6 +280,14 @@
       "label": "Teleport",
       "description": "Enable teleport UI in General settings for moving assistants between hosting environments",
       "defaultEnabled": false
+    },
+    {
+      "id": "permission-controls-v2",
+      "scope": "assistant",
+      "key": "permission-controls-v2",
+      "label": "Permission Controls V2",
+      "description": "Replace risk-level permission system with two independent controls: 'Ask before acting' (LLM behavior toggle) and 'Host access' (system-enforced gate)",
+      "defaultEnabled": false
     }
   ]
 }

package/src/config/schema.ts

@@ -3,6 +3,11 @@ import { z } from "zod";
 import { getDataDir } from "../util/platform.js";
 
 // Re-export all domain schemas
+export type { PermissionMode } from "../permissions/permission-mode.js";
+export {
+  DEFAULT_PERMISSION_MODE,
+  PermissionModeSchema,
+} from "../permissions/permission-mode.js";
 export type { AcpAgentConfig, AcpConfig } from "./acp-schema.js";
 export { AcpAgentConfigSchema, AcpConfigSchema } from "./acp-schema.js";
 export type {
@@ -143,6 +148,7 @@ export type {
 export {
   PermissionsConfigSchema,
   SecretDetectionConfigSchema,
+  VALID_PERMISSIONS_MODES,
 } from "./schemas/security.js";
 export type {
   ImageGenerationService,
@@ -197,6 +203,7 @@ import {
   WhatsAppConfigSchema,
 } from "./schemas/channels.js";
 import { ElevenLabsConfigSchema } from "./schemas/elevenlabs.js";
+import { FilingConfigSchema } from "./schemas/filing.js";
 import { FishAudioConfigSchema } from "./schemas/fish-audio.js";
 import { HeartbeatConfigSchema } from "./schemas/heartbeat.js";
 import {
@@ -272,6 +279,7 @@ export const AssistantConfigSchema = z
       .describe(
         "Custom pricing overrides for specific provider/model combinations",
       ),
+    filing: FilingConfigSchema.default(FilingConfigSchema.parse({})),
     heartbeat: HeartbeatConfigSchema.default(HeartbeatConfigSchema.parse({})),
     journal: JournalConfigSchema.default(JournalConfigSchema.parse({})),
     mcp: McpConfigSchema.default(McpConfigSchema.parse({})),

package/src/config/schemas/filing.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+
+import { SpeedSchema } from "./inference.js";
+
+export const FilingConfigSchema = z
+  .object({
+    enabled: z
+      .boolean({ error: "filing.enabled must be a boolean" })
+      .default(true)
+      .describe(
+        "Whether periodic PKB filing is enabled — processes buffer.md into topic files and reviews knowledge base organization",
+      ),
+    intervalMs: z
+      .number({ error: "filing.intervalMs must be a number" })
+      .int("filing.intervalMs must be an integer")
+      .positive("filing.intervalMs must be a positive integer")
+      .default(4 * 3_600_000)
+      .describe("Time between filing runs in milliseconds"),
+    speed: SpeedSchema.default("standard").describe(
+      "Inference speed mode for filing conversations",
+    ),
+    activeHoursStart: z
+      .number({ error: "filing.activeHoursStart must be a number" })
+      .int("filing.activeHoursStart must be an integer")
+      .min(0, "filing.activeHoursStart must be >= 0")
+      .max(23, "filing.activeHoursStart must be <= 23")
+      .default(8)
+      .describe("Hour of the day (0-23) when filing runs begin"),
+    activeHoursEnd: z
+      .number({ error: "filing.activeHoursEnd must be a number" })
+      .int("filing.activeHoursEnd must be an integer")
+      .min(0, "filing.activeHoursEnd must be >= 0")
+      .max(23, "filing.activeHoursEnd must be <= 23")
+      .default(22)
+      .describe("Hour of the day (0-23) when filing runs stop"),
+  })
+  .describe(
+    "Periodic PKB (personal knowledge base) filing — processes the buffer into topic files and maintains knowledge organization",
+  )
+  .superRefine((config, ctx) => {
+    if (config.activeHoursStart === config.activeHoursEnd) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["activeHoursEnd"],
+        message:
+          "filing.activeHoursStart and filing.activeHoursEnd must not be equal (would create an empty window)",
+      });
+    }
+  });
+
+export type FilingConfig = z.infer<typeof FilingConfigSchema>;

package/src/config/schemas/heartbeat.ts

@@ -12,7 +12,7 @@ export const HeartbeatConfigSchema = z
       .number({ error: "heartbeat.intervalMs must be a number" })
       .int("heartbeat.intervalMs must be an integer")
       .positive("heartbeat.intervalMs must be a positive integer")
-      .default(3_600_000)
+      .default(6 * 3_600_000)
       .describe("Time between heartbeat checks in milliseconds"),
     speed: SpeedSchema.default("standard").describe(
       "Inference speed mode for heartbeat conversations — defaults to standard to avoid inheriting the global fast mode multiplier",
@@ -22,35 +22,38 @@ export const HeartbeatConfigSchema = z
       .int("heartbeat.activeHoursStart must be an integer")
       .min(0, "heartbeat.activeHoursStart must be >= 0")
       .max(23, "heartbeat.activeHoursStart must be <= 23")
-      .optional()
+      .nullable()
+      .default(8)
       .describe(
-        "Hour of the day (0-23) when heartbeat checks begin — must be set together with activeHoursEnd",
+        "Hour of the day (0-23) when heartbeat checks begin, or null to disable active hours restriction",
       ),
     activeHoursEnd: z
       .number({ error: "heartbeat.activeHoursEnd must be a number" })
       .int("heartbeat.activeHoursEnd must be an integer")
       .min(0, "heartbeat.activeHoursEnd must be >= 0")
       .max(23, "heartbeat.activeHoursEnd must be <= 23")
-      .optional()
+      .nullable()
+      .default(22)
       .describe(
-        "Hour of the day (0-23) when heartbeat checks stop — must be set together with activeHoursStart",
+        "Hour of the day (0-23) when heartbeat checks stop, or null to disable active hours restriction",
       ),
   })
   .describe("Periodic heartbeat configuration for health monitoring")
   .superRefine((config, ctx) => {
-    const hasStart = config.activeHoursStart != null;
-    const hasEnd = config.activeHoursEnd != null;
-    if (hasStart !== hasEnd) {
+    const startNull = config.activeHoursStart == null;
+    const endNull = config.activeHoursEnd == null;
+    if (startNull !== endNull) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        path: [hasStart ? "activeHoursEnd" : "activeHoursStart"],
+        path: [startNull ? "activeHoursStart" : "activeHoursEnd"],
         message:
-          "heartbeat.activeHoursStart and heartbeat.activeHoursEnd must both be set or both be omitted",
+          "heartbeat.activeHoursStart and heartbeat.activeHoursEnd must both be set or both be null",
       });
+      return;
     }
     if (
-      hasStart &&
-      hasEnd &&
+      config.activeHoursStart != null &&
+      config.activeHoursEnd != null &&
       config.activeHoursStart === config.activeHoursEnd
     ) {
       ctx.addIssue({

package/src/config/schemas/memory-lifecycle.ts

@@ -72,6 +72,18 @@ export const MemoryCleanupConfigSchema = z
       .describe(
         "Number of days to retain conversation data before cleanup (0 disables pruning)",
       ),
+    llmRequestLogRetentionMs: z
+      .number({
+        error: "memory.cleanup.llmRequestLogRetentionMs must be a number",
+      })
+      .int("memory.cleanup.llmRequestLogRetentionMs must be an integer")
+      .nonnegative(
+        "memory.cleanup.llmRequestLogRetentionMs must be non-negative",
+      )
+      .default(7 * 24 * 60 * 60 * 1000)
+      .describe(
+        "Retention period for LLM request/response logs in milliseconds (0 disables pruning)",
+      ),
   })
   .describe("Automatic memory cleanup and garbage collection settings");
 

package/src/config/schemas/security.ts

@@ -79,6 +79,20 @@ export const PermissionsConfigSchema = z
       .describe(
         "Permission mode — 'strict' requires explicit approval for all operations, 'workspace' allows operations within the workspace",
       ),
+    askBeforeActing: z
+      .boolean({
+        error: "permissions.askBeforeActing must be a boolean",
+      })
+      .default(true)
+      .describe("Whether the assistant should check in before taking actions"),
+    hostAccess: z
+      .boolean({
+        error: "permissions.hostAccess must be a boolean",
+      })
+      .default(false)
+      .describe(
+        "Whether the assistant can execute commands on the host machine without prompting",
+      ),
   })
   .describe("Permission enforcement mode for tool operations");
 

package/src/daemon/app-source-watcher.ts

@@ -0,0 +1,93 @@
+/**
+ * Filesystem watcher for app source directories.
+ *
+ * Watches the apps root directory recursively using fs.watch (FSEvents on
+ * macOS). When a source file changes, debounces per app ID and calls the
+ * provided callback so the server can recompile + refresh surfaces.
+ *
+ * This catches ALL modification sources (file_edit, file_write, bash, etc.)
+ * without relying on individual tool hooks.
+ */
+
+import { existsSync, type FSWatcher, watch } from "node:fs";
+
+import {
+  getAppsDir,
+  resolveAppIdByDirName,
+} from "../memory/app-store.js";
+import { DebouncerMap } from "../util/debounce.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("app-source-watcher");
+
+const APP_REFRESH_DEBOUNCE_MS = 500;
+
+export type AppSourceChangeCallback = (appId: string) => void;
+
+/**
+ * Resolve app ID from a relative path within the apps directory.
+ * Returns null if the path is not an app source file (e.g. dist/, records/).
+ */
+function resolveAppIdFromRelPath(relPath: string): string | null {
+  const slashIdx = relPath.indexOf("/");
+  if (slashIdx === -1) return null; // file directly in apps/ (e.g. .json definition)
+
+  const dirName = relPath.slice(0, slashIdx);
+  const innerPath = relPath.slice(slashIdx + 1);
+
+  // Skip non-source directories (include bare directory names for fs.watch events)
+  if (
+    innerPath === "records" || innerPath.startsWith("records/") ||
+    innerPath === "dist" || innerPath.startsWith("dist/")
+  ) {
+    return null;
+  }
+
+  return resolveAppIdByDirName(dirName);
+}
+
+export class AppSourceWatcher {
+  private watcher: FSWatcher | null = null;
+  private debouncer = new DebouncerMap({
+    defaultDelayMs: APP_REFRESH_DEBOUNCE_MS,
+    maxEntries: 50,
+  });
+
+  start(onChange: AppSourceChangeCallback): void {
+    let appsDir: string;
+    try {
+      appsDir = getAppsDir();
+    } catch {
+      log.warn("Could not resolve apps directory; app source watching disabled");
+      return;
+    }
+
+    if (!existsSync(appsDir)) {
+      log.info("Apps directory does not exist yet; skipping source watcher");
+      return;
+    }
+
+    try {
+      this.watcher = watch(appsDir, { recursive: true }, (_eventType, filename) => {
+        if (!filename) return;
+
+        const appId = resolveAppIdFromRelPath(filename);
+        if (!appId) return;
+
+        this.debouncer.schedule(`app:${appId}`, () => {
+          onChange(appId);
+        });
+      });
+    } catch (err) {
+      log.warn({ err }, "Failed to watch apps directory; source watching disabled");
+    }
+  }
+
+  stop(): void {
+    this.debouncer.cancelAll();
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+}