@hienlh/ppm 0.17.46 → 0.17.48

package/src/providers/claude-agent-sdk.ts

@@ -5,6 +5,7 @@ import {
   getSessionMessages,
 } from "@anthropic-ai/claude-agent-sdk";
 import { buildModelQueryOptions } from "./claude-agent-sdk-query-options.ts";
+import { isImageLimitRejection } from "./image-limit-detection.ts";
 import type {
   AIProvider,
   Session,
@@ -332,6 +333,56 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     return null;
   }
 
+  /**
+   * Remove the image payloads the API is refusing from a session's transcript.
+   *
+   * Called mid-turn, with the CLI subprocess for this session already torn down by the retry
+   * path, so nothing is appending while the file is rewritten. The transcript is the only
+   * place these images live, and the CLI replays it verbatim, so editing the file is the only
+   * way to stop them being re-sent.
+   *
+   * `includeAttachments` is the second, lossier pass: images the user attached are normally
+   * left alone, but once they are what is failing every turn, keeping them costs the whole
+   * session.
+   */
+  private async stripSessionImages(
+    sessionId: string,
+    includeAttachments: boolean,
+  ): Promise<{ removed: number; bytesFreed: number; reason: string; failed: boolean }> {
+    const dir = resolve(CLAUDE_PROJECTS_DIR);
+    if (!existsSync(dir)) return { removed: 0, bytesFreed: 0, reason: "no transcript directory", failed: true };
+    let jsonlPath = "";
+    for (const sub of readdirSync(dir)) {
+      const candidate = resolve(dir, sub, `${sessionId}.jsonl`);
+      if (existsSync(candidate)) { jsonlPath = candidate; break; }
+    }
+    if (!jsonlPath) return { removed: 0, bytesFreed: 0, reason: "transcript not found", failed: true };
+
+    try {
+      const { stripTranscriptImagesFile } = await import("../services/transcript-images-file.ts");
+      const r = await stripTranscriptImagesFile(jsonlPath, "oversized", { includeAttachments });
+      if (r.removed > 0) return { removed: r.removed, bytesFreed: r.bytesFreed, reason: "", failed: false };
+      // Only images at or over the measurable cap are ever removed automatically. Falling back
+      // to "all" here would delete in-range images too, on nothing better than a guess that the
+      // API is applying a cap we cannot see — and for an attachment the transcript holds the
+      // only copy. When no image measures oversized, stop and let the user decide from the
+      // session debug dialog, which still offers the unrestricted removal.
+      return {
+        removed: 0,
+        bytesFreed: 0,
+        reason: includeAttachments
+          ? "no image measures over the dimension cap"
+          : "no oversized images found",
+        failed: false,
+      };
+    } catch (e) {
+      // A throw means the rewrite was refused, most often because the transcript grew while it
+      // was being read. That says nothing about whether images are there to remove, so the
+      // caller must not read it as "nothing found" and escalate to the lossy pass.
+      return { removed: 0, bytesFreed: 0, reason: (e as Error).message, failed: true };
+    }
+  }
+
   private buildQueryEnv(
     _projectPath: string | undefined,
     account: { id: string; accessToken: string } | null,
@@ -1158,8 +1209,11 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       // Allow 2 refresh attempts per turn (token can rotate mid-conversation).
       // Counter resets on successful turn (see result handler) so next turn gets a fresh budget.
       const MAX_AUTH_RETRIES = 2;
+      // Two passes: oversized images first, then attachments. A third would have nothing left.
+      const MAX_IMAGE_RETRIES = 2;
       let retryCount = 0;
       let rateLimitRetryCount = 0;
+      let imageRetryCount = 0;
       let authRetryCount = 0;
       let hadAnyEvents = false;
       // Accounts that hit a hard usage/session limit this turn — never retried again here.
@@ -1435,6 +1489,16 @@ export class ClaudeAgentSdkProvider implements AIProvider {
             }
           }
 
