@pasko70/pibo 1.0.5 → 1.2.0

package/dist/tools/runtime/registry.js

@@ -0,0 +1,255 @@
+import { randomUUID } from "node:crypto";
+import { PythonRuntimeBackend } from "./python-backend.js";
+import { NodeRuntimeBackend } from "./node-backend.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+function notFoundExec(sessionId = "auto") {
+    return {
+        status: "not_found",
+        sessionId,
+        durationMs: 0,
+        error: { name: "RuntimeNotFound", message: `Runtime session "${sessionId}" was not found.` },
+    };
+}
+function notFoundInspect(sessionId = "auto") {
+    return {
+        status: "not_found",
+        sessionId,
+        error: { name: "RuntimeNotFound", message: `Runtime session "${sessionId}" was not found.` },
+    };
+}
+function notFoundVars(sessionId = "auto") {
+    return {
+        status: "not_found",
+        sessionId,
+        variables: [],
+        error: { name: "RuntimeNotFound", message: `Runtime session "${sessionId}" was not found.` },
+    };
+}
+export class RuntimeSessionRegistry {
+    options;
+    sessions = new Map();
+    maxHistoryEntries;
+    constructor(options) {
+        this.options = options;
+        this.maxHistoryEntries = options.maxHistoryEntries ?? 100;
+    }
+    async start(controllerPiboSessionId, input) {
+        if (input.target?.type && input.target.type !== "local") {
+            return {
+                status: "error",
+                error: { name: "UnsupportedRuntimeTarget", message: `Runtime target "${input.target.type}" is not implemented yet.` },
+            };
+        }
+        const sessionId = `rt_${input.runtime}_${randomUUID().slice(0, 8)}`;
+        try {
+            const backend = input.runtime === "python"
+                ? await PythonRuntimeBackend.start(this.options.cwd, input)
+                : await NodeRuntimeBackend.start(this.options.cwd, input);
+            const startedAt = nowIso();
+            const record = backend.getRecord();
+            const session = {
+                sessionId,
+                runtime: input.runtime,
+                name: input.name,
+                cwd: record.cwd,
+                status: "idle",
+                startedAt,
+                updatedAt: startedAt,
+                executionCount: 0,
+                pid: record.pid,
+                executable: record.executable,
+                controllerPiboSessionId,
+                backend,
+                history: [],
+            };
+            this.sessions.set(sessionId, session);
+            return { status: "ok", sessionId, runtime: input.runtime, name: input.name, ...record, startedAt };
+        }
+        catch (error) {
+            return {
+                status: "failed",
+                sessionId,
+                runtime: input.runtime,
+                error: error instanceof Error
+                    ? { name: error.name, message: error.message, stack: error.stack }
+                    : { name: "RuntimeStartError", message: String(error) },
+            };
+        }
+    }
+    async exec(controllerPiboSessionId, input) {
+        const session = input.sessionId
+            ? this.getSessionForController(controllerPiboSessionId, input.sessionId)
+            : await this.getOrStartDefault(controllerPiboSessionId, input);
+        const sessionId = input.sessionId ?? session?.sessionId ?? "auto";
+        if (!session)
+            return notFoundExec(sessionId);
+        if (session.status === "closed" || session.status === "failed")
+            return notFoundExec(sessionId);
+        if (session.status === "busy") {
+            return {
+                status: "failed",
+                sessionId,
+                runtime: session.runtime,
+                durationMs: 0,
+                error: { name: "RuntimeBusy", message: `Runtime session "${sessionId}" is already busy.` },
+            };
+        }
+        const startedAt = nowIso();
+        session.status = "busy";
+        session.updatedAt = startedAt;
+        const result = await session.backend.exec(input);
+        result.sessionId = session.sessionId;
+        result.runtime = session.runtime;
+        session.executionCount += 1;
+        result.executionCount = session.executionCount;
+        session.lastExecAt = startedAt;
+        session.updatedAt = nowIso();
+        if (result.status === "failed" && !session.backend.isAlive()) {
+            session.status = "failed";
+        }
+        else {
+            session.status = "idle";
+        }
+        this.appendHistory(session, {
+            id: randomUUID(),
+            startedAt,
+            durationMs: result.durationMs,
+            code: input.code,
+            status: result.status,
+            error: result.error,
+        });
+        if (input.closeOnSuccess === true && result.status === "ok") {
+            await this.close(controllerPiboSessionId, { sessionId: session.sessionId });
+            result.autoClosed = true;
+        }
+        return result;
+    }
+    async inspect(controllerPiboSessionId, input) {
+        const session = input.sessionId ? this.getSessionForController(controllerPiboSessionId, input.sessionId) : this.getDefault(controllerPiboSessionId, input.runtime ?? "python");
+        if (!session)
+            return notFoundInspect(input.sessionId);
+        const result = await session.backend.inspect(input);
+        return { ...result, sessionId: session.sessionId };
+    }
+    async vars(controllerPiboSessionId, input) {
+        const session = input.sessionId ? this.getSessionForController(controllerPiboSessionId, input.sessionId) : this.getDefault(controllerPiboSessionId, input.runtime ?? "python");
+        if (!session)
+            return notFoundVars(input.sessionId);
+        const result = await session.backend.vars(input);
+        return { ...result, sessionId: session.sessionId };
+    }
+    async interrupt(controllerPiboSessionId, input) {
+        const session = input.sessionId ? this.getSessionForController(controllerPiboSessionId, input.sessionId) : this.getDefault(controllerPiboSessionId, input.runtime ?? "python");
+        const sessionId = input.sessionId ?? session?.sessionId ?? "auto";
+        if (!session)
+            return { status: "not_found", sessionId, message: `Runtime session "${sessionId}" was not found.` };
+        const result = await session.backend.interrupt();
+        return { ...result, sessionId: session.sessionId };
+    }
+    async close(controllerPiboSessionId, input) {
+        const session = this.getSessionForController(controllerPiboSessionId, input.sessionId);
+        if (!session)
+            return { status: "not_found", sessionId: input.sessionId, closed: false, message: `Runtime session "${input.sessionId}" was not found.` };
+        try {
+            await session.backend.close(input.force);
+            session.status = "closed";
+            session.updatedAt = nowIso();
+            this.sessions.delete(session.sessionId);
+            return { status: "ok", sessionId: input.sessionId, closed: true };
+        }
+        catch (error) {
+            session.status = "failed";
+            return {
+                status: "failed",
+                sessionId: input.sessionId,
+                closed: false,
+                error: error instanceof Error
+                    ? { name: error.name, message: error.message, stack: error.stack }
+                    : { name: "RuntimeCloseError", message: String(error) },
+            };
+        }
+    }
+    list(controllerPiboSessionId) {
+        return {
+            status: "ok",
+            sessions: [...this.sessions.values()]
+                .filter((session) => session.controllerPiboSessionId === controllerPiboSessionId)
+                .map(toRecord),
+        };
+    }
+    async closeControllerSessions(controllerPiboSessionId, options = {}) {
+        const sessions = [...this.sessions.values()].filter((session) => session.controllerPiboSessionId === controllerPiboSessionId);
+        await Promise.all(sessions.map((session) => this.close(controllerPiboSessionId, { sessionId: session.sessionId, force: options.force })));
+    }
+    async closeAll(options = {}) {
+        const sessions = [...this.sessions.values()];
+        await Promise.all(sessions.map((session) => this.close(session.controllerPiboSessionId, { sessionId: session.sessionId, force: options.force })));
+    }
+    pruneIdle(now = Date.now(), idleTimeoutMs = 30 * 60 * 1000) {
+        for (const session of this.sessions.values()) {
+            if (session.status !== "idle")
+                continue;
+            if (now - Date.parse(session.updatedAt) > idleTimeoutMs) {
+                void this.close(session.controllerPiboSessionId, { sessionId: session.sessionId, force: true });
+            }
+        }
+    }
+    createController(controllerPiboSessionId) {
+        return {
+            start: (input) => this.start(controllerPiboSessionId, input),
+            exec: (input) => this.exec(controllerPiboSessionId, input),
+            inspect: (input) => this.inspect(controllerPiboSessionId, input),
+            vars: (input) => this.vars(controllerPiboSessionId, input),
+            interrupt: (input) => this.interrupt(controllerPiboSessionId, input),
+            close: (input) => this.close(controllerPiboSessionId, input),
+            list: () => this.list(controllerPiboSessionId),
+        };
+    }
+    getDefault(controllerPiboSessionId, runtime) {
+        return [...this.sessions.values()].find((session) => session.controllerPiboSessionId === controllerPiboSessionId &&
+            session.runtime === runtime &&
+            session.status !== "closed" &&
+            session.status !== "failed");
+    }
+    async getOrStartDefault(controllerPiboSessionId, input) {
+        const runtime = input.runtime ?? "python";
+        const existing = this.getDefault(controllerPiboSessionId, runtime);
+        if (existing)
+            return existing;
+        const started = await this.start(controllerPiboSessionId, {
+            runtime,
+            name: input.name,
+            target: input.target,
+            timeoutMs: input.timeoutMs,
+        });
+        return started.sessionId ? this.getSessionForController(controllerPiboSessionId, started.sessionId) : undefined;
+    }
+    getSessionForController(controllerPiboSessionId, sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.controllerPiboSessionId !== controllerPiboSessionId)
+            return undefined;
+        return session;
+    }
+    appendHistory(session, entry) {
+        session.history.push(entry);
+        if (session.history.length > this.maxHistoryEntries)
+            session.history.splice(0, session.history.length - this.maxHistoryEntries);
+    }
+}
+function toRecord(session) {
+    return {
+        sessionId: session.sessionId,
+        runtime: session.runtime,
+        name: session.name,
+        cwd: session.cwd,
+        status: session.status,
+        startedAt: session.startedAt,
+        updatedAt: session.updatedAt,
+        lastExecAt: session.lastExecAt,
+        executionCount: session.executionCount,
+        pid: session.pid,
+        executable: session.executable,
+    };
+}

