@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/src/plugins/cli-notifier.ts

@@ -7,34 +7,77 @@ import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agen
 
 const execFileAsync = promisify(execFile);
 const maxMessageLength = 2048;
+const maxTitleLength = 256;
+const maxReasonLength = 1024;
 const maxNotifications = 20;
+const defaultTimeoutMs = 10_000;
+const maxCommandOutputBytes = 256 * 1024;
+const windowsNotificationScript =
+  "$message = [System.Security.SecurityElement]::Escape([string]$env:PI_HARNESS_NOTIFICATION_MESSAGE); $title = [System.Security.SecurityElement]::Escape([string]$env:PI_HARNESS_NOTIFICATION_TITLE); [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null; $xml = New-Object Windows.Data.Xml.Dom.XmlDocument; $xml.LoadXml(\"<toast><visual><binding template='ToastText02'><text id='1'>$message</text><text id='2'>$title</text></binding></visual></toast>\"); [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Pi Harness').Show([Windows.UI.Notifications.ToastNotification]::new($xml))";
 type Notification = { time: string; title: string; message: string; delivered: boolean; reason?: string };
 type NotificationResult = { title: string; message: string; delivered: boolean; platform: NodeJS.Platform; reason?: string };
 
 export interface CliNotifierPluginConfig {
   enabled?: boolean;
   title?: string;
+  timeoutMs?: number;
 }
 
-export const Config: z<CliNotifierPluginConfig> = z.object({ enabled: z.boolean().default(true), title: z.string().default("Pi Harness") });
+export const Config: z<CliNotifierPluginConfig> = z.object({
+  enabled: z.boolean().default(true),
+  title: z.string().max(maxTitleLength).default("Pi Harness"),
+  timeoutMs: z.number().min(100).max(60_000).step(1).default(defaultTimeoutMs),
+});
 
 function appleScriptString(value: string): string {
-  return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", " ")}"`;
+  return `"${value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replace(/[\r\n\u2028\u2029]/gu, " ")}"`;
 }
 
-async function deliver(title: string, message: string): Promise<NotificationResult> {
+function boundedEventMessage(value: string): string {
+  return value.length <= maxMessageLength ? value : `${value.slice(0, maxMessageLength - 1)}…`;
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error("Desktop notification was cancelled", { cause: signal.reason });
+}
+
+function normalizeText(value: unknown, label: "message" | "title", maximum: number): string {
+  if (typeof value !== "string") throw new Error(`Notification ${label} must be a string`);
+  if (value.length === 0 || value.length > maximum || value.trim().length === 0 || value.includes("\0"))
+    throw new Error(`Notification ${label} must be non-blank text between 1 and ${maximum} characters without null bytes`);
+  return value;
+}
+
+function normalizeTimeout(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return defaultTimeoutMs;
+  return Math.max(100, Math.min(60_000, Math.trunc(value)));
+}
+
+function boundedReason(value: unknown): string {
+  const reason = value instanceof Error ? value.message : String(value);
+  return reason.length <= maxReasonLength ? reason : `${reason.slice(0, maxReasonLength - 1)}…`;
+}
+
+async function deliver(title: string, message: string, timeoutMs: number, signal: AbortSignal): Promise<NotificationResult> {
   const platform = process.platform;
+  const options = { timeout: timeoutMs, maxBuffer: maxCommandOutputBytes, signal };
   if (platform === "darwin") {
-    await execFileAsync("osascript", ["-e", `display notification ${appleScriptString(message)} with title ${appleScriptString(title)}`]);
+    await execFileAsync("osascript", ["-e", `display notification ${appleScriptString(message)} with title ${appleScriptString(title)}`], options);
     return { title, message, delivered: true, platform };
   }
   if (platform === "linux") {
-    await execFileAsync("notify-send", [title, message]);
+    await execFileAsync("notify-send", ["--", title, message], options);
     return { title, message, delivered: true, platform };
   }
   if (platform === "win32") {
-    const script = `[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null; $xml = New-Object Windows.Data.Xml.Dom.XmlDocument; $xml.LoadXml('<toast><visual><binding template="ToastText02"><text id="1">${message.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}</text><text id="2">${title.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")}</text></binding></visual></toast>'); [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Pi Harness').Show([Windows.UI.Notifications.ToastNotification]::new($xml))`;
-    await execFileAsync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", script]);
+    await execFileAsync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", windowsNotificationScript], {
+      ...options,
+      env: { ...process.env, PI_HARNESS_NOTIFICATION_MESSAGE: message, PI_HARNESS_NOTIFICATION_TITLE: title },
+    });
     return { title, message, delivered: true, platform };
   }
   return { title, message, delivered: false, platform, reason: "unsupported-platform" };
