@poolzin/pool-bot 2026.2.19 → 2026.2.21

package/dist/agents/tools/deep-research-tool.js

@@ -0,0 +1,225 @@
+import { Type } from "@sinclair/typebox";
+import { ensureAuthProfileStore, listProfilesForProvider } from "../auth-profiles.js";
+import { resolveEnvApiKey } from "../model-auth.js";
+import { jsonResult, readNumberParam, readStringParam } from "./common.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const ZAI_BASE_URL = "https://open.bigmodel.cn/api/paas/v4";
+/**
+ * GLM-4.7-Flash is FREE and supports the built-in web_search tool ($0.01/use).
+ * Perfect for deep research: model synthesis is free, search costs are negligible.
+ */
+const RESEARCH_MODEL = "GLM-4.7-Flash";
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const DeepResearchSchema = Type.Object({
+    topic: Type.String({
+        description: "The research topic or question. Be specific — include what aspects to cover, time range, and scope.",
+    }),
+    depth: Type.Optional(Type.String({
+        description: 'Research depth: "shallow" (quick overview, 1 search), "standard" (balanced, 2-3 searches, default), or "deep" (thorough, 4-5 searches with follow-ups).',
+    })),
+    language: Type.Optional(Type.String({
+        description: 'Language for the research report. Default: "en" (English). Use ISO 639-1 codes (e.g. "pt", "zh", "ja").',
+    })),
+    max_sources: Type.Optional(Type.Number({
+        description: "Maximum number of sources to include. Default: 10. Range: 1–20.",
+    })),
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the Z.AI API key from environment or auth profiles.
+ * Same logic as image-generate-tool.ts — kept as a local copy to avoid
+ * cross-tool coupling.
+ */
+function resolveZaiApiKey(agentDir) {
+    const envKey = resolveEnvApiKey("zai");
+    if (envKey?.apiKey)
+        return envKey.apiKey;
+    const store = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
+    const profileIds = listProfilesForProvider(store, "zai");
+    for (const id of profileIds) {
+        const cred = store.profiles[id];
+        if (!cred)
+            continue;
+        if (cred.type === "api_key")
+            return cred.key;
+        if (cred.type === "token")
+            return cred.token;
+    }
+    return null;
+}
+function normalizeDepth(raw) {
+    if (!raw)
+        return "standard";
+    const lower = raw.trim().toLowerCase();
+    if (lower === "shallow" || lower === "quick" || lower === "brief")
+        return "shallow";
+    if (lower === "deep" || lower === "thorough" || lower === "comprehensive")
+        return "deep";
+    return "standard";
+}
+/**
+ * Build the system prompt for the research agent.
+ * Tailored to the requested depth and language.
+ */
+function buildSystemPrompt(depth, language, maxSources) {
+    const depthGuidance = {
+        shallow: "Provide a concise overview. Use 1 web search to gather key facts. Keep the report brief — 3-5 paragraphs max.",
+        standard: "Provide a balanced research report. Use 2-3 web searches to gather diverse perspectives. Structure with clear sections and cite sources.",
+        deep: "Provide a thorough, in-depth research report. Use 4-5 web searches covering different angles (academic, news, expert opinions, primary sources). Include nuanced analysis, counterarguments, and comprehensive source citations.",
+    };
+    const langInstruction = language === "en"
+        ? ""
+        : `\nWrite the entire report in ${language} language. Search queries can be in any language for best results, but the final output must be in ${language}.`;
+    return [
+        "You are a professional research analyst. Your task is to produce a well-structured research report on the given topic.",
+        "",
+        `Research depth: ${depth}.`,
+        depthGuidance[depth],
+        "",
+        "Guidelines:",
+        "- Use the web_search tool to find current, reliable information.",
+        "- Cross-reference multiple sources for accuracy.",
+        "- Cite all sources with titles and URLs.",
+        `- Include up to ${maxSources} sources.`,
+        "- Structure the report with: Summary, Key Findings, Detailed Analysis, Sources.",
+        "- Be factual and objective. Clearly distinguish facts from analysis.",
+        "- Include dates for time-sensitive information.",
+        langInstruction,
+    ]
+        .filter((line) => line !== undefined)
+        .join("\n");
+}
+/**
+ * Call Z.AI chat completions with web_search tool enabled.
+ */
+async function callZaiResearch(params) {
+    const systemPrompt = buildSystemPrompt(params.depth, params.language, params.maxSources);
+    const body = {
+        model: RESEARCH_MODEL,
+        messages: [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: params.topic },
+        ],
+        tools: [
+            {
+                type: "web_search",
+                web_search: {
+                    enable: true,
+                    search_result: true, // include search results in response metadata
+                },
+            },
+        ],
+        temperature: 0.3, // lower temp for factual research
+        stream: false,
+    };
+    const response = await fetch(`${ZAI_BASE_URL}/chat/completions`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${params.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "unknown error");
+        throw new Error(`Z.AI research request failed (HTTP ${response.status}): ${errorText}`);
+    }
+    const result = (await response.json());
+    if (result.error) {
+        throw new Error(`Z.AI research error: ${result.error.message} (${result.error.code})`);
+    }
+    const content = result.choices?.[0]?.message?.content;
+    if (!content) {
+        throw new Error("Z.AI research returned no content.");
+    }
+    return {
+        report: content,
+        sources: result.web_search ?? [],
+        usage: {
+            promptTokens: result.usage?.prompt_tokens ?? 0,
+            completionTokens: result.usage?.completion_tokens ?? 0,
+            totalTokens: result.usage?.total_tokens ?? 0,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the deep-research tool powered by Z.AI GLM-4.7-Flash + web_search.
+ *
+ * Cost breakdown:
+ * - GLM-4.7-Flash inference: FREE
+ * - web_search: $0.01/use (1-5 searches depending on depth)
+ * - Total per research query: ~$0.01–$0.05
+ *
+ * Returns null if no Z.AI API key is available (graceful degradation).
+ */
+export function createDeepResearchTool(options) {
+    const agentDir = options?.agentDir?.trim();
+    if (!agentDir)
+        return null;
+    const apiKey = resolveZaiApiKey(agentDir);
+    if (!apiKey)
+        return null;
+    return {
+        label: "Deep Research",
+        name: "deep_research",
+        description: [
+            "Perform deep web research on any topic using Z.AI GLM-4.7-Flash + web search.",
+            "Returns a structured research report with citations and sources.",
+            "",
+            "Depth options:",
+            '- "shallow": Quick overview (~$0.01, 1 search)',
+            '- "standard": Balanced report (~$0.03, 2-3 searches)',
+            '- "deep": Thorough analysis (~$0.05, 4-5 searches)',
+            "",
+            "Cost: GLM-4.7-Flash is FREE; only web search costs $0.01/use.",
+            "Best for: current events, technical topics, market research, fact-checking.",
+        ].join("\n"),
+        parameters: DeepResearchSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const topic = readStringParam(params, "topic", { required: true });
+            const depthRaw = readStringParam(params, "depth");
+            const language = readStringParam(params, "language") ?? "en";
+            const maxSourcesRaw = readNumberParam(params, "max_sources", { integer: true });
+            const depth = normalizeDepth(depthRaw);
+            const maxSources = Math.max(1, Math.min(20, maxSourcesRaw ?? 10));
+            const result = await callZaiResearch({
+                apiKey,
+                topic,
+                depth,
+                language,
+                maxSources,
+            });
+            // Build a structured response
+            const sourcesList = result.sources.map((s, i) => ({
+                index: i + 1,
+                title: s.title,
+                url: s.link,
+                snippet: s.content?.slice(0, 200),
+            }));
+            const estimatedSearches = depth === "shallow" ? 1 : depth === "standard" ? 3 : 5;
+            const estimatedCost = `~$${(estimatedSearches * 0.01).toFixed(2)}`;
+            return jsonResult({
+                report: result.report,
+                sources: sourcesList,
+                metadata: {
+                    model: RESEARCH_MODEL,
+                    depth,
+                    language,
+                    sourceCount: sourcesList.length,
+                    estimatedCost,
+                    tokens: result.usage,
+                },
+            });
+        },
+    };
+}

package/dist/agents/tools/image-generate-tool.js

@@ -0,0 +1,235 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Type } from "@sinclair/typebox";
+import { resolveUserPath } from "../../utils.js";
+import { ensureAuthProfileStore, listProfilesForProvider } from "../auth-profiles.js";
+import { resolveEnvApiKey } from "../model-auth.js";
+import { imageResult, readStringParam } from "./common.js";
+// Z.AI image generation models
+const ZAI_BASE_URL = "https://open.bigmodel.cn/api/paas/v4";
+const ImageGenerateSchema = Type.Object({
+    prompt: Type.String({
+        description: "Description of the image to generate. Be descriptive — include subject, style, lighting, mood, composition, and artistic direction.",
+    }),
+    model: Type.Optional(Type.String({
+        description: 'Image generation model: "cogview-4" (default, $0.01/img), "cogview-4-flash" (faster, $0.004/img), or "glm-image" (highest quality, $0.015/img). Default: cogview-4.',
+    })),
+    size: Type.Optional(Type.String({
+        description: 'Image dimensions (WxH). Supported: "1024x1024" (default), "768x1344", "864x1152", "1344x768", "1152x864", "1440x720", "720x1440". Must be multiples of 32, range 512–2048.',
+    })),
+    quality: Type.Optional(Type.String({
+        description: 'Image quality: "standard" (default) or "hd" (higher detail, slower).',
+    })),
+    save_path: Type.Optional(Type.String({
+        description: "File path to save the generated image. If omitted, saves to the agent working directory with an auto-generated name.",
+    })),
+});
+/**
+ * Resolve the Z.AI API key from environment or auth profiles.
+ */
+function resolveZaiApiKey(agentDir) {
+    const envKey = resolveEnvApiKey("zai");
+    if (envKey?.apiKey)
+        return envKey.apiKey;
+    const store = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
+    const profileIds = listProfilesForProvider(store, "zai");
+    for (const id of profileIds) {
+        const cred = store.profiles[id];
+        if (!cred)
+            continue;
+        if (cred.type === "api_key")
+            return cred.key;
+        if (cred.type === "token")
+            return cred.token;
+    }
+    return null;
+}
+/**
+ * Validate and normalize the image model identifier.
+ */
+function normalizeImageModel(raw) {
+    if (!raw)
+        return "cogview-4";
+    const lower = raw.trim().toLowerCase();
+    const validModels = [
+        "cogview-4",
+        "cogview-4-250304",
+        "cogview-4-flash",
+        "glm-image",
+    ];
+    if (validModels.includes(lower)) {
+        return lower;
+    }
+    // Fuzzy matching for common variants
+    if (lower.includes("flash"))
+        return "cogview-4-flash";
+    if (lower.includes("glm") || lower.includes("flagship"))
+        return "glm-image";
+    if (lower.includes("cog") || lower.includes("view"))
+        return "cogview-4";
+    return "cogview-4";
+}
+/**
+ * Validate image size. Z.AI accepts WxH where both dimensions are 512–2048 and multiples of 32.
+ */
+function normalizeImageSize(raw) {
+    if (!raw)
+        return "1024x1024";
+    const trimmed = raw.trim().toLowerCase();
+    // Parse WxH format
+    const match = trimmed.match(/^(\d+)\s*[x×]\s*(\d+)$/);
+    if (!match)
+        return "1024x1024";
+    let w = Number.parseInt(match[1], 10);
+    let h = Number.parseInt(match[2], 10);
+    // Clamp to valid range
+    w = Math.max(512, Math.min(2048, w));
+    h = Math.max(512, Math.min(2048, h));
+    // Round to nearest multiple of 32
+    w = Math.round(w / 32) * 32;
+    h = Math.round(h / 32) * 32;
+    return `${w}x${h}`;
+}
+/**
+ * Call the Z.AI image generation API.
+ */
+async function generateImage(params) {
+    const body = {
+        model: params.model,
+        prompt: params.prompt,
+        size: params.size,
+        quality: params.quality,
+        n: 1,
+    };
+    const response = await fetch(`${ZAI_BASE_URL}/images/generations`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${params.apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "unknown error");
+        throw new Error(`Z.AI image generation failed (HTTP ${response.status}): ${errorText}`);
+    }
+    const result = (await response.json());
+    if (result.error) {
+        throw new Error(`Z.AI image generation error: ${result.error.message} (${result.error.code})`);
+    }
+    if (!result.data?.[0]) {
+        throw new Error("Z.AI image generation returned no images.");
+    }
+    const imageData = result.data[0];
+    const imageUrl = imageData.url ?? imageData.b64_json;
+    if (!imageUrl) {
+        throw new Error("Z.AI image generation returned no image URL or data.");
+    }
+    return {
+        imageUrl: imageData.url ?? "",
+        revisedPrompt: imageData.revised_prompt,
+    };
+}
+/**
+ * Download an image from URL and return its buffer.
+ */
+async function downloadImage(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to download generated image (HTTP ${response.status})`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+}
+/**
+ * Generate a unique filename for saved images.
+ */
+function generateImageFilename(model) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    return `generated-${model}-${timestamp}.png`;
+}
+/**
+ * Create the image-generate tool for Z.AI CogView-4 / GLM-Image.
+ *
+ * Supports:
+ * - CogView-4: $0.01/image, general purpose
+ * - CogView-4-Flash: $0.004/image, faster generation
+ * - GLM-Image: $0.015/image, highest quality
+ */
+export function createImageGenerateTool(options) {
+    const agentDir = options?.agentDir?.trim();
+    if (!agentDir)
+        return null;
+    // Check if Z.AI API key is available
+    const apiKey = resolveZaiApiKey(agentDir);
+    if (!apiKey)
+        return null;
+    return {
+        label: "Image Generate",
+        name: "image_generate",
+        description: [
+            "Generate images from text descriptions using Z.AI (ZhipuAI) image models.",
+            "Available models:",
+            '- "cogview-4" (default): General-purpose, $0.01/image',
+            '- "cogview-4-flash": Faster generation, $0.004/image',
+            '- "glm-image": Highest quality, $0.015/image',
+            "",
+            "Write detailed, descriptive prompts for best results.",
+            "The generated image is saved to disk and returned as MEDIA: path.",
+            "Copy the MEDIA line exactly when presenting the image to the user.",
+        ].join("\n"),
+        parameters: ImageGenerateSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const prompt = readStringParam(params, "prompt", { required: true });
+            const modelRaw = readStringParam(params, "model");
+            const sizeRaw = readStringParam(params, "size");
+            const qualityRaw = readStringParam(params, "quality");
+            const savePathRaw = readStringParam(params, "save_path");
+            const model = normalizeImageModel(modelRaw);
+            const size = normalizeImageSize(sizeRaw);
+            const quality = qualityRaw?.toLowerCase() === "hd" ? "hd" : "standard";
+            // Generate the image
+            const result = await generateImage({
+                apiKey,
+                model,
+                prompt,
+                size,
+                quality,
+            });
+            // Download the generated image
+            const imageBuffer = await downloadImage(result.imageUrl);
+            const base64 = imageBuffer.toString("base64");
+            // Determine save path
+            const filename = generateImageFilename(model);
+            const savePath = savePathRaw
+                ? savePathRaw.startsWith("~")
+                    ? resolveUserPath(savePathRaw)
+                    : savePathRaw
+                : path.join(agentDir, filename);
+            // Ensure directory exists and write
+            await fs.mkdir(path.dirname(savePath), { recursive: true });
+            await fs.writeFile(savePath, imageBuffer);
+            return imageResult({
+                label: "image_generate",
+                path: savePath,
+                base64,
+                mimeType: "image/png",
+                extraText: [
+                    `MEDIA:${savePath}`,
+                    result.revisedPrompt ? `Revised prompt: ${result.revisedPrompt}` : "",
+                ]
+                    .filter(Boolean)
+                    .join("\n"),
+                details: {
+                    model,
+                    size,
+                    quality,
+                    prompt: prompt.slice(0, 200),
+                    revisedPrompt: result.revisedPrompt,
+                    cost: model === "glm-image" ? "$0.015" : model === "cogview-4-flash" ? "$0.004" : "$0.01",
+                },
+            });
+        },
+    };
+}

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026.2.19",
-  "commit": "8491aa098a0215c3b1d5e8c853c27400ec2924e8",
-  "builtAt": "2026-02-18T00:08:38.731Z"
+  "version": "2026.2.21",
+  "commit": "c1b8db5b38e189213061393716632d810d42bafd",
+  "builtAt": "2026-02-18T06:05:30.087Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolzin/pool-bot",
-  "version": "2026.2.19",
+  "version": "2026.2.21",
   "description": "🎱 Pool Bot - AI assistant with PLCODE integrations",
   "keywords": [],
   "license": "MIT",

package/skills/plcode-controller/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: plcode-controller
+description: "Control and operate PLCODE via CLI commands, slash commands, and multi-agent orchestration. Manage sessions, select models, delegate to agents (plan/code/review), and coordinate development workflows."
+metadata: {"poolbot":{"emoji":"🎛️","requires":{"anyBins":["plcode"]}}}
+---
+
+# PLCODE Controller
+
+## Core Rule
+
+All planning, coding, and review happens inside PLCODE.
+Use the appropriate agent for each phase of work.
+Never skip the planning phase.
+
+## Pre-flight
+
+- Confirm the user's working directory and project.
+- Ask which AI provider/model to use if not already configured.
+- Run `plcode doctor` to verify the environment is healthy.
+- Do not proceed if critical issues are detected.
+
+## Session Management
+
+- Check for existing sessions using:
+  ```
+  plcode session list
+  ```
+- If the current project already has a session, reuse it.
+- Never create a new session without user approval.
+- Sessions are tied to project directories and preserve full context.
+
+## Agent Control
+
+PLCODE uses multi-agent orchestration (AGNOS) with specialized agents. List available agents:
+
+```
+plcode agents list
+```
+
+Key agents for the standard workflow:
+
+| Agent          | Role                                         |
+| -------------- | -------------------------------------------- |
+| planner_agent  | Task analysis, step-by-step planning         |
+| code_agent     | Code implementation and refactoring          |
+| review_agent   | Code review with metrics, no subjective bias |
+| test_agent     | Test-driven development (RED-GREEN-REFACTOR) |
+| critic_agent   | Compare approaches and select best plan      |
+| executor_agent | Execute code in controlled sandbox           |
+
+Inspect any agent for details:
+
+```
+plcode agents inspect <agent-name>
+```
+
+## Model Selection
+
+- List available models:
+  ```
+  plcode models
+  ```
+- For detailed provider info:
+  ```
+  plcode models --verbose
+  ```
+- If authentication is needed:
+  ```
+  plcode auth
+  ```
+- Wait for the user to confirm auth is complete before continuing.
+
+## Planning Phase
+
+Use the `/plan` command to create structured execution plans:
+
+```
+/plan <task description>
+```
+
+The TaskPlanner will:
+
+- Analyze task complexity (simple / moderate / complex).
+- Assess risk level (low / medium / high).
+- Generate step-by-step execution plan with agent assignments.
+- Identify required MCP tools per step.
+
+Review the plan carefully:
+
+- If the plan is incorrect or incomplete, ask PLCODE to revise it.
+- If complexity is high, consider breaking into smaller tasks.
+- Do not proceed to implementation without an approved plan.
+
+## Implementation Phase
+
+Once the plan is approved, execute it. Two modes are available:
+
+- **one-shot**: Execute all steps sequentially in the current session.
+- **background**: Execute steps in the background, freeing the session.
+
+During implementation:
+
+- The code_agent handles code changes.
+- The test_agent runs tests as each step completes.
+- If a step fails, PLCODE will attempt recovery or escalate.
+
+## Review Phase
+
+After implementation, trigger a review:
+
+```
+/review
+```
+
+The review_agent evaluates:
+
+- Code quality and adherence to standards.
+- Test coverage and correctness.
+- Security and performance implications.
+
+If the review flags issues, return to the planning phase for that specific issue.
+
+## Question Handling
+
+If PLCODE or any agent asks a clarification question during implementation:
+
+- Pause implementation.
+- Provide the answer or switch context to the planner_agent.
+- Confirm the revised approach before resuming.
+- Never ignore questions during implementation.
+
+## Completion
+
+- Repeat the Plan -> Implement -> Review loop until all requirements are satisfied.
+- Never skip the planning phase.
+- Never bypass review for non-trivial changes.
+- Use `plcode session list` to verify session state.
+
+## MCP Tools Available
+
+PLCODE exposes 32+ MCP tools across 5 categories:
+
+| Category      | Tools | Examples                                                     |
+| ------------- | ----- | ------------------------------------------------------------ |
+| Observability | 7     | `get_service_health`, `get_bra_health`, `get_memory_metrics` |
+| Git           | 8     | `get_repo_structure`, `get_diff`, `open_pull_request`        |
+| LSP           | 9     | `lsp_diagnostics`, `find_references`, `code_metrics`         |
+| Knowledge     | 5     | `check_dependency_cves`, `analyze_dependencies`              |
+| Web           | 3     | `web_search`, `web_fetch`, `web_extract`                     |
+
+## Output Format
+
+- Show all CLI commands and slash commands explicitly.
+- State which agent is active and what mode is selected.
+- Provide auth links verbatim when they appear.
+- Display plan summaries with complexity and risk assessments.