package/dist/tools/runtime/tool.js

@@ -0,0 +1,168 @@
+import { StringEnum, Type } from "@mariozechner/pi-ai";
+import { defineTool } from "@mariozechner/pi-coding-agent";
+export function createRuntimeToolProfile() {
+    return {
+        name: "runtime",
+        description: "Run Python/Node code in persistent runtime sessions; exec runs normal scripts.",
+        yieldable: true,
+        builtInPiboTool: "runtime",
+    };
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`runtime.${field} must be a non-empty string`);
+    return value;
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function validateTarget(value) {
+    const object = asObject(value);
+    if (!object)
+        return undefined;
+    const target = {};
+    if (object.type !== undefined) {
+        if (object.type !== "local" && object.type !== "docker" && object.type !== "ssh")
+            throw new Error("runtime.target.type must be local, docker, or ssh");
+        target.type = object.type;
+    }
+    if (object.cwd !== undefined)
+        target.cwd = requireString(object.cwd, "target.cwd");
+    if (object.executable !== undefined)
+        target.executable = requireString(object.executable, "target.executable");
+    if (object.args !== undefined) {
+        if (!Array.isArray(object.args) || object.args.some((arg) => typeof arg !== "string"))
+            throw new Error("runtime.target.args must be an array of strings");
+        target.args = [...object.args];
+    }
+    if (object.env !== undefined) {
+        const env = asObject(object.env);
+        if (!env)
+            throw new Error("runtime.target.env must be an object");
+        target.env = Object.fromEntries(Object.entries(env).map(([key, value]) => [key, requireString(value, `target.env.${key}`)]));
+    }
+    return target;
+}
+function resultStatus(result) {
+    return asObject(result)?.status;
+}
+function isErrorStatus(status) {
+    return status !== undefined && status !== "ok";
+}
+function formatRuntimeResult(result) {
+    const object = asObject(result) ?? {};
+    const lines = [
+        `status: ${object.status ?? "unknown"}`,
+    ];
+    if (object.sessionId)
+        lines.push(`sessionId: ${object.sessionId}`);
+    if (object.runtime)
+        lines.push(`runtime: ${object.runtime}`);
+    if (object.autoClosed !== undefined)
+        lines.push(`autoClosed: ${object.autoClosed}`);
+    if (object.executionCount !== undefined)
+        lines.push(`executionCount: ${object.executionCount}`);
+    if (object.durationMs !== undefined)
+        lines.push(`durationMs: ${object.durationMs}`);
+    if (typeof object.stdout === "string" && object.stdout.length > 0)
+        lines.push("", "stdout:", object.stdout);
+    if (typeof object.stderr === "string" && object.stderr.length > 0)
+        lines.push("", "stderr:", object.stderr);
+    if (object.result !== undefined && object.result !== null)
+        lines.push("", "result:", JSON.stringify(object.result, null, 2));
+    if (object.error !== undefined)
+        lines.push("", "error:", JSON.stringify(object.error, null, 2));
+    if (object.sessions !== undefined)
+        lines.push("", "sessions:", JSON.stringify(object.sessions, null, 2));
+    if (object.variables !== undefined)
+        lines.push("", "variables:", JSON.stringify(object.variables, null, 2));
+    if (object.summary !== undefined)
+        lines.push("", "summary:", JSON.stringify(object.summary, null, 2));
+    if (object.signature !== undefined)
+        lines.push("", "signature:", String(object.signature));
+    if (object.members !== undefined)
+        lines.push("", "members:", JSON.stringify(object.members, null, 2));
+    if (object.source !== undefined)
+        lines.push("", "source:", String(object.source));
+    if (object.doc !== undefined)
+        lines.push("", "doc:", String(object.doc));
+    if (object.closed !== undefined)
+        lines.push(`closed: ${object.closed}`);
+    if (object.message !== undefined)
+        lines.push(`message: ${object.message}`);
+    return lines.join("\n");
+}
+export function createRuntimeToolDefinition(controller) {
+    return defineTool({
+        name: "runtime",
+        label: "Runtime",
+        description: "Run Python/Node code in persistent sessions. Use this instead of bash for Python/Node execution except trivial one-line shell checks.",
+        promptSnippet: "Use runtime for Python/Node execution, especially longer snippets (~20+ lines), uncertain code, or objects/state to inspect. Prefer runtime over bash for Python/Node except trivial one-line shell checks. Auto-starts on exec; print values you need. Runtime keeps variables and processes alive between calls; reuse sessionId to inspect or continue from that state after partial failures. This saves output tokens and keeps your mental model tied to live state. Use read for file contents; use bash for shell commands and package installs.",
+        executionMode: "parallel",
+        parameters: Type.Object({
+            action: StringEnum(["exec", "inspect", "vars", "interrupt", "list"], { description: "Runtime action to perform." }),
+            runtime: Type.Optional(StringEnum(["python", "node"], { description: "Runtime kind; default python." })),
+            name: Type.Optional(Type.String({ description: "Optional human-readable runtime name." })),
+            target: Type.Optional(Type.Any({ description: "Auto-start target options such as { type: 'local', cwd, executable, args, env }." })),
+            sessionId: Type.Optional(Type.String({ description: "Existing runtime session id; omit to use auto runtime." })),
+            code: Type.Optional(Type.String({ description: "Code to execute for exec." })),
+            timeoutMs: Type.Optional(Type.Number({ description: "Action timeout in milliseconds." })),
+            mode: Type.Optional(StringEnum(["exec", "eval", "auto"], { description: "For exec: execution mode. Use eval when you need an expression result." })),
+            closeOnSuccess: Type.Optional(Type.Boolean({ description: "For exec: close the runtime only if execution succeeds." })),
+            expression: Type.Optional(Type.String({ description: "Expression to inspect." })),
+            what: Type.Optional(StringEnum(["summary", "signature", "members", "source", "doc", "all"], { description: "Inspection detail to return." })),
+            maxBytes: Type.Optional(Type.Number({ description: "Maximum bytes for summaries or inspect fields." })),
+            includePrivate: Type.Optional(Type.Boolean({ description: "For vars: include private names." })),
+            maxItems: Type.Optional(Type.Number({ description: "For vars: maximum variables to return." })),
+        }),
+        async execute(_toolCallId, params) {
+            let result;
+            try {
+                switch (params.action) {
+                    case "exec":
+                        result = await controller.exec({
+                            sessionId: params.sessionId,
+                            runtime: params.runtime,
+                            name: params.name,
+                            target: validateTarget(params.target),
+                            code: requireString(params.code, "code"),
+                            timeoutMs: params.timeoutMs,
+                            mode: params.mode,
+                            closeOnSuccess: params.closeOnSuccess,
+                        });
+                        break;
+                    case "inspect":
+                        result = await controller.inspect({
+                            sessionId: params.sessionId,
+                            runtime: params.runtime,
+                            expression: requireString(params.expression, "expression"),
+                            what: params.what,
+                            maxBytes: params.maxBytes,
+                        });
+                        break;
+                    case "vars":
+                        result = await controller.vars({ sessionId: params.sessionId, runtime: params.runtime, includePrivate: params.includePrivate, maxItems: params.maxItems, maxBytes: params.maxBytes });
+                        break;
+                    case "interrupt":
+                        result = await controller.interrupt({ sessionId: params.sessionId, runtime: params.runtime });
+                        break;
+                    case "list":
+                        result = await controller.list({});
+                        break;
+                }
+            }
+            catch (error) {
+                result = {
+                    status: "failed",
+                    error: error instanceof Error ? { name: error.name, message: error.message, stack: error.stack } : { name: "RuntimeToolError", message: String(error) },
+                };
+            }
+            const status = resultStatus(result);
+            return {
+                content: [{ type: "text", text: formatRuntimeResult(result) }],
+                details: result,
+                isError: isErrorStatus(status),
+            };
+        },
+    });
+}

