@roackb2/heddle 0.0.2 → 0.0.4

package/dist/src/tools/view-image.js

@@ -0,0 +1,200 @@
+// ---------------------------------------------------------------------------
+// Tool: view_image
+// Host-side image viewing MVP backed by the active model provider.
+// ---------------------------------------------------------------------------
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+import { inferProviderFromModel } from '../llm/factory.js';
+import { DEFAULT_ANTHROPIC_MODEL, DEFAULT_OPENAI_MODEL } from '../config.js';
+const DEFAULT_IMAGE_PROMPT = 'Describe the image for a coding assistant. Focus on UI text, error messages, filenames, commands, code, diagrams, and any details relevant to software work.';
+export const viewImageTool = createViewImageTool();
+export function createViewImageTool(options = {}) {
+    return {
+        name: 'view_image',
+        description: 'Inspect a local image file when the user references a screenshot, diagram, or other visual file path and the image contents are actually needed. Use this only after the user has provided or implied a concrete image path. Input example: { "path": "/absolute/path/to/screenshot.png" }. Optional field: prompt for a more specific visual question. Returns a concise text description of the image contents.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'Path to the local image file.',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'Optional focused instruction for what to extract from the image.',
+                },
+            },
+            required: ['path'],
+        },
+        async execute(raw) {
+            if (!isViewImageInput(raw)) {
+                return {
+                    ok: false,
+                    error: 'Invalid input for view_image. Required field: path. Optional field: prompt.',
+                };
+            }
+            const input = raw;
+            const filePath = resolve(input.path);
+            const mediaType = detectMediaType(filePath);
+            if (!mediaType) {
+                return {
+                    ok: false,
+                    error: 'view_image supports .png, .jpg, .jpeg, .gif, and .webp files.',
+                };
+            }
+            const provider = options.provider ?? inferProviderFromModel(options.model ?? DEFAULT_OPENAI_MODEL);
+            const prompt = input.prompt?.trim() || DEFAULT_IMAGE_PROMPT;
+            try {
+                const data = await readFile(filePath);
+                switch (provider) {
+                    case 'openai':
+                        return await executeOpenAiImageView({ filePath, mediaType, data, prompt, options });
+                    case 'anthropic':
+                        return await executeAnthropicImageView({ filePath, mediaType, data, prompt, options });
+                    case 'google':
+                        return {
+                            ok: false,
+                            error: 'view_image is not wired for Google models yet.',
+                        };
+                }
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: `Image view failed: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        },
+    };
+}
+async function executeOpenAiImageView(args) {
+    const apiKey = firstDefinedNonEmpty(args.options.apiKey, process.env.OPENAI_API_KEY, process.env.PERSONAL_OPENAI_API_KEY);
+    if (!apiKey) {
+        return {
+            ok: false,
+            error: 'view_image requires OPENAI_API_KEY (or PERSONAL_OPENAI_API_KEY) when the active model provider is OpenAI.',
+        };
+    }
+    const client = new OpenAI({ apiKey });
+    const model = args.options.model ?? DEFAULT_OPENAI_MODEL;
+    const imageBase64 = args.data.toString('base64');
+    const response = await client.responses.create({
+        model,
+        input: [{
+                role: 'user',
+                content: [
+                    { type: 'input_text', text: args.prompt },
+                    {
+                        type: 'input_image',
+                        detail: 'auto',
+                        image_url: `data:${args.mediaType};base64,${imageBase64}`,
+                    },
+                ],
+            }],
+    });
+    return {
+        ok: true,
+        output: {
+            provider: 'openai',
+            model: response.model,
+            path: args.filePath,
+            summary: response.output_text?.trim() || 'No image description returned.',
+        },
+    };
+}
+async function executeAnthropicImageView(args) {
+    const apiKey = firstDefinedNonEmpty(args.options.apiKey, process.env.ANTHROPIC_API_KEY, process.env.PERSONAL_ANTHROPIC_API_KEY);
+    if (!apiKey) {
+        return {
+            ok: false,
+            error: 'view_image requires ANTHROPIC_API_KEY (or PERSONAL_ANTHROPIC_API_KEY) when the active model provider is Anthropic.',
+        };
+    }
+    const anthropicMediaType = toAnthropicMediaType(args.mediaType);
+    if (!anthropicMediaType) {
+        return {
+            ok: false,
+            error: 'Anthropic image viewing supports jpeg, png, gif, and webp.',
+        };
+    }
+    const client = new Anthropic({ apiKey });
+    const model = args.options.model ?? DEFAULT_ANTHROPIC_MODEL;
+    const response = await client.messages.create({
+        model,
+        max_tokens: 1024,
+        messages: [{
+                role: 'user',
+                content: [
+                    {
+                        type: 'image',
+                        source: {
+                            type: 'base64',
+                            media_type: anthropicMediaType,
+                            data: args.data.toString('base64'),
+                        },
+                    },
+                    {
+                        type: 'text',
+                        text: args.prompt,
+                    },
+                ],
+            }],
+    });
+    return {
+        ok: true,
+        output: {
+            provider: 'anthropic',
+            model: response.model,
+            path: args.filePath,
+            summary: response.content
+                .flatMap((block) => (block.type === 'text' ? [block.text] : []))
+                .join('\n')
+                .trim() || 'No image description returned.',
+        },
+    };
+}
+function isViewImageInput(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return false;
+    }
+    const input = raw;
+    const keys = Object.keys(input);
+    if (keys.some((key) => key !== 'path' && key !== 'prompt')) {
+        return false;
+    }
+    if (typeof input.path !== 'string' || input.path.trim().length === 0) {
+        return false;
+    }
+    return input.prompt === undefined || typeof input.prompt === 'string';
+}
+function detectMediaType(filePath) {
+    switch (extname(filePath).toLowerCase()) {
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.gif':
+            return 'image/gif';
+        case '.webp':
+            return 'image/webp';
+        default:
+            return undefined;
+    }
+}
+function toAnthropicMediaType(mediaType) {
+    if (mediaType === 'image/jpeg'
+        || mediaType === 'image/png'
+        || mediaType === 'image/gif'
+        || mediaType === 'image/webp') {
+        return mediaType;
+    }
+    return undefined;
+}
+function firstDefinedNonEmpty(...values) {
+    return values.find((value) => typeof value === 'string' && value.trim().length > 0);
+}
+//# sourceMappingURL=view-image.js.map

package/dist/src/tools/view-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-image.js","sourceRoot":"","sources":["../../../src/tools/view-image.ts"],"names":[],"mappings":"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"}

package/dist/src/tools/web-search.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDefinition } from '../types.js';
+import type { LlmProvider } from '../llm/types.js';
+export type WebSearchToolOptions = {
+    model?: string;
+    provider?: LlmProvider;
+    apiKey?: string;
+};
+export declare const webSearchTool: ToolDefinition;
+export declare function createWebSearchTool(options?: WebSearchToolOptions): ToolDefinition;
+//# sourceMappingURL=web-search.d.ts.map

package/dist/src/tools/web-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.d.ts","sourceRoot":"","sources":["../../../src/tools/web-search.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,aAAa,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQnD,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,cAAsC,CAAC;AAEnE,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,cAAc,CAoDtF"}

package/dist/src/tools/web-search.js

@@ -0,0 +1,205 @@
+// ---------------------------------------------------------------------------
+// Tool: web_search
+// Host-side web search MVP backed by the active model provider.
+// ---------------------------------------------------------------------------
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+import { inferProviderFromModel } from '../llm/factory.js';
+import { DEFAULT_ANTHROPIC_MODEL, DEFAULT_OPENAI_MODEL } from '../config.js';
+export const webSearchTool = createWebSearchTool();
+export function createWebSearchTool(options = {}) {
+    return {
+        name: 'web_search',
+        description: 'Search the public web when repository files, docs, and local tools are not enough to answer the user. This MVP tool is backed by the active model provider\'s hosted web search when available. Use it for current external facts, official product docs outside the repo, news, releases, APIs, or references that are not available locally. Do not use it for questions the workspace can already answer. Input example: { "query": "OpenAI Responses API web search tool" }. Optional field: contextSize ("low", "medium", or "high"). Returns a concise summary plus cited source URLs when available.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'The web search query.',
+                },
+                contextSize: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high'],
+                    description: 'How much search context to request from the hosted search tool. Defaults to "medium".',
+                },
+            },
+            required: ['query'],
+        },
+        async execute(raw) {
+            if (!isWebSearchInput(raw)) {
+                return {
+                    ok: false,
+                    error: 'Invalid input for web_search. Required field: query. Optional field: contextSize ("low", "medium", or "high").',
+                };
+            }
+            const input = raw;
+            const provider = options.provider ?? inferProviderFromModel(options.model ?? DEFAULT_OPENAI_MODEL);
+            try {
+                switch (provider) {
+                    case 'openai':
+                        return await executeOpenAiWebSearch(input, options);
+                    case 'anthropic':
+                        return await executeAnthropicWebSearch(input, options);
+                    case 'google':
+                        return {
+                            ok: false,
+                            error: 'web_search is not wired for Google models yet.',
+                        };
+                }
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: `Web search failed: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        },
+    };
+}
+async function executeOpenAiWebSearch(input, options) {
+    const apiKey = firstDefinedNonEmpty(options.apiKey, process.env.OPENAI_API_KEY, process.env.PERSONAL_OPENAI_API_KEY);
+    if (!apiKey) {
+        return {
+            ok: false,
+            error: 'web_search requires OPENAI_API_KEY (or PERSONAL_OPENAI_API_KEY) when the active model provider is OpenAI.',
+        };
+    }
+    const client = new OpenAI({ apiKey });
+    const model = options.model ?? process.env.OPENAI_WEB_SEARCH_MODEL ?? DEFAULT_OPENAI_MODEL;
+    const response = await client.responses.create({
+        model,
+        input: input.query,
+        tools: [{
+                type: 'web_search_preview',
+                search_context_size: input.contextSize ?? 'medium',
+            }],
+    });
+    return {
+        ok: true,
+        output: formatOpenAiWebSearchResult(response),
+    };
+}
+async function executeAnthropicWebSearch(input, options) {
+    const apiKey = firstDefinedNonEmpty(options.apiKey, process.env.ANTHROPIC_API_KEY, process.env.PERSONAL_ANTHROPIC_API_KEY);
+    if (!apiKey) {
+        return {
+            ok: false,
+            error: 'web_search requires ANTHROPIC_API_KEY (or PERSONAL_ANTHROPIC_API_KEY) when the active model provider is Anthropic.',
+        };
+    }
+    const client = new Anthropic({ apiKey });
+    const model = options.model ?? process.env.ANTHROPIC_WEB_SEARCH_MODEL ?? DEFAULT_ANTHROPIC_MODEL;
+    const toolChoice = { type: 'tool', name: 'web_search' };
+    const response = await client.messages.create({
+        model,
+        max_tokens: 1024,
+        tool_choice: toolChoice,
+        tools: [{
+                name: 'web_search',
+                type: 'web_search_20250305',
+                max_uses: 1,
+            }],
+        messages: [{
+                role: 'user',
+                content: `Search the web for the following query and answer concisely with citations when available:\n\n${input.query}`,
+            }],
+    });
+    return {
+        ok: true,
+        output: formatAnthropicWebSearchResult(response),
+    };
+}
+function firstDefinedNonEmpty(...values) {
+    return values.find((value) => typeof value === 'string' && value.trim().length > 0);
+}
+function isWebSearchInput(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return false;
+    }
+    const input = raw;
+    const keys = Object.keys(input);
+    if (keys.some((key) => key !== 'query' && key !== 'contextSize')) {
+        return false;
+    }
+    if (typeof input.query !== 'string' || input.query.trim().length === 0) {
+        return false;
+    }
+    return input.contextSize === undefined || input.contextSize === 'low' || input.contextSize === 'medium' || input.contextSize === 'high';
+}
+function formatOpenAiWebSearchResult(response) {
+    const summary = response.output_text?.trim() || 'No summary returned.';
+    const citations = extractOpenAiUrlCitations(response);
+    return {
+        provider: 'openai',
+        model: response.model,
+        summary,
+        citations,
+    };
+}
+function extractOpenAiUrlCitations(response) {
+    const outputItems = response.output ?? [];
+    const citations = [];
+    const seen = new Set();
+    for (const item of outputItems) {
+        if (item.type !== 'message') {
+            continue;
+        }
+        for (const content of item.content ?? []) {
+            if (content.type !== 'output_text') {
+                continue;
+            }
+            for (const annotation of content.annotations ?? []) {
+                if (annotation.type !== 'url_citation') {
+                    continue;
+                }
+                const key = `${annotation.title}|${annotation.url}`;
+                if (seen.has(key)) {
+                    continue;
+                }
+                seen.add(key);
+                citations.push({
+                    title: annotation.title,
+                    url: annotation.url,
+                });
+            }
+        }
+    }
+    return citations;
+}
+function formatAnthropicWebSearchResult(response) {
+    const textBlocks = response.content.filter((block) => block.type === 'text');
+    const summary = textBlocks.map((block) => block.text).join('\n').trim() || 'No summary returned.';
+    const citations = extractAnthropicUrlCitations(textBlocks.flatMap((block) => block.citations ?? []));
+    return {
+        provider: 'anthropic',
+        model: response.model,
+        summary,
+        citations,
+    };
+}
+function extractAnthropicUrlCitations(citationsInput) {
+    const citations = [];
+    const seen = new Set();
+    for (const citation of citationsInput) {
+        if (citation.type !== 'web_search_result_location') {
+            continue;
+        }
+        if (!citation.url) {
+            continue;
+        }
+        const title = citation.title ?? citation.url;
+        const key = `${title}|${citation.url}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        citations.push({
+            title,
+            url: citation.url,
+        });
+    }
+    return citations;
+}
+//# sourceMappingURL=web-search.js.map

package/dist/src/tools/web-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.js","sourceRoot":"","sources":["../../../src/tools/web-search.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,11 +1,24 @@
 {
   "name": "@roackb2/heddle",
-  "version": "0.0.2",
-  "description": "A minimal TypeScript runtime for tool-using agents",
+  "version": "0.0.4",
+  "description": "An open-source terminal coding agent runtime and CLI with OpenAI and Anthropic support",
+  "author": "Jay / Fienna Liang <roackb2@gmail.com>",
+  "license": "MIT",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/roackb2/heddle.git"
+  },
+  "homepage": "https://github.com/roackb2/heddle#readme",
+  "bugs": {
+    "url": "https://github.com/roackb2/heddle/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "heddle": "dist/src/cli/main.js"
   },
@@ -31,12 +44,21 @@
   },
   "keywords": [
     "agent",
+    "coding-agent",
+    "terminal-agent",
+    "cli-agent",
+    "ai-cli",
+    "developer-tools",
+    "workspace-agent",
+    "repository-tools",
     "llm",
-    "tools",
-    "runtime",
-    "trace"
+    "open-source",
+    "provider-agnostic",
+    "openai",
+    "anthropic",
+    "trace",
+    "chat"
   ],
-  "license": "MIT",
   "dependencies": {
     "@anthropic-ai/sdk": "^0.54.0",
     "@inkjs/ui": "^2.0.0",