@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/tools/schedule/update.ts

@@ -1,3 +1,6 @@
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import { getConfig } from "../../config/loader.js";
+import { validateScheduleInferenceProfile } from "../../schedule/inference-profile.js";
 import { validateRruleSetLines } from "../../schedule/recurrence-engine.js";
 import {
   detectScheduleSyntax,
@@ -17,7 +20,7 @@ import {
 } from "../../schedule/schedule-store.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
-const VALID_MODES: ScheduleMode[] = ["notify", "execute", "script"];
+const VALID_MODES: ScheduleMode[] = ["notify", "execute", "script", "workflow"];
 const VALID_ROUTING_INTENTS: RoutingIntent[] = [
   "single_channel",
   "multi_channel",
@@ -92,6 +95,17 @@ export async function executeScheduleUpdate(
     updates.mode = mode;
   }
 
+  // Workflow fields pass-through (validated against the resulting mode below)
+  if (input.workflow_name !== undefined) {
+    updates.workflowName =
+      typeof input.workflow_name === "string"
+        ? input.workflow_name.trim()
+        : null;
+  }
+  if (input.workflow_args !== undefined) {
+    updates.workflowArgs = input.workflow_args;
+  }
+
   // Routing intent validation and pass-through
   if (input.routing_intent !== undefined) {
     const routingIntent = input.routing_intent as RoutingIntent;
@@ -127,6 +141,27 @@ export async function executeScheduleUpdate(
     updates.retryBackoffMs = input.retry_backoff_ms;
   }
 
+  // Inference profile override (null clears it, reverting to the default
+  // main-agent model selection)
+  if (input.inference_profile !== undefined) {
+    if (input.inference_profile === null) {
+      updates.inferenceProfile = null;
+    } else {
+      const inferenceProfile = input.inference_profile;
+      if (typeof inferenceProfile !== "string") {
+        return {
+          content: "Error: inference_profile must be a string or null",
+          isError: true,
+        };
+      }
+      const profileError = validateScheduleInferenceProfile(inferenceProfile);
+      if (profileError) {
+        return { content: `Error: ${profileError}`, isError: true };
+      }
+      updates.inferenceProfile = inferenceProfile;
+    }
+  }
+
   // Script execution timeout override (null clears it, reverting to default)
   if (input.timeout_ms !== undefined) {
     if (input.timeout_ms === null) {
@@ -170,6 +205,39 @@ export async function executeScheduleUpdate(
     };
   }
 
+  // Mirror the HTTP route: a schedule whose RESULTING mode is `workflow` must be
+  // flag-enabled and carry a non-empty workflowName. Compute the post-update
+  // state (the update's value if present, else the persisted one) so both
+  // "switch to workflow without a name" and "clear the name on a workflow
+  // schedule" are rejected — otherwise the scheduler hits the `!job.workflowName`
+  // skip branch and a one-shot firing job wedges.
+  if (updates.mode !== undefined || updates.workflowName !== undefined) {
+    const existing = getSchedule(jobId);
+    if (existing) {
+      const resultingMode =
+        updates.mode !== undefined ? (updates.mode as string) : existing.mode;
+      if (resultingMode === "workflow") {
+        if (!isAssistantFeatureFlagEnabled("workflows", getConfig())) {
+          return {
+            content: "Error: workflows are not enabled.",
+            isError: true,
+          };
+        }
+        const resultingWorkflowName =
+          updates.workflowName !== undefined
+            ? ((updates.workflowName as string | null) ?? "")
+            : (existing.workflowName ?? "");
+        if (!resultingWorkflowName) {
+          return {
+            content:
+              "Error: workflow_name is required for workflow-mode schedules",
+            isError: true,
+          };
+        }
+      }
+    }
+  }
+
   // Set-aware pre-validation for RRULE expressions
   const effectiveSyntax = updates.syntax as string | undefined;
   const effectiveExpr =
@@ -210,6 +278,9 @@ export async function executeScheduleUpdate(
         maxRetries?: number;
         retryBackoffMs?: number;
         timeoutMs?: number | null;
+        workflowName?: string | null;
+        workflowArgs?: unknown;
+        inferenceProfile?: string | null;
       },
     );
 
@@ -231,6 +302,7 @@ export async function executeScheduleUpdate(
         `  Description: ${job.description}`,
         `  Syntax: ${job.syntax}`,
         `  Mode: ${job.mode}`,
+        `  Inference profile: ${job.inferenceProfile ?? "default (mainAgent)"}`,
         `  Schedule: ${scheduleDescription}${job.timezone ? ` (${job.timezone})` : ""}`,
         `  Enabled: ${job.enabled}`,
         `  Next run: ${job.enabled ? formatLocalDate(job.nextRunAt) : "n/a (disabled)"}`,

package/src/tools/skills/execute.ts

@@ -6,6 +6,62 @@ import type {
   ToolExecutionResult,
 } from "../types.js";
 
+/** Envelope keys consumed by `skill_execute` itself, never inner-tool params. */
+const SKILL_EXECUTE_ENVELOPE_KEYS = new Set(["tool", "input", "activity"]);
+
+/**
+ * Resolve the inner tool's parameters from a `skill_execute` envelope.
+ *
+ * The documented contract is `{ tool, input: {...}, activity }` — the inner
+ * tool's parameters nested under `input`. A correctly nested, non-empty object
+ * is returned unchanged, so well-formed callers are unaffected.
+ *
+ * Weaker models routinely misplace the parameters. Left unhandled, the inner
+ * tool receives `{}`, fails schema validation ("<field> is required"), and the
+ * model retries the identical malformed call until it gives up — the empty-
+ * input retry loop. Two common misplacements are rescued so the call can
+ * succeed instead:
+ *
+ * 1. `input` passed as a JSON-encoded string instead of an object.
+ * 2. Parameters spread as top-level siblings of `tool`/`activity`, with `input`
+ *    absent or an empty object.
+ */
+export function resolveSkillExecuteInput(
+  envelope: Record<string, unknown>,
+): Record<string, unknown> {
+  const raw = envelope.input;
+
+  if (raw != null && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw as Record<string, unknown>;
+    // A populated object is the well-formed case. An empty object falls
+    // through to sibling rescue: the model may have nested nothing yet placed
+    // the real parameters at the top level.
+    if (Object.keys(obj).length > 0) return obj;
+  } else if (typeof raw === "string" && raw.trim()) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (
+        parsed != null &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed)
+      ) {
+        return parsed as Record<string, unknown>;
+      }
+    } catch {
+      // Not JSON — fall through to sibling rescue.
+    }
+  }
+
+  const siblings = Object.fromEntries(
+    Object.entries(envelope).filter(
+      ([key]) => !SKILL_EXECUTE_ENVELOPE_KEYS.has(key),
+    ),
+  );
+  if (Object.keys(siblings).length > 0) return siblings;
+
+  return {};
+}
+
 export const skillExecuteTool = {
   name: "skill_execute",
   description:

package/src/tools/terminal/shell.ts

@@ -200,7 +200,7 @@ export const shellTool = {
         return {
           content: `Error: unknown credential reference(s): ${unresolvedRefs.join(
             ", ",
-          )}. Use credential_store list to see available credentials.`,
+          )}. Use \`assistant credentials list\` to see available credentials.`,
           isError: true,
         };
       }

