@vellumai/assistant 0.8.12 → 0.9.0-staging.1

package/src/runtime/routes/index.ts

@@ -110,6 +110,7 @@ import { ROUTES as PUBLISH_ROUTES } from "./publish-routes.js";
 import { ROUTES as QUESTION_ROUTES } from "./question-routes.js";
 import { ROUTES as RECORDING_ROUTES } from "./recording-routes.js";
 import { ROUTES as RENAME_CONVERSATION_ROUTES } from "./rename-conversation-routes.js";
+import { ROUTES as RETROSPECTIVE_ROUTES } from "./retrospective-routes.js";
 import { ROUTES as SANITY_ROUTES } from "./sanity-routes.js";
 import { ROUTES as SCHEDULE_ROUTES } from "./schedule-routes.js";
 import { ROUTES as SECRET_ROUTES } from "./secret-routes.js";
@@ -117,6 +118,7 @@ import { ROUTES as SEQUENCE_ROUTES } from "./sequence-routes.js";
 import { ROUTES as SETTINGS_ROUTES } from "./settings-routes.js";
 import { ROUTES as SKILL_ROUTES } from "./skills-routes.js";
 import { ROUTES as SLACK_CHANNEL_RESOLVE_ROUTES } from "./slack-channel-routes.js";
+import { ROUTES as SOUNDS_CONFIG_ROUTES } from "./sounds-config-routes.js";
 import { ROUTES as STT_ROUTES } from "./stt-routes.js";
 import { ROUTES as SUBAGENT_ROUTES } from "./subagents-routes.js";
 import { ROUTES as SUGGEST_TRUST_RULE_ROUTES } from "./suggest-trust-rule-routes.js";
@@ -138,6 +140,7 @@ import { ROUTES as WATCHER_ROUTES } from "./watcher-routes.js";
 import { ROUTES as WEBHOOK_ROUTES } from "./webhook-routes.js";
 import { ROUTES as WIPE_CONVERSATION_ROUTES } from "./wipe-conversation-routes.js";
 import { ROUTES as WORK_ITEM_ROUTES } from "./work-items-routes.js";
+import { ROUTES as WORKFLOW_ROUTES } from "./workflow-routes.js";
 import { ROUTES as WORKSPACE_COMMIT_ROUTES } from "./workspace-commit-routes.js";
 import { ROUTES as WORKSPACE_ROUTES } from "./workspace-routes.js";
 
