@ank1015/llm-agents 0.0.2

package/dist/tools/write.js

@@ -0,0 +1,83 @@
+import { mkdir as fsMkdir, writeFile as fsWriteFile } from 'fs/promises';
+import { dirname } from 'path';
+import { Type } from '@sinclair/typebox';
+import { resolveToCwd } from './path-utils.js';
+const writeSchema = Type.Object({
+    path: Type.String({ description: 'Path to the file to write (relative or absolute)' }),
+    content: Type.String({ description: 'Content to write to the file' }),
+});
+const defaultWriteOperations = {
+    writeFile: (path, content) => fsWriteFile(path, content, 'utf-8'),
+    mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => { }),
+};
+export function createWriteTool(cwd, options) {
+    const ops = options?.operations ?? defaultWriteOperations;
+    return {
+        name: 'write',
+        label: 'write',
+        description: "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+        parameters: writeSchema,
+        execute: async (_toolCallId, { path, content }, signal) => {
+            const absolutePath = resolveToCwd(path, cwd);
+            const dir = dirname(absolutePath);
+            return new Promise((resolve, reject) => {
+                // Check if already aborted
+                if (signal?.aborted) {
+                    reject(new Error('Operation aborted'));
+                    return;
+                }
+                let aborted = false;
+                // Set up abort handler
+                const onAbort = () => {
+                    aborted = true;
+                    reject(new Error('Operation aborted'));
+                };
+                if (signal) {
+                    signal.addEventListener('abort', onAbort, { once: true });
+                }
+                // Perform the write operation
+                (async () => {
+                    try {
+                        // Create parent directories if needed
+                        await ops.mkdir(dir);
+                        // Check if aborted before writing
+                        if (aborted) {
+                            return;
+                        }
+                        // Write the file
+                        await ops.writeFile(absolutePath, content);
+                        // Check if aborted after writing
+                        if (aborted) {
+                            return;
+                        }
+                        // Clean up abort handler
+                        if (signal) {
+                            signal.removeEventListener('abort', onAbort);
+                        }
+                        resolve({
+                            content: [
+                                {
+                                    type: 'text',
+                                    content: `Successfully wrote ${content.length} bytes to ${path}`,
+                                },
+                            ],
+                            details: undefined,
+                        });
+                    }
+                    catch (error) {
+                        // Clean up abort handler
+                        if (signal) {
+                            signal.removeEventListener('abort', onAbort);
+                        }
+                        if (!aborted) {
+                            reject(error);
+                        }
+                    }
+                })();
+            });
+        },
+    };
+}
+/** Default write tool using process.cwd() - for backwards compatibility */
+export const writeTool = createWriteTool(process.cwd());
+//# sourceMappingURL=write.js.map

package/dist/tools/write.js.map

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

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@ank1015/llm-agents",
+  "version": "0.0.2",
+  "description": "Node-only general-purpose agent toolkit with bundled skills and helper-backed workflows",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist coverage *.tsbuildinfo && tsc",
+    "dev": "tsc --watch",
+    "test": "pnpm run test:unit && pnpm run test:integration",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests vitest.config.ts",
+    "clean": "rm -rf dist coverage *.tsbuildinfo",
+    "prepack": "pnpm run build"
+  },
+  "keywords": [
+    "llm",
+    "agents",
+    "ai",
+    "node",
+    "tools",
+    "skills",
+    "typescript",
+    "images"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ank1015/llm.git",
+    "directory": "packages/agents"
+  },
+  "homepage": "https://github.com/ank1015/llm/tree/main/packages/agents",
+  "bugs": {
+    "url": "https://github.com/ank1015/llm/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ank1015/llm-sdk": "workspace:^",
+    "@ank1015/llm-sdk-adapters": "workspace:^",
+    "@silvia-odwyer/photon-node": "^0.3.4",
+    "@sinclair/typebox": "^0.34.48",
+    "chalk": "^5.6.2",
+    "diff": "^8.0.3",
+    "file-type": "^21.3.0",
+    "glob": "^13.0.6"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.0",
+    "@types/node": "^25.3.2",
+    "tsx": "^4.19.0",
+    "vitest": "^2.1.0"
+  }
+}

