@vellumai/assistant 0.4.49 → 0.4.50

package/src/config/schemas/memory-retrieval.ts

@@ -1,22 +1,5 @@
 import { z } from "zod";
 
-export const MemoryRerankingConfigSchema = z.object({
-  enabled: z
-    .boolean({ error: "memory.retrieval.reranking.enabled must be a boolean" })
-    .default(false),
-  modelIntent: z
-    .enum(["latency-optimized", "quality-optimized", "vision-optimized"], {
-      error:
-        "memory.retrieval.reranking.modelIntent must be a valid model intent",
-    })
-    .default("latency-optimized"),
-  topK: z
-    .number({ error: "memory.retrieval.reranking.topK must be a number" })
-    .int("memory.retrieval.reranking.topK must be an integer")
-    .positive("memory.retrieval.reranking.topK must be a positive integer")
-    .default(20),
-});
-
 export const MemoryDynamicBudgetConfigSchema = z.object({
   enabled: z
     .boolean({
@@ -55,49 +38,6 @@ export const MemoryDynamicBudgetConfigSchema = z.object({
     .default(10000),
 });
 
-export const MemoryEarlyTerminationConfigSchema = z.object({
-  enabled: z
-    .boolean({
-      error: "memory.retrieval.earlyTermination.enabled must be a boolean",
-    })
-    .default(true),
-  minCandidates: z
-    .number({
-      error: "memory.retrieval.earlyTermination.minCandidates must be a number",
-    })
-    .int("memory.retrieval.earlyTermination.minCandidates must be an integer")
-    .positive(
-      "memory.retrieval.earlyTermination.minCandidates must be a positive integer",
-    )
-    .default(20),
-  minHighConfidence: z
-    .number({
-      error:
-        "memory.retrieval.earlyTermination.minHighConfidence must be a number",
-    })
-    .int(
-      "memory.retrieval.earlyTermination.minHighConfidence must be an integer",
-    )
-    .positive(
-      "memory.retrieval.earlyTermination.minHighConfidence must be a positive integer",
-    )
-    .default(10),
-  confidenceThreshold: z
-    .number({
-      error:
-        "memory.retrieval.earlyTermination.confidenceThreshold must be a number",
-    })
-    .min(
-      0,
-      "memory.retrieval.earlyTermination.confidenceThreshold must be >= 0",
-    )
-    .max(
-      1,
-      "memory.retrieval.earlyTermination.confidenceThreshold must be <= 1",
-    )
-    .default(0.7),
-});
-
 /**
  * Per-kind freshness windows (in days). Items older than their window
  * (based on lastSeenAt) are down-ranked unless recently reinforced.
@@ -109,12 +49,13 @@ const MemoryFreshnessConfigSchema = z.object({
     .default(true),
   maxAgeDays: z
     .object({
-      fact: z
+      identity: z
         .number({
-          error: "memory.retrieval.freshness.maxAgeDays.fact must be a number",
+          error:
+            "memory.retrieval.freshness.maxAgeDays.identity must be a number",
         })
         .nonnegative(
-          "memory.retrieval.freshness.maxAgeDays.fact must be non-negative",
+          "memory.retrieval.freshness.maxAgeDays.identity must be non-negative",
         )
         .default(0),
       preference: z
@@ -126,34 +67,50 @@ const MemoryFreshnessConfigSchema = z.object({
           "memory.retrieval.freshness.maxAgeDays.preference must be non-negative",
         )
         .default(0),
-      behavior: z
+      project: z
         .number({
           error:
-            "memory.retrieval.freshness.maxAgeDays.behavior must be a number",
+            "memory.retrieval.freshness.maxAgeDays.project must be a number",
         })
         .nonnegative(
-          "memory.retrieval.freshness.maxAgeDays.behavior must be non-negative",
+          "memory.retrieval.freshness.maxAgeDays.project must be non-negative",
         )
-        .default(90),
-      event: z
+        .default(30),
+      decision: z
         .number({
-          error: "memory.retrieval.freshness.maxAgeDays.event must be a number",
+          error:
+            "memory.retrieval.freshness.maxAgeDays.decision must be a number",
         })
         .nonnegative(
-          "memory.retrieval.freshness.maxAgeDays.event must be non-negative",
+          "memory.retrieval.freshness.maxAgeDays.decision must be non-negative",
         )
         .default(30),
-      opinion: z
+      constraint: z
         .number({
           error:
-            "memory.retrieval.freshness.maxAgeDays.opinion must be a number",
+            "memory.retrieval.freshness.maxAgeDays.constraint must be a number",
+        })
+        .nonnegative(
+          "memory.retrieval.freshness.maxAgeDays.constraint must be non-negative",
+        )
+        .default(90),
+      event: z
+        .number({
+          error: "memory.retrieval.freshness.maxAgeDays.event must be a number",
         })
         .nonnegative(
-          "memory.retrieval.freshness.maxAgeDays.opinion must be non-negative",
+          "memory.retrieval.freshness.maxAgeDays.event must be non-negative",
         )
-        .default(60),
+        .default(30),
     })
-    .default({ fact: 0, preference: 0, behavior: 90, event: 30, opinion: 60 }),
+    .default({
+      identity: 0,
+      preference: 0,
+      project: 30,
+      decision: 30,
+      constraint: 90,
+      event: 30,
+    }),
   staleDecay: z
     .number({ error: "memory.retrieval.freshness.staleDecay must be a number" })
     .min(0, "memory.retrieval.freshness.staleDecay must be >= 0")
@@ -171,36 +128,11 @@ const MemoryFreshnessConfigSchema = z.object({
 });
 
 export const MemoryRetrievalConfigSchema = z.object({
-  lexicalTopK: z
-    .number({ error: "memory.retrieval.lexicalTopK must be a number" })
-    .int("memory.retrieval.lexicalTopK must be an integer")
-    .positive("memory.retrieval.lexicalTopK must be a positive integer")
-    .default(80),
-  semanticTopK: z
-    .number({ error: "memory.retrieval.semanticTopK must be a number" })
-    .int("memory.retrieval.semanticTopK must be an integer")
-    .positive("memory.retrieval.semanticTopK must be a positive integer")
-    .default(40),
   maxInjectTokens: z
     .number({ error: "memory.retrieval.maxInjectTokens must be a number" })
     .int("memory.retrieval.maxInjectTokens must be an integer")
     .positive("memory.retrieval.maxInjectTokens must be a positive integer")
     .default(10000),
-  injectionFormat: z
-    .enum(["markdown", "structured_v1"], {
-      error:
-        'memory.retrieval.injectionFormat must be "markdown" or "structured_v1"',
-    })
-    .default("markdown"),
-  injectionStrategy: z
-    .enum(["prepend_user_block", "separate_context_message"], {
-      error:
-        'memory.retrieval.injectionStrategy must be "prepend_user_block" or "separate_context_message"',
-    })
-    .default("prepend_user_block"),
-  reranking: MemoryRerankingConfigSchema.default(
-    MemoryRerankingConfigSchema.parse({}),
-  ),
   freshness: MemoryFreshnessConfigSchema.default(
     MemoryFreshnessConfigSchema.parse({}),
   ),
@@ -213,10 +145,6 @@ export const MemoryRetrievalConfigSchema = z.object({
   dynamicBudget: MemoryDynamicBudgetConfigSchema.default(
     MemoryDynamicBudgetConfigSchema.parse({}),
   ),
-  earlyTermination: MemoryEarlyTerminationConfigSchema.default(
-    MemoryEarlyTerminationConfigSchema.parse({}),
-  ),
 });
 
-export type MemoryRerankingConfig = z.infer<typeof MemoryRerankingConfigSchema>;
 export type MemoryRetrievalConfig = z.infer<typeof MemoryRetrievalConfigSchema>;

package/src/config/schemas/memory.ts

@@ -6,10 +6,7 @@ import {
   MemoryRetentionConfigSchema,
 } from "./memory-lifecycle.js";
 import {
-  MemoryConflictsConfigSchema,
-  MemoryEntityConfigSchema,
   MemoryExtractionConfigSchema,
-  MemoryProfileConfigSchema,
   MemorySummarizationConfigSchema,
 } from "./memory-processing.js";
 import { MemoryRetrievalConfigSchema } from "./memory-retrieval.js";
@@ -46,13 +43,6 @@ export const MemoryConfigSchema = z.object({
   summarization: MemorySummarizationConfigSchema.default(
     MemorySummarizationConfigSchema.parse({}),
   ),
-  entity: MemoryEntityConfigSchema.default(MemoryEntityConfigSchema.parse({})),
-  conflicts: MemoryConflictsConfigSchema.default(
-    MemoryConflictsConfigSchema.parse({}),
-  ),
-  profile: MemoryProfileConfigSchema.default(
-    MemoryProfileConfigSchema.parse({}),
-  ),
 });
 
 export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;

package/src/config/types.ts

@@ -12,13 +12,9 @@ export type {
   IngressConfig,
   LogFileConfig,
   MemoryConfig,
-  MemoryConflictsConfig,
   MemoryEmbeddingsConfig,
-  MemoryEntityConfig,
   MemoryExtractionConfig,
   MemoryJobsConfig,
-  MemoryProfileConfig,
-  MemoryRerankingConfig,
   MemoryRetentionConfig,
   MemoryRetrievalConfig,
   MemorySegmentationConfig,

package/src/context/window-manager.ts

@@ -671,7 +671,10 @@ function countPersistedMessages(messages: Message[]): number {
 function isToolResultOnly(message: Message): boolean {
   return (
     message.content.length > 0 &&
-    message.content.every((block) => block.type === "tool_result")
+    message.content.every(
+      (block) =>
+        block.type === "tool_result" || block.type === "web_search_tool_result",
+    )
   );
 }
 

package/src/daemon/config-watcher.ts

@@ -3,7 +3,13 @@
  * Watches workspace files (config, prompts), protected directory
  * (trust rules, secret allowlist), and skills directories for changes.
  */
-import { existsSync, type FSWatcher, readdirSync, watch } from "node:fs";
+import {
+  existsSync,
+  type FSWatcher,
+  mkdirSync,
+  readdirSync,
+  watch,
+} from "node:fs";
 import { join } from "node:path";
 
 import { getConfig, invalidateConfigCache } from "../config/loader.js";
@@ -98,8 +104,14 @@ export class ConfigWatcher {
    * Start all file watchers. `onSessionEvict` is called when watched
    * files change and sessions need to be evicted for reload.
    * `onIdentityChanged` is called when IDENTITY.md changes on disk.
+   * `onMcpReload` is called when the MCP section of config.json changes
+   * or when a signal file appears in the workspace `signals/` directory.
    */
-  start(onSessionEvict: () => void, onIdentityChanged?: () => void): void {
+  start(
+    onSessionEvict: () => void,
+    onIdentityChanged?: () => void,
+    onMcpReload?: () => void,
+  ): void {
     const workspaceDir = getWorkspaceDir();
     const protectedDir = join(getRootDir(), "protected");
 
@@ -107,8 +119,17 @@ export class ConfigWatcher {
       "config.json": () => {
         if (this.suppressReload) return;
         try {
+          const prevConfig = getConfig();
+          const prevMcpFingerprint = JSON.stringify(prevConfig.mcp ?? {});
           const changed = this.refreshConfigFromSources();
-          if (changed) onSessionEvict();
+          if (changed) {
+            onSessionEvict();
+            const newConfig = getConfig();
+            const newMcpFingerprint = JSON.stringify(newConfig.mcp ?? {});
+            if (newMcpFingerprint !== prevMcpFingerprint) {
+              onMcpReload?.();
+            }
+          }
         } catch (err) {
           log.error(
             { err, configPath: join(workspaceDir, "config.json") },
@@ -185,6 +206,7 @@ export class ConfigWatcher {
       );
     }
 
+    this.startSignalsWatcher(onMcpReload);
     this.startSkillsWatchers(onSessionEvict);
   }
 
@@ -196,6 +218,42 @@ export class ConfigWatcher {
     this.watchers = [];
   }
 
+  private startSignalsWatcher(onMcpReload?: () => void): void {
+    const signalsDir = join(getWorkspaceDir(), "signals");
+    try {
+      if (!existsSync(signalsDir)) {
+        mkdirSync(signalsDir, { recursive: true });
+      }
+    } catch {
+      // If we can't create it, watching will also fail — handled below.
+    }
+
+    const signalHandlers: Record<string, () => void> = {
+      "mcp-reload": () => {
+        onMcpReload?.();
+      },
+    };
+
+    try {
+      const watcher = watch(signalsDir, (_eventType, filename) => {
+        if (!filename) return;
+        const file = String(filename);
+        if (!signalHandlers[file]) return;
+        this.debounceTimers.schedule(`signal:${file}`, () => {
+          log.info({ file }, "Signal file detected");
+          signalHandlers[file]();
+        });
+      });
+      this.watchers.push(watcher);
+      log.info({ dir: signalsDir }, "Watching signals directory");
+    } catch (err) {
+      log.warn(
+        { err, dir: signalsDir },
+        "Failed to watch signals directory. Signal-based reload will be unavailable.",
+      );
+    }
+  }
+
   private startSkillsWatchers(onSessionEvict: () => void): void {
     const skillsDir = getWorkspaceSkillsDir();
     if (!existsSync(skillsDir)) return;

package/src/daemon/daemon-control.ts

@@ -143,7 +143,7 @@ function healthCheckHost(host: string): string {
 /** Hit the daemon's HTTP /healthz endpoint. Returns true if it responds
  *  with HTTP 200 within the timeout — false on connection refused, timeout,
  *  or any other error. */
-async function isHttpHealthy(): Promise<boolean> {
+export async function isHttpHealthy(): Promise<boolean> {
   const host = healthCheckHost(getRuntimeHttpHost());
   const port = getRuntimeHttpPort();
   try {

package/src/daemon/date-context.ts

@@ -33,10 +33,6 @@ const WEEKDAY_NAMES = [
   "Friday",
   "Saturday",
 ] as const;
-const TIMEZONE_SUBJECT_LINE_RE = /^\s*-\s*time\s*zone\s*:\s*(.+)$/i;
-const TIMEZONE_SUBJECT_COMPACT_RE = /^\s*-\s*timezone\s*:\s*(.+)$/i;
-const TIMEZONE_TOKEN_RE =
-  /\b(?:[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+)+|(?:UTC|GMT)(?:[+-]\d{1,2}(?::?\d{2})?)?)\b/gi;
 const UTC_GMT_OFFSET_TOKEN_RE = /^(?:UTC|GMT)([+-])(\d{1,2})(?::?(\d{2}))?$/i;
 
 function normalizeOffsetToken(offsetToken: string): string {
@@ -111,6 +107,17 @@ function canonicalizeTimeZone(timeZone: string): string | null {
       return null;
     }
   }
+  // Check abbreviation mapping before Intl (many abbreviations are not recognized by Intl)
+  const abbrIana = TIMEZONE_ABBREVIATIONS[trimmed.toUpperCase()];
+  if (abbrIana) {
+    try {
+      return new Intl.DateTimeFormat("en-US", {
+        timeZone: abbrIana,
+      }).resolvedOptions().timeZone;
+    } catch {
+      return null;
+    }
+  }
   try {
     return new Intl.DateTimeFormat("en-US", {
       timeZone: trimmed,
@@ -120,47 +127,123 @@ function canonicalizeTimeZone(timeZone: string): string | null {
   }
 }
 
-function extractTimeZoneCandidates(text: string): string[] {
-  const matches = (text.match(TIMEZONE_TOKEN_RE) ?? [])
-    .map((token) => token.trim())
-    .filter((token) => token.length > 0);
-  const ianaTokens = matches.filter((token) => token.includes("/"));
-  const offsetTokens = matches.filter((token) => !token.includes("/"));
-  return [...ianaTokens, ...offsetTokens];
-}
+/**
+ * Common timezone abbreviation → IANA identifier mapping.
+ * Used as a fallback when `Intl.DateTimeFormat` does not recognize the abbreviation.
+ */
+const TIMEZONE_ABBREVIATIONS: Record<string, string> = {
+  // North America
+  PST: "America/Los_Angeles",
+  PDT: "America/Los_Angeles",
+  MST: "America/Denver",
+  MDT: "America/Denver",
+  CST: "America/Chicago",
+  CDT: "America/Chicago",
+  EST: "America/New_York",
+  EDT: "America/New_York",
+  AKST: "America/Anchorage",
+  AKDT: "America/Anchorage",
+  HST: "Pacific/Honolulu",
+  AST: "America/Puerto_Rico",
+  NST: "America/St_Johns",
+  NDT: "America/St_Johns",
+  // Europe
+  BST: "Europe/London",
+  CET: "Europe/Paris",
+  CEST: "Europe/Paris",
+  EET: "Europe/Athens",
+  EEST: "Europe/Athens",
+  WEST: "Europe/Lisbon",
+  MSK: "Europe/Moscow",
+  // Asia / Oceania
+  JST: "Asia/Tokyo",
+  KST: "Asia/Seoul",
+  HKT: "Asia/Hong_Kong",
+  SGT: "Asia/Singapore",
+  WIB: "Asia/Jakarta",
+  PHT: "Asia/Manila",
+  PKT: "Asia/Karachi",
+  NPT: "Asia/Kathmandu",
+  AEST: "Australia/Sydney",
+  AEDT: "Australia/Sydney",
+  ACST: "Australia/Adelaide",
+  ACDT: "Australia/Adelaide",
+  AWST: "Australia/Perth",
+  NZST: "Pacific/Auckland",
+  NZDT: "Pacific/Auckland",
+  // South America
+  BRT: "America/Sao_Paulo",
+};
 
 /**
- * Extract a valid user timezone from compiled `<dynamic-user-profile>` text.
+ * Regex matching IANA timezone identifiers (e.g. "America/New_York"),
+ * UTC/GMT offset tokens (e.g. "UTC+5", "GMT-8:30"), and common
+ * timezone abbreviations (e.g. "PST", "EST", "JST").
  *
- * Prefers explicit `timezone:` profile lines, then falls back to scanning the
- * full profile body for valid IANA timezone identifiers.
+ * Abbreviation alternation is built from `TIMEZONE_ABBREVIATIONS` keys.
  */
-export function extractUserTimeZoneFromDynamicProfile(
-  profileText: string,
+const TIMEZONE_ABBR_ALTERNATION = Object.keys(TIMEZONE_ABBREVIATIONS).join("|");
+const TIMEZONE_TOKEN_RE = new RegExp(
+  `\\b(?:[A-Za-z][A-Za-z0-9_+-]*(?:/[A-Za-z0-9_+-]+)+|(?:UTC|GMT)(?:[+-]\\d{1,2}(?::?\\d{2})?)?|(?:${TIMEZONE_ABBR_ALTERNATION}))\\b`,
+  "gi",
+);
+
+/**
+ * Extract the user's timezone from V2 memory recall injected text.
+ *
+ * Scans the `<user_identity>` section (if present) for lines containing
+ * "timezone" and tries to resolve an IANA identifier. Falls back to
+ * scanning the full text body.
+ */
+export function extractUserTimeZoneFromRecall(
+  injectedText: string,
 ): string | null {
-  const trimmed = profileText.trim();
-  if (trimmed.length === 0) return null;
+  if (!injectedText || injectedText.trim().length === 0) return null;
 
-  const candidateTexts: string[] = [];
-  for (const line of trimmed.split("\n")) {
-    const match =
-      line.match(TIMEZONE_SUBJECT_LINE_RE) ??
-      line.match(TIMEZONE_SUBJECT_COMPACT_RE);
-    if (match) {
-      candidateTexts.push(match[1]);
+  // Prefer lines inside <user_identity> that mention "timezone"
+  const identityMatch = injectedText.match(
+    /<user_identity>([\s\S]*?)<\/user_identity>/,
+  );
+  if (identityMatch) {
+    const identityBlock = identityMatch[1];
+    for (const line of identityBlock.split("\n")) {
+      if (/time\s*zone/i.test(line)) {
+        for (const token of extractTimeZoneCandidates(line)) {
+          const canonical = canonicalizeTimeZone(token);
+          if (canonical) return canonical;
+        }
+      }
     }
-  }
-  candidateTexts.push(trimmed);
-
-  for (const text of candidateTexts) {
-    for (const token of extractTimeZoneCandidates(text)) {
+    // Scan full identity block for any timezone token
+    for (const token of extractTimeZoneCandidates(identityBlock)) {
       const canonical = canonicalizeTimeZone(token);
       if (canonical) return canonical;
     }
   }
+
+  // Fallback: scan entire injected text for timezone tokens in
+  // lines that mention "timezone"
+  for (const line of injectedText.split("\n")) {
+    if (/time\s*zone/i.test(line)) {
+      for (const token of extractTimeZoneCandidates(line)) {
+        const canonical = canonicalizeTimeZone(token);
+        if (canonical) return canonical;
+      }
+    }
+  }
+
   return null;
 }
 
+function extractTimeZoneCandidates(text: string): string[] {
+  const matches = (text.match(TIMEZONE_TOKEN_RE) ?? [])
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+  const ianaTokens = matches.filter((token) => token.includes("/"));
+  const offsetTokens = matches.filter((token) => !token.includes("/"));
+  return [...ianaTokens, ...offsetTokens];
+}
+
 /**
  * Get the local date parts for a given instant in the specified timezone.
  */

package/src/daemon/handlers/sessions.ts

@@ -421,8 +421,11 @@ export async function handleSessionCreate(
         pendingInteractions.resolve(requestId);
       });
       session.setHostFileProxy(fileProxy);
-      const cuProxy = new HostCuProxy(sendEvent);
+      const cuProxy = new HostCuProxy(sendEvent, (requestId) => {
+        pendingInteractions.resolve(requestId);
+      });
       session.setHostCuProxy(cuProxy);
+      session.addPreactivatedSkillId("computer-use");
     }
     session.updateClient(sendEvent, false);
     session
@@ -575,23 +578,24 @@ export function handleCancel(msg: CancelRequest, ctx: HandlerContext): void {
 }
 
 /**
- * Undo the last message in a session. Returns the removed count, or null if session not found.
+ * Undo the last message in a session. Returns the removed count, or null if
+ * the conversation does not exist. Restores evicted sessions from the database.
  */
-export function undoLastMessage(
+export async function undoLastMessage(
   sessionId: string,
   ctx: HandlerContext,
-): { removedCount: number } | null {
-  const session = ctx.sessions.get(sessionId);
-  if (!session) {
+): Promise<{ removedCount: number } | null> {
+  if (!getConversation(sessionId)) {
     return null;
   }
+  const session = await ctx.getOrCreateSession(sessionId);
   ctx.touchSession(sessionId);
   const removedCount = session.undo();
   return { removedCount };
 }
 
-export function handleUndo(msg: UndoRequest, ctx: HandlerContext): void {
-  const result = undoLastMessage(msg.sessionId, ctx);
+export async function handleUndo(msg: UndoRequest, ctx: HandlerContext): Promise<void> {
+  const result = await undoLastMessage(msg.sessionId, ctx);
   if (!result) {
     ctx.send({ type: "error", message: "No active session" });
     return;
@@ -606,17 +610,18 @@ export function handleUndo(msg: UndoRequest, ctx: HandlerContext): void {
 /**
  * Regenerate the last assistant response for a session. The caller provides
  * a `sendEvent` callback for delivering streaming events via HTTP/SSE.
- * Returns null if the session is not found. Throws on regeneration errors.
+ * Returns null if the conversation does not exist. Restores evicted sessions
+ * from the database when needed. Throws on regeneration errors.
  */
 export async function regenerateResponse(
   sessionId: string,
   ctx: HandlerContext,
   sendEvent: (event: ServerMessage) => void,
 ): Promise<{ requestId: string } | null> {
-  const session = ctx.sessions.get(sessionId);
-  if (!session) {
+  if (!getConversation(sessionId)) {
     return null;
   }
+  const session = await ctx.getOrCreateSession(sessionId);
   ctx.touchSession(sessionId);
   session.updateClient(sendEvent, false);
   const requestId = uuid();
@@ -647,11 +652,11 @@ export async function handleRegenerate(
   msg: RegenerateRequest,
   ctx: HandlerContext,
 ): Promise<void> {
-  const session = ctx.sessions.get(msg.sessionId);
-  if (!session) {
+  if (!getConversation(msg.sessionId)) {
     ctx.send({ type: "error", message: "No active session" });
     return;
   }
+  const session = await ctx.getOrCreateSession(msg.sessionId);
 
   const regenerateChannel =
     parseChannelId(session.getTurnChannelContext()?.assistantMessageChannel) ??

package/src/daemon/handlers/skills.ts

@@ -250,12 +250,20 @@ export interface SkillListItem {
   provenance: SkillProvenance;
 }
 
+/** Sorting rank for provenance-based ordering: first-party first, local last. */
+function provenanceSortRank(p: SkillProvenance): number {
+  if (p.kind === "first-party") return 0;
+  if (p.kind === "third-party" && p.provider) return 1;
+  if (p.kind === "third-party") return 2;
+  return 3; // local
+}
+
 export function listSkills(_ctx: SkillOperationContext): SkillListItem[] {
   const config = getConfig();
   const catalog = loadSkillCatalog();
   const resolved = resolveSkillStates(catalog, config);
 
-  return resolved.map((r) => ({
+  const items = resolved.map((r) => ({
     id: r.summary.id,
     name: r.summary.displayName,
     description: r.summary.description,
@@ -272,6 +280,17 @@ export function listSkills(_ctx: SkillOperationContext): SkillListItem[] {
     userInvocable: r.summary.userInvocable,
     provenance: resolveProvenance(r.summary),
   }));
+
+  // Sort: first-party > third-party with provider > third-party without > local,
+  // alphabetical by name within each tier.
+  items.sort((a, b) => {
+    const rankDiff =
+      provenanceSortRank(a.provenance) - provenanceSortRank(b.provenance);
+    if (rankDiff !== 0) return rankDiff;
+    return a.name.localeCompare(b.name);
+  });
+
+  return items;
 }
 
 export function enableSkill(