@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/runtime/routes/workflow-routes.ts

@@ -0,0 +1,363 @@
+/**
+ * Route handlers for workflow-run management.
+ *
+ * All routes are served by both the HTTP server and the IPC server via the
+ * shared ROUTES array. They are read/abort surfaces over the workflow run
+ * manager and the saved-workflow library — a human (via the `vellum workflows`
+ * CLI or the app) can inspect runs and abort an in-flight one.
+ *
+ * Every handler is gated on the `workflows` feature flag: when it is off, the
+ * routes behave as if they do not exist (404), so disabling the flag fully
+ * hides the surface.
+ */
+
+import { z } from "zod";
+
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import { getConfig } from "../../config/loader.js";
+import type { AssistantConfig } from "../../config/schema.js";
+import { getAutoApproveThreshold } from "../../permissions/gateway-threshold-reader.js";
+import { isFullAccessThreshold } from "../../permissions/threshold.js";
+import { manifestGrantsSideEffects } from "../../workflows/capabilities.js";
+import type { WorkflowRun } from "../../workflows/journal-store.js";
+import { listWorkflows } from "../../workflows/library.js";
+import {
+  getWorkflowRunManager,
+  WorkflowResumeNotPossibleError,
+  WorkflowRunCapError,
+  type WorkflowRunManager,
+} from "../../workflows/run-manager.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import {
+  ConflictError,
+  ForbiddenError,
+  NotFoundError,
+  TooManyRequestsError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Injectable dependencies (production defaults; tests override)
+// ---------------------------------------------------------------------------
+
+export interface WorkflowRoutesDeps {
+  getManager: () => Pick<
+    WorkflowRunManager,
+    "list" | "status" | "abort" | "resume"
+  >;
+  listWorkflows: typeof listWorkflows;
+  getConfig: () => AssistantConfig;
+  isFlagEnabled: (config: AssistantConfig) => boolean;
+  getAutoApproveThreshold: typeof getAutoApproveThreshold;
+}
+
+function defaultDeps(): WorkflowRoutesDeps {
+  return {
+    getManager: getWorkflowRunManager,
+    listWorkflows,
+    getConfig,
+    isFlagEnabled: (config) =>
+      isAssistantFeatureFlagEnabled("workflows", config),
+    getAutoApproveThreshold,
+  };
+}
+
+let deps: WorkflowRoutesDeps = defaultDeps();
+
+/** Test seam: override the route dependencies. Pass no arg to restore defaults. */
+export function __setWorkflowRoutesDeps(
+  overrides?: Partial<WorkflowRoutesDeps>,
+): void {
+  deps = overrides ? { ...defaultDeps(), ...overrides } : defaultDeps();
+}
+
+// ---------------------------------------------------------------------------
+// Response schemas
+// ---------------------------------------------------------------------------
+
+const VALID_RUN_STATUSES = [
+  "running",
+  "completed",
+  "failed",
+  "aborted",
+  "cap_exceeded",
+  "interrupted",
+] as const;
+
+const workflowRunSchema = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  scriptHash: z.string(),
+  status: z.enum(VALID_RUN_STATUSES),
+  conversationId: z.string().nullable(),
+  agentsSpawned: z.number(),
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  error: z.string().nullable(),
+  createdAt: z.number().nullable(),
+  updatedAt: z.number().nullable(),
+  finishedAt: z.number().nullable(),
+});
+
+const savedWorkflowSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  path: z.string(),
+});
+
+// ---------------------------------------------------------------------------
+// Handlers (transport-agnostic)
+// ---------------------------------------------------------------------------
+
+/**
+ * Throw a 404 when the `workflows` flag is off, hiding the whole surface. The
+ * NotFoundError (rather than a 403) keeps a disabled-flag indistinguishable
+ * from a route that does not exist.
+ */
+function assertFlagEnabled(): void {
+  if (!deps.isFlagEnabled(deps.getConfig())) {
+    throw new NotFoundError("Workflows are not enabled.");
+  }
+}
+
+/**
+ * The single compact-run wire contract, inferred from {@link workflowRunSchema}.
+ * The HTTP routes return this shape; other producers (e.g. the CLI's client-side
+ * mirror) should track it so projections can't silently drift.
+ */
+export type WorkflowRunWire = z.infer<typeof workflowRunSchema>;
+
+/** Project a stored run into the wire shape (drops bulky source/args/result). */
+export function toWireRun(run: WorkflowRun): WorkflowRunWire {
+  return {
+    id: run.id,
+    name: run.name,
+    scriptHash: run.scriptHash,
+    status: run.status,
+    conversationId: run.conversationId,
+    agentsSpawned: run.agentsSpawned,
+    inputTokens: run.inputTokens,
+    outputTokens: run.outputTokens,
+    error: run.error,
+    createdAt: run.createdAt,
+    updatedAt: run.updatedAt,
+    finishedAt: run.finishedAt,
+  };
+}
+
+function parseLimit(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return undefined;
+  return Math.min(Math.max(Math.floor(n), 1), 200);
+}
+
+function parseStatus(
+  raw: string | undefined,
+): WorkflowRun["status"] | undefined {
+  if (raw === undefined) return undefined;
+  return (VALID_RUN_STATUSES as readonly string[]).includes(raw)
+    ? (raw as WorkflowRun["status"])
+    : undefined;
+}
+
+function handleListRuns(queryParams: Record<string, string>) {
+  assertFlagEnabled();
+  const limit = parseLimit(queryParams.limit);
+  const status = parseStatus(queryParams.status);
+  const runs = deps.getManager().list({
+    ...(limit !== undefined ? { limit } : {}),
+    ...(status !== undefined ? { status } : {}),
+  });
+  return { runs: runs.map(toWireRun) };
+}
+
+function handleGetRun(id: string) {
+  assertFlagEnabled();
+  const run = deps.getManager().status(id);
+  if (!run) {
+    throw new NotFoundError(`Workflow run ${id} not found`);
+  }
+  return toWireRun(run);
+}
+
+function handleAbortRun(id: string) {
+  assertFlagEnabled();
+  // status() is the source of truth for existence; abort() itself is a no-op
+  // for unknown/finished runs, so 404 on an unknown id is surfaced here.
+  const manager = deps.getManager();
+  if (!manager.status(id)) {
+    throw new NotFoundError(`Workflow run ${id} not found`);
+  }
+  manager.abort(id);
+  return { ok: true, runId: id };
+}
+
+async function handleResumeRun(id: string) {
+  assertFlagEnabled();
+  const manager = deps.getManager();
+  // status() is the source of truth for existence, so 404 an unknown id here
+  // (matching abort) rather than letting resume's "not_found" reach the client
+  // as a 409.
+  const run = manager.status(id);
+  if (!run) {
+    throw new NotFoundError(`Workflow run ${id} not found`);
+  }
+  // Consent gate. Resuming restarts the run's unfinished leaves, which execute
+  // the side-effecting tools/host functions the original manifest granted. The
+  // conversational `manage_workflows` resume path promotes such resumes to a
+  // fresh interactive approval (executor.ts → requireFreshApproval); this
+  // HTTP/IPC route (and the `vellum workflows resume` CLI on top of it) has no
+  // prompt channel. At full-access posture the user has opted into
+  // auto-approving even high-risk tools, so the resume proceeds without a
+  // prompt; otherwise it must not silently bypass consent — refuse and direct
+  // the caller to the assistant. A read-only run (no declared tools/host
+  // functions) resumes freely regardless of posture.
+  if (manifestGrantsSideEffects(run.capabilities)) {
+    const threshold = await deps.getAutoApproveThreshold(
+      run.conversationId ?? undefined,
+      "conversation",
+    );
+    if (!isFullAccessThreshold(threshold)) {
+      throw new ForbiddenError(
+        `Workflow run ${id} was granted side-effecting capabilities; resuming it ` +
+          `can restart steps that perform those side effects. Resume it through ` +
+          `the assistant (which will ask for approval) instead of this route.`,
+      );
+    }
+  }
+  try {
+    const { runId } = manager.resume(id);
+    return { ok: true, runId };
+  } catch (err) {
+    if (err instanceof WorkflowResumeNotPossibleError) {
+      if (err.reason === "not_found") {
+        throw new NotFoundError(`Workflow run ${id} not found`);
+      }
+      // not_interrupted / in_flight — the run exists but isn't resumable now.
+      throw new ConflictError(err.message);
+    }
+    if (err instanceof WorkflowRunCapError) {
+      throw new TooManyRequestsError(err.message);
+    }
+    throw err;
+  }
+}
+
+function handleListSavedWorkflows() {
+  assertFlagEnabled();
+  return { workflows: deps.listWorkflows() };
+}
+
+// ---------------------------------------------------------------------------
+// Shared route definitions (HTTP + IPC)
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "listWorkflowRuns",
+    endpoint: "workflows/runs",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List workflow runs",
+    description: "Return recent workflow runs, newest first.",
+    tags: ["workflows"],
+    queryParams: [
+      {
+        name: "limit",
+        schema: { type: "integer" },
+        description: "Max runs to return (default 50, max 200)",
+      },
+      {
+        name: "status",
+        schema: { type: "string" },
+        description:
+          "Filter by run status (running, completed, failed, aborted, cap_exceeded, interrupted).",
+      },
+    ],
+    responseBody: z.object({
+      runs: z.array(workflowRunSchema).describe("Workflow run objects"),
+    }),
+    handler: ({ queryParams }: RouteHandlerArgs) =>
+      handleListRuns(queryParams ?? {}),
+  },
+  {
+    operationId: "getWorkflowRun",
+    endpoint: "workflows/runs/:id",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get workflow run",
+    description: "Return a single workflow run by ID.",
+    tags: ["workflows"],
+    responseBody: workflowRunSchema,
+    additionalResponses: { "404": { description: "Run not found" } },
+    handler: ({ pathParams }: RouteHandlerArgs) => handleGetRun(pathParams!.id),
+  },
+  {
+    operationId: "abortWorkflowRun",
+    endpoint: "workflows/runs/:id/abort",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Abort workflow run",
+    description: "Signal an in-flight workflow run to abort.",
+    tags: ["workflows"],
+    responseBody: z.object({
+      ok: z.boolean(),
+      runId: z.string(),
+    }),
+    additionalResponses: { "404": { description: "Run not found" } },
+    handler: ({ pathParams }: RouteHandlerArgs) =>
+      handleAbortRun(pathParams!.id),
+  },
+  {
+    operationId: "resumeWorkflowRun",
+    endpoint: "workflows/runs/:id/resume",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Resume workflow run",
+    description:
+      "Resume an interrupted workflow run (one orphaned by an assistant restart), replaying its journaled prefix and continuing from the first unfinished step.",
+    tags: ["workflows"],
+    responseBody: z.object({
+      ok: z.boolean(),
+      runId: z.string(),
+    }),
+    additionalResponses: {
+      "404": { description: "Run not found" },
+      "409": { description: "Run is not resumable (not interrupted)" },
+      "429": { description: "Concurrent-run cap reached" },
+    },
+    handler: ({ pathParams }: RouteHandlerArgs) =>
+      handleResumeRun(pathParams!.id),
+  },
+  {
+    operationId: "listSavedWorkflows",
+    endpoint: "workflows",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List saved workflows",
+    description: "Return the saved (named) workflows the assistant can run.",
+    tags: ["workflows"],
+    responseBody: z.object({
+      workflows: z
+        .array(savedWorkflowSchema)
+        .describe("Saved workflow entries"),
+    }),
+    handler: () => handleListSavedWorkflows(),
+  },
+];

