@vellumai/assistant 0.11.2 → 0.11.3-staging.2

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

@@ -17,6 +17,8 @@ import {
 } from "../../persistence/llm-usage-store.js";
 import { isDeferSchedule } from "../../schedule/defer-provenance.js";
 import { validateScheduleInferenceProfile } from "../../schedule/inference-profile.js";
+import { declarationExistsOnDisk } from "../../schedule/plugin-schedule-declarations.js";
+import { isPluginSchedulesEnabled } from "../../schedule/plugin-schedules-gate.js";
 import {
   describeRRuleExpression,
   isSingleFireRRule,
@@ -39,6 +41,7 @@ import {
   listSchedules,
   resolveScheduleConversationGroupId,
   type ScheduleJob,
+  setUserEnabled,
   updateSchedule,
 } from "../../schedule/schedule-store.js";
 import { getScheduleUsageSummaries } from "../../schedule/schedule-usage-store.js";
@@ -135,7 +138,24 @@ const scheduleSchema = z.object({
   reuseConversation: z.boolean(),
   wakeConversationId: z.string().nullable(),
   workflowName: z.string().nullable(),
+  sourceKey: z
+    .string()
+    .nullable()
+    .describe(
+      "Plugin declaration this schedule mirrors (plugin:<pluginName>/<scheduleName>); null for user-created schedules",
+    ),
+  userEnabled: z
+    .boolean()
+    .nullable()
+    .describe(
+      "User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules.",
+    ),
   isOneShot: z.boolean(),
+  // A deferred wake ("remind me about this tomorrow") is an ordinary schedule
+  // row created by the defer path, distinguishable only by `createdBy`, which
+  // is not otherwise projected. Clients need it to separate the user's named
+  // schedules from their reminders when listing what a change affects.
+  isDeferred: z.boolean(),
 });
 
 const scheduleRunSchema = z.object({
@@ -218,6 +238,15 @@ function getCadenceDescription(
   return describeRRuleExpression(job.cronExpression);
 }
 
+/**
+ * Whether a schedule still has a firing ahead of it. `fired` and `cancelled`
+ * are the two terminal states a one-shot lands in; everything else (including
+ * a disabled row, which fires again once re-enabled) can still run.
+ */
+function canScheduleStillRun(job: Pick<ScheduleJob, "status">): boolean {
+  return job.status !== "fired" && job.status !== "cancelled";
+}
+
 /**
  * Presentation-layer one-shot flag. A COUNT=1 rrule fires exactly once and
  * should read as one-time in clients, even though the scheduler internally
@@ -271,13 +300,19 @@ function serializeSchedule(
     reuseConversation: j.reuseConversation,
     wakeConversationId: j.wakeConversationId,
     workflowName: j.workflowName,
+    sourceKey: j.sourceKey,
+    userEnabled: j.userEnabled,
     isOneShot: isOneShotForDisplay(j),
+    isDeferred: isDeferSchedule(j.createdBy),
   };
 }
 
 function handleListSchedules(queryParams: Record<string, string>) {
   const includeAll = queryParams.include_all === "true";
-  const jobs = listSchedules();
+  const inferenceProfile = queryParams.inference_profile?.trim();
+  const jobs = listSchedules(
+    inferenceProfile ? { inferenceProfile } : undefined,
+  );
   const filtered = includeAll
     ? jobs
     : jobs.filter((j) => !isDeferSchedule(j.createdBy));
@@ -300,6 +335,88 @@ function handleGetSchedule(id: string) {
   return { schedule: serializeSchedule(job, new Map()) };
 }
 
+/**
+ * Move schedules onto the `to` inference profile.
+ *
+ * `from` narrows the move to the schedules pinned to that profile. It is the
+ * companion to deleting an inference profile: without it the profile's
+ * schedules keep a pin that no longer names anything. The dangling pin is not
+ * fatal (the resolver drops a missing override and falls through to the call
+ * site's own selection), so this exists to keep the user's stated model choice
+ * rather than to prevent a failure.
+ *
+ * Omitting `from` selects every schedule that can still run, which is what
+ * re-pinning the whole set onto the current default needs: schedules pinned by
+ * earlier defaults name several different profiles, so there is no single
+ * source to move from. A one-shot that already fired and a cancelled row are
+ * left out: their profile is history, and rewriting them would report a move
+ * larger than the set the user was looking at. An explicit `from` still
+ * selects exactly the rows pinned to it, dead or not, since a deleted profile
+ * has to be swept out of every row that names it. Rows already pinned to `to`
+ * are skipped either way, so the returned count is the number of schedules
+ * whose model actually changed.
+ *
+ * Each row goes through `updateSchedule`, so the store's profile validation
+ * and re-snapshot semantics apply exactly as they do to a single-row PATCH.
+ * Deferred-wake rows are moved too, since a defer inherits the profile of the
+ * conversation it was created in and would otherwise be the one row left
+ * dangling. Callers that warn a user before deleting a profile must count
+ * those rows as well, which is what `include_all` plus the serialized
+ * `isDeferred` flag on the list route are for. Moving one is a guardian-owned
+ * state change, so the whole call requires owner authority as soon as a wake
+ * row is in the selected set.
+ */
+async function handleReassignScheduleInferenceProfile(
+  body: Record<string, unknown>,
+  headers?: Record<string, string>,
+) {
+  const hasFrom = body.from !== undefined && body.from !== null;
+  const from = typeof body.from === "string" ? body.from.trim() : "";
+  const to = typeof body.to === "string" ? body.to.trim() : "";
+  if (hasFrom && !from) {
+    throw new BadRequestError(
+      "from must name an inference profile when provided",
+    );
+  }
+  if (!to) {
+    throw new BadRequestError("to is required");
+  }
+  // `to` must name a configured profile; `from` deliberately is not validated
+  // so an already-deleted profile's leftover pins can still be swept up.
+  const profileError = validateScheduleInferenceProfile(to);
+  if (profileError) {
+    throw new BadRequestError(profileError);
+  }
+
+  const selected = hasFrom
+    ? listSchedules({ inferenceProfile: from })
+    : listSchedules().filter(canScheduleStillRun);
+  const matches = selected.filter((job) => job.inferenceProfile !== to);
+  // The guard depends only on the caller, so its answer is the same for every
+  // row: settle it once for the whole set. Checking per row would spend a
+  // cache-bypassing gateway round trip per matching reminder, and a profile
+  // that many reminders point at would take seconds to move or time out.
+  // All-or-nothing either way: one wake row in scope refuses the whole call
+  // before anything moves.
+  const wakeMatch = matches.find((job) => job.mode === "wake") ?? null;
+  await assertWakeMutationAllowed(wakeMatch, undefined, headers);
+
+  let reassigned = 0;
+  for (const job of matches) {
+    const updated = await updateSchedule(job.id, { inferenceProfile: to });
+    if (updated) {
+      reassigned += 1;
+    }
+  }
+  if (reassigned > 0) {
+    log.info(
+      { from: hasFrom ? from : null, to, reassigned },
+      "Schedules reassigned to new profile",
+    );
+  }
+  return { reassigned };
+}
+
 async function handleCreateSchedule(body: Record<string, unknown>) {
   const name = typeof body.name === "string" ? body.name.trim() : "";
   const expression =
@@ -382,6 +499,7 @@ async function handleCreateSchedule(body: Record<string, unknown>) {
         timezone,
         expression: normalized.expression,
         syntax: normalized.syntax,
+        inferenceProfile,
       });
       log.info(
         { id: job.id, name: job.name, workflowName },
@@ -420,6 +538,7 @@ async function handleCreateSchedule(body: Record<string, unknown>) {
         expression: normalized.expression,
         syntax: normalized.syntax,
         timeoutMs,
+        inferenceProfile,
       });
       log.info({ id: job.id, name: job.name }, "Script schedule created");
       return { schedule: serializeSchedule(job, new Map()) };
@@ -468,7 +587,9 @@ async function handleToggleSchedule(
   // enabled, with no further caller involvement.
   await assertWakeMutationAllowed(getSchedule(id), undefined, headers);
 
-  const updated = await updateSchedule(id, { enabled });
+  // One endpoint serves both kinds of row: imperative schedules take the
+  // plain enabled write, plugin-sourced ones record the user_enabled override.
+  const updated = await setUserEnabled(id, enabled);
   if (!updated) {
     throw new NotFoundError("Schedule not found");
   }
@@ -481,7 +602,18 @@ async function handleDeleteSchedule(
   headers?: Record<string, string>,
 ) {
   await assertWakeMutationAllowed(getSchedule(id), undefined, headers);
-  const removed = await deleteSchedule(id);
+  let removed: boolean;
+  try {
+    removed = await deleteSchedule(id);
+  } catch (err) {
+    // Store-layer refusals (e.g. plugin-sourced rows, which only the plugin's
+    // schedule file can remove) are caller mistakes with an actionable
+    // message, not daemon faults.
+    if (err instanceof UserError) {
+      throw new BadRequestError(err.message);
+    }
+    throw err;
+  }
   if (!removed) {
     throw new NotFoundError("Schedule not found");
   }
@@ -494,7 +626,18 @@ async function handleCancelSchedule(
   headers?: Record<string, string>,
 ) {
   await assertWakeMutationAllowed(getSchedule(id), undefined, headers);
-  const cancelled = await cancelSchedule(id);
+  let cancelled: boolean;
+  try {
+    cancelled = await cancelSchedule(id);
+  } catch (err) {
+    // Store-layer refusals (plugin-sourced rows, for which cancellation is a
+    // permanent latch) are caller mistakes with an actionable message, not
+    // daemon faults.
+    if (err instanceof UserError) {
+      throw new BadRequestError(err.message);
+    }
+    throw err;
+  }
   if (!cancelled) {
     throw new NotFoundError("Schedule not found or not cancellable");
   }
@@ -625,8 +768,8 @@ async function handleUpdateSchedule(
     }
   }
 
-  // Inference profile: null clears the override (back to the default
-  // main-agent model selection); a string must name a configured profile.
+  // Inference profile: null re-pins to the currently resolved default; a
+  // string must name a configured profile.
   if ("inferenceProfile" in body) {
     const inferenceProfile = body.inferenceProfile;
     if (inferenceProfile !== null && typeof inferenceProfile !== "string") {
@@ -761,6 +904,12 @@ export const ROUTES: RouteDefinition[] = [
         description:
           "When 'true', include deferred schedules that are normally hidden.",
       },
+      {
+        name: "inference_profile",
+        schema: { type: "string" },
+        description:
+          "Return only schedules pinned to this inference profile (llm.profiles key).",
+      },
     ],
     responseBody: z.object({
       schedules: z.array(scheduleSchema).describe("Schedule objects"),
@@ -802,8 +951,38 @@ export const ROUTES: RouteDefinition[] = [
     handler: ({ queryParams }: RouteHandlerArgs) =>
       handleScheduleUsageSummary(queryParams ?? {}),
   },
-  // Must stay after literal `schedules/*` GET siblings (e.g. usage-summary):
-  // the router matches in declaration order and `:id` would shadow them.
+  {
+    operationId: "reassignScheduleInferenceProfile",
+    endpoint: "schedules/reassign-profile",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Reassign schedules to another inference profile",
+    description:
+      "Move schedules onto one inference profile. Pass 'from' to move only the schedules pinned to that profile, so deleting a profile does not leave its schedules pointing at a name that no longer exists. Omit 'from' to move every schedule, which re-pins the whole set onto one profile. Schedules already pinned to the target are skipped.",
+    tags: ["schedules"],
+    requestBody: z.object({
+      from: z
+        .string()
+        .optional()
+        .describe(
+          "Inference profile key the schedules are pinned to now; omit to select every schedule",
+        ),
+      to: z
+        .string()
+        .describe("Inference profile key to move them to; must be configured"),
+    }),
+    responseBody: z.object({
+      reassigned: z.number().describe("Number of schedules moved"),
+    }),
+    handler: ({ body, headers }: RouteHandlerArgs) =>
+      handleReassignScheduleInferenceProfile(body ?? {}, headers),
+  },
+  // Must stay after literal `schedules/*` siblings (e.g. usage-summary,
+  // reassign-profile): the router matches in declaration order and `:id`
+  // would shadow them.
   {
     operationId: "getSchedule",
     endpoint: "schedules/:id",
@@ -882,7 +1061,7 @@ export const ROUTES: RouteDefinition[] = [
         .string()
         .nullable()
         .describe(
-          "Inference profile (llm.profiles key) the schedule's runs use. Omitted or null = default, i.e. the mainAgent call-site model selection.",
+          "Inference profile (llm.profiles key) the schedule's runs use. Omitted or null pins the schedule to the currently resolved default profile, so its model does not move when that default changes. Workflow-mode schedules resolve a model per workflow step, so the pin is recorded but does not govern their runs.",
         )
         .optional(),
     }),
@@ -919,7 +1098,8 @@ export const ROUTES: RouteDefinition[] = [
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "Toggle schedule",
-    description: "Enable or disable a schedule.",
+    description:
+      "Enable or disable a schedule. On a plugin-managed schedule this records the user's override (userEnabled).",
     tags: ["schedules"],
     requestBody: z.object({
       enabled: z.boolean().describe("New enabled state"),
@@ -1002,7 +1182,7 @@ export const ROUTES: RouteDefinition[] = [
         .string()
         .nullable()
         .describe(
-          "Inference profile (llm.profiles key) the schedule's runs use; null clears it back to the default mainAgent call-site model selection",
+          "Inference profile (llm.profiles key) the schedule's runs use; null re-pins the schedule to the currently resolved default profile. Workflow-mode schedules resolve a model per workflow step, so the pin is recorded but does not govern their runs.",
         )
         .optional(),
     }),
@@ -1038,7 +1218,8 @@ export const ROUTES: RouteDefinition[] = [
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "Run schedule now",
-    description: "Trigger an immediate execution of a schedule.",
+    description:
+      "Trigger an immediate execution of a schedule. A plugin-sourced schedule is rejected with a 400 when its plugin is disabled or no longer declares it.",
     tags: ["schedules"],
     responseBody: z.object({
       schedules: z.array(scheduleSchema).describe("Updated schedule list"),
@@ -1057,6 +1238,23 @@ async function handleRunScheduleNow(
     throw new NotFoundError("Schedule not found");
   }
 
+  // A plugin-sourced row runs the plugin's own script or prompt, so run-now is
+  // only offered while that plugin is something the runtime would activate.
+  // `declarationExistsOnDisk` is the same probe the enable path uses: it covers
+  // a disabled plugin, an unreadable or invalid manifest, and a declaration
+  // that is simply gone. Turning the feature flag off retires the surface
+  // wholesale and takes the same path. The row can still be armed at this
+  // point, because the reconciler that disarms it runs on its own schedule.
+  if (
+    schedule.sourceKey !== null &&
+    (!isPluginSchedulesEnabled() ||
+      !(await declarationExistsOnDisk(schedule.sourceKey)))
+  ) {
+    throw new BadRequestError(
+      "This schedule's plugin is disabled or no longer declares it, so it cannot be run.",
+    );
+  }
+
   // ── Script mode (shell command, no LLM) ──────────────────────────
   if (schedule.mode === "script") {
     if (!schedule.script) {

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

@@ -108,7 +108,7 @@ async function queueApiKeyPropagation(
           getPlatformAssistantId() || undefined,
         );
         log.info(
-          "Pushed queued assistant API key to CES after handshake completed",
+          "Notified CES of the queued assistant API key after handshake completed (ack only; CES reads the durable value from the credential store)",
         );
       } catch (err) {
         log.warn(
@@ -124,6 +124,44 @@ async function queueApiKeyPropagation(
   );
 }
 
+/**
+ * Notify CES that the assistant API key changed. This is advisory: the key is
+ * durably stored in the credential vault and CES reads it from there. When no
+ * CES client is connected the notification is skipped, but the skip is logged
+ * rather than dropped silently. Exported for direct testing.
+ */
+export async function notifyCesOfAssistantApiKeyUpdate(
+  value: string,
+  cesClient: CesClient | undefined,
+  logger: Pick<ReturnType<typeof getLogger>, "info" | "warn"> = log,
+): Promise<void> {
+  const generation = ++apiKeyGeneration;
+  if (!cesClient) {
+    logger.warn(
+      "Assistant API key updated but no CES client is connected; skipping the CES key-update notification (advisory only; CES reads the durable value from the credential store)",
+    );
+    return;
+  }
+  if (cesClient.isReady()) {
+    try {
+      await cesClient.updateAssistantApiKey(
+        value,
+        getPlatformAssistantId() || undefined,
+      );
+      logger.info(
+        "Notified CES of the updated assistant API key (ack only; CES reads the durable value from the credential store)",
+      );
+    } catch (err) {
+      logger.warn(
+        { error: err instanceof Error ? err.message : String(err) },
+        "Failed to notify CES of the assistant API key update (non-fatal)",
+      );
+    }
+    return;
+  }
+  void queueApiKeyPropagation(cesClient, value, generation);
+}
+
 // ---------------------------------------------------------------------------
 // Provider refresh after secret changes
 // ---------------------------------------------------------------------------
@@ -381,28 +419,7 @@ async function handleAddSecret({ body }: RouteHandlerArgs) {
         // pages unseeded until restart. Detached — must not block the response.
         void maybeReseedCapabilitiesAfterManagedCredential(getConfig());
         if (service === "vellum" && field === "assistant_api_key") {
-          const generation = ++apiKeyGeneration;
-          const cesClient = getCesClient();
-          if (cesClient) {
-            if (cesClient.isReady()) {
-              try {
-                await cesClient.updateAssistantApiKey(
-                  value,
-                  getPlatformAssistantId() || undefined,
-                );
-                log.info(
-                  "Pushed assistant API key to CES after managed proxy credential update",
-                );
-              } catch (err) {
-                log.warn(
-                  { error: err instanceof Error ? err.message : String(err) },
-                  "Failed to push assistant API key to CES (non-fatal)",
-                );
-              }
-            } else {
-              void queueApiKeyPropagation(cesClient, value, generation);
-            }
-          }
+          await notifyCesOfAssistantApiKeyUpdate(value, getCesClient());
         }
       }
       if (

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

@@ -46,6 +46,7 @@ import { getSecureKeyAsync } from "../../security/secure-keys.js";
 import { parseToolManifestFile } from "../../skills/tool-manifest.js";
 import { getSubagentManager } from "../../subagent/index.js";
 import { mergeSkillIds } from "../../subagent/manager.js";
+import { resolveSubagentRole } from "../../subagent/role-resolution.js";
 import {
   SUBAGENT_ROLE_REGISTRY,
   type SubagentRole,
@@ -407,10 +408,24 @@ type SchemaShape = {
   required?: string[];
 };
 
+/** How an `agent` query param was read, when one was given by role. */
+interface ResolvedAgentInfo {
+  /** The `agent` value as asked for. */
+  requested: string;
+  /** The subagent type whose surface is listed. */
+  role: SubagentRole;
+  /** The older type name that produced `role`, when one did. */
+  alias?: string;
+  /** The free text carried as a persona, when `requested` named no type. */
+  persona?: string;
+}
+
 interface ToolNamesListResponse {
   names: string[];
   schemas: Record<string, SchemaShape>;
   tools: ToolListEntry[];
+  /** Present only for an `agent` listing resolved from a role string. */
+  agent?: ResolvedAgentInfo;
 }
 
 /**
@@ -475,7 +490,11 @@ function handleToolNamesList(
 
 /**
  * Resolve the tool surface a subagent would receive, identified either by a
- * role name (e.g. "researcher") or a live subagent id.
+ * live subagent id or by any string a spawn's `role` field accepts: a type
+ * name (e.g. "researcher"), an older type name, or free text that a spawn
+ * carries as a persona. The response reports which type the string landed on
+ * and what carried it there, so a surface that came from an alias or a persona
+ * fallback is not mistaken for one that was asked for by name.
  *
  * For a role name: build a minimal {@link Conversation} stand-in matching what
  * the {@link SubagentManager} sets up at spawn time (isSubagent, allowedTools,
@@ -495,16 +514,13 @@ function handleAgentToolList(agent: string): ToolNamesListResponse {
     return handleConversationToolList(state.conversationId);
   }
 
-  // Otherwise, treat as a role name.
-  const role = agent as SubagentRole;
-  const roleConfig = SUBAGENT_ROLE_REGISTRY[role];
-  if (!roleConfig) {
-    throw new NotFoundError(
-      `Unknown agent "${agent}". Expected a subagent role ` +
-        `(general, researcher, coder, planner, investigator, advisor) ` +
-        `or a live subagent id.`,
-    );
-  }
+  // Otherwise, read it the way a spawn reads its `role` field. Resolution is
+  // total: a type name passes through, an older name resolves to its successor
+  // type, and anything else is a persona that runs as a researcher. Rejecting
+  // what a spawn accepts would leave the two spawn shapes a caller most wants
+  // to preview (an alias, a persona) with no way to see their tool surface.
+  const resolved = resolveSubagentRole(agent);
+  const roleConfig = SUBAGENT_ROLE_REGISTRY[resolved.role];
 
   // Build the same context the SubagentManager creates at spawn time. The
   // resolver reads only this subset of Conversation state, so a minimal
@@ -525,6 +541,11 @@ function handleAgentToolList(agent: string): ToolNamesListResponse {
       ? new Set(roleConfig.allowedTools)
       : undefined,
     subagentToolGateMode: undefined,
+    // Roles that refuse side effects require an allowed name to resolve to a
+    // first-party built-in, so a workspace or plugin tool claiming one is off
+    // the surface. Without this the preview would advertise a tool the live
+    // subagent refuses at dispatch.
+    subagentDenySideEffects: roleConfig.denySideEffects === true,
     toolsDisabledDepth: 0,
     diskPressureCleanupModeActive: false,
     skillProjectionState: new Map<string, string>(),
@@ -533,12 +554,19 @@ function handleAgentToolList(agent: string): ToolNamesListResponse {
     preactivatedSkillIds: mergedSkillIds,
   } as unknown as Conversation;
 
+  const agentInfo: ResolvedAgentInfo = {
+    requested: agent,
+    role: resolved.role,
+    ...(resolved.alias ? { alias: resolved.alias } : {}),
+    ...(resolved.personaText ? { persona: resolved.personaText } : {}),
+  };
+
   // Run the real tool resolver — the same callback a subagent conversation
   // uses each turn. An empty message history simulates the first turn before
   // any skill activations have been recorded.
   const resolveTools = createResolveToolsCallback(toolDefs, ctx);
   if (!resolveTools) {
-    return { names: [], schemas: {}, tools: [] };
+    return { names: [], schemas: {}, tools: [], agent: agentInfo };
   }
   const resolvedDefs = resolveTools([]);
   const names = resolvedDefs
@@ -562,7 +590,7 @@ function handleAgentToolList(agent: string): ToolNamesListResponse {
     tools.push(toolEntryForName(name));
   }
 
-  return { names, schemas, tools };
+  return { names, schemas, tools, agent: agentInfo };
 }
 
 /**

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

@@ -23,10 +23,12 @@ import {
   listSkills,
   listSkillsFiltered,
   searchSkills,
+  skillExistsLocally,
   uninstallSkill,
   updateSkill,
 } from "../../daemon/handlers/skills.js";
 import { getCategories } from "../../skills/categories-cache.js";
+import { getSkillHistory } from "../../skills/skill-history.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -351,6 +353,83 @@ export const ROUTES: RouteDefinition[] = [
       return result;
     },
   },
+  {
+    operationId: "getSkillHistory",
+    endpoint: "skills/:id/history",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get skill revision history",
+    description:
+      "Return a skill's recent updates, newest first, each with a combined diff across the skill directory. Read-only: revisions come from the workspace git repository, which already retains prior content. Commits whose only in-skill change is the `lastUsedAt` usage stamp are omitted, so entries are edits rather than loads.",
+    tags: ["skills"],
+    queryParams: [
+      {
+        name: "limit",
+        schema: { type: "integer" },
+        required: false,
+        description:
+          "Maximum revisions to return, newest first. Defaults to 20 and is clamped to 100.",
+      },
+    ],
+    responseBody: z.object({
+      skillId: z.string().describe("The skill these revisions belong to"),
+      revisions: z
+        .array(
+          z.object({
+            id: z.string().describe("Opaque revision identifier"),
+            changedAt: z.string().describe("ISO-8601 time of the update"),
+            files: z
+              .array(z.string())
+              .describe("Paths changed, relative to the skill directory"),
+            diff: z
+              .string()
+              .describe("Unified diff of this update, scoped to the skill"),
+          }),
+        )
+        .describe("Recent updates, newest first"),
+      truncatedByCompaction: z
+        .boolean()
+        .describe(
+          "Older history was squashed away, so the oldest entry is a floor rather than the skill's creation",
+        ),
+    }),
+    handler: async ({ pathParams, queryParams }: RouteHandlerArgs) => {
+      const rawLimit = queryParams?.limit;
+      const limit =
+        typeof rawLimit === "string" && rawLimit.trim().length > 0
+          ? Number.parseInt(rawLimit, 10)
+          : undefined;
+      try {
+        // Same current-resource boundary as the file routes. Git retains a
+        // deleted skill's commits, so without this a removed skill keeps
+        // answering with history for something the rest of the API reports as
+        // gone. An existing skill with nothing recorded still gets an empty
+        // list, which is the honest answer for a bundled skill or one the
+        // workspace has not committed yet.
+        if (!skillExistsLocally(pathParams!.id)) {
+          throw new NotFoundError(`Skill "${pathParams!.id}" not found`);
+        }
+        return await getSkillHistory(pathParams!.id, {
+          ...(limit !== undefined && Number.isFinite(limit) ? { limit } : {}),
+        });
+      } catch (err) {
+        if (err instanceof NotFoundError) {
+          throw err;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        // The id reaches a git pathspec, so a malformed one is the caller's
+        // error. Anything else escaping the service is a server fault: the
+        // read is otherwise fail-soft and returns an empty history.
+        if (message.startsWith("Invalid skill id")) {
+          throw new BadRequestError(message);
+        }
+        throw new InternalError(message);
+      }
+    },
+  },
   {
     operationId: "enableSkill",
     endpoint: "skills/:id/enable",

package/src/runtime/routes/ui-snapshot-routes.ts

@@ -206,6 +206,7 @@ async function handleHostUiSnapshotResult({ body, headers }: RouteHandlerArgs) {
       targetActorPrincipalId: peeked.targetActorPrincipalId,
       targetClientId: peeked.targetClientId,
       op: "host_ui_snapshot",
+      hubForMissingTarget: assistantEventHub,
     });
   }