+          // An image the API refuses poisons every later turn: the transcript is replayed in
+          // full each time, so the same rejected payload comes back and the session can never
+          // make progress again. Recognised even when `error` is already set, since the API
+          // reports it as invalid_request — a code that also covers faults which must surface
+          // as-is. See image-limit-detection.ts for why wording alone is not enough.
+          if (isImageLimitRejection(msg)) {
+            assistantError = "image_limit";
+            console.warn(`[sdk] session=${sessionId} API rejected an image in the replayed transcript — will strip and retry`);
+          }
+
           if (assistantError) {
             // Dump full SDK message for debugging
             console.error(`[sdk] session=${sessionId} cwd=${effectiveCwd} assistant error: ${assistantError} (isFirst=${isFirstMessage} retry=${retryCount})`);
@@ -1553,6 +1617,49 @@ export class ClaudeAgentSdkProvider implements AIProvider {
               break;
             }
 
+            // An image in the replayed transcript is being refused. Nothing about retrying the
+            // same bytes can succeed, and nothing else will ever remove them — the CLI keeps
+            // replaying the file — so the payload is taken out of the transcript and the turn
+            // is retried against the trimmed history.
+            //
+            // Escalates: first pass drops only images at or over the dimension cap, which is
+            // lossless because the API already refuses them. Only if that changed nothing does
+            // it take the attachments too, since by then the session is unusable either way and
+            // a lost screenshot beats a dead conversation.
+            if (assistantError === "image_limit") {
+              if (imageRetryCount >= MAX_IMAGE_RETRIES) {
+                console.warn(`[sdk] session=${sessionId} image limit persists after ${imageRetryCount} strip attempt(s) — stopping`);
+                yield { type: "error", message: "The API keeps refusing an image in this conversation, and removing the offending images did not clear it. Start a new session, or use /compact to summarise the history away." };
+                break;
+              }
+              const escalate = imageRetryCount > 0;
+              imageRetryCount++;
+              yield { type: "status_update", phase: "retrying", message: escalate ? "Removing attached images..." : "Removing oversized images..." };
+              // Close the subprocess before touching the file it appends to. Rewriting a
+              // transcript underneath a live CLI drops whatever it wrote in the meantime,
+              // which breaks the parentUuid chain and hides the history from that point back.
+              closeCurrentStream();
+              let stripped = await this.stripSessionImages(sessionId, escalate);
+              // Nothing oversized among the tool results, but an attachment can be over the cap
+              // too and only the opt-in pass reaches those. Skipped when the strip failed rather
+              // than came up empty — a refused rewrite is not evidence that attachments are the
+              // problem, and this pass is the one that deletes the only copy of them.
+              if (stripped.removed === 0 && !escalate && !stripped.failed) {
+                console.warn(`[sdk] session=${sessionId} nothing oversized to strip — escalating to attachments`);
+                imageRetryCount++;
+                yield { type: "status_update", phase: "retrying", message: "Removing attached images..." };
+                stripped = await this.stripSessionImages(sessionId, true);
+              }
+              if (stripped.removed === 0) {
+                console.warn(`[sdk] session=${sessionId} nothing left to strip (${stripped.reason}) — stopping`);
+                yield { type: "error", message: `The API refused an image in this conversation, but nothing could be removed automatically (${stripped.reason}). Open Session debug to remove images yourself, start a new session, or use /compact to summarise the history away.` };
+                break;
+              }
+              console.warn(`[sdk] session=${sessionId} stripped ${stripped.removed} image(s), ${(stripped.bytesFreed / 1048576).toFixed(2)}MB — retrying turn`);
+              eventSource = rebuildQuery(account);
+              continue retryLoop;
+            }
+
             const errorHints: Record<string, string> = {
               authentication_failed: "API authentication failed. Check your account credentials in Settings → Accounts.",
               billing_error: "Billing error on this account. Check your subscription status.",
@@ -1773,13 +1880,20 @@ export class ClaudeAgentSdkProvider implements AIProvider {
           resultSubtype = subtype;
           resultNumTurns = result.num_turns as number | undefined;
 
-          // Extract context window usage from modelUsage
+          // Extract context window usage from modelUsage.
+          // Cached prefix tokens occupy the context window exactly like fresh ones — they are
+          // only cheaper, not absent. Leaving them out made a warm session, where most of the
+          // prefix arrives as a cache read, report a fraction of the context it truly holds,
+          // so the meter stayed low while the session grew past the point of being affordable.
           const modelUsage = (result.modelUsage ?? result.model_usage) as Record<string, any> | undefined;
           if (modelUsage) {
             for (const usage of Object.values(modelUsage)) {
               const cw = usage.contextWindow ?? 0;
               if (cw > 0) {
-                const total = (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+                const total = (usage.inputTokens ?? 0)
+                  + (usage.cacheReadInputTokens ?? 0)
+                  + (usage.cacheCreationInputTokens ?? 0)
+                  + (usage.outputTokens ?? 0);
                 resultContextWindowPct = Math.min(Math.round((total / cw) * 100), 100);
                 break;
               }

package/src/providers/image-limit-detection.ts

@@ -0,0 +1,30 @@
+/**
+ * Recognise the API refusing an image that the replayed transcript keeps re-sending.
+ *
+ * The API reports this as `invalid_request`, a code that also covers faults which must surface
+ * to the user untouched, so the wording is what identifies it. Two phrasings are in use: one
+ * naming the dimension cap and telling the user to start a new session, and a softer one saying
+ * the image was removed.
+ *
+ * Wording alone is not enough to act on. A hit tears down the subprocess and rewrites the
+ * user's transcript, dropping image payloads — and for an attachment that payload is usually
+ * the only copy left. The same phrases are ordinary in any session that merely talks about
+ * images ("the hero image is too large", "try fewer images"), so an ungated match would do
+ * that damage to a perfectly healthy turn. Only the synthetic error record the CLI writes
+ * carries `isApiErrorMessage`, which is what separates the two.
+ */
+
+const IMAGE_REJECTION_WORDING =
+  /image[\s\S]{0,80}(dimension limit|could not be processed|too large)|fewer images/i;
+
+/** True when this assistant message is the API refusing an image, not prose about one. */
+export function isImageLimitRejection(msg: unknown): boolean {
+  if ((msg as { isApiErrorMessage?: unknown } | null)?.isApiErrorMessage !== true) return false;
+  const content = (msg as { message?: { content?: unknown } }).message?.content;
+  if (!Array.isArray(content)) return false;
+  const text = content
+    .filter((b: unknown) => (b as { type?: unknown })?.type === "text" && typeof (b as { text?: unknown }).text === "string")
+    .map((b: unknown) => (b as { text: string }).text)
+    .join("");
+  return text.length > 0 && IMAGE_REJECTION_WORDING.test(text);
+}

package/src/server/routes/chat.ts

@@ -14,7 +14,8 @@ import { getCachedUsage, refreshUsageNow } from "../../services/claude-usage.ser
 import { getSessionLog } from "../../services/session-log.service.ts";
 import { parseJsonlTranscript, validateJsonlPath } from "../../services/jsonl-transcript-parser.ts";
 import { aggregateTasks } from "../../services/task-status-aggregator.ts";
-import { auditTranscriptImages, stripTranscriptImages, MANY_IMAGE_DIMENSION_LIMIT, type StripMode } from "../../services/transcript-images.ts";
+import { MANY_IMAGE_DIMENSION_LIMIT, type StripMode } from "../../services/transcript-images.ts";
+import { auditTranscriptImagesFile, stripTranscriptImagesFile } from "../../services/transcript-images-file.ts";
 import { getSessionProjectPath, setSessionMetadata, setSessionTitle, getSessionTitle, getPinnedSessionIds, pinSession, unpinSession, deleteSessionMapping, deleteSessionMetadata, deleteSessionTitle, getAllUnread, clearSessionUnread, setSessionUnread } from "../../services/db.service.ts";
 import { setSessionTag, bulkSetSessionTag, getTagById, getSessionTags, getProjectDefaultTagId } from "../../services/tag.service.ts";
 import { recordBranch, resolveVersionGroup, resolveVersionMap, collapseTreesToHeads, hasChildren, deleteBranchesFor, getRootId } from "../../services/session-branch.service.ts";
@@ -754,31 +755,30 @@ function cacheHitRateOf(r: { input_tokens: number; cache_read_tokens: number; ca
   return prefix > 0 ? r.cache_read_tokens / prefix : 0;
 }
 
-/** Largest transcript the image routes will read into memory in one go. */
-const MAX_TRANSCRIPT_SCAN_BYTES = 64 * 1024 * 1024;
-
 /**
- * Locate a session transcript and read it, or explain why that was not possible.
+ * Locate a session transcript, or explain why that was not possible.
  *
  * The id becomes a filename, and the strip route writes to what this returns, so anything
  * that is not a plain session id is refused before it can reach into another directory.
+ *
+ * No size limit: both routes stream the file a record at a time, so a transcript costs one
+ * line of memory rather than its whole length. The cap that used to live here turned the
+ * cleanup off for exactly the transcripts big enough to need it.
  */
-function readTranscript(sessionId: string): { path: string; text: string } | { error: string; status: 400 | 404 | 413 } {
+function locateTranscript(sessionId: string): { path: string } | { error: string; status: 400 | 404 } {
   if (!/^[A-Za-z0-9_-]{8,64}$/.test(sessionId)) return { error: "Invalid session id", status: 400 };
   const { jsonlPath, exists } = resolveSessionJsonlPath(sessionId);
   if (!exists || !jsonlPath) return { error: "Transcript not found for this session", status: 404 };
-  if (statSync(jsonlPath).size > MAX_TRANSCRIPT_SCAN_BYTES) {
-    return { error: "Transcript too large to scan", status: 413 };
-  }
-  return { path: jsonlPath, text: readFileSync(jsonlPath, "utf8") };
+  return { path: jsonlPath };
 }
 
 /** GET /chat/sessions/:id/images — count the image payloads the transcript replays every turn */
-chatRoutes.get("/sessions/:id/images", (c) => {
+chatRoutes.get("/sessions/:id/images", async (c) => {
   try {
-    const read = readTranscript(c.req.param("id"));
-    if ("error" in read) return c.json(err(read.error), read.status);
-    return c.json(ok({ ...auditTranscriptImages(read.text), limit: MANY_IMAGE_DIMENSION_LIMIT }));
+    const found = locateTranscript(c.req.param("id"));
+    if ("error" in found) return c.json(err(found.error), found.status);
+    const audit = await auditTranscriptImagesFile(found.path);
+    return c.json(ok({ ...audit, limit: MANY_IMAGE_DIMENSION_LIMIT }));
   } catch (e) {
     return c.json(err((e as Error).message), 500);
   }
@@ -787,31 +787,34 @@ chatRoutes.get("/sessions/:id/images", (c) => {
 /**
  * POST /chat/sessions/:id/images/strip — replace image payloads with their placeholder text.
  *
- * Rewrites the transcript in place rather than swapping in a new file: the CLI holds the
- * original open in append mode, so a rename would leave it writing to an orphaned inode.
  * A turn in flight is refused outright, since the record it is midway through appending
  * would be lost by the rewrite.
+ *
+ * `includeAttachments` also clears images the user attached to their own messages. It is
+ * opt-in because the transcript usually holds the only copy, but it has to be reachable: one
+ * oversized attachment makes every later turn of the session fail, and nothing else can
+ * remove it.
  */
 chatRoutes.post("/sessions/:id/images/strip", async (c) => {
   try {
     const sessionId = c.req.param("id");
     const body = await c.req.json().catch(() => ({}));
     const mode: StripMode = (body as { mode?: unknown }).mode === "all" ? "all" : "oversized";
+    const includeAttachments = (body as { includeAttachments?: unknown }).includeAttachments === true;
 
     const { listRunningSessions } = await import("../ws/chat.ts");
     if (listRunningSessions().some((s) => s.sessionId === sessionId)) {
       return c.json(err("Session is running — wait for the turn to finish"), 409);
     }
 
-    const read = readTranscript(sessionId);
-    if ("error" in read) return c.json(err(read.error), read.status);
+    const found = locateTranscript(sessionId);
+    if ("error" in found) return c.json(err(found.error), found.status);
 
-    const result = stripTranscriptImages(read.text, mode);
-    if (result.removed > 0) writeFileSync(read.path, result.text);
+    const result = await stripTranscriptImagesFile(found.path, mode, { includeAttachments });
     return c.json(ok({
       removed: result.removed,
       bytesFreed: result.bytesFreed,
-      remaining: { ...auditTranscriptImages(result.text), limit: MANY_IMAGE_DIMENSION_LIMIT },
+      remaining: { ...result.remaining, limit: MANY_IMAGE_DIMENSION_LIMIT },
     }));
   } catch (e) {
     return c.json(err((e as Error).message), 500);

package/src/server/routes/upgrade.ts

@@ -7,25 +7,41 @@ import {
   compareSemver,
   applyUpgrade,
   signalSupervisorUpgrade,
+  getLatestPublishedVersion,
 } from "../../services/upgrade.service.ts";
 import { ok, err } from "../../types/api.ts";
 import { getPpmDir } from "../../services/ppm-dir.ts";
 
 export const upgradeRoutes = new Hono();
 
-/** GET / — upgrade status (current version, available version, install method) */
-upgradeRoutes.get("/", (c) => {
-  let availableVersion: string | null = null;
+/** Last version the supervisor's periodic check recorded, if any. */
+function readRecordedVersion(): string | null {
   try {
-    if (existsSync(resolve(getPpmDir(), "status.json"))) {
-      const data = JSON.parse(readFileSync(resolve(getPpmDir(), "status.json"), "utf-8"));
-      const candidate = data.availableVersion ?? null;
-      // Only report if actually newer than current version
-      if (candidate && compareSemver(VERSION, candidate) < 0) {
-        availableVersion = candidate;
-      }
-    }
-  } catch {}
+    const path = resolve(getPpmDir(), "status.json");
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf-8")).availableVersion ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check the registry directly rather than only reading what the supervisor
+ * recorded: that record is written 5min after startup and every 15min after,
+ * so a UI opened inside that window would see no update and offer no upgrade.
+ * The supervisor's record is the offline fallback.
+ */
+export async function resolveAvailableVersion(
+  getLatest: () => Promise<string | null> = getLatestPublishedVersion,
+): Promise<string | null> {
+  const candidate = (await getLatest()) ?? readRecordedVersion();
+  // Only report if actually newer than current version
+  return candidate && compareSemver(VERSION, candidate) < 0 ? candidate : null;
+}
+
+/** GET / — upgrade status (current version, available version, install method) */
+upgradeRoutes.get("/", async (c) => {
+  const availableVersion = await resolveAvailableVersion();
 
   return c.json(ok({
     currentVersion: VERSION,

package/src/server/ws/chat.ts

@@ -947,6 +947,33 @@ export const chatWebSocket = {
         setSessionThinking(sessionId, parsed.thinking ? THINKING_ADAPTIVE : 0);
       }
 
+      // Kits that self-namespace their skills (AgentKit's `/ak:debug`) publish a
+      // name the runtime never registers — it names plugin items after the plugin
+      // and directory instead. Rewrite before the echo so every consumer (other
+      // devices, the stored transcript, the SDK) sees the name that actually ran.
+      const typedContent = parsed.content.trimStart();
+      if (typedContent.startsWith("/")) {
+        const { listSlashItems, rewriteSlashAlias } = await import("../../services/slash-discovery/index.ts");
+        const canonical = rewriteSlashAlias(typedContent, listSlashItems(entry.projectPath ?? ""));
+        if (canonical !== typedContent) parsed.content = canonical;
+      }
+
+      // Echo the user message to OTHER connected clients (second device/tab).
+      // The sender renders it optimistically; without this echo a live-connected
+      // second device only sees the assistant stream for this turn.
+      if (entry.clients.size > 1) {
+        const echo = JSON.stringify({
+          type: "user_message",
+          content: parsed.content,
+          imageCount: parsed.images?.length ?? 0,
+          timestamp: new Date().toISOString(),
+        });
+        for (const client of entry.clients) {
+          if (client === ws) continue;
+          try { client.send(echo); } catch { evictClient(entry, client); }
+        }
+      }
+
       // Intercept PPM-handled built-in commands (e.g. /skills, /version)
       const content = parsed.content.trim();
       const slashMatch = content.match(/^\/(\S+)/);

package/src/services/slash-discovery/discover-skill-roots.ts

@@ -1,4 +1,4 @@
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, basename } from "node:path";
 import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -39,13 +39,14 @@ function addRoot(
   basePath: string,
   origin: ItemOrigin,
   source: DefinitionSource,
+  pluginName?: string,
 ): void {
   const full = resolve(basePath, origin);
   if (!isDir(full)) return;
   const resolved = resolve(full);
   if (seen.has(resolved)) return;
   seen.add(resolved);
-  roots.push({ path: resolved, source, origin });
+  roots.push({ path: resolved, source, origin, ...(pluginName && { pluginName }) });
 }
 
 /**
@@ -143,6 +144,23 @@ export function resolveInstalledPlugins(pluginsDir: string): InstalledPlugin[] {
   }
 }
 
+/**
+ * Plugin identifier used as the namespace prefix. The registry key is
+ * `plugin-id@marketplace-id`, so the id is everything before the `@`; scanned
+ * fallbacks read the manifest, and the directory name is the last resort.
+ */
+export function resolvePluginName(plugin: InstalledPlugin): string {
+  const fromKey = plugin.key?.split("@")[0]?.trim();
+  if (fromKey) return fromKey;
+  try {
+    const manifest = JSON.parse(
+      readFileSync(resolve(plugin.path, ".claude-plugin", "plugin.json"), "utf-8"),
+    ) as { name?: unknown };
+    if (typeof manifest.name === "string" && manifest.name.trim()) return manifest.name.trim();
+  } catch { /* manifest missing or malformed — fall through */ }
+  return basename(plugin.path);
+}
+
 /** Add roots for Claude Code plugins, which ship their own skills/commands/agents */
 function addPluginRoots(roots: SkillRoot[], seen: Set<string>, projectPath: string): void {
   const pluginsDir = resolve(homedir(), ".claude", "plugins");
@@ -150,8 +168,9 @@ function addPluginRoots(roots: SkillRoot[], seen: Set<string>, projectPath: stri
   const disabled = loadDisabledPluginKeys(projectPath);
   for (const plugin of resolveInstalledPlugins(pluginsDir)) {
     if (plugin.key && disabled.has(plugin.key)) continue;
+    const pluginName = resolvePluginName(plugin);
     for (const origin of ORIGINS) {
-      addRoot(roots, seen, plugin.path, origin, "user-plugin");
+      addRoot(roots, seen, plugin.path, origin, "user-plugin", pluginName);
     }
   }
 }

package/src/services/slash-discovery/index.ts

@@ -11,6 +11,7 @@ export { isPpmHandled, getBuiltinByName } from "./builtin-commands.ts";
 export { executeBuiltin } from "./builtin-handlers.ts";
 export { invalidateCache, invalidateAll } from "./cache.ts";
 export { ensureSdkCommands, invalidateSdkCommands } from "./sdk-commands.ts";
+export { rewriteSlashAlias } from "./rewrite-slash-alias.ts";
 export type { SlashItem, SlashItemWithSource, ShadowedItem, DiscoveryResult, SkillRoot, DefinitionSource } from "./types.ts";
 
 /**

package/src/services/slash-discovery/rewrite-slash-alias.ts

@@ -0,0 +1,35 @@
+import type { SlashItem } from "./types.ts";
+
+/** Split a leading `/name` off a message, if there is one. */
+function splitCommand(content: string): { name: string; rest: string } | null {
+  const match = content.match(/^\/(\S+)/);
+  if (!match) return null;
+  return { name: match[1]!, rest: content.slice(match[0].length) };
+}
+
+/**
+ * Rewrite a leading slash command that used a legacy alias into the name the
+ * runtime actually registers.
+ *
+ * Claude Code names a plugin item after its location, prefixed by the owning
+ * plugin (`/ak-engineer:ak-debug`). Kits that instead declare a self-namespaced
+ * frontmatter name (AgentKit ships `name: ak:debug`) publish a name nothing can
+ * resolve, so users typing the documented `/ak:debug` get a dead command. The
+ * declared name is kept as an alias during discovery; this turns it back into
+ * the canonical one.
+ *
+ * When two plugins claim the same alias — the AgentKit engineer and marketing
+ * kits overlap on ~30 skills — the first match in discovery order wins, which
+ * follows the plugin registry order.
+ *
+ * Unknown commands pass through untouched: reporting those is the SDK's job.
+ */
+export function rewriteSlashAlias(content: string, items: SlashItem[]): string {
+  const cmd = splitCommand(content);
+  if (!cmd) return content;
+  // A name that already resolves is never rewritten, even if some other item
+  // happens to alias it.
+  if (items.some((item) => item.name === cmd.name)) return content;
+  const hit = items.find((item) => item.aliases?.includes(cmd.name));
+  return hit ? `/${hit.name}${cmd.rest}` : content;
+}

package/src/services/slash-discovery/skill-loader.ts

@@ -53,6 +53,34 @@ function walkDir(dir: string, visitor: (filePath: string) => void, visited = new
   }
 }
 
+/**
+ * Resolve the invocable name for an item found under `root`.
+ *
+ * Plugin items are namespaced by their owning plugin, but the two kinds differ
+ * in what follows the prefix. A skill or command is named after where its file
+ * lives, so a kit that self-namespaces instead (AgentKit ships `name: ak:debug`)
+ * is not invocable under that declared name — it is kept as an alias so typed
+ * input can be rewritten to the canonical one. An agent is named after its
+ * frontmatter `name`, which is also how the runtime addresses it for delegation.
+ */
+function qualify(
+  root: SkillRoot,
+  pathName: string,
+  declared: string | undefined,
+  nameSource: "path" | "declared" = "path",
+): { name: string; aliases?: string[] } {
+  if (!root.pluginName) return { name: declared ?? pathName };
+  if (nameSource === "declared") {
+    const suffix = declared || pathName;
+    return { name: suffix ? `${root.pluginName}:${suffix}` : "" };
+  }
+  // A SKILL.md sitting at the plugin root has no directory to take a name from
+  const suffix = pathName || declared;
+  if (!suffix) return { name: "" };
+  const name = `${root.pluginName}:${suffix}`;
+  return { name, ...(declared && declared !== name && { aliases: [declared] }) };
+}
+
 /** Collect commands from a root with origin "commands" */
 function loadCommands(root: SkillRoot): SlashItemWithSource[] {
   const items: SlashItemWithSource[] = [];
@@ -66,10 +94,13 @@ function loadCommands(root: SkillRoot): SlashItemWithSource[] {
       const content = readFileSync(filePath, "utf-8");
       const { meta } = parseFrontmatter(content);
       const rel = relative(root.path, filePath);
-      const name = rel.replace(/\.md$/, "").split(sep).join("/");
+      const pathName = rel.replace(/\.md$/, "").split(sep).join("/");
+      const { name, aliases } = qualify(root, pathName, str(meta.name));
+      if (!name) return;
       items.push({
         type: "command",
-        name: str(meta.name) ?? name,
+        name,
+        ...(aliases && { aliases }),
         description: str(meta.description) ?? "",
         argumentHint: str(meta["argument-hint"]),
         scope,
@@ -106,11 +137,12 @@ function loadSkills(root: SkillRoot): SlashItemWithSource[] {
       dirsWithSkillMd.add(skillDir);
       const rel = relative(root.path, skillDir);
       const pathName = rel.split(sep).join("/");
-      const name = str(meta.name) ?? pathName;
+      const { name, aliases } = qualify(root, pathName, str(meta.name));
       if (!name) return;
       items.push({
         type: "skill",
         name,
+        ...(aliases && { aliases }),
         description: str(meta.description) ?? "",
         argumentHint: str(meta["argument-hint"]),
         scope,
@@ -136,11 +168,12 @@ function loadSkills(root: SkillRoot): SlashItemWithSource[] {
         const { meta } = parseFrontmatter(content);
         const rel = relative(root.path, filePath);
         const pathName = rel.replace(/\.md$/, "").split(sep).join("/");
-        const name = str(meta.name) ?? pathName;
+        const { name, aliases } = qualify(root, pathName, str(meta.name));
         if (!name) return;
         items.push({
           type: "skill",
           name,
+          ...(aliases && { aliases }),
           description: str(meta.description) ?? "",
           argumentHint: str(meta["argument-hint"]),
           scope,
@@ -168,7 +201,9 @@ function loadAgents(root: SkillRoot): SlashItemWithSource[] {
       const content = readFileSync(filePath, "utf-8");
       const { meta } = parseFrontmatter(content);
       const rel = relative(root.path, filePath);
-      const name = str(meta.name) ?? rel.replace(/\.md$/, "").split(sep).join("/");
+      const pathName = rel.replace(/\.md$/, "").split(sep).join("/");
+      const { name } = qualify(root, pathName, str(meta.name), "declared");
+      if (!name) return;
       items.push({
         type: "agent",
         name,

package/src/services/slash-discovery/types.ts

@@ -41,6 +41,12 @@ export interface SkillRoot {
   path: string;              // Resolved absolute path
   source: DefinitionSource;
   origin: ItemOrigin;
+  /**
+   * Owning Claude Code plugin, set only for roots under ~/.claude/plugins/.
+   * Items below such a root are namespaced `<pluginName>:<path>`, matching how
+   * Claude Code itself registers them.
+   */
+  pluginName?: string;
 }
 
 /** Extends SlashItem with source metadata */