@pasko70/pibo 1.4.4 → 1.4.6

package/dist/session-ui/terminalRows.js

@@ -8,7 +8,7 @@ export function buildCompactTerminalRows(traceView, options) {
     const flatNodes = flattenTraceNodes(traceView.nodes)
         .sort((left, right) => compareTraceNodes(left.node, right.node))
         .filter((item) => item.node.type !== "agent.turn" && (options.showThinking || item.node.type !== "model.reasoning"));
-    const candidates = flatNodes.map((item) => createRowCandidate(item.node, item.turnId));
+    const candidates = syncThinkingToolRows(flatNodes.map((item) => createRowCandidate(item.node, item.turnId)));
     return groupRelatedToolCandidates(candidates).map((candidate) => candidate.row);
 }
 function flattenTraceNodes(nodes, turnId) {
@@ -128,7 +128,7 @@ function createToolRowCandidate(node, turnId) {
     const image = classifyImageTool(node);
     if (image) {
         const row = createImageToolRow(node, image);
-        return { row, turnId, image: image.detail };
+        return { row, turnId, image: image.groupable ? image.detail : undefined };
     }
     const preview = previewLines(node.error ?? node.output, COMPACT_TERMINAL_OUTPUT_PREVIEW_LINES, node.error ? "red" : "dim");
     const row = {
@@ -159,7 +159,7 @@ function createToolRowCandidate(node, turnId) {
 }
 function createImageToolRow(node, image) {
     const status = mapStatus(node.status);
-    const detailLabel = image.path ? `Path: ${image.path}` : image.query ? `Query: ${image.query}` : image.mimeType ? `Type: ${image.mimeType}` : "Image content returned";
+    const detailLabel = image.path ? `Path: ${image.path}` : image.artifactId ? `Artifact: ${image.artifactId}` : image.query ? `Query: ${image.query}` : image.mimeType ? `Type: ${image.mimeType}` : "Image content returned";
     return {
         id: node.id,
         kind: "tool.image",
@@ -168,7 +168,7 @@ function createImageToolRow(node, image) {
         lines: [
             {
                 prefix: "bullet",
-                tokens: [token(imageToolVerb(node.status, image.count), toneForStatus(node.status), "semibold")],
+                tokens: [token(image.verb, toneForStatus(node.status), "semibold")],
             },
             {
                 prefix: "detail",
@@ -186,7 +186,7 @@ function createToolResultRowCandidate(node, turnId) {
     const image = classifyImageTool(node);
     if (image) {
         const row = createImageToolRow(node, image);
-        return { row, turnId, image: image.detail };
+        return { row, turnId, image: image.groupable ? image.detail : undefined };
     }
     return { row: createToolResultRow(node), turnId };
 }
@@ -311,7 +311,7 @@ function createExecutionCommandRow(node) {
         return createStatusToolRow(node);
     }
     if (node.title === "thinking") {
-        return createThinkingToolRow(node);
+        return isThinkingLevelSetOutput(node.output) ? createThinkingLevelSetRow(node) : createThinkingToolRow(node);
     }
     if (node.title === "fast_mode") {
         return createFastModeToolRow(node);
@@ -369,6 +369,33 @@ function createThinkingToolRow(node) {
         expandable: false,
     };
 }
+function createThinkingLevelSetRow(node) {
+    const result = isRecord(node.output) ? node.output : undefined;
+    const level = stringValue(result?.level);
+    const changed = result?.changed !== false;
+    const supported = result?.supported !== false;
+    const label = !supported
+        ? "Thinking level is not supported by this model."
+        : level
+            ? changed ? `Thinking level set to ${level}.` : `Thinking level is already ${level}.`
+            : "Thinking level updated.";
+    return {
+        id: node.id,
+        kind: "execution.command",
+        status: mapStatus(node.status),
+        lines: [
+            {
+                prefix: "bullet",
+                tokens: [token(label, supported ? "green" : "dim", "semibold")],
+            },
+        ],
+        sourceNodeIds: [node.id],
+        input: node.input,
+        output: node.output,
+        error: node.error,
+        expandable: false,
+    };
+}
 function createFastModeToolRow(node) {
     const result = isRecord(node.output) ? node.output : undefined;
     const mode = result?.mode === "fast" ? "fast" : result?.mode === "normal" ? "normal" : undefined;
@@ -495,6 +522,33 @@ function sessionErrorDetailLines(details) {
         tokens: [token(`${label}: `, "dim"), token(value, "red")],
     }));
 }
+function syncThinkingToolRows(candidates) {
+    const latest = candidates.map((candidate) => candidate.row.output).filter(isThinkingOutput).at(-1);
+    if (!latest)
+        return [...candidates];
+    return candidates.map((candidate) => {
+        if (candidate.row.kind !== "tool.thinking" || !isRecord(candidate.row.output))
+            return candidate;
+        return {
+            ...candidate,
+            row: {
+                ...candidate.row,
+                output: {
+                    ...candidate.row.output,
+                    level: latest.level,
+                    availableLevels: latest.availableLevels,
+                    supported: latest.supported,
+                },
+            },
+        };
+    });
+}
+function isThinkingOutput(value) {
+    return isRecord(value) && typeof value.level === "string" && Array.isArray(value.availableLevels);
+}
+function isThinkingLevelSetOutput(value) {
+    return isRecord(value) && value.action === "set_thinking_level";
+}
 function groupRelatedToolCandidates(candidates) {
     const grouped = [];
     for (let index = 0; index < candidates.length; index += 1) {
@@ -640,32 +694,48 @@ function detailItemsForGroup(candidates, kind) {
 function classifyImageTool(node) {
     const normalized = (node.title ?? "").trim().toLowerCase();
     const args = isRecord(node.input) ? node.input : undefined;
-    const path = previewPath(args) ?? previewPath(isRecord(node.output) ? recordField(node.output, "details") : undefined) ?? previewPath(isRecord(node.output) ? node.output : undefined);
+    const output = isRecord(node.output) ? node.output : undefined;
+    const details = recordField(output, "details");
+    const codexOperation = normalized === "codex_image_generation" ? codexImageOperation(details) ?? codexImageOperationFromInput(args) : undefined;
+    const path = codexOperation
+        ? stringValue(details?.savedPath) ?? previewPath(details)
+        : previewPath(args) ?? previewPath(details) ?? previewPath(output);
+    const artifactId = codexOperation ? stringValue(details?.artifactId) : undefined;
     const query = previewQuery(args);
     const images = collectImagePayloads(node.output);
     const isImageTool = matchesTool(normalized, ["view_image", "image", "screenshot"]);
-    if (!images.length && !isImageTool)
+    if (!images.length && !isImageTool && !codexOperation)
         return undefined;
     const mimeType = images.map((image) => image.mimeType).find((value) => Boolean(value));
     const count = Math.max(1, images.length);
     const summary = {
         type: images.length > 1 ? "images" : images.length === 1 ? "image" : "image_reference",
+        toolName: codexOperation ? node.title : undefined,
+        operation: codexOperation,
         path,
+        savedPath: codexOperation ? path : undefined,
+        artifactId,
+        model: codexOperation ? stringValue(details?.model) : undefined,
+        referencedImageCount: codexOperation ? numberValue(details?.referencedImageCount) : undefined,
         query,
         mimeType,
         count: count > 1 ? count : undefined,
         detail: images.length ? "Image data hidden in terminal view." : "Image path only; binary data is hidden in terminal view.",
     };
-    const labelTarget = path ?? query ?? mimeType ?? "image";
+    const labelTarget = path ?? artifactId ?? query ?? mimeType ?? "image";
+    const verb = codexOperation ? codexImageVerb(node.status, codexOperation) : imageToolVerb(node.status, count);
     return {
         count,
         path,
+        artifactId,
         query,
         mimeType,
+        verb,
+        groupable: !codexOperation,
         summary,
         detail: {
             id: node.id,
-            label: `${node.status === "error" ? "Image failed" : "Viewed image"} ${labelTarget}`,
+            label: `${verb} ${labelTarget}`,
             status: mapStatus(node.status),
             input: sanitizeImagePayload(node.input),
             output: summary,
@@ -725,6 +795,34 @@ function imageToolVerb(status, count) {
         return count > 1 ? "Image reads failed" : "Image read failed";
     return count > 1 ? "Viewed images" : "Viewed image";
 }
+function codexImageOperation(details) {
+    const operation = stringValue(details?.operation);
+    return operation === "generate" || operation === "edit" ? operation : undefined;
+}
+function codexImageOperationFromInput(args) {
+    if (!args)
+        return undefined;
+    const referencedPaths = args.referenced_image_paths;
+    if (Array.isArray(referencedPaths) && referencedPaths.length > 0)
+        return "edit";
+    if (numberValue(args.num_last_images_to_include) !== undefined)
+        return "edit";
+    return "generate";
+}
+function codexImageVerb(status, operation) {
+    if (operation === "edit") {
+        if (status === "running")
+            return "Editing image";
+        if (status === "error")
+            return "Image edit failed";
+        return "Edited image";
+    }
+    if (status === "running")
+        return "Generating image";
+    if (status === "error")
+        return "Image generation failed";
+    return "Generated image";
+}
 function recordField(record, key) {
     const value = record?.[key];
     return isRecord(value) ? value : undefined;
@@ -789,6 +887,9 @@ function previewQuery(value) {
     }
     return undefined;
 }
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
 function previewLines(value, maxVisibleLines, tone = "dim", _maxLineLength = 160) {
     const empty = { lines: [], visibleLineCount: 0, omittedLineCount: 0, totalLineCount: 0, maxVisibleLineCount: maxVisibleLines };
     const text = previewText(value);

package/dist/shared/trace-nodes.js

@@ -19,6 +19,9 @@ function areTraceNodesSorted(nodes) {
     return true;
 }
 export function compareTraceNodes(left, right) {
+    const bySameTurnPhase = compareSameTurnPhase(left, right);
+    if (bySameTurnPhase !== 0)
+        return bySameTurnPhase;
     const byStartTime = compareOptionalIsoTime(left.startedAt, right.startedAt);
     if (byStartTime !== 0)
         return byStartTime;
@@ -27,6 +30,15 @@ export function compareTraceNodes(left, right) {
         return byOrder;
     return left.id.localeCompare(right.id);
 }
+function compareSameTurnPhase(left, right) {
+    if (!left.eventId || left.eventId !== right.eventId)
+        return 0;
+    const leftPhase = left.orderKey?.phaseRank;
+    const rightPhase = right.orderKey?.phaseRank;
+    if (leftPhase === undefined || rightPhase === undefined)
+        return 0;
+    return leftPhase - rightPhase;
+}
 function compareOptionalIsoTime(left, right) {
     if (!left && !right)
         return 0;

package/dist/skills/cli.js

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { createDefaultPiboPluginRegistry } from "../plugins/builtin.js";
 import { UserSkillManager } from "../user-skills/manager.js";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
@@ -9,7 +10,30 @@ function printJson(value) {
 export async function runSkillsCli(argv) {
     const manager = new UserSkillManager(os.homedir());
     const program = new Command();
-    program.name("pibo skills").description("Manage Pibo user skills (not built-in or plugin skills)");
+    program
+        .name("pibo skills")
+        .description("Manage Pibo user skills and inspect the built-in/plugin skill catalog")
+        .addHelpText("after", "\nBuilt-in/plugin skills are selected by agent profiles. Run `pibo skills catalog` to list them.\n");
+    program
+        .command("catalog")
+        .description("List built-in and plugin skills available to profiles")
+        .option("--json", "Print JSON")
+        .action((options) => {
+        const registry = createDefaultPiboPluginRegistry();
+        const skills = registry.getCapabilityCatalog().skills.filter((skill) => skill.kind !== "user");
+        if (options.json) {
+            printJson(skills);
+            return;
+        }
+        if (skills.length === 0) {
+            console.log("No built-in or plugin skills registered.");
+            return;
+        }
+        console.log("NAME\tKIND\tPATH");
+        for (const skill of skills) {
+            console.log(`${skill.name}\t${skill.kind ?? "plugin"}\t${skill.path}`);
+        }
+    });
     program
         .command("list")
         .description("List user skills managed by this CLI")

package/dist/tools/codex-image-generation.js

@@ -0,0 +1,272 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { platform, release, arch } from "node:os";
+import { dirname, extname, isAbsolute, join, resolve } from "node:path";
+import { AuthStorage } from "@mariozechner/pi-coding-agent";
+import { Type } from "@mariozechner/pi-ai";
+import { defineTool } from "@mariozechner/pi-coding-agent";
+import { getPiboHome } from "../core/pibo-home.js";
+const OPENAI_CODEX_PROVIDER = "openai-codex";
+const DEFAULT_CODEX_BACKEND_BASE_URL = "https://chatgpt.com/backend-api";
+const CODEX_IMAGE_MODEL = "gpt-image-2";
+const MAX_EDIT_IMAGES = 5;
+const OPENAI_JWT_CLAIM_PATH = "https://api.openai.com/auth";
+function trimTrailingSlashes(value) {
+    return value.replace(/\/+$/, "");
+}
+export function resolveCodexImageUrl(operation, baseUrl) {
+    const raw = baseUrl && baseUrl.trim().length > 0 ? baseUrl : DEFAULT_CODEX_BACKEND_BASE_URL;
+    let normalized = trimTrailingSlashes(raw.trim());
+    if (normalized.endsWith("/codex/responses"))
+        normalized = normalized.slice(0, -"/responses".length);
+    if (!normalized.endsWith("/codex"))
+        normalized = `${normalized}/codex`;
+    return `${normalized}/images/${operation}`;
+}
+function decodeJwtPayload(token) {
+    try {
+        const payload = token.split(".")[1];
+        if (!payload)
+            return undefined;
+        const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+        const parsed = JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getOpenAiAccountId(accessToken, storedAccountId) {
+    if (typeof storedAccountId === "string" && storedAccountId.trim().length > 0)
+        return storedAccountId;
+    const payload = decodeJwtPayload(accessToken);
+    const auth = payload?.[OPENAI_JWT_CLAIM_PATH];
+    if (!auth || typeof auth !== "object" || Array.isArray(auth))
+        return undefined;
+    const accountId = auth.chatgpt_account_id;
+    return typeof accountId === "string" && accountId.trim().length > 0 ? accountId : undefined;
+}
+async function getCodexImageAuth() {
+    const authStorage = AuthStorage.create();
+    const credential = authStorage.get(OPENAI_CODEX_PROVIDER);
+    if (credential?.type !== "oauth") {
+        throw new Error("codex_image_generation requires ChatGPT/Codex OAuth login for provider openai-codex. Use the existing OpenAI Codex login flow; API keys are not supported for this tool.");
+    }
+    const accessToken = await authStorage.getApiKey(OPENAI_CODEX_PROVIDER, { includeFallback: false });
+    if (!accessToken) {
+        throw new Error("codex_image_generation could not load a ChatGPT/Codex OAuth access token for provider openai-codex. Please log in again with the OpenAI Codex login flow.");
+    }
+    const accountId = getOpenAiAccountId(accessToken, credential.accountId);
+    if (!accountId) {
+        throw new Error("codex_image_generation could not resolve the ChatGPT account id from the openai-codex OAuth credential. Please log in again with the OpenAI Codex login flow.");
+    }
+    return { accessToken, accountId };
+}
+function mimeTypeForPath(path) {
+    switch (extname(path).toLowerCase()) {
+        case ".jpg":
+        case ".jpeg":
+            return "image/jpeg";
+        case ".webp":
+            return "image/webp";
+        case ".gif":
+            return "image/gif";
+        default:
+            return "image/png";
+    }
+}
+function resolveCwd(baseCwd, path) {
+    return isAbsolute(path) ? path : resolve(baseCwd, path);
+}
+function isImageContent(value) {
+    return Boolean(value)
+        && typeof value === "object"
+        && value.type === "image"
+        && typeof value.data === "string"
+        && typeof value.mimeType === "string";
+}
+function imageContentToDataUrl(image) {
+    if (image.data.startsWith("data:"))
+        return image.data;
+    return `data:${image.mimeType};base64,${image.data}`;
+}
+async function imageFileToDataUrl(cwd, path) {
+    const resolved = resolveCwd(cwd, path);
+    const data = await readFile(resolved);
+    return `data:${mimeTypeForPath(resolved)};base64,${data.toString("base64")}`;
+}
+function contentFromSessionEntry(entry) {
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    const record = entry;
+    if (record.type === "message") {
+        const message = record.message;
+        return message && typeof message === "object" ? message.content : undefined;
+    }
+    if (record.type === "custom_message")
+        return record.content;
+    return undefined;
+}
+function recentImagesFromSessionEntries(entries, count) {
+    const images = [];
+    for (const entry of [...entries].reverse()) {
+        const content = contentFromSessionEntry(entry);
+        if (!Array.isArray(content))
+            continue;
+        for (const item of [...content].reverse()) {
+            if (!isImageContent(item))
+                continue;
+            images.push(imageContentToDataUrl(item));
+            if (images.length === count)
+                break;
+        }
+        if (images.length === count)
+            break;
+    }
+    images.reverse();
+    return images.map((image_url) => ({ image_url }));
+}
+function validateImageArgs(params) {
+    if (params.prompt.trim().length === 0)
+        throw new Error("`prompt` must not be empty.");
+    const pathCount = params.referenced_image_paths?.length ?? 0;
+    if (pathCount > MAX_EDIT_IMAGES)
+        throw new Error(`\`referenced_image_paths\` must contain at most ${MAX_EDIT_IMAGES} paths.`);
+    if (pathCount > 0 && params.num_last_images_to_include !== undefined) {
+        throw new Error("Provide only one of `referenced_image_paths` or `num_last_images_to_include`.");
+    }
+    if (params.num_last_images_to_include !== undefined) {
+        if (!Number.isInteger(params.num_last_images_to_include) || params.num_last_images_to_include < 1 || params.num_last_images_to_include > MAX_EDIT_IMAGES) {
+            throw new Error(`\`num_last_images_to_include\` must be an integer between 1 and ${MAX_EDIT_IMAGES}.`);
+        }
+    }
+}
+function sanitizePathPart(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 120) || "unknown";
+}
+function artifactPath(sessionId, toolCallId) {
+    const safeSessionId = sanitizePathPart(sessionId?.trim() || "local");
+    const safeToolCallId = sanitizePathPart(toolCallId || `image_${Date.now()}`);
+    const artifactId = `${safeSessionId}/${safeToolCallId}.png`;
+    return {
+        artifactId,
+        savedPath: join(getPiboHome(), "generated_images", safeSessionId, `${safeToolCallId}.png`),
+    };
+}
+async function saveGeneratedImage(sessionId, toolCallId, b64Json) {
+    const target = artifactPath(sessionId, toolCallId);
+    await mkdir(dirname(target.savedPath), { recursive: true });
+    await writeFile(target.savedPath, Buffer.from(b64Json.trim(), "base64"));
+    return target;
+}
+function truncateErrorBody(text) {
+    const compact = text.replace(/\s+/g, " ").trim();
+    return compact.length > 1000 ? `${compact.slice(0, 1000)}…` : compact;
+}
+async function postCodexImageRequest(operation, body, auth, signal, baseUrl) {
+    const url = resolveCodexImageUrl(operation, baseUrl);
+    const response = await fetch(url, {
+        method: "POST",
+        signal,
+        headers: {
+            Authorization: `Bearer ${auth.accessToken}`,
+            "chatgpt-account-id": auth.accountId,
+            originator: "pi",
+            "User-Agent": `pibo (${platform()} ${release()}; ${arch()})`,
+            Accept: "application/json",
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        throw new Error(`Codex image ${operation} request failed: ${response.status}${text ? ` ${truncateErrorBody(text)}` : ""}`);
+    }
+    return await response.json();
+}
+function firstImageB64(response) {
+    const b64 = response.data?.[0]?.b64_json;
+    if (!b64 || typeof b64 !== "string")
+        throw new Error("Codex image generation returned no image data.");
+    return b64;
+}
+function createRequest(prompt, images) {
+    return {
+        ...(images && images.length > 0 ? { images } : {}),
+        prompt,
+        background: "auto",
+        model: CODEX_IMAGE_MODEL,
+        quality: "auto",
+        size: "auto",
+    };
+}
+async function collectEditImages(params, cwd, sessionEntries) {
+    const paths = params.referenced_image_paths ?? [];
+    if (paths.length > 0) {
+        return await Promise.all(paths.map(async (path) => ({ image_url: await imageFileToDataUrl(cwd, path) })));
+    }
+    if (params.num_last_images_to_include !== undefined) {
+        const images = recentImagesFromSessionEntries(sessionEntries, params.num_last_images_to_include);
+        if (images.length !== params.num_last_images_to_include) {
+            throw new Error(`Requested the last ${params.num_last_images_to_include} conversation images, but only ${images.length} were available.`);
+        }
+        return images;
+    }
+    return [];
+}
+export function createCodexImageGenerationToolDefinition(context = {}, options = {}) {
+    return defineTool({
+        name: "codex_image_generation",
+        label: "Codex Image Generation",
+        description: "Generates or edits images through the ChatGPT/Codex backend API using openai-codex OAuth entitlement. Does not use the public OpenAI Images API.",
+        promptSnippet: "Use codex_image_generation to create an image from a prompt, or to edit referenced/recent images with the Codex/ChatGPT image backend.",
+        promptGuidelines: [
+            "Use codex_image_generation for image generation and image edits when the user asks for pictures, visual variants, or edits to existing images.",
+            "For edits, pass either referenced_image_paths for local image files or num_last_images_to_include for recent conversation images, but not both.",
+        ],
+        executionMode: "sequential",
+        parameters: Type.Object({
+            prompt: Type.String({ description: "Image generation/editing prompt. Be specific about the desired final image." }),
+            referenced_image_paths: Type.Optional(Type.Array(Type.String({ description: "Local filesystem image path to edit." }), { description: `Optional local image paths to edit. At most ${MAX_EDIT_IMAGES}.` })),
+            num_last_images_to_include: Type.Optional(Type.Number({ description: `Use the last N conversation images as edit references. Must be between 1 and ${MAX_EDIT_IMAGES}.` })),
+        }),
+        async execute(toolCallId, params, signal, _onUpdate, ctx) {
+            validateImageArgs(params);
+            const images = await collectEditImages(params, ctx.cwd, ctx.sessionManager.getBranch());
+            const operation = images.length > 0 ? "edit" : "generate";
+            const endpoint = operation === "edit" ? "edits" : "generations";
+            const auth = await getCodexImageAuth();
+            const response = await postCodexImageRequest(endpoint, createRequest(params.prompt, images), auth, signal, options.baseUrl);
+            const result = firstImageB64(response);
+            const saved = await saveGeneratedImage(context.piboSessionId, toolCallId, result);
+            const details = {
+                provider: OPENAI_CODEX_PROVIDER,
+                api: "codex-chatgpt-images",
+                operation,
+                model: CODEX_IMAGE_MODEL,
+                savedPath: saved.savedPath,
+                artifactId: saved.artifactId,
+                referencedImageCount: images.length,
+                endpoint,
+                created: response.created,
+                background: response.background,
+                quality: response.quality,
+                size: response.size,
+            };
+            return {
+                content: [
+                    { type: "image", data: result, mimeType: "image/png" },
+                    { type: "text", text: `Generated image saved to ${saved.savedPath}` },
+                ],
+                details,
+            };
+        },
+    });
+}
+export function createCodexImageGenerationToolProfile() {
+    return {
+        name: "codex_image_generation",
+        description: "Generate and edit images through the ChatGPT/Codex backend API using openai-codex OAuth.",
+        createDefinition: createCodexImageGenerationToolDefinition,
+    };
+}

package/dist/tools/guides.js

@@ -379,6 +379,77 @@ If \`browser-use --connect\` cannot find Chrome, ask the user whether they want
 14. If Chrome fails to start with a "SingletonLock" error, the wrapper auto-detects and terminates stale Chrome processes holding the lock. Retry your command.
 `,
 };
+export const GRAPHIFY_GUIDE = {
+    name: 'graphify',
+    description: 'Generate codebase knowledge graphs with the Graphify CLI.',
+    content: `---
+name: graphify
+description: Generates interactive codebase knowledge graphs and markdown reports from a workspace folder.
+allowed-tools: Bash(graphify:*)
+---
+
+# Codebase Visualization with Graphify
+
+Graphify turns a folder into derived artifacts under \`graphify-out/\`:
+
+- \`graphify-out/graph.html\` — an interactive clickable graph;
+- \`graphify-out/graph.json\` — machine-readable graph data;
+- \`graphify-out/GRAPH_REPORT.md\` — a markdown summary with key concepts and suggested questions.
+
+Use it when a user asks to graph, map, visualize, or quickly understand a repo/workspace shape.
+
+## Prerequisites
+
+Install and apply the Pibo tool environment:
+
+\`\`\`bash
+pibo tools install graphify
+eval "$(pibo tools env graphify)"
+graphify --help
+\`\`\`
+
+Inside the Pibo source repo, use \`npm run --silent dev -- tools ...\` while testing local changes:
+
+\`\`\`bash
+npm run --silent dev -- tools install graphify
+eval "$(npm run --silent dev -- tools env graphify)"
+\`\`\`
+
+The installer uses the PyPI package \`graphifyy\` and runs \`graphify install --platform pi\` so the CLI is ready for Pi/Pibo workflows.
+
+## Core Workflow
+
+1. Choose the workspace path. Prefer the active Pibo Room or session workspace boundary when known.
+2. Run Graphify from that folder or pass the target path explicitly. With \`graphifyy==0.9.x\`, \`graphify .\` writes extraction output under \`graphify-out/\`.
+3. For a code-only workspace without an LLM key, run \`graphify cluster-only . --no-label\` after extraction to produce the HTML graph and markdown report.
+4. Put generated artifacts in an ignored room/session artifact directory when possible; do not commit them unless the user explicitly asks.
+5. Read \`graphify-out/GRAPH_REPORT.md\` first, then open \`graphify-out/graph.html\` when an interactive view is useful.
+
+\`\`\`bash
+cd /path/to/workspace
+graphify .
+graphify cluster-only . --no-label
+ls graphify-out/graph.html graphify-out/graph.json graphify-out/GRAPH_REPORT.md
+\`\`\`
+
+## Pibo Usage Notes
+
+- For Room-bound work, graph the Room workspace rather than the agent harness checkout unless the user asks otherwise.
+- If generating inside a Git repo, check \`git status --short\` before and after so graph artifacts are not accidentally included in unrelated commits.
+- Code-only extraction can run without an LLM API key. Including docs, README files, papers, images, or semantic-labeling steps may require a configured Graphify backend/API key; if no key is available, graph a code-only subdirectory or skip semantic labels with \`cluster-only . --no-label\`.
+- For large monorepos, start with a subdirectory such as \`src/\`, a code package, or a docs folder only when the needed LLM backend is configured.
+- Treat graph output as derived data. Recompute on demand when the branch or workspace changes.
+
+## Next Commands
+
+\`\`\`bash
+pibo tools show graphify
+pibo tools guide graphify graphify
+pibo tools path graphify
+pibo tools doctor graphify
+\`\`\`
+`,
+};
 export const REMOTE_BROWSER_GUIDE = {
     name: 'remote-browser',
     description: 'Browser automation workflow for sandboxed or remote agents.',

package/dist/tools/index.js

@@ -166,9 +166,13 @@ function printEnv(name) {
         return;
     }
     const binDir = status.executablePath.replace(/\/[^/]+$/, '');
-    const wrapperPath = entry.name === 'agent-browser' ? ensureAgentBrowserWrapper(status) : ensureBrowserUseWrapper(status);
-    const wrapperBinDir = wrapperPath ? wrapperPath.replace(/\/[^/]+$/, '') : `${status.homeDir}/bin`;
-    console.log(`export PATH="${wrapperBinDir}:${binDir}:$PATH"`);
+    const wrapperPath = entry.name === 'browser-use'
+        ? ensureBrowserUseWrapper(status)
+        : entry.name === 'agent-browser'
+            ? ensureAgentBrowserWrapper(status)
+            : undefined;
+    const envBinDirs = wrapperPath ? `${wrapperPath.replace(/\/[^/]+$/, '')}:${binDir}` : binDir;
+    console.log(`export PATH="${envBinDirs}:$PATH"`);
     if (entry.runtime.homeEnvVar)
         console.log(`export ${entry.runtime.homeEnvVar}="${status.homeDir}"`);
     if (desktop.display)

package/dist/tools/python-runtime.js

@@ -123,8 +123,8 @@ export async function printToolPythonRuntimeDoctor(name, spec) {
     if (name === 'browser-use' && process.platform === 'linux' && !hasDesktopDisplay(detectDesktopEnv())) {
         printLinuxVirtualDisplayHint('  ');
     }
-    if (existsSync(paths.executablePath)) {
-        const doctor = await runBuffered(paths.executablePath, ['doctor'], getToolPythonRuntimeEnv(paths, spec));
+    if (existsSync(paths.executablePath) && spec.doctorArgs?.length) {
+        const doctor = await runBuffered(paths.executablePath, spec.doctorArgs, getToolPythonRuntimeEnv(paths, spec));
         console.log(`  tool doctor: ${doctor.ok ? 'ok' : 'failed'}`);
         if (doctor.output) {
             console.log(doctor.output.split('\n').map((line) => `    ${line}`).join('\n'));