package/skills/ai-images/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ai-images
+description: 'Create brand-new images or edit existing images with state-of-the-art image generation models. Use this skill when the task involves image generation, visual variations, or image transformation.'
+---
+
+# AI Images
+
+## When To Use
+
+Use this skill when the user wants to:
+
+- generate a new image from a prompt
+- create image variations from reference images
+- edit or transform one or more existing images
+- use the latest image models exposed through `@ank1015/llm-agents`
+
+## Required Reading Order
+
+1. Read this file first.
+2. If the task is generating a new image, read [references/create.md](references/create.md).
+3. If the task is editing or transforming an existing image, read [references/edit.md](references/edit.md).
+4. Do not read both reference files unless the task genuinely includes both create and edit flows.
+
+## Available Functions
+
+- `createImage(request)`
+  - create a new image from a prompt
+  - optionally condition the generation on reference images
+- `editImage(request)`
+  - modify or transform one or more existing images
+  - requires at least one input image
+
+Import from the package root:
+
+```ts
+import { createImage, editImage } from '@ank1015/llm-agents';
+```
+
+## Choose The Next Reference
+
+- Read [references/create.md](references/create.md) for request shape, model-specific create options, output behavior, and example usage of `createImage()`.
+- Read [references/edit.md](references/edit.md) for request shape, supported inputs, model-specific edit options, output behavior, and example usage of `editImage()`.
+
+Load only the reference that matches the current task so you do not pull unnecessary context into
+the conversation.

package/skills/ai-images/references/create.md

@@ -0,0 +1,106 @@
+# Create Images
+
+Use this reference when the user wants to generate a brand-new image or create a new image while
+optionally conditioning on reference images.
+
+## Import
+
+```ts
+import { createImage } from '@ank1015/llm-agents';
+```
+
+## Request Shape
+
+```ts
+await createImage({
+  provider: {
+    model: 'gpt-5.4',
+  },
+  prompt: 'A cinematic product photo of a matte black camera on a warm stone pedestal',
+  outputDir: '/absolute/output/dir',
+  outputName: 'camera-hero',
+});
+```
+
+## Fields
+
+- `provider.model`
+  - required
+  - one of `gpt-5.4`, `gemini-3.1-flash-image-preview`, `gemini-3-pro-image-preview`
+- `provider.imageOptions`
+  - optional model-specific controls
+- `prompt`
+  - required
+- `outputDir`
+  - required absolute or relative directory for the final image
+- `outputName`
+  - optional filename stem only, not a path
+- `images`
+  - optional reference image paths or URLs
+  - useful when the model should create from existing visual context
+- `systemPrompt`
+  - optional additional instruction layer
+- `onUpdate`
+  - optional callback for partial, thought, and final image events
+
+## OpenAI Options
+
+For `gpt-5.4`, `provider.imageOptions` can include:
+
+- `format`: `png | jpeg | webp`
+- `quality`: `low | medium | high | auto`
+- `background`: `transparent | opaque | auto`
+- `size`: `1024x1024 | 1024x1536 | 1536x1024 | auto`
+- `partialImages`: `0 | 1 | 2 | 3`
+- `moderation`: `auto | low`
+
+Do not use `inputFidelity` with `createImage()`.
+
+## Google Options
+
+For Google image models, `provider.imageOptions` can include:
+
+- `imageSize`: `1K | 2K | 4K`
+- `aspectRatio`
+
+Flash model aspect ratios:
+
+- `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`, `4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`
+
+Pro model aspect ratios:
+
+- `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`
+
+## Output Behavior
+
+- The final image is written to `outputDir/outputName.<ext>`.
+- Intermediate outputs are written to `outputDir/outputName__updates/`.
+- The returned value is:
+
+```ts
+{ path: '/final/image/path.png' }
+```
+
+## Example With Progress Updates
+
+```ts
+import { createImage } from '@ank1015/llm-agents';
+
+const result = await createImage({
+  provider: {
+    model: 'gemini-3-pro-image-preview',
+    imageOptions: {
+      aspectRatio: '16:9',
+      imageSize: '2K',
+    },
+  },
+  prompt: 'A dramatic sunrise over a foggy mountain village, painterly but realistic',
+  outputDir: '/absolute/output/dir',
+  outputName: 'mountain-village',
+  onUpdate(update) {
+    console.log(update.stage, update.path);
+  },
+});
+
+console.log(result.path);
+```

