@ank1015/llm-agents 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this package will be documented in this file.
 
 ## Unreleased
 
+## 0.0.3 - 2026-03-15
+
+- added a local CLI agent runner backed by `Conversation`, the file keys adapter, and an in-memory session manager
+- added section override support in `createSystemPrompt()` and used it for the CLI's directory-only prompt
+- expanded the `ai-images` skill with model-selection guidance and a new `choose-model.md` reference
+
 ## 0.0.2 - 2026-03-15
 
 - aligned the package around general-purpose tools, skill runtime, and helper-backed skill APIs

package/README.md

@@ -8,6 +8,7 @@ This package is the home of:
 - system-prompt construction for the monorepo's general-purpose agent
 - bundled skill packaging and installation
 - helper-backed skill APIs such as AI image generation/editing
+- a local CLI runner for directory-scoped agent sessions
 
 ## What It Exports
 
@@ -61,7 +62,7 @@ The current bundled skill is:
 
 - `ai-images`
   - overview: [skills/ai-images/SKILL.md](/Users/notacoder/Desktop/agents/llm/packages/agents/skills/ai-images/SKILL.md)
-  - task-specific references for image creation and image editing
+  - task-specific references for model choice, image creation, and image editing
 
 ## Helper-Backed Temp Workspace
 
@@ -97,9 +98,25 @@ These helpers:
 
 See the skill docs for the task-specific API guidance:
 
+- [choose-model.md](/Users/notacoder/Desktop/agents/llm/packages/agents/skills/ai-images/references/choose-model.md)
 - [create.md](/Users/notacoder/Desktop/agents/llm/packages/agents/skills/ai-images/references/create.md)
 - [edit.md](/Users/notacoder/Desktop/agents/llm/packages/agents/skills/ai-images/references/edit.md)
 
+## Local CLI
+
+For local testing and temporary directory-scoped sessions, run:
+
+```bash
+pnpm --filter @ank1015/llm-agents agent:cli
+```
+
+The CLI:
+
+- asks which directory Max should work in
+- installs the `ai-images` skill into that directory's `.max/skills/`
+- uses the file keys adapter for credentials
+- uses `codex` / `gpt-5.4` with the package's general-purpose tools
+
 ## Docs
 
 - [docs/vision.md](/Users/notacoder/Desktop/agents/llm/packages/agents/docs/vision.md)
@@ -109,6 +126,7 @@ See the skill docs for the task-specific API guidance:
 ## Commands
 
 - `pnpm build`
+- `pnpm agent:cli`
 - `pnpm test`
 - `pnpm test:unit`
 - `pnpm test:integration`

package/dist/agents/skills/index.js