package/src/runtime/routes/workspace-routes.test.ts

@@ -5,7 +5,15 @@
  * directory listing, file metadata, write/mkdir/rename/delete, and raw
  * content serving with range support (HTTP-only).
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  linkSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { join } from "node:path";
 import { beforeAll, describe, expect, test } from "bun:test";
 
@@ -676,6 +684,58 @@ describe("POST /v1/workspace/rename", () => {
     ).toThrow(ConflictError);
   });
 
+  // Hard links share an inode while being distinct entries, and POSIX
+  // rename() between two hard links is a silent no-op — must 409 instead
+  // of reporting a successful rename that never happened.
+  test("throws ConflictError when renaming a hard link over its sibling link", () => {
+    writeFileSync(join(testWorkspaceDir, "hard-a.txt"), "hard");
+    linkSync(
+      join(testWorkspaceDir, "hard-a.txt"),
+      join(testWorkspaceDir, "hard-b.txt"),
+    );
+
+    expect(() =>
+      handler({
+        body: { oldPath: "hard-a.txt", newPath: "hard-b.txt" },
+      }),
+    ).toThrow(ConflictError);
+  });
+
+  // statSync would follow both links to the shared target and treat them as
+  // the same entry, letting the rename clobber a real, separate symlink.
+  test("throws ConflictError when renaming a symlink over a sibling symlink to the same target", () => {
+    writeFileSync(join(testWorkspaceDir, "link-target.txt"), "target");
+    symlinkSync(
+      join(testWorkspaceDir, "link-target.txt"),
+      join(testWorkspaceDir, "link-a.txt"),
+    );
+    symlinkSync(
+      join(testWorkspaceDir, "link-target.txt"),
+      join(testWorkspaceDir, "link-b.txt"),
+    );
+
+    expect(() =>
+      handler({
+        body: { oldPath: "link-a.txt", newPath: "link-b.txt" },
+      }),
+    ).toThrow(ConflictError);
+  });
+
+  // On case-insensitive filesystems (macOS default) the destination "exists"
+  // because it resolves to the source itself — must rename, not conflict.
+  test("allows case-only rename of the same file", () => {
+    const srcPath = join(testWorkspaceDir, "CaseFile.txt");
+    writeFileSync(srcPath, "case test");
+
+    const result = handler({
+      body: { oldPath: "CaseFile.txt", newPath: "casefile.txt" },
+    }) as { oldPath: string; newPath: string };
+    expect(result.newPath).toBe("casefile.txt");
+    const names = readdirSync(testWorkspaceDir);
+    expect(names).toContain("casefile.txt");
+    expect(names).not.toContain("CaseFile.txt");
+  });
+
   test("rejects path traversal on oldPath", () => {
     expect(() =>
       handler({

package/src/runtime/routes/workspace-routes.ts

@@ -6,9 +6,11 @@
 import {
   type Dirent,
   existsSync,
+  lstatSync,
   mkdirSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
   rmSync,
   statSync,
@@ -448,6 +450,29 @@ function handleWorkspaceMkdir({ body, headers }: RouteHandlerArgs) {
 // POST /v1/workspace/rename — rename/move files and directories
 // ---------------------------------------------------------------------------
 
+/**
+ * On case-insensitive filesystems (macOS/iOS defaults) a case-only rename's
+ * destination "exists" because it resolves to the source itself. Treat only
+ * true path aliases of one directory entry as the same file:
+ * - lstat, not stat, so two symlinks to one target stay distinct entries;
+ * - matching inodes alone are not enough — hard links share an inode while
+ *   being distinct entries, and POSIX rename() between two hard links is a
+ *   silent no-op. realpath canonicalizes case/normalization aliases of the
+ *   same entry to one string, while distinct entries keep distinct names.
+ */
+function isSamePathAlias(a: string, b: string): boolean {
+  try {
+    const statA = lstatSync(a);
+    const statB = lstatSync(b);
+    if (statA.dev !== statB.dev || statA.ino !== statB.ino) {
+      return false;
+    }
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+
 function handleWorkspaceRename({ body, headers }: RouteHandlerArgs) {
   const oldPath = body?.oldPath as string | undefined;
   const newPath = body?.newPath as string | undefined;
@@ -474,7 +499,7 @@ function handleWorkspaceRename({ body, headers }: RouteHandlerArgs) {
     throw new NotFoundError("Source path not found");
   }
 
-  if (existsSync(resolvedNew)) {
+  if (existsSync(resolvedNew) && !isSamePathAlias(resolvedOld, resolvedNew)) {
     throw new ConflictError("Destination already exists");
   }
 

package/src/runtime/services/__tests__/analyze-conversation.test.ts

@@ -365,6 +365,44 @@ describe("analyzeConversation", () => {
     expect(mockAddMessage).not.toHaveBeenCalled();
   });
 
+  test.each(["memory-retrospective", "memory-retrospective-fork"])(
+    "auto: rejects when the source conversation is a %s conversation",
+    async (source) => {
+      // Fork-kind retrospective conversations carry a full copy of the
+      // source conversation's history; auto-analyzing one would re-process
+      // the entire source conversation and double-write memory.
+      mockGetConversationSource.mockImplementation(() => source);
+
+      const result = await analyzeConversation("conv-1", {
+        trigger: "auto",
+      });
+
+      expect("error" in result).toBe(true);
+      if (!("error" in result)) throw new Error("expected error");
+      expect(result.error.kind).toBe("BAD_REQUEST");
+      expect(result.error.status).toBe(400);
+
+      // Nothing downstream of the guard should have fired.
+      expect(mockFindAnalysisConversationFor).not.toHaveBeenCalled();
+      expect(mockCreateConversation).not.toHaveBeenCalled();
+      expect(mockAddMessage).not.toHaveBeenCalled();
+    },
+  );
+
+  test("manual: does NOT reject a memory-retrospective conversation (guard is auto-only)", async () => {
+    mockGetConversationSource.mockImplementation(
+      () => "memory-retrospective-fork",
+    );
+
+    const result = await analyzeConversation("conv-1", {
+      trigger: "manual",
+    });
+
+    expect("error" in result).toBe(false);
+    if ("error" in result) throw new Error("expected success");
+    expect(result.analysisConversationId).toBe("analysis-new");
+  });
+
   test("auto: routes the agent loop through callSite: 'analyzeConversation'", async () => {
     await analyzeConversation("conv-1", { trigger: "auto" });
 

package/src/runtime/services/analyze-conversation.ts

@@ -34,6 +34,7 @@ import {
   getMessages,
 } from "../../memory/conversation-crud.js";
 import { resolveConversationId } from "../../memory/conversation-key-store.js";
+import { isMemoryRetrospectiveSource } from "../../memory/memory-retrospective-constants.js";
 import { getLogger } from "../../util/logger.js";
 import { assistantEventHub, broadcastMessage } from "../assistant-event-hub.js";
 import {
@@ -118,19 +119,31 @@ export async function analyzeConversation(
 
   // e. Defense-in-depth recursion guard for auto mode: refuse to
   // auto-analyze a conversation that is itself an auto-analysis
-  // conversation. Prevents job-handler bugs from triggering runaway
-  // self-analysis loops.
-  if (
-    opts.trigger === "auto" &&
-    getConversationSource(resolvedId) === AUTO_ANALYSIS_SOURCE
-  ) {
-    return {
-      error: {
-        kind: "BAD_REQUEST",
-        status: 400,
-        message: "Cannot auto-analyze an auto-analysis conversation",
-      },
-    };
+  // conversation (prevents job-handler bugs from triggering runaway
+  // self-analysis loops) or a memory-retrospective conversation
+  // (fork-kind retrospectives carry a full copy of the source history,
+  // so auto-analyzing one would re-process the entire source
+  // conversation and double-write memory).
+  if (opts.trigger === "auto") {
+    const source = getConversationSource(resolvedId);
+    if (source === AUTO_ANALYSIS_SOURCE) {
+      return {
+        error: {
+          kind: "BAD_REQUEST",
+          status: 400,
+          message: "Cannot auto-analyze an auto-analysis conversation",
+        },
+      };
+    }
+    if (source !== null && isMemoryRetrospectiveSource(source)) {
+      return {
+        error: {
+          kind: "BAD_REQUEST",
+          status: 400,
+          message: "Cannot auto-analyze a memory-retrospective conversation",
+        },
+      };
+    }
   }
 
   // f. Build the analysis transcript

package/src/schedule/inference-profile.ts

@@ -0,0 +1,28 @@
+import { getConfigReadOnly } from "../config/loader.js";
+
+/**
+ * Validate a schedule's inference-profile key against the configured
+ * `llm.profiles` catalog. Returns a user-facing error message when the key is
+ * empty or unknown, or `null` when valid.
+ *
+ * Only create/update paths validate — a profile deleted after a schedule was
+ * created degrades gracefully at run time (the resolver silently drops a
+ * missing `overrideProfile` reference and falls through to the defaults).
+ */
+export function validateScheduleInferenceProfile(
+  profile: string,
+): string | null {
+  if (!profile.trim()) {
+    return "inferenceProfile must be a non-empty string";
+  }
+  const profiles = getConfigReadOnly().llm?.profiles ?? {};
+  if (!Object.prototype.hasOwnProperty.call(profiles, profile)) {
+    const available = Object.keys(profiles).sort();
+    const hint =
+      available.length > 0
+        ? ` Available profiles: ${available.join(", ")}.`
+        : " No profiles defined in llm.profiles.";
+    return `Inference profile "${profile}" is not defined in llm.profiles.${hint}`;
+  }
+  return null;
+}