@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/tools/shared/filesystem/path-policy.ts

@@ -35,6 +35,26 @@ export function isDeniedBasename(path: string): boolean {
   return DENIED_BASENAMES.has(basename(path));
 }
 
+/**
+ * `/proc/<pid>/environ` for any pid, including the `self` and `thread-self`
+ * aliases. Reading one yields the target process's full environment.
+ */
+const PROC_ENVIRON_PATTERN = /^\/proc\/(?:\d+|self|thread-self)\/environ$/;
+
+/**
+ * Whether a path exposes a process environment block.
+ *
+ * The daemon's own environment carries credential material the file tools
+ * must never hand back: the actor token signing key, the CES service token,
+ * the guardian bootstrap secret, and any provider API keys forwarded in at
+ * launch. The bash tool strips those from the child processes it spawns via
+ * the `SAFE_ENV_VARS` allowlist, so denying them here keeps the file tools
+ * from becoming the looser path to the same secrets.
+ */
+export function isProcessEnvironPath(path: string): boolean {
+  return PROC_ENVIRON_PATTERN.test(path);
+}
+
 export type PathResult =
   | { ok: true; resolved: string }
   | { ok: false; reason: PathFailureReason; error: string };
@@ -186,6 +206,16 @@ function deniedFailure(target: SandboxTarget): PathResult | null {
       error: `Access to "${basename(target.resolved)}" is denied`,
     };
   }
+  if (
+    isProcessEnvironPath(target.resolved) ||
+    isProcessEnvironPath(target.realResolved)
+  ) {
+    return {
+      ok: false,
+      reason: "denied",
+      error: "Access to process environment blocks is denied",
+    };
+  }
   return null;
 }
 
@@ -336,8 +366,8 @@ export function sandboxPolicy(
 }
 
 /**
- * Sandbox policy that permits out-of-workspace targets on non-containerized
- * installs.
+ * Write-side sandbox policy: permits out-of-workspace targets on
+ * non-containerized installs.
  *
  * Identical to {@link sandboxPolicy} for in-bounds targets. A target that
  * escapes the boundary is allowed with host-style validation: the basename
@@ -348,9 +378,9 @@ export function sandboxPolicy(
  * FileRiskClassifier), so an escape reaching this policy has already been
  * threshold-approved or user-approved.
  *
- * In containerized mode the boundary stays hard: the container filesystem is
- * not the host, and the host_file_* proxy tools are the escape hatch for the
- * guardian's device.
+ * In containerized mode the boundary stays hard for writes: the container
+ * filesystem is the install tree the assistant runs from, and the
+ * host_file_* proxy tools are the escape hatch for the guardian's device.
  */
 export function sandboxPolicyWithHostFallback(
   rawPath: string,
@@ -365,6 +395,41 @@ export function sandboxPolicyWithHostFallback(
   );
 }
 