package/skills/ai-images/references/edit.md

@@ -0,0 +1,107 @@
+# Edit Images
+
+Use this reference when the user wants to modify, transform, or extend one or more existing
+images.
+
+## Import
+
+```ts
+import { editImage } from '@ank1015/llm-agents';
+```
+
+## Request Shape
+
+```ts
+await editImage({
+  provider: {
+    model: 'gpt-5.4',
+  },
+  prompt: 'Turn this product photo into a premium studio ad with soft rim light',
+  images: ['/absolute/path/to/input.png'],
+  outputDir: '/absolute/output/dir',
+  outputName: 'product-ad',
+});
+```
+
+## Fields
+
+- `provider.model`
+  - required
+  - one of `gpt-5.4`, `gemini-3.1-flash-image-preview`, `gemini-3-pro-image-preview`
+- `provider.imageOptions`
+  - optional model-specific controls
+- `prompt`
+  - required
+- `images`
+  - required
+  - one path/URL or an array of paths/URLs
+- `outputDir`
+  - required
+- `outputName`
+  - optional filename stem only
+- `systemPrompt`
+  - optional
+- `onUpdate`
+  - optional callback for progress artifacts
+
+## Supported Inputs
+
+The helper accepts:
+
+- local image paths
+- remote `http` / `https` image URLs
+
+The helper infers image type from content type, file bytes, or file extension.
+
+## OpenAI Options
+
+For `gpt-5.4`, `provider.imageOptions` can include:
+
+- `format`: `png | jpeg | webp`
+- `quality`: `low | medium | high | auto`
+- `background`: `transparent | opaque | auto`
+- `size`: `1024x1024 | 1024x1536 | 1536x1024 | auto`
+- `partialImages`: `0 | 1 | 2 | 3`
+- `inputFidelity`: `low | high`
+- `moderation`: `auto | low`
+
+`inputFidelity` is valid here and is specific to edit flows.
+
+## Google Options
+
+For Google image models, `provider.imageOptions` can include:
+
+- `imageSize`: `1K | 2K | 4K`
+- `aspectRatio`
+
+Use the same aspect-ratio families described in the create flow, depending on whether the model is
+Flash or Pro.
+
+## Output Behavior
+
+- The final edited image is written to `outputDir/outputName.<ext>`.
+- Intermediate outputs are written to `outputDir/outputName__updates/`.
+- The helper throws if no final image is returned by the provider.
+
+## Example
+
+```ts
+import { editImage } from '@ank1015/llm-agents';
+
+const result = await editImage({
+  provider: {
+    model: 'gpt-5.4',
+    imageOptions: {
+      inputFidelity: 'high',
+      quality: 'high',
+      format: 'png',
+    },
+  },
+  prompt: 'Replace the background with a clean beige studio wall and add a subtle floor shadow',
+  images: ['https://example.com/reference/product.png'],
+  outputDir: '/absolute/output/dir',
+  outputName: 'product-edit',
+});
+
+console.log(result.path);
+```

package/skills/registry.json

@@ -0,0 +1,10 @@
+[
+  {
+    "name": "ai-images",
+    "description": "Create brand-new images or edit existing images with state-of-the-art image generation models. Use this skill when the task involves image generation, visual variations, or image transformation.",
+    "helperProject": {
+      "runtime": "typescript",
+      "package": "@ank1015/llm-agents"
+    }
+  }
+]