package/dist/tools/runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/web-search.js

@@ -1,3 +1,4 @@
+export const WEB_SEARCH_PROMPT_CONTRIBUTION = "web_search is available as a Pibo native tool through the OpenAI provider adapter. Use it when current or externally sourced information is needed.";
 const WEB_SEARCH_SOURCES_INCLUDE = "web_search_call.action.sources";
 function hasProviderResponsesShape(payload) {
     return Boolean(payload && typeof payload === "object" && "input" in payload);
@@ -100,7 +101,7 @@ const openAiWebSearchAdapter = {
                 systemPrompt: [
                     event.systemPrompt,
                     "# Native Web Search",
-                    "web_search is available as a Pibo native tool through the OpenAI provider adapter. Use it when current or externally sourced information is needed.",
+                    WEB_SEARCH_PROMPT_CONTRIBUTION,
                 ].join("\n\n"),
             }));
             pi.on("before_provider_request", (event) => addOpenAiWebSearchProviderTool(event.payload, config));

package/dist/user-skills/installer.js

@@ -0,0 +1,214 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { defaultUserSkillDir, parseSkillMd } from "./store.js";
+export function parseSkillUrl(url) {
+    const trimmed = url.trim();
+    // skills.sh: https://skills.sh/{account}/skills/{skill-name}
+    // skills.sh: https://skills.sh/{account}/{repo}/{skill-name}
+    if (trimmed.startsWith("https://skills.sh/")) {
+        const rest = trimmed.slice("https://skills.sh/".length);
+        const parts = rest.split("/").filter(Boolean);
+        if (parts.length >= 3) {
+            // Format: {account}/{repo}/{skill-name} (e.g. softaworks/agent-toolkit/writing-clearly)
+            const account = parts[0];
+            const repo = parts[1];
+            const skillName = parts[2];
+            return { account, repo, path: `skills/${skillName}`, skillName };
+        }
+        if (parts.length >= 2 && parts[1] === "skills") {
+            const account = parts[0];
+            const skillName = parts[2] ?? parts[0];
+            return { account, repo: "skills", path: `skills/${skillName}`, skillName };
+        }
+        if (parts.length === 2) {
+            // Format: {account}/skills or {account}/{repo}
+            if (parts[1] === "skills") {
+                return { account: parts[0], repo: "skills" };
+            }
+            return { account: parts[0], repo: parts[1] };
+        }
+        if (parts.length === 1) {
+            return { account: parts[0], repo: "skills" };
+        }
+    }
+    // GitHub tree URL: https://github.com/{account}/{repo}/tree/{branch}/{path}
+    const githubTreeMatch = trimmed.match(/^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/tree\/[^\/]+\/(.+)$/);
+    if (githubTreeMatch) {
+        const account = githubTreeMatch[1];
+        const repo = githubTreeMatch[2];
+        const path = githubTreeMatch[3];
+        const skillName = path.split("/").pop() ?? repo;
+        return { account, repo, path, skillName };
+    }
+    // GitHub shorthand or repo URL: https://github.com/{account}/{repo}
+    const githubRepoMatch = trimmed.match(/^https:\/\/github\.com\/([^\/]+)\/([^\/]+)$/);
+    if (githubRepoMatch) {
+        return { account: githubRepoMatch[1], repo: githubRepoMatch[2] };
+    }
+    // Bare shorthand: {account}/{repo} or {account}/{repo}/{skill-path}
+    const shorthandMatch = trimmed.match(/^([^\/\s]+)\/([^\/\s]+)(?:\/(.+))?$/);
+    if (shorthandMatch && !trimmed.startsWith("http")) {
+        const account = shorthandMatch[1];
+        const repo = shorthandMatch[2];
+        const path = shorthandMatch[3];
+        const skillName = path?.split("/").pop() ?? repo;
+        return { account, repo, path, skillName };
+    }
+    return undefined;
+}
+async function fetchGitHubContents(account, repo, path) {
+    const apiUrl = `https://api.github.com/repos/${encodeURIComponent(account)}/${encodeURIComponent(repo)}/contents/${encodeURIComponent(path)}`;
+    const response = await fetch(apiUrl, {
+        headers: { Accept: "application/vnd.github.v3+json", "User-Agent": "pibo-skills-installer" },
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`GitHub API error (${response.status}): ${text || response.statusText}`);
+    }
+    const data = (await response.json());
+    if (!Array.isArray(data)) {
+        throw new Error(`Expected directory listing from GitHub API, got: ${typeof data}`);
+    }
+    return data;
+}
+async function fetchGitHubFile(downloadUrl) {
+    const response = await fetch(downloadUrl, { headers: { "User-Agent": "pibo-skills-installer" } });
+    if (!response.ok) {
+        throw new Error(`Failed to download file (${response.status}): ${downloadUrl}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}
+async function downloadDirectory(account, repo, path, targetDir) {
+    const items = await fetchGitHubContents(account, repo, path);
+    for (const item of items) {
+        const targetPath = join(targetDir, item.name);
+        if (item.type === "file") {
+            if (!item.download_url)
+                continue;
+            const content = await fetchGitHubFile(item.download_url);
+            mkdirSync(dirname(targetPath), { recursive: true });
+            writeFileSync(targetPath, content);
+        }
+        else if (item.type === "dir") {
+            mkdirSync(targetPath, { recursive: true });
+            await downloadDirectory(account, repo, item.path, targetPath);
+        }
+    }
+}
+async function findSkillMdPath(items) {
+    return items.find((item) => item.type === "file" && item.name.toLowerCase() === "skill.md");
+}
+async function findSkillDirectory(account, repo, path) {
+    if (path) {
+        const items = await fetchGitHubContents(account, repo, path);
+        const skillMd = await findSkillMdPath(items);
+        if (skillMd) {
+            return { path, skillName: path.split("/").pop() ?? repo };
+        }
+        // If no SKILL.md at this path, search subdirectories one level deep
+        for (const item of items) {
+            if (item.type === "dir") {
+                const subItems = await fetchGitHubContents(account, repo, item.path).catch(() => []);
+                const subSkillMd = await findSkillMdPath(subItems);
+                if (subSkillMd) {
+                    return { path: item.path, skillName: item.name };
+                }
+            }
+        }
+    }
+    // Try common skill directories
+    const candidates = ["skills", "skill", "src/skills", "agents/skills"];
+    for (const candidate of candidates) {
+        const items = await fetchGitHubContents(account, repo, candidate).catch(() => []);
+        const skillMd = await findSkillMdPath(items);
+        if (skillMd) {
+            return { path: candidate, skillName: candidate };
+        }
+        // Search one level deep
+        for (const item of items) {
+            if (item.type === "dir") {
+                const subItems = await fetchGitHubContents(account, repo, item.path).catch(() => []);
+                const subSkillMd = await findSkillMdPath(subItems);
+                if (subSkillMd) {
+                    return { path: item.path, skillName: item.name };
+                }
+            }
+        }
+    }
+    // Search repository root for SKILL.md
+    const rootItems = await fetchGitHubContents(account, repo, "").catch(() => []);
+    const rootSkillMd = await findSkillMdPath(rootItems);
+    if (rootSkillMd) {
+        return { path: "", skillName: repo };
+    }
+    throw new Error(`Could not find a SKILL.md in ${account}/${repo}${path ? `/${path}` : ""}`);
+}
+export async function installSkillFromUrl(url, cwd = process.cwd()) {
+    const source = parseSkillUrl(url);
+    if (!source) {
+        throw new Error(`Unsupported skill URL format: ${url}`);
+    }
+    const { account, repo, path, skillName } = source;
+    const resolved = path
+        ? { path, skillName: skillName ?? path.split("/").pop() ?? repo }
+        : await findSkillDirectory(account, repo);
+    const targetName = resolved.skillName;
+    const targetDir = join(defaultUserSkillDir(cwd), targetName);
+    if (existsSync(targetDir)) {
+        throw new Error(`A skill named "${targetName}" already exists. Delete it first or choose a different name.`);
+    }
+    mkdirSync(targetDir, { recursive: true });
+    try {
+        await downloadDirectory(account, repo, resolved.path, targetDir);
+    }
+    catch (error) {
+        // Clean up on failure
+        try {
+            const { rmSync } = await import("node:fs");
+            rmSync(targetDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+        throw error;
+    }
+    // Read SKILL.md to extract name and description
+    const skillMdPath = join(targetDir, "SKILL.md");
+    if (!existsSync(skillMdPath)) {
+        throw new Error(`Download completed but no SKILL.md found in ${targetName}`);
+    }
+    const { readFileSync } = await import("node:fs");
+    const content = readFileSync(skillMdPath, "utf-8");
+    const parsed = parseSkillMd(content);
+    const name = parsed.name || targetName;
+    const description = parsed.description || "";
+    // Store the skill metadata (description lives in SKILL.md only, not JSON)
+    const { randomUUID } = await import("node:crypto");
+    const now = new Date().toISOString();
+    const skill = {
+        id: randomUUID(),
+        name,
+        description,
+        path: skillMdPath,
+        enabled: true,
+        source: url.includes("skills.sh") ? "skills.sh" : "github",
+        sourceUrl: url,
+        createdAt: now,
+        updatedAt: now,
+    };
+    const { loadUserSkillStore, saveUserSkillStore } = await import("./store.js");
+    const store = loadUserSkillStore(cwd);
+    const existing = store.skills.find((s) => s.name === name);
+    if (existing) {
+        const { rmSync } = await import("node:fs");
+        rmSync(targetDir, { recursive: true, force: true });
+        throw new Error(`A skill named "${name}" already exists. Delete it first or choose a different name.`);
+    }
+    // Strip description before persisting to JSON store.
+    const storedSkill = { ...skill };
+    delete storedSkill.description;
+    store.skills.push(storedSkill);
+    store.skills.sort((a, b) => a.name.localeCompare(b.name));
+    saveUserSkillStore(store, cwd);
+    return skill;
+}