@jancellor/ask 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jancellor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# Ask
+
+A minimal coding agent.
+
+![Ask demo](https://raw.githubusercontent.com/jancellor/ask/main/demo/demo.gif)
+
+## Why
+
+Ask is a small, working coding agent built as a demo project.
+It keeps the setup deliberately minimal: one shell execution tool and
+standard CLI utilities (`rg`, `sed`, `cat`, etc.) instead of a large custom tool surface.
+It supports AGENTS.md and skills.
+The goal is to show the core loop clearly and keep the code easy to read, run, and modify.
+It's a proof-of-concept.
+
+Should you use this? Probably not for day-to-day work.
+It runs with full shell access, so it needs an external sandbox.
+Basic features are missing.
+Even so, the core loop works and is useful for real coding tasks.
+It should be easy to experiment with different task delegation patterns.
+For example, subagents are just self invocations `ask "msg"`.
+Usage is controlled by the system prompt.
+
+## Features
+
+- **Single tool.** One `execute` tool runs bash commands. No specialized file-editing, search, or filesystem tools.
+- **Interactive and scriptable.** Terminal UI with markdown rendering, or `ask "msg"` for batch mode use.
+- **Session persistence.** Conversations are saved as JSONL to `~/.ask/sessions/`.
+- **Subagent delegation.** An agent can simply invoke `ask "msg"` to isolate context or run in parallel.
+- **Project-level instructions.** `AGENTS.md` files provide project-specific context. `SKILL.md` files describe reusable capabilities.
+
+## Setup
+
+Install from npm:
+
+```bash
+npm install -g @jancellor/ask
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/jancellor/ask.git
+cd ask
+npm install
+npm run build
+npm link
+```
+
+Configure a provider:
+
+```bash
+export ASK_API_KEY="your-api-key"
+export ASK_MODEL="anthropic/claude-sonnet-4.6"
+export ASK_BASE_URL="https://openrouter.ai/api/v1"
+```
+
+Or create `~/.config/ask/config.json`:
+
+```json
+{
+  "api_key": "your-api-key",
+  "model": "anthropic/claude-sonnet-4.6",
+  "base_url": "https://openrouter.ai/api/v1"
+}
+```
+
+Run:
+
+```bash
+ask                          # Interactive mode
+ask "refactor"               # Batch mode (single positional arg)
+cat file.ts | ask "explain"  # Pipe context, ask a question
+ask --resume                 # Resume most recent session (interactive)
+ask --resume <uuid>          # Resume a specific session
+ask --resume -- "refactor"   # Resume most recent session in batch mode
+ask --fork                   # Fork most recent session into a new session (interactive)
+ask --fork -- "try this"     # Fork most recent session in batch mode
+ask --resume <uuid> --fork   # Fork a specific session into a new session
+ask --help                   # More options
+```
+
+## Architecture
+
+```
+User input
+  → generateText() via Vercel AI SDK
+    → Model returns text + tool calls
+      → execute({ command }) — bash -c with timeout
+      → stdout/stderr/exit code returned to model
+    → Loop until no more tool calls
+  → Append messages to session JSONL
+```

package/assets/system-prompt.md

@@ -0,0 +1,107 @@
+# System prompt
+
+You are an expert coding agent or coding assistant.
+You are typically invoked via the `ask` executable harness.
+The user may refer to you as "Ask".
+You help users with tasks including coding by executing commands
+including those for searching, reading, editing and writing files.
+
+Available tools:
+
+- `execute`: execute shell commands using bash.
+
+Guidelines:
+
+- Read relevant files and understand context before making changes.
+- Use `execute` for file operations like `ls`, `rg`, `fd`.
+- When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did.
+- Be concise in your responses.
+- Show file paths clearly when working with files.
+
+## Searching
+
+Use `ls`, `rg`, `fd` for exploring the filesystem.
+Use flags for following symlinks, including hidden items,
+and not ignoring ignored items where appropriate,
+eg `ls -a`, `rg -L -uu`, `fd -L -u`.
+
+## File editing
+
+### Reading
+
+Prefer `sed` to `cat` to avoid dumping large files into context.
+
+```bash
+sed -n '1,200p' path/to/file
+```
+
+### Writing
+
+Use `cat` with heredocs to create new files.
+Check the file doesn't already exist before writing.
+
+```bash
+cat > path/to/new-file <<'EOF'
+<new content>
+EOF
+```
+
+### Editing
+
+Use `sd -F` with `cat` and heredocs for targeted edits.
+Generally prefer making targeted edits rather than rewriting the entire file.
+After editing, read back the modified region to verify.
+
+```bash
+OLD_BLOCK=$(cat <<'OLD_EOF'
+<old content>
+OLD_EOF
+)
+
+NEW_BLOCK=$(cat <<'NEW_EOF'
+<new content>
+NEW_EOF
+)
+
+sd -F -- "$OLD_BLOCK" "$NEW_BLOCK" path/to/file
+```
+
+## Background processes
+
+Use `tmux` when processes need to run in the background.
+For full output, use `capture-pane -S -` or `pipe-pane` to file.
+Prefix session names with "agents-".
+
+## Subagents, task delegation, and context management
+
+Typically the user has invoked you by running `ask` from a terminal shell.
+You may also run `ask "<msg>"` to invoke another copy of the agent,
+which may be referred to as a subagent.
+You may do this in shell commands or in scripts you execute to help you achieve your tasks.
+However you should not use `ask` in code you generate for the user to run independently.
+The point of delegating is to control the context which you, the main agent, and the subagent sees.
+If you need to answer a complicated query in the middle of a conversation, by delegating to a subagent,
+the subagent does not see the unnecessary full context of your conversation.
+It only sees what you explicitly include in the prompt.
+Similarly, you do not see the output of the intermediate steps the subagent used to answer the question.
+By keeping the context of yourself and subagents limited to only the scope they require,
+overall accuracy is typically improved.
+Also, by invoking multiple subagents in a single turn, you can achieve parallelism
+and therefore faster performance for tasks that are truly independent.
+
+## Session storage
+
+When `ask` runs, messages are persisted to `~/.ask/sessions/<id>.jsonl` as AI SDK messages.
+IDs are UUIDs.
+Messages include additional metadata in a `_meta` property, including `id`, `parentId`, `uiHidden`, and `timestamp`.
+When using subagents, consider passing an explicit session ID via `ask --resume <id> ...`.
+This allows you to inspect the context of the subagent, though note that
+usually you explicitly don't want the subagent context in your own.
+This also allows you ask a subagent follow up question by supplying the same session ID twice.
+It may be useful to make focused searches of the subagent context.
+
+## Web
+
+For searching or fetching from the web, you may delegate to `codex`, another coding agent.
+
+    codex exec --skip-git-repo-check "What is the weather like in London today?"

package/dist/agent/agent.js

@@ -0,0 +1,132 @@
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { generateText, } from 'ai';
+import { ConfigReader } from './config.js';
+import { InitPrompt } from './init-prompt.js';
+import { Session } from './session.js';
+import { SystemPrompt } from './system-prompt.js';
+import { Serializer } from './serializer.js';
+import { Tools } from './tools.js';
+export const ABORTED_MESSAGE = '[Aborted]';
+export const ERROR_MESSAGE = '[Error]';
+export class Agent {
+    modelId;
+    baseUrl;
+    listeners = [];
+    languageModel;
+    systemPrompt;
+    tools;
+    session;
+    serializer = new Serializer();
+    controller = null;
+    constructor(session) {
+        this.session = session;
+        const config = new ConfigReader().read();
+        this.modelId = config.model;
+        this.baseUrl = config.baseUrl;
+        const provider = createOpenAICompatible({
+            name: 'ask',
+            apiKey: config.apiKey,
+            baseURL: config.baseUrl,
+        });
+        this.languageModel = provider(config.model);
+        this.systemPrompt = new SystemPrompt().build();
+        this.tools = new Tools();
+    }
+    static async create(options) {
+        const session = await Session.create(options);
+        return new Agent(session);
+    }
+    addListener(listener) {
+        this.listeners.push(listener);
+    }
+    removeListener(listener) {
+        const i = this.listeners.indexOf(listener);
+        if (i !== -1)
+            this.listeners.splice(i, 1);
+    }
+    get messages() {
+        return this.session.messages;
+    }
+    get sessionId() {
+        return this.session.sessionId;
+    }
+    ask(message) {
+        return this.serializer.submit(async () => {
+            await this.addInitialMessages();
+            await this.addMessages([{ role: 'user', content: message }]);
+            this.controller = new AbortController();
+            const { signal } = this.controller;
+            try {
+                while (true) {
+                    const result = await generateText({
+                        model: this.languageModel,
+                        system: this.systemPrompt,
+                        messages: this.session.messages,
+                        tools: this.tools.definitions(),
+                        abortSignal: signal,
+                    });
+                    await this.addMessages(result.response.messages);
+                    if (result.toolCalls.length === 0)
+                        break;
+                    const toolResults = await this.callTools(result.toolCalls, signal);
+                    await this.addMessages([{ role: 'tool', content: toolResults }]);
+                }
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                await this.addMessages([
+                    { role: 'assistant', content: ERROR_MESSAGE + ': ' + msg },
+                ]);
+            }
+            finally {
+                this.controller = null;
+            }
+        });
+    }
+    abort() {
+        this.controller?.abort();
+    }
+    async cancelAll() {
+        this.abort();
+        await this.serializer.cancelPending();
+    }
+    async clear(beforeClear) {
+        await this.cancelAll();
+        await this.serializer.submit(async () => {
+            beforeClear?.();
+            this.session = await this.session.cleared();
+            await Promise.all(this.listeners.map((l) => l.onClear?.()));
+        });
+    }
+    async fork(sessionId, beforeFork) {
+        await this.cancelAll();
+        await this.serializer.submit(async () => {
+            beforeFork?.();
+            await this.session.fork(sessionId);
+            await Promise.all(this.listeners.map((l) => l.onFork?.()));
+        });
+    }
+    async addMessages(newMessages, uiHidden = false) {
+        const appended = await this.session.append(newMessages, uiHidden);
+        await Promise.all(this.listeners.map((l) => l.onMessages?.(appended)));
+    }
+    async addInitialMessages() {
+        if (!this.session.messages.length) {
+            const initContent = await new InitPrompt().build();
+            if (initContent) {
+                await this.addMessages([{ role: 'user', content: initContent }], true);
+            }
+        }
+    }
+    async callTools(toolCalls, signal) {
+        return await Promise.all(toolCalls.map(async (toolCall) => ({
+            type: 'tool-result',
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            output: {
+                type: 'json',
+                value: await this.tools.execute(toolCall.toolName, toolCall.input, signal),
+            },
+        })));
+    }
+}

package/dist/agent/agents-prompt.js

@@ -0,0 +1,23 @@
+import { readFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+import { ancestorPaths } from './paths.js';
+export class AgentsPrompt {
+    async build() {
+        const contents = (await Promise.all([join(homedir(), '.agents'), ...ancestorPaths(process.cwd())].map((dir) => this.tryRead(join(dir, 'AGENTS.md'))))).filter(Boolean);
+        if (!contents.length)
+            return '';
+        return [
+            'Follow the instructions below that have come from AGENTS.md files.',
+            '<AGENT_INSTRUCTIONS>',
+            ...contents,
+            '</AGENT_INSTRUCTIONS>',
+        ].join('\n\n');
+    }
+    async tryRead(path) {
+        try {
+            return await readFile(path, 'utf-8');
+        }
+        catch { }
+    }
+}

package/dist/agent/config.js

@@ -0,0 +1,54 @@
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+export class ConfigReader {
+    static CONFIG_PATH = join(homedir(), '.config', 'ask', 'config.json');
+    readConfigFile() {
+        try {
+            return JSON.parse(readFileSync(ConfigReader.CONFIG_PATH, 'utf-8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    envOrFile(envKey, fileKey, fileValues) {
+        const envValue = process.env[envKey];
+        if (envValue)
+            return envValue.trim();
+        const fileValue = fileValues[fileKey];
+        if (fileValue != null)
+            return String(fileValue).trim();
+        throw new Error(`neither ${envKey} nor ${fileKey} is set`);
+    }
+    optionalEnvOrFile(envKey, fileKey, fileValues) {
+        const envValue = process.env[envKey];
+        if (envValue && envValue.trim())
+            return envValue.trim();
+        const fileValue = fileValues[fileKey];
+        if (fileValue == null)
+            return undefined;
+        const value = String(fileValue).trim();
+        return value ? value : undefined;
+    }
+    isOpenAIBaseUrl(baseUrl) {
+        try {
+            return new URL(baseUrl).hostname.includes('openai.com');
+        }
+        catch {
+            return baseUrl.includes('openai.com');
+        }
+    }
+    read() {
+        const fileValues = this.readConfigFile();
+        const baseUrl = this.envOrFile('ASK_BASE_URL', 'base_url', fileValues);
+        const apiKey = this.optionalEnvOrFile('ASK_API_KEY', 'api_key', fileValues);
+        if (!apiKey && !this.isOpenAIBaseUrl(baseUrl)) {
+            throw new Error('neither ASK_API_KEY nor api_key is set (required unless ASK_BASE_URL/base_url points to openai.com)');
+        }
+        return {
+            apiKey: apiKey ?? 'oauth',
+            model: this.envOrFile('ASK_MODEL', 'model', fileValues),
+            baseUrl,
+        };
+    }
+}

package/dist/agent/execute-tool.js

@@ -0,0 +1,80 @@
+import { tool } from 'ai';
+import { spawn } from 'child_process';
+import process from 'process';
+import { z } from 'zod';
+const DEFAULT_TIMEOUT_S = 60;
+const TERMINATION_GRACE_MS = 5000;
+const executeInputSchema = z.object({
+    command: z
+        .string()
+        .describe('The shell command to execute using `bash -c`'),
+});
+export class ExecuteTool {
+    name = 'execute';
+    definition() {
+        return tool({
+            description: 'Executes a shell command using `bash -c`. ' +
+                'Can be multiline or whatever `bash -c` accepts. ' +
+                'Returns stdout/stderr/exit/signal/error. ' +
+                `Commands are killed after ${DEFAULT_TIMEOUT_S}s. `,
+            inputSchema: executeInputSchema,
+        });
+    }
+    async execute(input, signal) {
+        const timeoutSignal = AbortSignal.timeout(DEFAULT_TIMEOUT_S * 1000);
+        const combinedSignal = AbortSignal.any([signal, timeoutSignal]);
+        if (combinedSignal.aborted) {
+            return {};
+        }
+        const { command } = executeInputSchema.parse(input);
+        const child = spawn('bash', ['-c', command], {
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let error;
+        let closed = false;
+        const onAbort = () => {
+            if (!closed)
+                this.signalProcessGroup(child, 'SIGTERM');
+            setTimeout(() => {
+                if (!closed)
+                    this.signalProcessGroup(child, 'SIGKILL');
+            }, TERMINATION_GRACE_MS).unref();
+        };
+        combinedSignal.addEventListener('abort', onAbort);
+        child.stdout.on('data', (data) => {
+            stdoutChunks.push(data.toString());
+        });
+        child.stderr.on('data', (data) => {
+            stderrChunks.push(data.toString());
+        });
+        child.on('error', (err) => {
+            error = err.message || String(err);
+        });
+        return new Promise((resolve) => {
+            child.on('close', (exit, signal) => {
+                closed = true;
+                combinedSignal.removeEventListener('abort', onAbort);
+                resolve({
+                    ...(exit !== null && { exit }),
+                    ...(signal && { signal }),
+                    ...(error && { error }),
+                    ...(stdoutChunks.length && { stdout: stdoutChunks.join('') }),
+                    ...(stderrChunks.length && { stderr: stderrChunks.join('') }),
+                });
+            });
+        });
+    }
+    signalProcessGroup(child, signal) {
+        if (child.killed || !child.pid)
+            return;
+        try {
+            process.kill(-child.pid, signal);
+        }
+        catch (error) {
+            console.error(error);
+        }
+    }
+}

package/dist/agent/index.js

@@ -0,0 +1 @@
+export { Agent, ABORTED_MESSAGE, ERROR_MESSAGE, } from './agent.js';

package/dist/agent/init-prompt.js

@@ -0,0 +1,11 @@
+import { AgentsPrompt } from './agents-prompt.js';
+import { SkillsPrompt } from './skills-prompt.js';
+export class InitPrompt {
+    async build() {
+        const parts = await Promise.all([
+            new AgentsPrompt().build(),
+            new SkillsPrompt().build(),
+        ]);
+        return parts.filter(Boolean).join('\n\n');
+    }
+}

package/dist/agent/messages.js

@@ -0,0 +1 @@
+export {};