package/src/tools/ui-surface/definitions.ts

@@ -35,6 +35,22 @@ function proxyExecute(toolName: string) {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> => {
+    if (toolName === "ui_show" && isEmptyDynamicPage(input)) {
+      return {
+        content:
+          "Error: ui_show dynamic_page requires non-empty HTML in `data.html`. The surface was not displayed because no content was provided — the user would see a blank box. Resend ui_show with the full HTML markup in `data.html`.",
+        isError: true,
+      };
+    }
+
+    if (toolName === "ui_show" && isEmptyCard(input)) {
+      return {
+        content:
+          "Error: ui_show card requires content — provide `data.body`, a `template` (e.g. task_progress with steps), `data.metadata`, or `actions`. The surface was not displayed because it carried only a title, which renders as a blank box. Resend ui_show with populated card content.",
+        isError: true,
+      };
+    }
+
     if (toolName === "ui_show" && isDynamicPageAppSubstitute(input)) {
       return {
         content:
@@ -49,10 +65,83 @@ function proxyExecute(toolName: string) {
         isError: true,
       };
     }
-    return context.proxyToolResolver(toolName, input);
+    const result = await context.proxyToolResolver(toolName, input);
+    if (
+      toolName === "ui_show" &&
+      !result.isError &&
+      typeof result.content === "string" &&
+      isTaskProgressCardShow(input)
+    ) {
+      return {
+        ...result,
+        content: `${result.content}\n\n${TASK_PROGRESS_UPDATE_HINT}`,
+      };
+    }
+    return result;
   };
 }
 
+/**
+ * Worked ui_update example, appended to a successful task_progress `ui_show`
+ * result so the model learns the update pattern at the point of use (with the
+ * real surface_id in hand) rather than carrying it in the always-present tool
+ * description.
+ */
+const TASK_PROGRESS_UPDATE_HINT =
+  'As each step finishes, call ui_update with this surface_id to advance it — e.g. ui_update { surface_id: "<the surface_id above>", data: { templateData: { steps: [{ label: "Scaffold project", status: "completed" }, { label: "Wire up commands", status: "in_progress" }] } } }';
+
+function isTaskProgressCardShow(input: Record<string, unknown>): boolean {
+  if (input.template === "task_progress") {
+    return true;
+  }
+  const data = asRecord(input.data);
+  return data?.template === "task_progress";
+}
+
+function isEmptyDynamicPage(input: Record<string, unknown>): boolean {
+  if (input.surface_type !== "dynamic_page") {
+    return false;
+  }
+  const data = asRecord(input.data);
+  const html = data?.html;
+  return typeof html !== "string" || html.trim().length === 0;
+}
+
+/**
+ * A `card` ui_show carrying no renderable content — only a title (or nothing)
+ * — renders as a blank bordered box. A declared `template` (task_progress,
+ * weather_forecast, …) renders its own shell, and `body`/`subtitle`/`metadata`/
+ * `actions` are real content; any of those passes. The model places these
+ * either nested in `data` or at the top level, so both are checked. Title is
+ * intentionally not content: a title-only card is the blank box.
+ */
+function isEmptyCard(input: Record<string, unknown>): boolean {
+  if (input.surface_type !== "card") {
+    return false;
+  }
+  const data = asRecord(input.data) ?? {};
+
+  const template =
+    nonEmptyString(input.template) ?? nonEmptyString(data.template);
+  if (template) {
+    return false;
+  }
+
+  const hasBody = !!(nonEmptyString(input.body) ?? nonEmptyString(data.body));
+  const hasSubtitle = !!nonEmptyString(data.subtitle);
+  const hasMetadata = Array.isArray(data.metadata) && data.metadata.length > 0;
+  const actions = input.actions ?? data.actions;
+  const hasActions = Array.isArray(actions) && actions.length > 0;
+
+  return !(hasBody || hasSubtitle || hasMetadata || hasActions);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0
+    ? value
+    : undefined;
+}
+
 function isDynamicPageAppSubstitute(input: Record<string, unknown>): boolean {
   if (input.surface_type !== "dynamic_page") {
     return false;
@@ -137,7 +226,7 @@ export const uiShowTool = {
     "- file_upload: { prompt, acceptedTypes?, maxFiles? }\n" +
     "- task_preferences: {} (no data needed — categories are rendered client-side)\n" +
     '- work_result: { eyebrow?, status?: "completed"|"partial"|"failed"|"in_progress", summary?, metrics?: [{ label, value, detail?, tone?: "neutral"|"positive"|"warning"|"negative" }], sections?: [{ id?, title, description?, type?: "items"|"timeline"|"diff"|"artifacts"|"warnings", items?: [{ id?, title, description?, status?, tone?, metadata?: [{ label, value }], href? }], diffs?: [{ label?, before?, after? }] }] }. Shows a structured receipt after real work: what changed, what was skipped, proof points, and next actions. Keep display-only unless explicit follow-up buttons are needed.\n\n' +
-    "Emit a task_progress card BEFORE your first tool call on any multi-step, long-running, or post-form turn (web searches, file operations, research), and keep its steps updated as work progresses. Skills that estimate >30s of work should declare progress upfront with concrete step labels (and counts when known).",
+    "For multi-step or long-running turns (web searches, file operations, research), show a task_progress card early and keep its steps updated as work progresses. Coarse steps are fine, and you can add or revise them as the work takes shape — a rough card beats no signal.",
   category: "ui-surface",
   defaultRiskLevel: RiskLevel.Low,
   executionTarget: "host",

package/src/tools/workflows/manage-workflows.ts

@@ -0,0 +1,183 @@
+/**
+ * `manage_workflows` core implementation — thin reads/controls over
+ * {@link WorkflowRunManager}: check a run's status, abort a run, or list recent
+ * runs. All state lives in the run manager / journal; this delegates and
+ * compacts the result to JSON.
+ *
+ * NOTE: this runs in-process and returns a `runId`-keyed, deliberately trimmed
+ * projection for the model — a DIFFERENT contract from the HTTP wire shape
+ * (`id`-keyed `toWireRun`/`workflowRunSchema` in
+ * `runtime/routes/workflow-routes.ts`). The two are intentionally not unified:
+ * converging on `toWireRun` here would change this tool's emitted JSON. Both
+ * project from the same `WorkflowRun` source type, so field renames are caught
+ * by the type checker.
+ */
+
+import { loadConfig } from "../../config/loader.js";
+import { callerOwnsWorkflowRun } from "../../workflows/capabilities.js";
+import type { WorkflowRun } from "../../workflows/journal-store.js";
+import { getWorkflowRunManager } from "../../workflows/run-manager.js";
+import type { ToolContext, ToolExecutionResult } from "../types.js";
+
+export async function executeManageWorkflows(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const action = input.action as string | undefined;
+  const runId = input.run_id as string | undefined;
+  const manager = getWorkflowRunManager();
+
+  // Authorization scope ({@link callerOwnsWorkflowRun}, shared with the
+  // executor's resume-approval gate): a guardian may inspect/control every run,
+  // but a non-guardian conversation is limited to runs IT originated. Without
+  // this, a contact could enumerate a guardian's workflows (names/statuses) via
+  // list_runs and then abort/resume them by id — the tool is low-risk and
+  // reachable in non-guardian conversations. A run the caller may not see is
+  // treated as not-found so the tool never reveals another conversation's run.
+  const ownsRun = (run: WorkflowRun): boolean =>
+    callerOwnsWorkflowRun(run, context);
+
+  switch (action) {
+    case "status": {
+      if (!runId) {
+        return {
+          content: '"run_id" is required for action "status".',
+          isError: true,
+        };
+      }
+      const run = manager.status(runId);
+      if (!run || !ownsRun(run)) {
+        return {
+          content: JSON.stringify({ runId, found: false }),
+          isError: false,
+        };
+      }
+      return {
+        content: JSON.stringify({
+          runId: run.id,
+          name: run.name,
+          status: run.status,
+          agentsSpawned: run.agentsSpawned,
+          inputTokens: run.inputTokens,
+          outputTokens: run.outputTokens,
+          error: run.error,
+        }),
+        isError: false,
+      };
+    }
+    case "get_result": {
+      if (!runId) {
+        return {
+          content: '"run_id" is required for action "get_result".',
+          isError: true,
+        };
+      }
+      // The full result payload rides on the run record (journal getRun);
+      // `status` omits it to stay lightweight, so this action returns it in
+      // full. The completion-summary wake truncates large results and points
+      // the assistant here for the complete value.
+      const run = manager.status(runId);
+      if (!run || !ownsRun(run)) {
+        return {
+          content: JSON.stringify({ runId, found: false }),
+          isError: false,
+        };
+      }
+      return {
+        content: JSON.stringify({
+          runId: run.id,
+          status: run.status,
+          result: run.result ?? null,
+          error: run.error ?? null,
+        }),
+        isError: false,
+      };
+    }
+    case "abort": {
+      if (!runId) {
+        return {
+          content: '"run_id" is required for action "abort".',
+          isError: true,
+        };
+      }
+      // Only signal a run the caller owns. A non-owned (or absent) run is a
+      // no-op with the same response shape, so existence is never revealed.
+      const run = manager.status(runId);
+      if (run && ownsRun(run)) manager.abort(runId);
+      return {
+        content: JSON.stringify({
+          runId,
+          message: "Abort signalled (no-op if the run already finished).",
+        }),
+        isError: false,
+      };
+    }
+    case "resume": {
+      if (!runId) {
+        return {
+          content: '"run_id" is required for action "resume".',
+          isError: true,
+        };
+      }
+      // Don't resume — or reveal — a run the caller doesn't own; mirror
+      // resume()'s own not-found message.
+      const run = manager.status(runId);
+      if (!run || !ownsRun(run)) {
+        return {
+          content: `Failed to resume workflow: Workflow run ${runId} not found.`,
+          isError: true,
+        };
+      }
+      try {
+        const { runId: resumedId } = manager.resume(runId);
+        return {
+          content: JSON.stringify({
+            runId: resumedId,
+            status: "running",
+            message:
+              "Workflow resumed. The completed prefix is replayed from the journal and the run continues from the first unfinished step. You will be notified in this conversation when it completes — do NOT poll.",
+          }),
+          isError: false,
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { content: `Failed to resume workflow: ${msg}`, isError: true };
+      }
+    }
+    case "list_runs": {
+      const runs = manager.list().filter(ownsRun);
+      return {
+        content: JSON.stringify({
+          runs: runs.map((r) => ({
+            runId: r.id,
+            name: r.name,
+            status: r.status,
+            agentsSpawned: r.agentsSpawned,
+          })),
+        }),
+        isError: false,
+      };
+    }
+    case "list_profiles": {
+      // Mirror the `config/llm/profiles` route: sorted profile names plus the
+      // workspace-wide active profile. Read-only — leaves use this to pick a
+      // valid `profile` for `run_workflow` (an unknown profile throws).
+      const { llm } = loadConfig();
+      const profiles = llm?.profiles ?? {};
+      return {
+        content: JSON.stringify({
+          profiles: Object.keys(profiles).sort(),
+          activeProfile:
+            typeof llm?.activeProfile === "string" ? llm.activeProfile : null,
+        }),
+        isError: false,
+      };
+    }
+    default:
+      return {
+        content:
+          'Unknown action. Use one of: "status", "get_result", "abort", "resume", "list_runs", "list_profiles".',
+        isError: true,
+      };
+  }
+}