@@ -238,10 +241,12 @@ export const ROUTES: RouteDefinition[] = [
   ...QUESTION_ROUTES,
   ...RECORDING_ROUTES,
   ...RENAME_CONVERSATION_ROUTES,
+  ...RETROSPECTIVE_ROUTES,
   ...SCHEDULE_ROUTES,
   ...SANITY_ROUTES,
   ...SECRET_ROUTES,
   ...SETTINGS_ROUTES,
+  ...SOUNDS_CONFIG_ROUTES,
   ...SKILL_ROUTES,
   ...A2A_ROUTES,
   ...SLACK_CHANNEL_CONFIG_ROUTES,
@@ -264,6 +269,7 @@ export const ROUTES: RouteDefinition[] = [
   ...USAGE_ROUTES,
   ...VERCEL_ROUTES,
   ...WORK_ITEM_ROUTES,
+  ...WORKFLOW_ROUTES,
   ...WATCHER_ROUTES,
   ...WEBHOOK_ROUTES,
   ...WIPE_CONVERSATION_ROUTES,

package/src/runtime/routes/log-export/AGENTS.md

@@ -5,7 +5,7 @@ from audit DB rows, daemon logs under `<workspace>/data/logs/`, and a
 sanitized `config.json` snapshot. This directory
 (`assistant/src/runtime/routes/log-export/`) houses the allowlist module
 that governs which subpaths of the user's workspace directory
-(`~/.vellum/workspace/`) are permitted to flow into that archive.
+(`$VELLUM_WORKSPACE_DIR/`) are permitted to flow into that archive.
 
 Workspace contents are **opt-in (allowlist), not opt-out**. The workspace
 contains arbitrary user files — skills, hooks, routes, conversations,

package/src/runtime/routes/log-export/workspace-allowlist.ts

@@ -3,7 +3,7 @@
  *
  * `POST /v1/export` collects audit DB rows, daemon logs, and a sanitized
  * `config.json` snapshot. This module governs which subpaths of the user's
- * workspace directory (`~/.vellum/workspace/`) are *opted in* to the export
+ * workspace directory (`$VELLUM_WORKSPACE_DIR/`) are *opted in* to the export
  * archive. The default is "nothing from the workspace ships" — every entry
  * here must be justified against the rules in `./AGENTS.md`.
  *

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

@@ -359,15 +359,11 @@ export async function handleMigrationExport(
         // flush on a multi-GB WAL file can otherwise stall the daemon's
         // event loop for the full duration of the flush.
         //
-        // FULL (not TRUNCATE): TRUNCATE has a side effect where, if the
-        // WAL is empty after the checkpoint, SQLite unlinks the WAL file
-        // from the directory. When the daemon's in-process connection
-        // still holds the original WAL fd, the unlink orphans that fd
-        // into a "ghost WAL" only the daemon can reach, and subsequent
-        // connections create a fresh WAL on disk — split-brain. FULL
-        // gives us the same flush-completion guarantee without the
-        // unlink side effect. See assistant/AGENTS.md "SQLite WAL
-        // checkpointing".
+        // FULL (not TRUNCATE): FULL blocks until every committed frame is
+        // written back to the main `.db` file, which is all the export
+        // needs since it copies that file. TRUNCATE additionally restarts
+        // the WAL and truncates it to zero bytes — extra work and blocking
+        // this path does not need.
         const result = await runAsyncSqlite("PRAGMA wal_checkpoint(FULL)");
         if (!result.ok) {
           // Best-effort: if the DB can't be checkpointed (e.g. not a valid

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

@@ -295,6 +295,12 @@ const pluginLocalInfoSchema = z
       .describe(
         "Resolved commit the copy was installed at; null when no provenance was recorded.",
       ),
+    committedAt: z
+      .string()
+      .nullable()
+      .describe(
+        "ISO-8601 committer timestamp (UTC) of the installed commit — the human-readable version; null for installs predating commit-timestamp capture. Distinct from `installedAt`.",
+      ),
     version: z
       .string()
       .nullable()
@@ -342,6 +348,12 @@ const pluginRemoteInfoSchema = z
       .describe(
         "Pinned commit SHA the marketplace currently resolves installs to.",
       ),
+    committedAt: z
+      .string()
+      .nullable()
+      .describe(
+        "ISO-8601 committer timestamp (UTC) of the pinned commit, resolved from GitHub; null when the commit metadata could not be fetched.",
+      ),
     description: z.string().nullable(),
     homepage: z.string().nullable(),
     license: z.string().nullable(),
@@ -413,11 +425,23 @@ const pluginUpgradeResponseSchema = z.object({
     .describe(
       "Installed commit before the upgrade; null when no provenance was recorded.",
     ),
+  fromTimestamp: z
+    .string()
+    .nullable()
+    .describe(
+      "ISO-8601 committer timestamp (UTC) of `fromCommit` — the version moved from; null when not recorded.",
+    ),
   toCommit: z
     .string()
     .describe(
       "Marketplace-pinned commit the install was (or would be) moved to.",
     ),
+  toTimestamp: z
+    .string()
+    .nullable()
+    .describe(
+      "ISO-8601 committer timestamp (UTC) of `toCommit` — the version moved to; null when it could not be resolved.",
+    ),
   target: z
     .string()
     .describe("Absolute path to the installed plugin directory on the host."),
@@ -740,7 +764,9 @@ async function handleUpgradePlugin({
       name: result.name,
       outcome: result.outcome,
       fromCommit: result.fromCommit,
+      fromTimestamp: result.fromTimestamp,
       toCommit: result.toCommit,
+      toTimestamp: result.toTimestamp,
       target: result.target,
       fileCount: result.fileCount,
       dryRun: result.dryRun,

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

@@ -29,14 +29,16 @@ interface ProcessEntry {
   info?: string;
 }
 
-const processEntrySchema: z.ZodType<ProcessEntry> = z.lazy(() =>
-  z.object({
-    name: z.string(),
-    status: z.enum(["running", "not_running", "unreachable"]),
-    children: z.array(processEntrySchema).optional(),
-    info: z.string().optional(),
-  }),
-);
+const processEntrySchema: z.ZodType<ProcessEntry> = z
+  .lazy(() =>
+    z.object({
+      name: z.string(),
+      status: z.enum(["running", "not_running", "unreachable"]),
+      children: z.array(processEntrySchema).optional(),
+      info: z.string().optional(),
+    }),
+  )
+  .meta({ id: "ProcessEntry" });
 
 const psResponseSchema = z.object({
   processes: z.array(processEntrySchema),

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

@@ -0,0 +1,235 @@
+/**
+ * Route handlers for memory retrospective background runs.
+ *
+ * Retrospectives are per-conversation background passes that review recent
+ * activity in a source conversation and persist durable memories. They are
+ * event-driven — enqueued by per-conversation triggers (time/message-count
+ * thresholds after activity, pre-compaction) via
+ * `maybeEnqueueMemoryRetrospective` in `memory/memory-retrospective-enqueue.ts`
+ * — never globally scheduled, so there is no run-now endpoint and `nextRunAt`
+ * is always null. These routes only surface config and run history for the
+ * Settings UI.
+ *
+ * `available` gates on `memory.enabled` alone (matching `isMemoryEnabled` in
+ * the enqueue path). Retrospectives do NOT depend on `memory.v2.enabled`.
+ */
+
+import { z } from "zod";
+
+import { getConfig } from "../../config/loader.js";
+import type { ConversationRow } from "../../memory/conversation-crud.js";
+import {
+  getMessageRoleStatsByConversation,
+  listConversationsBySource,
+} from "../../memory/conversation-queries.js";
+import { isMemoryEnabled } from "../../memory/jobs-store.js";
+import { getUsageCostForConversationWindow } from "../../memory/llm-usage-store.js";
+import {
+  MEMORY_RETROSPECTIVE_FORK_SOURCE,
+  MEMORY_RETROSPECTIVE_SOURCE,
+} from "../../memory/memory-retrospective-constants.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import {
+  paginateRuns,
+  parseRunsBeforeCursor,
+  parseRunsLimit,
+  RUNS_NEXT_CURSOR_SCHEMA,
+  RUNS_PAGINATION_QUERY_PARAMS,
+} from "./runs-pagination.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+type RetrospectiveKind = "legacy" | "fork";
+
+const SOURCE_KINDS: ReadonlyArray<{
+  source: string;
+  kind: RetrospectiveKind;
+}> = [
+  { source: MEMORY_RETROSPECTIVE_SOURCE, kind: "legacy" },
+  { source: MEMORY_RETROSPECTIVE_FORK_SOURCE, kind: "fork" },
+];
+
+/**
+ * Fetch the most recent retrospective conversations across BOTH source
+ * sentinels (legacy + fork), newest first. Fetches `limit` rows from each
+ * source before merging so the merged top-N is correct regardless of how
+ * runs are distributed across kinds. The same `before` cursor applies to
+ * each source query, so paging never skips rows from either kind.
+ */
+function listRetrospectiveConversations(
+  limit: number,
+  before?: number,
+): Array<{ row: ConversationRow; kind: RetrospectiveKind }> {
+  const merged = SOURCE_KINDS.flatMap(({ source, kind }) =>
+    listConversationsBySource(source, limit, {
+      beforeCreatedAt: before,
+    }).map((row) => ({ row, kind })),
+  );
+  merged.sort((a, b) => b.row.createdAt - a.row.createdAt);
+  return merged.slice(0, limit);
+}
+
+function readRetrospectiveConfigResponse() {
+  const config = getConfig();
+  const available = isMemoryEnabled();
+  const enabled = available;
+  const intervalMs = config.memory.retrospective.timeThresholdMs;
+  // Retrospectives have no global schedule — runs are triggered per
+  // conversation after activity, so a future run time is never known.
+  const nextRunAt = null;
+  const lastRunAt = listRetrospectiveConversations(1)[0]?.row.createdAt ?? null;
+  return {
+    available,
+    enabled,
+    intervalMs,
+    nextRunAt,
+    lastRunAt,
+    success: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Shared ROUTES
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "getRetrospectiveConfig",
+    endpoint: "retrospective/config",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get memory retrospective config",
+    description:
+      "Return the memory retrospective configuration. Retrospectives are " +
+      "event-driven background passes triggered per conversation after " +
+      "activity (time/message thresholds, pre-compaction) — there is no " +
+      "global schedule, so `nextRunAt` is always null and no run-now " +
+      "endpoint exists. `intervalMs` is the per-conversation time threshold " +
+      "(`memory.retrospective.timeThresholdMs`), `lastRunAt` is the " +
+      "`createdAt` of the most recent retrospective conversation across " +
+      "both legacy and fork sources, and `available` gates on " +
+      "`memory.enabled` (not `memory.v2.enabled`).",
+    tags: ["retrospective"],
+    responseBody: z.object({
+      available: z.boolean(),
+      enabled: z.boolean(),
+      intervalMs: z.number(),
+      nextRunAt: z.number().nullable(),
+      lastRunAt: z.number().nullable(),
+      success: z.boolean(),
+    }),
+    handler: async (_args: RouteHandlerArgs) => {
+      return readRetrospectiveConfigResponse();
+    },
+  },
+  {
+    operationId: "listRetrospectiveRuns",
+    endpoint: "retrospective/runs",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List memory retrospective runs",
+    description:
+      "Return recent memory retrospective conversations as run records, " +
+      "merged across both sources (`memory-retrospective` → kind `legacy`, " +
+      "`memory-retrospective-fork` → kind `fork`) and sorted newest first. " +
+      "Each retrospective dispatch creates exactly one background " +
+      "conversation; that conversation IS the run. Shape mirrors " +
+      "`consolidation/runs` (synthetic `id`/`scheduledFor`/`startedAt` from " +
+      "the conversation row, `finishedAt`/`status` from assistant-message " +
+      "presence, `skipReason`/`error` always null) plus `kind` and `title` " +
+      "(fork runs are titled '<source title> (Retrospective)', which " +
+      "identifies what was reviewed). For fork runs, copied source messages " +
+      "keep their original timestamps, so only assistant messages at or " +
+      "after the fork's creation count as agent output. NOTE: superseded " +
+      "runs are garbage-collected by default " +
+      "(`memory.retrospective.keepSupersededRuns: false` deletes the prior " +
+      "run when a newer one succeeds), so this lists what currently exists " +
+      "— typically the most recent run per source conversation unless the " +
+      "operator retains history.",
+    tags: ["retrospective"],
+    queryParams: RUNS_PAGINATION_QUERY_PARAMS(20),
+    responseBody: z.object({
+      runs: z
+        .array(
+          z.object({
+            id: z.string(),
+            scheduledFor: z.number(),
+            startedAt: z.number().nullable(),
+            finishedAt: z.number().nullable(),
+            durationMs: z.number().nullable(),
+            status: z.enum(["ok", "running"]),
+            skipReason: z.string().nullable(),
+            error: z.string().nullable(),
+            conversationId: z.string().nullable(),
+            conversationExists: z.boolean(),
+            conversationArchivedAt: z.number().nullable(),
+            estimatedCostUsd: z.number(),
+            createdAt: z.number(),
+            kind: z.enum(["legacy", "fork"]),
+            title: z.string().nullable(),
+          }),
+        )
+        .describe("Retrospective run records"),
+      nextCursor: RUNS_NEXT_CURSOR_SCHEMA,
+    }),
+    handler: async ({ queryParams }: RouteHandlerArgs) => {
+      const params = queryParams ?? {};
+      const limit = parseRunsLimit(params, 20);
+      const before = parseRunsBeforeCursor(params);
+      const { rows, nextCursor } = paginateRuns(
+        listRetrospectiveConversations(limit + 1, before),
+        limit,
+        (r) => r.row.createdAt,
+      );
+      const assistantStats = getMessageRoleStatsByConversation(
+        rows.map((r) => r.row.id),
+        "assistant",
+      );
+      const now = Date.now();
+      return {
+        nextCursor,
+        runs: rows.map(({ row: c, kind }) => {
+          const stat = assistantStats.get(c.id);
+          // Fork-based retrospectives copy the source conversation's
+          // messages with their ORIGINAL timestamps, so assistant messages
+          // can predate the fork row's createdAt. Only an assistant message
+          // at-or-after the conversation's creation is evidence the
+          // retrospective agent itself emitted output — without this guard
+          // an in-flight fork run would read "ok" with a negative duration.
+          const hasAssistantOutput = stat != null && stat.lastAt >= c.createdAt;
+          const finishedAt = hasAssistantOutput ? stat.lastAt : null;
+          const estimatedCostUsd =
+            c.totalEstimatedCost > 0
+              ? c.totalEstimatedCost
+              : getUsageCostForConversationWindow({
+                  conversationId: c.id,
+                  from: c.createdAt,
+                  to: finishedAt ?? now,
+                });
+          return {
+            id: c.id,
+            scheduledFor: c.createdAt,
+            startedAt: c.createdAt,
+            finishedAt,
+            durationMs: finishedAt != null ? finishedAt - c.createdAt : null,
+            status: (hasAssistantOutput ? "ok" : "running") as "ok" | "running",
+            skipReason: null,
+            error: null,
+            conversationId: c.id,
+            conversationExists: true,
+            conversationArchivedAt: c.archivedAt,
+            estimatedCostUsd,
+            createdAt: c.createdAt,
+            kind,
+            title: c.title ?? null,
+          };
+        }),
+      };
+    },
+  },
+];

package/src/runtime/routes/runs-pagination.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared cursor-pagination helpers for run-history routes
+ * (`heartbeat/runs`, `consolidation/runs`, `schedules/:id/runs`).
+ *
+ * Pages are keyed by each route's epoch-millis sort column. Clients pass the
+ * previous page's `nextCursor` back as `before` to fetch strictly older rows;
+ * a null `nextCursor` means the history is exhausted.
+ */
+
+import { z } from "zod";
+
+import type { RouteQueryParam } from "./types.js";
+
+/** Parse the optional `before` cursor query param (epoch millis). */
+export function parseRunsBeforeCursor(
+  queryParams: Record<string, string>,
+): number | undefined {
+  const raw = Number(queryParams.before);
+  return Number.isFinite(raw) ? raw : undefined;
+}
+
+/** Parse and clamp the `limit` query param to 1..100. */
+export function parseRunsLimit(
+  queryParams: Record<string, string>,
+  defaultLimit: number,
+): number {
+  const raw = Number(queryParams.limit ?? defaultLimit);
+  return Number.isFinite(raw)
+    ? Math.min(Math.max(Math.floor(raw), 1), 100)
+    : defaultLimit;
+}
+
+/**
+ * Slice a `limit + 1`-sized fetch down to the page and derive `nextCursor`
+ * from the last returned row's sort key (null when no older rows remain).
+ */
+export function paginateRuns<T>(
+  rows: T[],
+  limit: number,
+  cursorOf: (row: T) => number,
+): { rows: T[]; nextCursor: number | null } {
+  const hasMore = rows.length > limit;
+  const page = hasMore ? rows.slice(0, limit) : rows;
+  return {
+    rows: page,
+    nextCursor: hasMore ? cursorOf(page[page.length - 1]) : null,
+  };
+}
+
+/** Shared `nextCursor` response field for the paginated run-list routes. */
+export const RUNS_NEXT_CURSOR_SCHEMA = z
+  .number()
+  .nullable()
+  .describe(
+    "Cursor for fetching older runs (pass as `before`); null when no " +
+      "older runs exist",
+  );
+
+/** OpenAPI query-param entries shared by the paginated run-list routes. */
+export const RUNS_PAGINATION_QUERY_PARAMS = (
+  defaultLimit: number,
+): RouteQueryParam[] => [
+  {
+    name: "limit",
+    schema: { type: "integer" },
+    description: `Max runs to return (default ${defaultLimit}, max 100)`,
+  },
+  {
+    name: "before",
+    schema: { type: "integer" },
+    description:
+      "Cursor for older runs: pass the previous page's `nextCursor` to " +
+      "return runs strictly older than it.",
+  },
+];