+/**
+ * Read-side sandbox policy: the working directory bounds where the assistant
+ * *writes*, not what it may look at.
+ *
+ * Everything the process can open, it may read. A containerized install owns
+ * its whole filesystem (the workspace, the install tree it runs from, `/tmp`),
+ * and `bash cat` already reads all of it at Low risk, so denying the file
+ * tools the same reach only pushes reads through a shell. A bare-metal install
+ * reaches the host filesystem, which the permission lane classifies as
+ * elevated risk before execution (see the gateway FileRiskClassifier). Either
+ * way the boundary is not what protects secrets.
+ *
+ * The denials are what protect secrets, and they apply to every read: the
+ * service security directories (gateway trust material, CES credential keys,
+ * the daemon dotenv), the basename denylist, and process environment blocks
+ * (see {@link isProcessEnvironPath}), each checked on both the logical and
+ * the symlink-resolved path. When that deny set cannot be mirrored faithfully
+ * (see {@link securityDirConfigMirrorable}), reads fail closed to the hard
+ * boundary rather than escape it unprotected.
+ *
+ * Write-side policies do not take this allowance.
+ */
+export function sandboxReadPolicy(
+  rawPath: string,
+  boundaryDir: string,
+  options?: { mustExist?: boolean },
+): PathResult {
+  return evaluateSandboxPolicy(
+    rawPath,
+    boundaryDir,
+    options,
+    securityDirConfigMirrorable(),
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Host policy
 // ---------------------------------------------------------------------------

package/src/tools/shared/filesystem/size-guard.ts

@@ -1,4 +1,4 @@
-import { statSync } from "node:fs";
+import { stat } from "node:fs/promises";
 
 /** Default maximum file size: 100 MB */
 export const MAX_FILE_SIZE_BYTES = 100 * 1024 * 1024;
@@ -17,13 +17,13 @@ function formatBytes(bytes: number): string {
  * Check whether a file on disk exceeds the size limit.
  * Returns an error string if the file is too large, or undefined if OK.
  */
-export function checkFileSizeOnDisk(
+export async function checkFileSizeOnDisk(
   filePath: string,
   limit: number = MAX_FILE_SIZE_BYTES,
-): string | undefined {
-  const stat = statSync(filePath);
-  if (stat.size > limit) {
-    return `File size (${formatBytes(stat.size)}) exceeds the ${formatBytes(
+): Promise<string | undefined> {
+  const fileStat = await stat(filePath);
+  if (fileStat.size > limit) {
+    return `File size (${formatBytes(fileStat.size)}) exceeds the ${formatBytes(
       limit,
     )} limit: ${filePath}`;
   }

package/src/tools/shared/input-misuse.ts

@@ -0,0 +1,72 @@
+/**
+ * Targeted guidance for tool calls whose parameter names reveal that the
+ * caller wanted a different tool, or a different spelling of a parameter this
+ * tool does accept.
+ *
+ * `validateInputAgainstSchema` rejects any key a tool's `TOOLS.json`
+ * `properties` block does not declare, and its generic `Unknown parameter
+ * "path". Supported: ...` error lists the accepted keys without naming the
+ * tool the caller actually wants. A tool listed here replaces that error with
+ * a redirect the caller can act on in a single retry. Declaring these keys in
+ * `properties` instead would advertise parameters the tool does not accept.
+ *
+ * Rules describe the first-party tools that ship in `bundled-skills/`, and tool
+ * names are not reserved: a managed, workspace, extra, or plugin skill may
+ * define its own `subagent_read` with an entirely different contract. The
+ * `bundled` prefix on the exports below is the reminder that callers must
+ * establish bundled provenance before consulting the table.
+ *
+ * Pure data plus a lookup, with no imports from tool executors, so both the
+ * skill-tool factory (`createSkillTool`, which validates before it reaches an
+ * executor) and the executors themselves can consult it.
+ */
+
+interface ToolInputMisuseRule {
+  /** Input keys that trigger this rule. Rules are matched in array order. */
+  keys: readonly string[];
+  /** Guidance returned in place of the generic validation error. */
+  message: string;
+}
+
+const MISUSE_RULES: Readonly<Record<string, readonly ToolInputMisuseRule[]>> = {
+  subagent_read: [
+    {
+      keys: ["path", "file", "filename"],
+      message:
+        "subagent_read returns a subagent's output, it does not read files. Use file_read for files. Pass subagent_id or label here.",
+    },
+    {
+      keys: ["subagentId", "agent_id"],
+      message: "Unknown parameter. Use subagent_id (snake_case) or label.",
+    },
+  ],
+};
+
+/**
+ * Return the redirect for a misused parameter shape on a bundled tool, or
+ * `undefined` when the tool has no rule for the keys present (the caller then
+ * falls back to its own error message).
+ *
+ * Only call this for a tool that came from a bundled skill. `toolName` alone
+ * does not establish that.
+ */
+export function bundledToolInputMisuseMessage(
+  toolName: string,
+  input: Record<string, unknown>,
+): string | undefined {
+  const rules = MISUSE_RULES[toolName];
+  if (!rules) {
+    return undefined;
+  }
+  for (const rule of rules) {
+    if (rule.keys.some((key) => key in input)) {
+      return rule.message;
+    }
+  }
+  return undefined;
+}
+
+/** Every key that carries a redirect for bundled `toolName`, for drift guards. */
+export function bundledToolInputMisuseKeys(toolName: string): string[] {
+  return (MISUSE_RULES[toolName] ?? []).flatMap((rule) => [...rule.keys]);
+}

package/src/tools/skills/scaffold-managed.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import type { SkillSource } from "../../config/skills.js";
 import { loadSkillCatalog } from "../../config/skills.js";
 import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
+import { emitNotificationSignal } from "../../notifications/emit-signal.js";
 import { getConversation } from "../../persistence/conversation-crud.js";
 import { upsertSkillCardInsertJob } from "../../persistence/jobs-store.js";
 import { MEMORY_RETROSPECTIVE_ORIGIN } from "../../plugins/defaults/memory/memory-retrospective-constants.js";
@@ -66,6 +67,72 @@ function normalizeOptionalStringArray(
   return { value: normalized.length > 0 ? normalized : undefined };
 }
 
+/**
+ * Tell the user that a background pass changed a skill they already have.
+ *
+ * A newly authored skill announces itself in the conversation through the
+ * `skill_card` surface; an update announces itself here instead. The pass
+ * runs in a background fork and rewrites the body of a skill the user may be
+ * relying on, and `createManagedSkill` writes through an atomic rename
+ * keeping no prior version, so the notification pipeline is what puts the
+ * change in the background feed alongside the other unattended work (sweeps,
+ * scheduled jobs, heartbeat), where a user already looks to see what the
+ * assistant did on its own.
+ *
+ * `sourceContextId` is a conversation id so the feed item's "Go to Convo"
+ * target resolves (see `home-feed-side-effect.ts`, which looks it up via
+ * `getConversation`): the source conversation when lineage resolved, else the
+ * run's own conversation. Deduped per skill per day, so a pass that refines
+ * the same skill repeatedly cannot flood the feed. Best-effort and
+ * non-blocking: the skill is already written, and a notification failure must
+ * never turn that into a tool error.
+ */
+function notifyBackgroundSkillUpdate(args: {
+  skillId: string;
+  name: string;
+  conversationId: string;
+}): void {
+  const day = new Date().toISOString().slice(0, 10);
+  void emitNotificationSignal({
+    // This emit is a tool executor's, not the scheduler's. The channel is
+    // provenance the pipeline reads: `home-feed-side-effect` derives
+    // `fromAssistant` from it, so labelling this "scheduler" would drop the
+    // item from the feed's assistant-initiated filter despite being exactly
+    // that.
+    sourceChannel: "assistant_tool",
+    sourceContextId: args.conversationId,
+    sourceEventName: "activity.complete",
+    dedupeKey: `skill-updated:${args.skillId}:${day}`,
+    contextPayload: {
+      // `summary` feeds the copy composer; `title`/`body` are the home feed's
+      // fallback when no channel copy was rendered. Without them a fully
+      // suppressed delivery (the intended shape for this signal: low urgency,
+      // background, no interruption) leaves the feed writer with no summary
+      // and it skips the item entirely, so the quiet case would surface
+      // nothing at all.
+      summary: `Updated the skill "${args.name}" from something learned in an earlier conversation.`,
+      // Named, not just "Skill updated": the feed sits several rows deep and
+      // a generic title is unscannable next to entries that name their
+      // subject (`Background job failed: memory.v2.sweep`). The word "Skill"
+      // stays because a bare skill name does not always read as one.
+      title: `Skill updated: ${args.name}`,
+      body: `Updated the skill "${args.name}" from something learned in an earlier conversation.`,
+      skillId: args.skillId,
+    },
+    attentionHints: {
+      requiresAction: false,
+      urgency: "low",
+      isAsyncBackground: true,
+      visibleInSourceNow: false,
+    },
+  }).catch((err: unknown) => {
+    log.warn(
+      { err, skillId: args.skillId },
+      "skill update notification failed; the skill write stands",
+    );
+  });
+}
+
 /**
  * Core execution logic for scaffold_managed_skill.
  * Exported so bundled-skill executors and tests can call it directly.
@@ -355,6 +422,21 @@ export async function executeScaffoldManagedSkill(
     }
   }
 
+  // A background pass changed a skill that already existed. Creates announce
+  // themselves through the skill card below; updates announce themselves in
+  // the background activity feed. Covers an explicit `overwrite: true`
+  // refinement as well as any other background write onto a pre-existing
+  // skill.
+  const notifyConversationId =
+    sourceConversationId ?? retrospectiveConversationId;
+  if (fromRetrospective && managedSkillExistedBefore && notifyConversationId) {
+    notifyBackgroundSkillUpdate({
+      skillId: id,
+      name: normalizedName,
+      conversationId: notifyConversationId,
+    });
+  }
+
   // Surface a genuine retrospective CREATE to the user as a skill card on the
   // source conversation, via the durable `skill_card_insert` delivery job
   // (memory-retrospective-skill-card.ts). The creation site is the one place

package/src/tools/skills/skill-tool-factory.ts

@@ -5,6 +5,7 @@ import {
   coerceStringNumbers,
   validateInputAgainstSchema,
 } from "../../skills/validate-input.js";
+import { bundledToolInputMisuseMessage } from "../shared/input-misuse.js";
 import type { ExecutionTarget } from "../tool-types.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 import { runSkillToolScript } from "./skill-script-runner.js";
@@ -53,8 +54,20 @@ export function createSkillTool(
         schema,
       );
       if (!validation.ok) {
+        // A parameter shape with its own redirect (e.g. a file path passed to
+        // `subagent_read`) answers with that redirect: the generic "Unknown
+        // parameter" list names the accepted keys but not the tool the caller
+        // is actually reaching for. Redirects describe first-party tools, so
+        // only bundled skills consult them. A managed, workspace, extra, or
+        // plugin skill that reuses a bundled tool name keeps the generic error,
+        // which is the one that matches its own manifest.
+        const misuse = bundled
+          ? bundledToolInputMisuseMessage(entry.name, coercedInput)
+          : undefined;
         return {
-          content: `Invalid input for tool "${entry.name}": ${validation.errors.join("; ")}. Fix the arguments and retry.`,
+          content:
+            misuse ??
+            `Invalid input for tool "${entry.name}": ${validation.errors.join("; ")}. Fix the arguments and retry.`,
           isError: true,
         };
       }

package/src/tools/subagent/consult-deadline.ts

@@ -2,19 +2,24 @@
  * A progress-aware deadline for the synchronous advisor consult.
  *
  * A reasoning advisor profile spends most of its window *thinking*, streaming
- * reasoning tokens the whole time. A fixed wall-clock ceiling would cut it off
- * mid-thought, so this aborts only after the consult goes `idleMs` without any
- * streamed token (thinking or text) — i.e. genuine silence — with an absolute
- * `maxMs` backstop so a runaway or looping stream can't block the parent
- * forever.
+ * reasoning tokens the whole time, and a consult that opens a file goes silent
+ * for the whole read. A fixed wall-clock ceiling would cut either one off
+ * mid-work, so this aborts only after the consult goes `idleMs` with no sign of
+ * progress at all, meaning neither a streamed token (thinking or text) nor tool
+ * activity, with an absolute `maxMs` backstop so a runaway or looping stream
+ * can't block the parent forever.
+ *
+ * The idle window is the caller's liveness check, not its budget: because tool
+ * activity re-arms it, a consult that keeps reading is bounded by `maxMs` and
+ * by whatever ceiling the caller puts on tool rounds, not by `idleMs`.
  *
  * Usage: combine `signal` with the caller's own signal, call `recordProgress()`
- * on every streamed chunk, and `dispose()` once the consult settles.
+ * on every sign of forward progress, and `dispose()` once the consult settles.
  */
 export interface ConsultDeadline {
   /** Aborts when the idle window lapses or the absolute max elapses. */
   readonly signal: AbortSignal;
-  /** Reset the idle window — call on every streamed chunk (thinking or text). */
+  /** Reset the idle window: call on every streamed chunk and tool event. */
   recordProgress(): void;
   /** Clear both timers; call once the consult settles (success or failure). */
   dispose(): void;

package/src/tools/subagent/message.ts

@@ -49,7 +49,9 @@ export async function executeSubagentMessage(
     };
   }
 
-  const result = await manager.sendMessage(subagentId, content);
+  const result = await manager.sendMessage(subagentId, content, {
+    cronRunId: context.cronRunId ?? null,
+  });
 
   if (result === "empty") {
     return {

package/src/tools/subagent/read.ts

@@ -1,6 +1,12 @@
 import { getMessages } from "../../persistence/conversation-crud.js";
 import { extractTextFromStoredMessageContent } from "../../persistence/message-content.js";
-import { TERMINAL_STATUSES } from "../../subagent/index.js";
+import { getSubagentManager, TERMINAL_STATUSES } from "../../subagent/index.js";
+import {
+  formatSubagentToolStats,
+  SUBAGENT_READ_STILL_PROCESSING,
+  SUBAGENT_STATS_UNAVAILABLE,
+} from "../../subagent/types.js";
+import { bundledToolInputMisuseMessage } from "../shared/input-misuse.js";
 import { invalidToolInputResult } from "../shared/zod-tool-schema.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 import {
@@ -9,6 +15,34 @@ import {
   subagentRefInputSchema,
 } from "./resolve.js";
 
+/**
+ * The machine truth envelope appended to a read: what the subagent actually
+ * ran, so the parent can check the output above against it.
+ *
+ * The counters are re-read first, because a child that was sent guidance keeps
+ * running after the harvest its own run took. `settled` is false when that
+ * guidance is still being processed, which makes both the transcript above and
+ * these counts an interim reading, so the footer says so.
+ *
+ * The manager owns the whole answer, including why there are no counters: they
+ * live in memory only, so a subagent rebuilt from its durable row says they are
+ * unavailable rather than reporting zero calls, which would read as "this
+ * subagent did nothing", while a live run that never reached its harvest has
+ * nothing measured to report and claims nothing.
+ */
+function statsFooter(subagentId: string, settled: boolean): string {
+  const note = settled ? "" : `\n\n${SUBAGENT_READ_STILL_PROCESSING}`;
+  const reading = getSubagentManager().currentToolStats(subagentId);
+  switch (reading.kind) {
+    case "counted":
+      return `${note}\n\n${formatSubagentToolStats(reading.stats)}`;
+    case "unrecoverable":
+      return `${note}\n\n${SUBAGENT_STATS_UNAVAILABLE}`;
+    default:
+      return note;
+  }
+}
+
 // `last_n` is deliberately UNDECLARED (loose passthrough): the executor's
 // typeof-guarded read below ignores it when malformed — including non-integer
 // numbers the advertised `integer` type wouldn't admit.
@@ -18,6 +52,16 @@ export async function executeSubagentRead(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
+  // File-reader keys and misspellings of `subagent_id` name a wrong-tool or
+  // wrong-parameter call, so they get the redirect rather than the generic
+  // '"subagent_id" or "label" is required'. `createSkillTool` runs the same
+  // check for calls the manifest validator rejects before they reach here.
+  // This executor backs the bundled subagent skill, so the bundled table is
+  // the right one to consult.
+  const misuse = bundledToolInputMisuseMessage("subagent_read", input);
+  if (misuse) {
+    return { content: misuse, isError: true };
+  }
   const parsedInput = subagentReadInputSchema.safeParse(input);
   if (!parsedInput.success) {
     return invalidToolInputResult("subagent_read", parsedInput.error);
@@ -54,12 +98,25 @@ export async function executeSubagentRead(
   }
 
   if (!TERMINAL_STATUSES.has(state.status)) {
+    // A premature read is often the only result a parent ever captures, so the
+    // message has to close the loop itself: the completion notification is
+    // already coming, and re-reading only burns another turn.
     return {
-      content: `Subagent "${state.config.label}" is still ${state.status}. Wait for it to finish.`,
+      content: `Subagent "${state.config.label}" is still ${state.status}. Do not poll: you will be notified automatically when it completes, and that notification tells you whether the result is inlined or waiting behind a read.`,
       isError: false,
     };
   }
 
+  // A terminal subagent can still have a follow-up turn in flight: guidance
+  // queued during its run drains after the run itself returns, which is what
+  // the completion notification's "queued follow-up guidance is still being
+  // processed, read for the latest output" points at. Reading straight through
+  // would answer that pointer with the transcript from before the guidance
+  // landed, so wait for the queued turn. The wait is bounded and its result
+  // reported either way: a subagent still working at the deadline is read as
+  // it stands, labelled as unfinished rather than presented as the result.
+  const settled = await getSubagentManager().settleQueuedTurns(subagentId);
+
   // Read the subagent's conversation messages from DB.
   const dbMessages = getMessages(state.conversationId);
   if (!dbMessages || dbMessages.length === 0) {
@@ -96,8 +153,13 @@ export async function executeSubagentRead(
     }
   }
 
+  const footer = statsFooter(subagentId, settled);
+
   if (messageTexts.length === 0) {
-    return { content: "Subagent produced no text output.", isError: false };
+    return {
+      content: `Subagent produced no text output.${footer}`,
+      isError: false,
+    };
   }
 
   const lastN =
@@ -107,7 +169,7 @@ export async function executeSubagentRead(
   const sliced = lastN ? messageTexts.slice(-lastN) : messageTexts;
 
   return {
-    content: sliced.join("\n\n"),
+    content: `${sliced.join("\n\n")}${footer}`,
     isError: false,
   };
 }