@@ -44,32 +87,43 @@ export default {
   name: "pi-cli-notifier",
   inject: ["piPluginUi", "piTools"],
   Config,
-  apply(context: Context, config: CliNotifierPluginConfig) {
+  apply(context: Context, config: CliNotifierPluginConfig = {}) {
+    if (config.enabled !== undefined && typeof config.enabled !== "boolean") throw new Error("CLI Notifier enabled must be a boolean");
     const enabled = config.enabled !== false;
-    const defaultTitle = config.title?.trim() || "Pi Harness";
+    const configuredTitle = config.title === undefined || config.title.trim() === "" ? "Pi Harness" : config.title.trim();
+    const defaultTitle = normalizeText(configuredTitle, "title", maxTitleLength);
+    const timeoutMs = normalizeTimeout(config.timeoutMs);
+    const lifecycle = new AbortController();
+    let deliveryQueue: Promise<void> = Promise.resolve();
     const notifications: Notification[] = [];
-    const notify = async (message: string, title = defaultTitle): Promise<NotificationResult> => {
-      if (message.length === 0 || message.length > maxMessageLength)
-        throw new Error(`Notification message must be between 1 and ${maxMessageLength} characters`);
-      if (title.length === 0 || title.length > 256) throw new Error("Notification title must be between 1 and 256 characters");
+    const record = (result: NotificationResult): NotificationResult => {
+      notifications.unshift({ time: new Date().toISOString(), ...result });
+      notifications.splice(maxNotifications);
+      return result;
+    };
+    const notify = async (messageValue: unknown, titleValue: unknown = defaultTitle, signal = lifecycle.signal): Promise<NotificationResult> => {
+      const message = normalizeText(messageValue, "message", maxMessageLength);
+      const title = normalizeText(titleValue, "title", maxTitleLength);
+      throwIfAborted(signal);
       if (!enabled) {
-        const result: NotificationResult = { title, message, delivered: false, platform: process.platform, reason: "disabled" };
-        notifications.unshift({ time: new Date().toISOString(), ...result });
-        notifications.splice(maxNotifications);
-        return result;
-      }
-      try {
-        const result = await deliver(title, message);
-        notifications.unshift({ time: new Date().toISOString(), ...result });
-        notifications.splice(maxNotifications);
-        return result;
-      } catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        const result: NotificationResult = { title, message, delivered: false, platform: process.platform, reason };
-        notifications.unshift({ time: new Date().toISOString(), ...result });
-        notifications.splice(maxNotifications);
-        return result;
+        return record({ title, message, delivered: false, platform: process.platform, reason: "disabled" });
       }
+      const operation = deliveryQueue.then(async () => {
+        throwIfAborted(signal);
+        try {
+          return record(await deliver(title, message, timeoutMs, signal));
+        } catch (error) {
+          throwIfAborted(signal);
+          const timedOut = typeof error === "object" && error !== null && "killed" in error && (error as { killed?: unknown }).killed === true;
+          const reason = timedOut ? `Notification command timed out after ${timeoutMs} ms` : boundedReason(error);
+          return record({ title, message, delivered: false, platform: process.platform, reason });
+        }
+      });
+      deliveryQueue = operation.then(
+        () => undefined,
+        () => undefined,
+      );
+      return operation;
     };
     const unregisterTool = context.piTools.register(
       defineTool({
@@ -77,17 +131,23 @@ export default {
         label: "CLI notify",
         description: "Send a local desktop notification without invoking a shell.",
         promptSnippet: "send a desktop notification when this task finishes",
-        parameters: Type.Object({
-          message: Type.String({ description: "Notification body" }),
-          title: Type.Optional(Type.String({ description: "Notification title" })),
-        }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<NotificationResult>> {
-          const result = await notify(params.message, params.title ?? defaultTitle);
+        parameters: Type.Object(
+          {
+            message: Type.String({ description: "Notification body", minLength: 1, maxLength: maxMessageLength }),
+            title: Type.Optional(Type.String({ description: "Notification title", minLength: 1, maxLength: maxTitleLength })),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
+        async execute(_toolCallId, params, signal): Promise<AgentToolResult<NotificationResult>> {
+          const record = params !== null && typeof params === "object" && !Array.isArray(params) ? (params as Record<string, unknown>) : {};
+          const actionSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+          const result = await notify(record.message, record.title ?? defaultTitle, actionSignal);
           return {
             content: [
               { type: "text", text: result.delivered ? "Desktop notification sent." : `Desktop notification not sent: ${result.reason ?? "unknown reason"}` },
             ],
-            details: result,
+            details: structuredClone(result),
           };
         },
       }),
@@ -97,15 +157,23 @@ export default {
         type?: string;
         messages?: readonly { role?: string; stopReason?: string; errorMessage?: string }[];
         errorMessage?: string;
+        willRetry?: boolean;
       };
-      if (current.type === "agent_end") {
+      if (current.type === "agent_end" && current.willRetry !== true) {
         const last = current.messages?.at(-1);
         if (last?.role === "assistant") {
-          const message = last.stopReason === "error" ? `Agent failed: ${last.errorMessage ?? "unknown error"}` : "Agent turn completed.";
-          void notify(message);
+          const message =
+            last.stopReason === "error"
+              ? `Agent failed: ${last.errorMessage ?? "unknown error"}`
+              : last.stopReason === "aborted"
+                ? "Agent turn aborted."
+                : last.stopReason === "length"
+                  ? "Agent turn stopped at the model output limit."
+                  : "Agent turn completed.";
+          void notify(boundedEventMessage(message), defaultTitle, lifecycle.signal).catch(() => undefined);
         }
       } else if (current.type === "compaction_end" && current.errorMessage) {
-        void notify(`Context compaction failed: ${current.errorMessage}`);
+        void notify(boundedEventMessage(`Context compaction failed: ${current.errorMessage}`), defaultTitle, lifecycle.signal).catch(() => undefined);
       }
     });
     const disposePanel = context.piPluginUi.register({
@@ -114,9 +182,10 @@ export default {
       title: "CLI Notifier",
       description: "长任务完成后发送本机桌面通知。",
       icon: "♢",
-      read: () => ({ enabled, platform: process.platform, notifications: [...notifications] }),
+      read: () => ({ enabled, platform: process.platform, timeoutMs, notifications: structuredClone(notifications) }),
     });
     context.effect(() => () => {
+      lifecycle.abort(new Error("CLI Notifier plugin disposed"));
       unregisterTool();
       unsubscribeSession();
       disposePanel();

package/packages/core/src/plugins/code2skill.ts

@@ -1,12 +1,19 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, join, relative, resolve } from "node:path";
+import { lstat, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, sep } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type AgentToolResult } from "@earendil-works/pi-coding-agent";
+import { readBoundedFile } from "../bounded-file.js";
+import { prepareWorkspaceFile, resolveExistingWorkspacePath } from "../workspace-path.js";
+import { EmptyConfig } from "../config.js";
 
 const maxFiles = 32;
+const maxNameLength = 128;
+const maxDescriptionLength = 1024;
+const maxPathLength = 4096;
 const maxFileBytes = 256 * 1024;
 const maxTotalBytes = 2 * 1024 * 1024;
+const parameterNames = new Set(["name", "description", "files"]);
 
 type SkillFile = { path: string; bytes: number };
 type SkillReport = { slug: string; directory: string; files: SkillFile[]; bytes: number };
@@ -18,52 +25,160 @@ function slugify(name: string): string {
     .replace(/[^a-z0-9]+/gu, "-")
     .replace(/^-+|-+$/gu, "")
     .slice(0, 64);
-  if (slug.length === 0) throw new Error("Skill name must contain at least one letter or number");
+  if (slug.length === 0) throw new Error("Skill name must contain at least one ASCII letter or number");
   return slug;
 }
 
-function resolveWorkspaceFile(cwd: string, input: string): { absolute: string; display: string } {
+function throwIfAborted(signal: AbortSignal): void {
+  if (!signal.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error("Skill creation was cancelled", { cause: signal.reason });
+}
+
+function hasControlCharacters(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)!;
+    if (codePoint <= 31 || codePoint === 127) return true;
+  }
+  return false;
+}
+
+function parseParams(value: unknown): { name: string; description: string; files: string[] } {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Skill parameters must be an object");
+  let descriptors: PropertyDescriptorMap;
+  try {
+    const prototype = Object.getPrototypeOf(value) as unknown;
+    if (prototype !== Object.prototype && prototype !== null) throw new Error("Skill parameters must be a plain object");
+    descriptors = Object.getOwnPropertyDescriptors(value);
+  } catch (error) {
+    if (error instanceof Error && error.message === "Skill parameters must be a plain object") throw error;
+    throw new Error("Skill parameters must be an accessible plain object", { cause: error });
+  }
+  if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !parameterNames.has(key)))
+    throw new Error("Skill parameters contain an unknown property");
+  if (Object.values(descriptors).some((descriptor) => !("value" in descriptor))) throw new Error("Skill parameters must use data properties");
+  const name: unknown = descriptors.name?.value;
+  const description: unknown = descriptors.description?.value;
+  const rawFiles: unknown = descriptors.files?.value;
+  if (typeof name !== "string" || name.trim().length === 0 || name.length > maxNameLength || name.includes("\0"))
+    throw new Error(`Skill name must be non-blank text between 1 and ${maxNameLength} characters`);
+  if (typeof description !== "string" || description.trim().length === 0 || description.length > maxDescriptionLength || description.includes("\0"))
+    throw new Error(`Skill description must be non-blank text between 1 and ${maxDescriptionLength} characters`);
+  if (!Array.isArray(rawFiles)) throw new Error(`Skill files must contain between 1 and ${maxFiles} source paths`);
+  let fileDescriptors: Record<PropertyKey, PropertyDescriptor>;
+  try {
+    if (Object.getPrototypeOf(rawFiles) !== Array.prototype) throw new Error("Skill files must be a plain array");
+    fileDescriptors = Object.getOwnPropertyDescriptors(rawFiles) as unknown as Record<PropertyKey, PropertyDescriptor>;
+  } catch (error) {
+    if (error instanceof Error && error.message === "Skill files must be a plain array") throw error;
+    throw new Error("Skill files must be an accessible plain array", { cause: error });
+  }
+  const length: unknown = fileDescriptors.length?.value;
+  if (typeof length !== "number" || !Number.isSafeInteger(length) || length === 0 || length > maxFiles)
+    throw new Error(`Skill files must contain between 1 and ${maxFiles} source paths`);
+  if (Reflect.ownKeys(fileDescriptors).some((key) => typeof key !== "string" || (key !== "length" && !/^(0|[1-9]\d*)$/u.test(key))))
+    throw new Error("Skill files contain an unknown property");
+  const files: string[] = [];
+  for (let index = 0; index < length; index += 1) {
+    const descriptor = fileDescriptors[String(index)];
+    if (descriptor === undefined || !("value" in descriptor)) throw new Error("Skill files must be a dense array of data properties");
+    const file: unknown = descriptor.value;
+    if (typeof file !== "string" || file.trim().length === 0 || file.length > maxPathLength || hasControlCharacters(file))
+      throw new Error(`Each skill file must be a non-empty relative path of at most ${maxPathLength} characters`);
+    files.push(file);
+  }
+  return { name, description, files };
+}
+
+function markdownLabel(value: string): string {
+  return value.replaceAll("\\", "\\\\").replaceAll("[", "\\[").replaceAll("]", "\\]");
+}
+
+function markdownTarget(value: string): string {
+  return value
+    .split("/")
+    .map((component) => encodeURIComponent(component).replace(/[!'()*]/gu, (character) => `%${character.codePointAt(0)!.toString(16).toUpperCase()}`))
+    .join("/");
+}
+
+function isMissing(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && (error as { code?: unknown }).code === "ENOENT";
+}
+
+async function assertSkillTargetAvailable(directory: string, slug: string, boundaryError: string): Promise<void> {
+  try {
+    const metadata = await lstat(directory);
+    if (metadata.isSymbolicLink()) throw new Error(boundaryError);
+    throw new Error(`Skill pack already exists: ${slug}`);
+  } catch (error) {
+    if (!isMissing(error)) throw error;
+  }
+}
+
+async function resolveWorkspaceFile(cwd: string, input: string): Promise<{ absolute: string; display: string }> {
   if (typeof input !== "string" || input.trim() === "" || isAbsolute(input)) throw new Error("Skill files must be non-empty relative paths");
-  const absolute = resolve(cwd, input);
-  const display = relative(cwd, absolute);
-  if (display === "" || display.startsWith("..") || isAbsolute(display)) throw new Error(`Skill file must stay inside the workspace: ${input}`);
-  return { absolute, display };
+  const resolved = await resolveExistingWorkspacePath(cwd, input, `Skill file must stay inside the workspace: ${input}`);
+  if (resolved.relativePath === ".") throw new Error(`Skill file must stay inside the workspace: ${input}`);
+  return { absolute: resolved.target, display: resolved.relativePath.split(sep).join("/") };
 }
 
-async function createSkill(context: Context, params: { name: string; description: string; files: string[] }): Promise<SkillReport> {
-  if (!Array.isArray(params.files) || params.files.length === 0) throw new Error("At least one source file is required");
-  if (params.files.length > maxFiles) throw new Error(`A skill can include at most ${maxFiles} files`);
+async function createSkill(context: Context, params: { name: string; description: string; files: string[] }, signal: AbortSignal): Promise<SkillReport> {
+  throwIfAborted(signal);
   const cwd = context.piHarnessLaunch.cwd;
-  const slug = slugify(params.name);
-  const sources = params.files.map((file) => resolveWorkspaceFile(cwd, file));
+  const displayName = params.name.trim().replace(/\s+/gu, " ");
+  const slug = slugify(displayName);
+  const description = params.description.trim();
+  const sources = [];
+  for (const file of params.files) {
+    throwIfAborted(signal);
+    sources.push(await resolveWorkspaceFile(cwd, file));
+  }
   const unique = new Set(sources.map((source) => source.display));
   if (unique.size !== sources.length) throw new Error("Skill files must be unique");
   let bytes = 0;
-  const files: SkillFile[] = [];
-  const output = join(cwd, ".pi", "skills", slug);
+  const loaded: Array<SkillFile & { content: Buffer }> = [];
   for (const source of sources) {
-    const content = await readFile(source.absolute);
-    if (content.byteLength > maxFileBytes) throw new Error(`Skill file exceeds ${maxFileBytes} bytes: ${source.display}`);
+    throwIfAborted(signal);
+    const content = await readBoundedFile(source.absolute, maxFileBytes, `Skill file ${source.display}`);
     bytes += content.byteLength;
     if (bytes > maxTotalBytes) throw new Error(`Skill sources exceed ${maxTotalBytes} bytes`);
-    const target = join(output, "references", source.display);
-    await mkdir(resolve(target, ".."), { recursive: true });
-    await writeFile(target, content);
-    files.push({ path: source.display, bytes: content.byteLength });
+    loaded.push({ path: source.display, bytes: content.byteLength, content });
   }
-  const description = params.description.trim();
-  if (description.length === 0) throw new Error("Skill description must not be empty");
-  const references = files.map((file) => `- [${file.path}](references/${file.path})`).join("\n");
-  const markdown = `---\nname: ${slug}\ndescription: ${description.replaceAll("\n", " ")}\n---\n\n# ${params.name.trim()}\n\n${description}\n\n## Reference files\n\n${references}\n`;
-  await mkdir(output, { recursive: true });
-  await writeFile(join(output, "SKILL.md"), markdown, "utf8");
-  return { slug, directory: output, files, bytes };
+  const boundaryError = "Skill output path must stay inside the workspace and must not overwrite an existing skill";
+  const boundary = await prepareWorkspaceFile(cwd, join(".pi", "skills", ".code2skill-boundary"), boundaryError);
+  const skillsDirectory = dirname(boundary.target);
+  const finalDirectory = join(skillsDirectory, slug);
+  await assertSkillTargetAvailable(finalDirectory, slug, boundaryError);
+  const files = loaded.map((file) => ({ path: file.path, bytes: file.bytes }));
+  const references = files.map((file) => `- [${markdownLabel(file.path)}](references/${markdownTarget(file.path)})`).join("\n");
+  const frontmatterDescription = description.replace(/\s+/gu, " ");
+  const markdown = `---\nname: ${slug}\ndescription: ${JSON.stringify(frontmatterDescription)}\n---\n\n# ${displayName}\n\n${description}\n\n## Reference files\n\n${references}\n`;
+  const stagingDirectory = await mkdtemp(join(skillsDirectory, ".code2skill-"));
+  try {
+    for (const [index, file] of loaded.entries()) {
+      throwIfAborted(signal);
+      const target = join(stagingDirectory, "references", ...file.path.split("/"));
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, loaded[index]!.content, { flag: "wx", mode: 0o600 });
+    }
+    throwIfAborted(signal);
+    await writeFile(join(stagingDirectory, "SKILL.md"), markdown, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    throwIfAborted(signal);
+    await assertSkillTargetAvailable(finalDirectory, slug, boundaryError);
+    await rename(stagingDirectory, finalDirectory);
+  } catch (error) {
+    await rm(stagingDirectory, { recursive: true, force: true });
+    throw error;
+  }
+  return { slug, directory: join(".pi", "skills", slug), files, bytes };
 }
 
 export default {
   name: "pi-code2skill",
   inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
+  Config: EmptyConfig,
   apply(context: Context) {
+    const lifecycle = new AbortController();
+    let creationQueue: Promise<void> = Promise.resolve();
     let generated = 0;
     let latest: SkillReport | undefined;
     const unregisterTool = context.piTools.register(
@@ -72,11 +187,36 @@ export default {
         label: "Create skill pack",
         description: "Package selected workspace source files into a local .pi/skills skill with a manifest and references.",
         promptSnippet: "turn selected project files into a reusable skill pack",
-        parameters: Type.Object({ name: Type.String(), description: Type.String(), files: Type.Array(Type.String()) }),
-        async execute(_toolCallId, params): Promise<AgentToolResult<SkillReport>> {
-          latest = await createSkill(context, params);
-          generated += 1;
-          return { content: [{ type: "text", text: `Skill pack created: ${latest.slug} (${latest.files.length} file(s)).` }], details: latest };
+        parameters: Type.Object(
+          {
+            name: Type.String({ minLength: 1, maxLength: maxNameLength }),
+            description: Type.String({ minLength: 1, maxLength: maxDescriptionLength }),
+            files: Type.Array(Type.String({ minLength: 1, maxLength: maxPathLength, pattern: "^[^\\u0000-\\u001F\\u007F]+$" }), {
+              minItems: 1,
+              maxItems: maxFiles,
+            }),
+          },
+          { additionalProperties: false },
+        ),
+        executionMode: "sequential",
+        async execute(_toolCallId, params, signal): Promise<AgentToolResult<SkillReport>> {
+          const validated = parseParams(params);
+          const actionSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([signal, lifecycle.signal]);
+          throwIfAborted(actionSignal);
+          const operation = creationQueue.then(async () => {
+            const report = await createSkill(context, validated, actionSignal);
+            latest = report;
+            generated += 1;
+            return {
+              content: [{ type: "text" as const, text: `Skill pack created: ${report.slug} (${report.files.length} file(s)).` }],
+              details: structuredClone(report),
+            };
+          });
+          creationQueue = operation.then(
+            () => undefined,
+            () => undefined,
+          );
+          return operation;
         },
       }),
     );
@@ -86,9 +226,10 @@ export default {
       title: "Code2Skill",
       description: "把工作区代码打包为可复用的 Pi Skill，保留来源文件并生成 SKILL.md。",
       icon: "✦",
-      read: () => ({ generated, latest: latest ?? null }),
+      read: () => ({ generated, latest: latest === undefined ? null : structuredClone(latest) }),
     });
     context.effect(() => () => {
+      lifecycle.abort(new Error("Code2Skill plugin disposed"));
       unregisterTool();
       disposePanel();
     });