@@ -363,7 +363,7 @@ function normalizeObjectRecord(value) {
 async function readCurrentPackageVersion() {
     const packageJsonPath = join(packageRoot, 'package.json');
     const parsed = JSON.parse(await readFile(packageJsonPath, 'utf-8'));
-    return parsed.version ?? '0.0.2';
+    return parsed.version ?? '0.0.3';
 }
 async function readCurrentTsxVersion() {
     const packageJsonPath = join(packageRoot, 'package.json');

package/dist/agents/system-prompt.d.ts

@@ -1,7 +1,16 @@
-export declare function createSystemPrompt({ projectName, projectDir, artifactName, artifactDir, }: {
+export interface CreateSystemPromptOptions {
     projectName: string;
     projectDir: string;
     artifactName: string;
     artifactDir: string;
-}): Promise<string>;
+    identity?: string;
+    tools?: string;
+    tools_guidelines?: string;
+    skills?: string;
+    project_information?: string;
+    working_dir?: string;
+    agent_state?: string;
+    current_date?: string;
+}
+export declare function createSystemPrompt({ projectName, projectDir, artifactName, artifactDir, identity, tools, tools_guidelines, skills, project_information, working_dir, agent_state, current_date, }: CreateSystemPromptOptions): Promise<string>;
 //# sourceMappingURL=system-prompt.d.ts.map

package/dist/agents/system-prompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agents/system-prompt.ts"],"names":[],"mappings":"AAIA,wBAAsB,kBAAkB,CAAC,EACvC,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,EAAE;IACD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6FlB"}
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../../src/agents/system-prompt.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAQD,wBAAsB,kBAAkB,CAAC,EACvC,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,KAAK,EACL,gBAAgB,EAChB,MAAM,EACN,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,YAAY,GACb,EAAE,yBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiH7C"}

package/dist/agents/system-prompt.js

@@ -1,6 +1,11 @@
 import { join } from 'node:path';
 import { listInstalledSkills } from './skills/index.js';
-export async function createSystemPrompt({ projectName, projectDir, artifactName, artifactDir, }) {
+function renderSection(name, content) {
+    return `<${name}>
+${content}
+</${name}>`;
+}
+export async function createSystemPrompt({ projectName, projectDir, artifactName, artifactDir, identity, tools, tools_guidelines, skills, project_information, working_dir, agent_state, current_date, }) {
     const now = new Date();
     const artifactMaxDir = join(artifactDir, '.max');
     const artifactSkillsDir = join(artifactMaxDir, 'skills');
@@ -12,20 +17,18 @@ export async function createSystemPrompt({ projectName, projectDir, artifactName
         day: 'numeric',
     });
     const availableSkills = await formatInstalledSkills(artifactDir);
-    const prompt = `You are Max. Max is an intelligent assistant. Max is an expert generalist and helps the user with all sorts of tasks. Max has access to tools such as read, write, edit, bash, and file exploration tools like ls, grep, and find. Using these tools and the available skills, Max can help with any task by reading files, writing files, editing code, and running commands to achieve the desired result.
-
-<tools>
-- read: Read file contents
+    const identitySection = identity ??
+        'You are Max. Max is an intelligent assistant. Max is an expert generalist and helps the user with all sorts of tasks. Max has access to tools such as read, write, edit, bash, and file exploration tools like ls, grep, and find. Using these tools and the available skills, Max can help with any task by reading files, writing files, editing code, and running commands to achieve the desired result.';
+    const toolsSection = tools ??
+        `- read: Read file contents
 - bash: Execute bash commands
 - edit: Make precise edits to files by replacing exact text
 - write: Create or overwrite files
 - grep: Search file contents for patterns (respects .gitignore)
 - find: Find files by glob pattern (respects .gitignore)
-- ls: List directory contents
-</tools>
-
-<tools_guidelines>
-- Prefer grep, find, and ls over bash for file exploration because they are faster and respect .gitignore.
+- ls: List directory contents`;
+    const toolsGuidelinesSection = tools_guidelines ??
+        `- Prefer grep, find, and ls over bash for file exploration because they are faster and respect .gitignore.
 - Use read to inspect files before editing them. Max should use read instead of shell commands like cat or sed for file inspection.
 - Use edit for precise changes when the existing text is known.
 - Use write only for creating new files or completely rewriting a file.
@@ -33,11 +36,9 @@ export async function createSystemPrompt({ projectName, projectDir, artifactName
 - When helpful, Max should verify changes by reading the updated file or running an appropriate command.
 - When summarizing actions, Max should respond in plain text and should not use bash to print the summary.
 - Max should be concise in responses.
-- Max should show file paths clearly when working with files.
-</tools_guidelines>
-
-<skills>
-- Max is a generalist and can help with any kind of task. Skills help Max perform specialized tasks in the way the user expects.
+- Max should show file paths clearly when working with files.`;
+    const skillsSection = skills ??
+        `- Max is a generalist and can help with any kind of task. Skills help Max perform specialized tasks in the way the user expects.
 - A skill is an artifact-local folder containing a SKILL.md plus optional scripts, references, or assets.
 - Only the skills listed below are available for this artifact.
 - The user may explicitly mention a skill during a conversation, or Max may decide to load a relevant skill from the available skills list.
@@ -51,18 +52,14 @@ export async function createSystemPrompt({ projectName, projectDir, artifactName
 - If a relevant skill applies, Max should trust it and follow it closely unless it conflicts with the user's explicit instructions or the available tools.
 <available_skills>
 ${availableSkills}
-</available_skills>
-</skills>
-
-<project_information>
-- The user is currently working in the Project named: ${projectName} and the Artifact named: ${artifactName}.
+</available_skills>`;
+    const projectInformationSection = project_information ??
+        `- The user is currently working in the Project named: ${projectName} and the Artifact named: ${artifactName}.
 - A Project is a top-level folder that contains related Artifacts.
 - An Artifact is a folder inside the Project that contains files related to one part of the overall work.
-- The current Artifact is the default place where Max should do its work unless the user says otherwise.
-</project_information>
-
-<working_dir>
-Max is currently working in the following project:
+- The current Artifact is the default place where Max should do its work unless the user says otherwise.`;
+    const workingDirSection = working_dir ??
+        `Max is currently working in the following project:
 - project name: ${projectName}
 - project dir: ${projectDir}
 
@@ -72,10 +69,9 @@ and the following artifact:
 
 - The tools are initialized in the current artifact directory, and Max should treat this artifact as the default working area.
 - If the user mentions files or directories from other artifacts, Max should explicitly read them.
-- Max must not modify files in other artifacts unless the user explicitly asks for changes there.
-
-<agent_state>
-- Artifact-local agent state lives under: ${artifactMaxDir}
+- Max must not modify files in other artifacts unless the user explicitly asks for changes there.`;
+    const agentStateSection = agent_state ??
+        `- Artifact-local agent state lives under: ${artifactMaxDir}
 - Installed artifact skills live under: ${artifactSkillsDir}
 - Max may use ${artifactTempDir} as a writable scratchpad for temporary files, helper projects, scripts, installs, previews, logs, JSON summaries, unpacked folders, and other ephemeral outputs.
 - ${artifactTempDir} may already be initialized as a lightweight TypeScript workspace for helper-backed skills, including a \`package.json\`, \`tsconfig.json\`, and \`scripts/\` folder.
@@ -84,10 +80,24 @@ and the following artifact:
 - If the user wants code or scripts to live in the artifact project itself, Max may write them in ${artifactDir} instead and import helper functions from \`@ank1015/llm-agents\` there.
 - Final user-facing outputs should be written to ${artifactDir} unless the user explicitly asks for a different location.
 - Max should treat ${artifactTempDir} as ephemeral scratch space. Other contents under ${artifactMaxDir} are agent state, not normal project files.
-- Max should keep bundled skill files inside installed skill directories unchanged unless the user explicitly asks to modify them.
-</agent_state>
+- Max should keep bundled skill files inside installed skill directories unchanged unless the user explicitly asks to modify them.`;
+    const currentDateSection = current_date ?? `Current date: ${dateTime}`;
+    const prompt = `${identitySection}
+
+${renderSection('tools', toolsSection)}
+
+${renderSection('tools_guidelines', toolsGuidelinesSection)}
+
+${renderSection('skills', skillsSection)}
+
+${renderSection('project_information', projectInformationSection)}
+
+<working_dir>
+${workingDirSection}
+
+${renderSection('agent_state', agentStateSection)}
 
-Current date: ${dateTime}
+${currentDateSection}
 </working_dir>
 `;
     return prompt;

package/dist/agents/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agents/system-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,GAMZ;IACC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IACvB,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACjD,MAAM,iBAAiB,GAAG,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACzD,MAAM,eAAe,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,CAAC,OAAO,EAAE;QAC3C,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;KACf,CAAC,CAAC;IACH,MAAM,eAAe,GAAG,MAAM,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAEjE,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sJAmCqI,eAAe;;;EAGnK,eAAe;;;;;wDAKuC,WAAW,4BAA4B,YAAY;;;;;;;;kBAQzF,WAAW;iBACZ,UAAU;;;mBAGR,YAAY;kBACb,WAAW;;;;;;;4CAOe,cAAc;0CAChB,iBAAiB;gBAC3C,eAAe;IAC3B,eAAe;;2DAEwC,eAAe,8BAA8B,eAAe;oGACnB,WAAW;mDAC5D,WAAW;qBACzC,eAAe,qDAAqD,cAAc;;;;gBAIvF,QAAQ;;CAEvB,CAAC;IAEA,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,qBAAqB,CAAC,WAAmB;IACtD,MAAM,eAAe,GAAG,MAAM,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAE/D,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,OAAO,eAAe;SACnB,GAAG,CACF,CAAC,KAAK,EAAE,EAAE,CACR,WAAW,KAAK,CAAC,IAAI;iBACZ,KAAK,CAAC,WAAW;UACxB,KAAK,CAAC,IAAI,EAAE,CACjB;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/agents/system-prompt.ts"],"names":[],"mappings":"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"}

package/dist/cli/agent-cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import type { Api, BaseAssistantMessage } from '@ank1015/llm-sdk';
+export interface CliDirectoryContext {
+    projectName: string;
+    projectDir: string;
+    artifactName: string;
+    artifactDir: string;
+}
+export declare function isExitCommand(input: string): boolean;
+export declare function resolveCliDirectoryContext(directory: string): CliDirectoryContext;
+export declare function extractAssistantText(message: BaseAssistantMessage<Api>): string;
+export declare function runAgentCli(): Promise<void>;
+//# sourceMappingURL=agent-cli.d.ts.map

package/dist/cli/agent-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-cli.d.ts","sourceRoot":"","sources":["../../src/cli/agent-cli.ts"],"names":[],"mappings":";AAeA,OAAO,KAAK,EAGV,GAAG,EAEH,oBAAoB,EAGrB,MAAM,kBAAkB,CAAC;AAY1B,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,mBAAmB,CAYjF;AA+BD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,CAAC,GAAG,CAAC,GAAG,MAAM,CA2B/E;AAkFD,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAoHjD"}

package/dist/cli/agent-cli.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { realpath, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+import { Conversation, createSessionManager, getModel } from '@ank1015/llm-sdk';
+import { createFileKeysAdapter, InMemorySessionsAdapter } from '@ank1015/llm-sdk-adapters';
+import { addSkill } from '../agents/skills/index.js';
+import { createSystemPrompt } from '../agents/system-prompt.js';
+import { createAllTools } from '../tools/index.js';
+const CLI_API = 'codex';
+const CLI_MODEL_ID = 'gpt-5.4';
+const CLI_PROVIDER_OPTIONS = {
+    reasoning: {
+        effort: 'high',
+        summary: 'detailed',
+    },
+};
+const EXIT_COMMANDS = new Set(['exit', 'quit', ':q']);
+export function isExitCommand(input) {
+    return EXIT_COMMANDS.has(input.trim().toLowerCase());
+}
+export function resolveCliDirectoryContext(directory) {
+    const artifactDir = resolve(directory);
+    const artifactName = basename(artifactDir) || 'artifact';
+    const projectDir = dirname(artifactDir);
+    const projectName = basename(projectDir) || artifactName;
+    return {
+        projectName,
+        projectDir,
+        artifactName,
+        artifactDir,
+    };
+}
+function createCliSystemPromptOverrides(context) {
+    const stateDir = join(context.artifactDir, '.max');
+    const skillsDir = join(stateDir, 'skills');
+    const tempDir = join(stateDir, 'temp');
+    return {
+        project_information: `- Max is working in this directory: ${context.artifactDir}.`,
+        working_dir: `Max is currently working in the following directory:
+- working dir: ${context.artifactDir}
+
+- The tools are initialized in this directory, and Max should treat it as the default working area.
+- Max should read and write files relative to this directory unless the user explicitly asks for another location.
+- If Max needs to inspect files outside this directory, Max should do so explicitly and avoid modifying them unless the user asks.`,
+        agent_state: `- Agent-local state lives under: ${stateDir}
+- Installed skills live under: ${skillsDir}
+- Max may use ${tempDir} as writable scratch space for temporary files, helper projects, scripts, installs, previews, logs, JSON summaries, unpacked folders, and other ephemeral outputs.
+- ${tempDir} may already be initialized as a lightweight TypeScript workspace for helper-backed skills, including a \`package.json\`, \`tsconfig.json\`, and \`scripts/\` folder.
+- When that temp workspace already exists, Max should inspect it and reuse it instead of creating a new scratch setup.
+- Max may place one-off TypeScript helper scripts inside ${tempDir}/scripts and run them from ${tempDir} when that workspace fits the task.
+- Final user-facing outputs should be written inside ${context.artifactDir} unless the user explicitly asks for a different location.
+- Max should treat ${tempDir} as ephemeral scratch space. Other contents under ${stateDir} are agent state, not normal project files.
+- Max should keep bundled skill files inside installed skill directories unchanged unless the user explicitly asks to modify them.`,
+    };
+}
+export function extractAssistantText(message) {
+    const textParts = [];
+    let sawNonTextContent = false;
+    for (const block of message.content) {
+        if (block.type !== 'response') {
+            continue;
+        }
+        for (const item of block.content) {
+            if (item.type === 'text') {
+                textParts.push(item.content);
+            }
+            else {
+                sawNonTextContent = true;
+            }
+        }
+    }
+    if (textParts.length > 0) {
+        return textParts.join('\n\n').trim();
+    }
+    if (sawNonTextContent) {
+        return '[assistant returned non-text content]';
+    }
+    return '';
+}
+function isReadlineInterruptError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        (error.code === 'ERR_USE_AFTER_CLOSE' || error.code === 'ABORT_ERR'));
+}
+function isAssistantStreamEvent(message) {
+    return 'type' in message;
+}
+async function resolveExistingDirectory(directoryInput) {
+    const requestedPath = directoryInput.trim() || process.cwd();
+    const resolvedPath = resolve(requestedPath);
+    const stats = await stat(resolvedPath);
+    if (!stats.isDirectory()) {
+        throw new Error(`Path is not a directory: ${resolvedPath}`);
+    }
+    return resolveCliDirectoryContext(await realpath(resolvedPath));
+}
+function createEventPrinter() {
+    let sawAssistantText = false;
+    let assistantLineOpen = false;
+    return (event) => {
+        switch (event.type) {
+            case 'message_start': {
+                if (event.messageType === 'assistant') {
+                    sawAssistantText = false;
+                    assistantLineOpen = true;
+                    stdout.write('\nassistant> ');
+                }
+                break;
+            }
+            case 'message_update': {
+                if (event.messageType === 'assistant' &&
+                    isAssistantStreamEvent(event.message) &&
+                    event.message.type === 'text_delta') {
+                    sawAssistantText = true;
+                    stdout.write(event.message.delta);
+                }
+                break;
+            }
+            case 'tool_execution_start': {
+                if (assistantLineOpen) {
+                    stdout.write('\n');
+                    assistantLineOpen = false;
+                }
+                stdout.write(`[tool:${event.toolName}] running\n`);
+                break;
+            }
+            case 'tool_execution_end': {
+                stdout.write(`[tool:${event.toolName}] ${event.isError ? 'failed' : 'done'}\n`);
+                break;
+            }
+            case 'message_end': {
+                if (event.messageType === 'assistant') {
+                    if (!sawAssistantText) {
+                        const text = extractAssistantText(event.message);
+                        if (text) {
+                            stdout.write(text);
+                        }
+                    }
+                    stdout.write('\n');
+                    sawAssistantText = false;
+                    assistantLineOpen = false;
+                }
+                break;
+            }
+        }
+    };
+}
+export async function runAgentCli() {
+    const readline = createInterface({ input: stdin, output: stdout });
+    let conversation;
+    let isRunning = false;
+    const handleSigint = () => {
+        if (isRunning && conversation) {
+            stdout.write('\nAborting current run...\n');
+            conversation.abort();
+            return;
+        }
+        stdout.write('\nExiting.\n');
+        readline.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', handleSigint);
+    try {
+        let directoryInput;
+        try {
+            directoryInput = await readline.question(`Run agent in directory [${process.cwd()}]: `);
+        }
+        catch (error) {
+            if (isReadlineInterruptError(error)) {
+                return;
+            }
+            throw error;
+        }
+        const context = await resolveExistingDirectory(directoryInput);
+        stdout.write(`\nPreparing agent for ${context.artifactDir}\n`);
+        await addSkill('ai-images', context.artifactDir);
+        const tools = Object.values(createAllTools(context.artifactDir));
+        const systemPrompt = await createSystemPrompt({
+            ...context,
+            ...createCliSystemPromptOverrides(context),
+        });
+        const model = getModel(CLI_API, CLI_MODEL_ID);
+        if (!model) {
+            throw new Error(`Model "${CLI_MODEL_ID}" not found for API "${CLI_API}"`);
+        }
+        const keysAdapter = createFileKeysAdapter();
+        const sessionManager = createSessionManager(new InMemorySessionsAdapter());
+        const { sessionId, header } = await sessionManager.createSession({
+            projectName: context.projectName,
+            sessionName: `${context.artifactName} CLI Session`,
+        });
+        let currentLeafNodeId = header.id;
+        conversation = new Conversation({
+            keysAdapter,
+            streamAssistantMessage: true,
+            initialState: {
+                tools,
+            },
+        });
+        conversation.setProvider({
+            model,
+            providerOptions: CLI_PROVIDER_OPTIONS,
+        });
+        conversation.setSystemPrompt(systemPrompt);
+        conversation.setTools(tools);
+        conversation.subscribe(createEventPrinter());
+        stdout.write(`Session ${sessionId} ready.\n`);
+        stdout.write(`Using ${CLI_API}/${CLI_MODEL_ID} with directory-local tools in ${context.artifactDir}\n`);
+        stdout.write('Type a prompt and press Enter. Type "exit" to quit.\n');
+        while (true) {
+            let promptText;
+            try {
+                promptText = await readline.question('\nyou> ');
+            }
+            catch (error) {
+                if (isReadlineInterruptError(error)) {
+                    break;
+                }
+                throw error;
+            }
+            if (!promptText.trim()) {
+                continue;
+            }
+            if (isExitCommand(promptText)) {
+                break;
+            }
+            isRunning = true;
+            try {
+                await conversation.prompt(promptText, undefined, async (message) => {
+                    const { node } = await sessionManager.appendMessage({
+                        projectName: context.projectName,
+                        path: '',
+                        sessionId,
+                        parentId: currentLeafNodeId,
+                        branch: 'main',
+                        message,
+                        api: CLI_API,
+                        modelId: CLI_MODEL_ID,
+                        providerOptions: CLI_PROVIDER_OPTIONS,
+                    });
+                    currentLeafNodeId = node.id;
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                stdout.write(`\nerror> ${message}\n`);
+            }
+            finally {
+                isRunning = false;
+            }
+        }
+    }
+    finally {
+        process.off('SIGINT', handleSigint);
+        readline.close();
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void runAgentCli();
+}
+//# sourceMappingURL=agent-cli.js.map

package/dist/cli/agent-cli.js.map

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

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Agent toolkit for the LLM SDK.
  */
-export declare const VERSION = "0.0.2";
+export declare const VERSION = "0.0.3";
 export * from './tools/index.js';
 export * from './agents/system-prompt.js';
 export * from './agents/tools.js';

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Agent toolkit for the LLM SDK.
  */
-export const VERSION = '0.0.2';
+export const VERSION = '0.0.3';
 export * from './tools/index.js';
 export * from './agents/system-prompt.js';
 export * from './agents/tools.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ank1015/llm-agents",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Node-only general-purpose agent toolkit with bundled skills and helper-backed workflows",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,7 @@
   "scripts": {
     "build": "rm -rf dist coverage *.tsbuildinfo && tsc",
     "dev": "tsc --watch",
+    "agent:cli": "tsx src/cli/agent-cli.ts",
     "test": "pnpm run test:unit && pnpm run test:integration",
     "test:watch": "vitest",
     "test:unit": "vitest run tests/unit",

package/skills/ai-images/SKILL.md

@@ -17,9 +17,10 @@ Use this skill when the user wants to:
 ## 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.
+2. If the task needs model selection help or the best image model is not obvious, read [references/choose-model.md](references/choose-model.md).
+3. If the task is generating a new image, read [references/create.md](references/create.md).
+4. If the task is editing or transforming an existing image, read [references/edit.md](references/edit.md).
+5. Do not read both task references unless the task genuinely includes both create and edit flows.
 
 ## Available Functions
 
@@ -38,6 +39,7 @@ import { createImage, editImage } from '@ank1015/llm-agents';
 
 ## Choose The Next Reference
 
+- Read [references/choose-model.md](references/choose-model.md) when you need to choose between `gpt-5.4`, `gemini-3.1-flash-image-preview`, and `gemini-3-pro-image-preview`.
 - 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()`.
 

package/skills/ai-images/references/choose-model.md

@@ -0,0 +1,54 @@
+# Choose An Image Model
+
+Use this reference when the task needs model-selection help before you call `createImage()` or
+`editImage()`.
+
+## Model Priority
+
+- If the user explicitly names a model, use that model.
+- If the task is serious, high-stakes, detail-sensitive, or likely to need the best typography,
+  precise edits, or careful composition, prefer `gemini-3-pro-image-preview`.
+- If the task is normal or exploratory, `gpt-5.4` and `gemini-3.1-flash-image-preview` are both
+  good defaults.
+- `gemini-3-pro-image-preview` is the strongest overall model of the three, but it is a bit more
+  expensive than the other two.
+
+## When To Prefer `gemini-3-pro-image-preview`
+
+Prefer `gemini-3-pro-image-preview` when the task needs:
+
+- precise text rendering inside the image
+- small visual details to survive edits
+- careful local changes or cleaner instruction-following
+- a serious deliverable where quality matters more than cost
+
+This is the safest “best quality” choice when the user cares about polish.
+
+## When `gpt-5.4` Or `gemini-3.1-flash-image-preview` Are Good
+
+Use `gpt-5.4` or `gemini-3.1-flash-image-preview` when:
+
+- the task is normal importance
+- you want a faster or cheaper first pass
+- the required provider-specific image options line up better with one of those models
+- you want to try multiple candidates before spending more on the final pass
+
+Neither is far behind for typical work.
+
+## Option Matching Matters
+
+Model choice is not only about raw quality. Also look at `provider.imageOptions`.
+
+- If the desired size, aspect ratio, fidelity, background, or other image controls fit a Google
+  model better, choose the Google model that matches the task.
+- If the desired controls fit `gpt-5.4` better, choose `gpt-5.4`.
+- When the user’s constraints clearly match one provider’s options better than another, prefer the
+  better fit even if another model is stronger in the abstract.
+
+## Iteration Strategy
+
+- For important work, it is valid to try more than one model and keep the best result.
+- A common pattern is to start with `gpt-5.4` or `gemini-3.1-flash-image-preview`, then rerun with
+  `gemini-3-pro-image-preview` if the result needs more polish.
+- If the first result misses on text, precision, or edit fidelity, switch to
+  `gemini-3-pro-image-preview`.

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

@@ -3,6 +3,8 @@
 Use this reference when the user wants to generate a brand-new image or create a new image while
 optionally conditioning on reference images.
 
+If you are not sure which model to use, read [choose-model.md](choose-model.md) first.
+
 ## Import
 
 ```ts

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

@@ -3,6 +3,8 @@
 Use this reference when the user wants to modify, transform, or extend one or more existing
 images.
 
+If you are not sure which model to use, read [choose-model.md](choose-model.md) first.
+
 ## Import
 
 ```ts