@oh-my-pi/pi-coding-agent 14.9.9 → 15.0.0

package/src/eval/js/shared/rewrite-imports.ts

@@ -1,9 +1,10 @@
 import { parse as babelParse } from "@babel/parser";
 
-// Static ESM `import` declarations are not valid inside vm.runInContext (script-mode parsing).
-// We rewrite top-level imports to dynamic-import expressions in the user-supplied source so
-// pasted ESM runs verbatim. A real parser keeps imports embedded in string literals, template
-// literals, or comments intact.
+// Static ESM `import` declarations are not valid inside vm.runInContext (script-mode parsing),
+// and dynamic `import(...)` would otherwise resolve specifiers against the worker module's URL
+// instead of the session cwd. We rewrite both forms so they route through the worker-injected
+// `__omp_import__` helper, which resolves the specifier against the active session cwd. A real
+// parser keeps imports embedded in string literals, template literals, or comments intact.
 
 type BabelImportDeclaration = {
 	type: "ImportDeclaration";
@@ -25,26 +26,78 @@ type BabelLexicalDecl =
 	| { type: "VariableDeclaration"; kind: "const" | "let" | "var"; start: number; end: number }
 	| { type: "ClassDeclaration"; start: number; end: number; id: { start: number; end: number; name: string } | null };
 
-function buildDynamicImportCall(sourceLiteral: string, withClause: string | undefined): string {
+type BabelExpressionStatement = {
+	type: "ExpressionStatement";
+	start: number;
+	end: number;
+	expression?: { type?: string };
+};
+
+type BabelProgramNode = BabelImportDeclaration | BabelLexicalDecl | BabelExpressionStatement | { type: string };
+
+type BabelNode = { type: string; start: number; end: number; [key: string]: unknown };
+
+function parseProgram(code: string): { program: { body: ReadonlyArray<BabelProgramNode> } } | null {
+	try {
+		return babelParse(code, {
+			sourceType: "module",
+			allowAwaitOutsideFunction: true,
+			allowReturnOutsideFunction: true,
+			allowImportExportEverywhere: true,
+			allowNewTargetOutsideFunction: true,
+			allowSuperOutsideMethod: true,
+			allowUndeclaredExports: true,
+			errorRecovery: true,
+		}) as unknown as { program: { body: ReadonlyArray<BabelProgramNode> } };
+	} catch {
+		return null;
+	}
+}
+
+function buildOmpImportCall(sourceLiteral: string, optionsLiteral: string | undefined): string {
 	// Route every static import through the worker-injected `__omp_import__` helper so the
 	// specifier resolves against the session cwd (and `with`-attribute imports keep working).
-	return withClause ? `__omp_import__(${sourceLiteral}, ${withClause})` : `__omp_import__(${sourceLiteral})`;
+	return optionsLiteral ? `__omp_import__(${sourceLiteral}, ${optionsLiteral})` : `__omp_import__(${sourceLiteral})`;
 }
 
-function buildWithClause(node: BabelImportDeclaration): string | undefined {
+// Walks every node in `root`, depth-first, invoking `visit` on each one. Skips Babel's
+// non-AST bookkeeping fields so we don't recurse into source locations or comment arrays.
+function walkNodes(root: unknown, visit: (node: BabelNode) => void): void {
+	const stack: unknown[] = [root];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (!current || typeof current !== "object") continue;
+		if (Array.isArray(current)) {
+			for (let i = current.length - 1; i >= 0; i--) stack.push(current[i]);
+			continue;
+		}
+		const node = current as Record<string, unknown>;
+		if (typeof node.type === "string") visit(node as unknown as BabelNode);
+		for (const key in node) {
+			if (key === "loc" || key === "extra" || key === "range") continue;
+			if (key === "leadingComments" || key === "trailingComments" || key === "innerComments") continue;
+			const value = node[key];
+			if (value && typeof value === "object") stack.push(value);
+		}
+	}
+}
+
+function buildOptionsLiteral(node: BabelImportDeclaration): string | undefined {
 	const attrs = node.attributes;
 	if (!attrs || attrs.length === 0) return undefined;
 	const pairs = attrs.map(attr => {
 		const key = attr.key.type === "Identifier" ? attr.key.name : JSON.stringify(attr.key.value);
 		return `${key}: ${JSON.stringify(attr.value.value)}`;
 	});
-	return `{ ${pairs.join(", ")} }`;
+	// Native dynamic import takes options as `{ with: { ... } }`. `__omp_import__` forwards the
+	// options bag verbatim, so we wrap the attribute pairs accordingly.
+	return `{ with: { ${pairs.join(", ")} } }`;
 }
 
 function rewriteImportNode(node: BabelImportDeclaration): string {
 	const sourceLiteral = JSON.stringify(node.source.value);
-	const withClause = buildWithClause(node);
-	const importCall = buildDynamicImportCall(sourceLiteral, withClause);
+	const optionsLiteral = buildOptionsLiteral(node);
+	const importCall = buildOmpImportCall(sourceLiteral, optionsLiteral);
 
 	let defaultName: string | undefined;
 	let namespaceName: string | undefined;
@@ -73,37 +126,43 @@ function rewriteImportNode(node: BabelImportDeclaration): string {
 	return `await ${importCall};`;
 }
 
-export function rewriteStaticImports(code: string): string {
+export function rewriteImports(code: string): string {
 	if (!code.includes("import")) return code;
 
-	let ast: { program: { body: ReadonlyArray<{ type: string }> } };
-	try {
-		ast = babelParse(code, {
-			sourceType: "module",
-			allowAwaitOutsideFunction: true,
-			allowReturnOutsideFunction: true,
-			allowImportExportEverywhere: true,
-			allowNewTargetOutsideFunction: true,
-			allowSuperOutsideMethod: true,
-			allowUndeclaredExports: true,
-			errorRecovery: true,
-		}) as unknown as typeof ast;
-	} catch {
+	const ast = parseProgram(code);
+	if (!ast) {
 		// Parser bailed entirely — let the VM surface the real syntax error.
 		return code;
 	}
 
-	const imports: BabelImportDeclaration[] = [];
+	type Edit = { start: number; end: number; text: string };
+	const edits: Edit[] = [];
+
+	// Top-level static `import` declarations become `await __omp_import__(...)` calls.
 	for (const node of ast.program.body) {
-		if (node.type === "ImportDeclaration") imports.push(node as unknown as BabelImportDeclaration);
+		if (node.type !== "ImportDeclaration") continue;
+		const decl = node as unknown as BabelImportDeclaration;
+		edits.push({ start: decl.start, end: decl.end, text: rewriteImportNode(decl) });
 	}
-	if (imports.length === 0) return code;
+
+	// Dynamic `import(...)` expressions (anywhere) get their callee swapped for `__omp_import__`
+	// so the specifier resolves against the session cwd instead of the worker module's URL.
+	walkNodes(ast, node => {
+		if (node.type !== "CallExpression") return;
+		const call = node as unknown as { callee?: { type?: string; start?: number; end?: number } };
+		const callee = call.callee;
+		if (!callee || callee.type !== "Import" || typeof callee.start !== "number" || typeof callee.end !== "number")
+			return;
+		edits.push({ start: callee.start, end: callee.end, text: "__omp_import__" });
+	});
+
+	if (edits.length === 0) return code;
 
 	// Splice from the back so earlier offsets stay valid.
-	imports.sort((a, b) => b.start - a.start);
+	edits.sort((a, b) => b.start - a.start);
 	let result = code;
-	for (const node of imports) {
-		result = result.slice(0, node.start) + rewriteImportNode(node) + result.slice(node.end);
+	for (const edit of edits) {
+		result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
 	}
 	return result;
 }
@@ -124,19 +183,8 @@ export function rewriteStaticImports(code: string): string {
 export function demoteTopLevelLexicals(code: string): string {
 	if (!/\b(?:const|let|class)\b/.test(code)) return code;
 
-	let ast: { program: { body: ReadonlyArray<{ type: string }> } };
-	try {
-		ast = babelParse(code, {
-			sourceType: "module",
-			allowAwaitOutsideFunction: true,
-			allowReturnOutsideFunction: true,
-			allowImportExportEverywhere: true,
-			allowNewTargetOutsideFunction: true,
-			allowSuperOutsideMethod: true,
-			allowUndeclaredExports: true,
-			errorRecovery: true,
-		}) as unknown as typeof ast;
-	} catch {
+	const ast = parseProgram(code);
+	if (!ast) {
 		return code;
 	}
 
@@ -172,6 +220,24 @@ export function demoteTopLevelLexicals(code: string): string {
 	return result;
 }
 
+function returnFinalExpression(code: string): { source: string; returned: boolean } {
+	const ast = parseProgram(code);
+	const body = ast?.program.body;
+	if (!body) return { source: code, returned: false };
+	let lastIndex = body.length - 1;
+	while (lastIndex >= 0 && body[lastIndex]?.type === "EmptyStatement") lastIndex--;
+	const last = lastIndex >= 0 ? body[lastIndex] : undefined;
+	if (last?.type !== "ExpressionStatement") return { source: code, returned: false };
+
+	const expression = last as BabelExpressionStatement;
+	const prefix = code.slice(0, expression.start);
+	const statement = code.slice(expression.start, expression.end);
+	const suffix = code.slice(expression.end);
+	const semicolonMatch = statement.match(/;\s*$/);
+	const trimmedStatement = semicolonMatch ? statement.slice(0, semicolonMatch.index) : statement;
+	return { source: `${prefix}__omp_set_final_expr__((${trimmedStatement}));${suffix}`, returned: true };
+}
+
 /**
  * Strip TypeScript syntax (type annotations, `interface`, `as`, `satisfies`, generics in
  * call expressions, etc.) before the import/lexical rewriters parse the code. We use Bun's
@@ -198,14 +264,20 @@ export function stripTypeScript(code: string): string {
 const LOOKS_LIKE_TS =
 	/(?:\binterface\s+\w|\btype\s+\w+\s*=|\b(?:as|satisfies)\s+(?:[A-Z]|\bconst\b)|:\s*(?:string|number|boolean|any|unknown|void|never|object|[A-Z]\w*)\b|<\s*[A-Z]\w*\s*[,>])/;
 
-export function wrapCode(code: string): { source: string; asyncWrapped: boolean } {
-	const rewritten = demoteTopLevelLexicals(rewriteStaticImports(stripTypeScript(code)));
-	const needsAsyncWrapper = /\bawait\b|\breturn\b/.test(rewritten);
+export function wrapCode(code: string): { source: string; asyncWrapped: boolean; finalExpressionReturned: boolean } {
+	const stripped = stripTypeScript(code);
+	const finalExpression = returnFinalExpression(stripped);
+	const rewritten = {
+		source: demoteTopLevelLexicals(rewriteImports(finalExpression.source)),
+		returned: finalExpression.returned,
+	};
+	const needsAsyncWrapper = /\bawait\b|\breturn\b/.test(rewritten.source);
 	if (!needsAsyncWrapper) {
-		return { source: rewritten, asyncWrapped: false };
+		return { source: rewritten.source, asyncWrapped: false, finalExpressionReturned: rewritten.returned };
 	}
 	return {
-		source: `(async () => {\n${rewritten}\n})()`,
+		source: `(async () => {\n${rewritten.source}\n})()`,
 		asyncWrapped: true,
+		finalExpressionReturned: rewritten.returned,
 	};
 }

package/src/eval/js/shared/runtime.ts

@@ -4,6 +4,8 @@ import * as path from "node:path";
 import { pathToFileURL } from "node:url";
 import * as util from "node:util";
 
+import { logger } from "@oh-my-pi/pi-utils";
+
 import { ToolError } from "../../../tools/tool-errors";
 import { createHelpers, type HelperBundle } from "./helpers";
 import { awaitMaybePromise, indirectEval } from "./indirect-eval";
@@ -48,6 +50,8 @@ export class JsRuntime {
 	readonly sessionId: string;
 	#env: Map<string, string>;
 	#getHooks: () => RuntimeHooks | null;
+	#finalExpressionSet = false;
+	#finalExpressionValue: unknown;
 
 	constructor(opts: RuntimeOptions) {
 		this.#cwd = opts.initialCwd;
@@ -82,8 +86,20 @@ export class JsRuntime {
 	}
 
 	async run(code: string, filename?: string): Promise<unknown> {
+		this.#finalExpressionSet = false;
+		this.#finalExpressionValue = undefined;
 		const wrapped = wrapCode(code);
 		const value = indirectEval(wrapped.source, filename);
+		if (wrapped.finalExpressionReturned) {
+			const awaited = await awaitMaybePromise(value);
+			if (this.#finalExpressionSet) {
+				const finalValue = this.#finalExpressionValue;
+				this.#finalExpressionSet = false;
+				this.#finalExpressionValue = undefined;
+				return await awaitMaybePromise(finalValue);
+			}
+			return awaited;
+		}
 		return await awaitMaybePromise(value);
 	}
 
@@ -97,7 +113,14 @@ export class JsRuntime {
 				hooks.onDisplay({ type: "image", data: record.data, mimeType: record.mimeType });
 				return;
 			}
-			hooks.onDisplay({ type: "json", data: structuredClone(value) });
+			try {
+				hooks.onDisplay({ type: "json", data: structuredClone(value) });
+			} catch (err) {
+				logger.debug("js displayValue: value is not structured-cloneable, falling back to text", {
+					error: err instanceof Error ? err.message : String(err),
+				});
+				hooks.onText(`${Object.prototype.toString.call(value)}\n`);
+			}
 			return;
 		}
 		hooks.onText(`${String(value)}\n`);
@@ -112,9 +135,9 @@ export class JsRuntime {
 				if (!hooks) throw new ToolError("Tool calls are only valid inside an active run");
 				return await hooks.callTool(name, args);
 			},
-			__omp_import__: async (source: string, attrs?: Record<string, string>) => {
+			__omp_import__: async (source: string, options?: ImportCallOptions) => {
 				const target = resolveImportSpecifier(this.#cwd, source);
-				return attrs ? await import(target, { with: attrs }) : await import(target);
+				return options !== undefined ? await import(target, options) : await import(target);
 			},
 			__omp_emit_status__: (op: string, data: Record<string, unknown> = {}) => {
 				const event: JsStatusEvent = { op, ...data };
@@ -126,6 +149,10 @@ export class JsRuntime {
 				this.#getHooks()?.onText(text.endsWith("\n") ? text : `${text}\n`);
 			},
 			__omp_display__: (value: unknown) => this.displayValue(value),
+			__omp_set_final_expr__: (value: unknown) => {
+				this.#finalExpressionSet = true;
+				this.#finalExpressionValue = value;
+			},
 			webcrypto: crypto,
 			// `process` is intentionally not overridden — user code gets the host worker's real
 			// `process` object. Subsetting it caused segfaults in workers that share state with
@@ -152,7 +179,7 @@ function buildRequire(cwd: string): NodeJS.Require {
 }
 
 /**
- * Resolve an import specifier emitted by `rewriteStaticImports` against the active session
+ * Resolve an import specifier emitted by `rewriteImports` against the active session
  * cwd. Relative paths (`./`, `../`, `/`) and bare specifiers (`pkg`, `@scope/pkg`) both go
  * through `Bun.resolveSync` rooted at the cwd so user-pasted ESM behaves as if it lived in
  * the project — not next to the worker module. URL-like specifiers (`file://`, `data:`,

package/src/eval/js/tool-bridge.ts

@@ -17,7 +17,17 @@ type ToolValue =
 			text: string;
 			details?: unknown;
 			images?: Array<{ mimeType: string; data: string }>;
+			hasError?: boolean;
 	  };
+function toolResultHasError(result: AgentToolResult): boolean {
+	if ((result as { isError?: unknown }).isError === true) {
+		return true;
+	}
+	if (!(result.details && typeof result.details === "object")) {
+		return false;
+	}
+	return (result.details as { isError?: unknown }).isError === true;
+}
 
 function getTool(session: ToolSession, name: string): AgentTool {
 	const tool = session.getToolByName?.(name);
@@ -38,7 +48,13 @@ function normalizeArgs(args: unknown): unknown {
 	return record;
 }
 
-function summarizeToolResult(name: string, args: unknown, result: AgentToolResult, text: string): JsStatusEvent {
+function summarizeToolResult(
+	name: string,
+	args: unknown,
+	result: AgentToolResult,
+	text: string,
+	hasError: boolean,
+): JsStatusEvent {
 	const record = (args && typeof args === "object" ? (args as Record<string, unknown>) : {}) as Record<
 		string,
 		unknown
@@ -46,39 +62,41 @@ function summarizeToolResult(name: string, args: unknown, result: AgentToolResul
 	const details = (
 		result.details && typeof result.details === "object" ? (result.details as Record<string, unknown>) : {}
 	) as Record<string, unknown>;
+	const withError = (event: JsStatusEvent): JsStatusEvent =>
+		hasError ? { ...event, hasError: true, error: text.slice(0, 500) } : event;
 
 	switch (name) {
 		case "read":
-			return { op: "read", path: record.path, chars: text.length, preview: text.slice(0, 500) };
+			return withError({ op: "read", path: record.path, chars: text.length, preview: text.slice(0, 500) });
 		case "write":
-			return {
+			return withError({
 				op: "write",
 				path: record.path,
 				chars: typeof record.content === "string" ? record.content.length : 0,
-			};
+			});
 		case "grep":
-			return {
+			return withError({
 				op: "grep",
 				pattern: record.pattern,
 				path: record.path,
 				count: details.matchCount ?? undefined,
-			};
+			});
 		case "find":
-			return {
+			return withError({
 				op: "find",
 				pattern: record.pattern,
 				count: details.fileCount ?? undefined,
 				matches: Array.isArray(details.files) ? details.files.slice(0, 20) : undefined,
-			};
+			});
 		case "bash":
-			return {
+			return withError({
 				op: "run",
 				cmd: record.command,
 				code: typeof details.exitCode === "number" ? details.exitCode : undefined,
 				output: text.slice(0, 500),
-			};
+			});
 		default:
-			return { op: name, chars: text.length };
+			return withError({ op: name, chars: text.length });
 	}
 }
 
@@ -97,21 +115,25 @@ export async function callSessionTool(name: string, args: unknown, options: Tool
 				content.type === "image" && typeof content.mimeType === "string" && typeof content.data === "string",
 		);
 		const text = textBlocks.map(block => block.text).join("");
-		options.emitStatus?.(summarizeToolResult(name, normalizedArgs, result, text));
-		if (result.details === undefined && imageBlocks.length === 0) {
+		const hasError = toolResultHasError(result);
+		options.emitStatus?.(summarizeToolResult(name, normalizedArgs, result, text, hasError));
+		if (result.details === undefined && imageBlocks.length === 0 && !hasError) {
 			return text;
 		}
-		return {
+		const value: Exclude<ToolValue, string> = {
 			text,
 			details: result.details,
-			images:
-				imageBlocks.length > 0
-					? imageBlocks.map(block => ({
-							mimeType: block.mimeType,
-							data: block.data,
-						}))
-					: undefined,
 		};
+		if (imageBlocks.length > 0) {
+			value.images = imageBlocks.map(block => ({
+				mimeType: block.mimeType,
+				data: block.data,
+			}));
+		}
+		if (hasError) {
+			value.hasError = true;
+		}
+		return value;
 	} catch (error) {
 		options.emitStatus?.({
 			op: name,

package/src/extensibility/extensions/runner.ts

@@ -2,7 +2,7 @@
  * Extension runner - executes extensions and manages their lifecycle.
  */
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import type { ImageContent, Model, ProviderResponseMetadata } from "@oh-my-pi/pi-ai";
+import type { CredentialDisabledEvent, ImageContent, Model, ProviderResponseMetadata } from "@oh-my-pi/pi-ai";
 import type { KeyId } from "@oh-my-pi/pi-tui";
 import { logger } from "@oh-my-pi/pi-utils";
 import type { ModelRegistry } from "../../config/model-registry";
@@ -69,6 +69,8 @@ export function __test_setExtensionHandlerTimeoutMs(timeoutMs: number): void {
 
 const EXTENSION_HANDLER_TIMEOUT = Symbol("extensionHandlerTimeout");
 
+const MAX_PENDING_CREDENTIAL_DISABLED = 32;
+
 /**
  * Events handled by the generic emit() method.
  * Events with dedicated emitXxx() methods are excluded for stronger type safety.
@@ -185,6 +187,15 @@ export class ExtensionRunner {
 	#reloadHandler: () => Promise<void> = async () => {};
 	#shutdownHandler: ShutdownHandler = () => {};
 	#commandDiagnostics: Array<{ type: string; message: string; path: string }> = [];
+	#initialized = false;
+	/**
+	 * Buffer for `credential_disabled` events received via {@link emitCredentialDisabled}
+	 * before {@link initialize} has run. Drained through {@link emit} once initialize sets
+	 * up the runtime context, so extension handlers see a populated UI/runtime context
+	 * rather than the constructor's no-op default. Bounded at
+	 * {@link MAX_PENDING_CREDENTIAL_DISABLED}; oldest entries are dropped under pressure.
+	 */
+	#pendingCredentialDisabled: CredentialDisabledEvent[] = [];
 
 	constructor(
 		private readonly extensions: Extension[],
@@ -237,6 +248,48 @@ export class ExtensionRunner {
 		}
 
 		this.#uiContext = uiContext ?? noOpUIContext;
+		this.#initialized = true;
+
+		// Drain events buffered by emitCredentialDisabled() before initialize ran. The
+		// spread adds the `type` discriminator — `event` is the pi-ai shape (no `type`).
+		// Deferred by one microtask so callers that register an onError listener
+		// synchronously after initialize() see handler errors routed through it.
+		const pending = this.#pendingCredentialDisabled.splice(0);
+		queueMicrotask(() => {
+			for (const event of pending) {
+				this.emit({ type: "credential_disabled", ...event }).catch((error: unknown) => {
+					logger.warn("credential_disabled handler threw during initialize flush", {
+						provider: event.provider,
+						error: error instanceof Error ? error.message : String(error),
+					});
+				});
+			}
+		});
+	}
+
+	/**
+	 * Forward a `credential_disabled` event from `AuthStorage` to extension handlers.
+	 *
+	 * If {@link initialize} has not yet run, the event is buffered and replayed once
+	 * initialize wires the runtime/UI context. This matters because mode controllers
+	 * (interactive, RPC, ACP, print, subagent) call `initialize()` AFTER `createAgentSession`
+	 * returns, but `AuthStorage` can fire `credential_disabled` during startup model probes
+	 * inside `createAgentSession()`. Without deferral, extension handlers would observe
+	 * `hasUI=false`, an unset model, and no-op runtime actions on exactly the headline
+	 * "OAuth invalid_grant during startup" path the event was designed to surface.
+	 *
+	 * Always returns; never throws. Errors from handlers are routed through
+	 * {@link onError} via {@link emit}'s normal isolation.
+	 */
+	async emitCredentialDisabled(event: CredentialDisabledEvent): Promise<void> {
+		if (!this.#initialized) {
+			if (this.#pendingCredentialDisabled.length >= MAX_PENDING_CREDENTIAL_DISABLED) {
+				this.#pendingCredentialDisabled.shift();
+			}
+			this.#pendingCredentialDisabled.push(event);
+			return;
+		}
+		await this.emit({ type: "credential_disabled", ...event });
 	}
 
 	getUIContext(): ExtensionUIContext {

package/src/extensibility/extensions/types.ts

@@ -624,6 +624,15 @@ export interface TodoReminderEvent {
 	maxAttempts: number;
 }
 
+/** Fired when AuthStorage automatically soft-disables a credential (e.g. OAuth `invalid_grant`). Not fired for user-initiated `remove()` or duplicate-credential dedup. */
+export interface CredentialDisabledEvent {
+	type: "credential_disabled";
+	/** Provider id whose credential was disabled (e.g. "anthropic"). */
+	provider: string;
+	/** Verbatim error captured for forensics (truncated upstream). */
+	disabledCause: string;
+}
+
 // ============================================================================
 // User Bash Events
 // ============================================================================
@@ -831,6 +840,7 @@ export type ExtensionEvent =
 	| AutoRetryEndEvent
 	| TtsrTriggeredEvent
 	| TodoReminderEvent
+	| CredentialDisabledEvent
 	| UserBashEvent
 	| UserPythonEvent
 	| InputEvent
@@ -1012,6 +1022,7 @@ export interface ExtensionAPI {
 	on(event: "auto_retry_end", handler: ExtensionHandler<AutoRetryEndEvent>): void;
 	on(event: "ttsr_triggered", handler: ExtensionHandler<TtsrTriggeredEvent>): void;
 	on(event: "todo_reminder", handler: ExtensionHandler<TodoReminderEvent>): void;
+	on(event: "credential_disabled", handler: ExtensionHandler<CredentialDisabledEvent>): void;
 	on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): void;
 	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
 	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;

package/src/extensibility/skills.ts

@@ -6,8 +6,8 @@ import type { SourceMeta } from "../capability/types";
 import type { SkillsSettings } from "../config/settings";
 import { type Skill as CapabilitySkill, loadCapability } from "../discovery";
 import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
+import type { SkillPromptDetails } from "../session/messages";
 import { expandTilde } from "../tools/path-utils";
-
 export interface Skill {
 	name: string;
 	description: string;
@@ -270,3 +270,35 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		warnings: [...(result.warnings ?? []).map(w => ({ skillPath: "", message: w })), ...collisionWarnings],
 	};
 }
+
+export interface BuiltSkillPromptMessage {
+	message: string;
+	details: SkillPromptDetails;
+}
+
+export function getSkillSlashCommandName(skill: Pick<Skill, "name">): string {
+	return `skill:${skill.name}`;
+}
+
+export async function buildSkillPromptMessage(
+	skill: Pick<Skill, "name" | "filePath">,
+	args: string,
+): Promise<BuiltSkillPromptMessage> {
+	const content = await Bun.file(skill.filePath).text();
+	const body = content.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
+	const metaLines = [`Skill: ${skill.filePath}`];
+	const trimmedArgs = args.trim();
+	if (trimmedArgs) {
+		metaLines.push(`User: ${trimmedArgs}`);
+	}
+	const message = `${body}\n\n---\n\n${metaLines.join("\n")}`;
+	return {
+		message,
+		details: {
+			name: skill.name,
+			path: skill.filePath,
+			args: trimmedArgs || undefined,
+			lineCount: body ? body.split("\n").length : 0,
+		},
+	};
+}