featherslop 0.0.0-stage → 0.1.0

package/dist/bin/featherslop.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/featherslop.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import OpenAI from 'openai';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { AnthropicProvider, Loop, ManagedFileTools, ParallelWebSearchTool, ShellTool, SimpleUI, WebFetchTool, } from '../src/index.js';
+const argv = await yargs(hideBin(process.argv))
+    .scriptName('featherslop')
+    .usage('$0 [options] [prompt]\n\nChat with an agent in the terminal, or run one prompt and exit.')
+    .option('model', {
+    alias: 'm',
+    type: 'string',
+    default: process.env.MODEL ?? 'qwen-3.5-9b',
+    describe: 'Model (env MODEL)',
+})
+    .option('provider', {
+    choices: ['openai', 'anthropic'],
+    describe: 'API to use (default: anthropic for claude-* models, otherwise openai)',
+})
+    .option('base-url', {
+    type: 'string',
+    default: process.env.OPENAI_BASE_URL ?? 'http://127.0.0.1:9931/v1',
+    describe: 'OpenAI-compatible endpoint (env OPENAI_BASE_URL)',
+})
+    .option('shell', { type: 'boolean', default: false, describe: 'Add an unsandboxed shell tool' })
+    .epilogue('Tools: read, write, update, webfetch; websearch when PARALLEL_API_KEY is set.\n' +
+    'Keys: OPENAI_API_KEY, ANTHROPIC_API_KEY, PARALLEL_API_KEY.')
+    .version(version())
+    .alias('h', 'help')
+    .alias('v', 'version')
+    .strictOptions()
+    .parseAsync();
+const { model, shell } = argv;
+const provider = argv.provider ?? (model.startsWith('claude-') ? 'anthropic' : 'openai');
+const api = provider === 'anthropic' ? await anthropic() : openai();
+// A factory, so `/c` starts over with fresh tool state (e.g. which files were read).
+const createAgent = () => {
+    const tools = {
+        // read, write and update; updates and overwrites only after a read.
+        ...ManagedFileTools(),
+        webfetch: WebFetchTool(provider === 'openai'
+            ? // llama.cpp: skip thinking for compaction; other servers ignore unknown fields.
+                { params: { compactOptions: { value: { chat_template_kwargs: { enable_thinking: false } } } } }
+            : {}),
+    };
+    if (process.env.PARALLEL_API_KEY)
+        tools.websearch = ParallelWebSearchTool();
+    if (shell)
+        tools.shell = ShellTool();
+    return Loop(api, tools);
+};
+const ui = new SimpleUI(createAgent, {
+    model,
+    system: `Concise assistant. Today is ${new Date().toISOString().slice(0, 10)}. cwd: ${process.cwd()}`,
+});
+const prompt = argv._.join(' ');
+if (prompt)
+    await ui.ask(prompt);
+else
+    await ui.start();
+function openai() {
+    return new OpenAI({
+        baseURL: argv.baseUrl,
+        apiKey: process.env.OPENAI_API_KEY ?? 'none',
+    });
+}
+/** `@anthropic-ai/sdk` is an optional peer dependency; load it only when asked for. */
+async function anthropic() {
+    try {
+        const { default: Anthropic } = await import('@anthropic-ai/sdk');
+        // Agentic work does better at high effort than Claude Opus 5.5's medium default.
+        return new AnthropicProvider(new Anthropic(), { effort: 'high' });
+    }
+    catch (err) {
+        if (err.code !== 'ERR_MODULE_NOT_FOUND')
+            throw err;
+        console.error('The anthropic provider needs @anthropic-ai/sdk: npm install @anthropic-ai/sdk');
+        process.exit(1);
+    }
+}
+/** Finds our package.json from either bin/ (source) or dist/bin/ (built). */
+function version() {
+    for (let dir = dirname(fileURLToPath(import.meta.url)); dir !== dirname(dir); dir = dirname(dir)) {
+        const file = join(dir, 'package.json');
+        if (existsSync(file))
+            return JSON.parse(readFileSync(file, 'utf8')).version;
+    }
+    return 'unknown';
+}

package/dist/src/compact.d.ts

@@ -0,0 +1,14 @@
+import type { ToolContext } from './tool.ts';
+export interface CompactOptions {
+    /** Instruction for the compacting model. */
+    prompt: string;
+    content: string;
+    /** What the calling agent cares about, if it said. */
+    focus?: string | undefined;
+    /** Defaults to the model the loop is running with. */
+    model?: string | undefined;
+    /** Extra request fields, e.g. `{ chat_template_kwargs: { enable_thinking: false } }` for llama.cpp. */
+    request?: Record<string, unknown> | undefined;
+}
+/** Shrinks a tool result with a single inference call before it reaches the agent's context. */
+export declare function compact(ctx: ToolContext, { prompt, content, focus, model, request }: CompactOptions): Promise<string>;

package/dist/src/compact.js

@@ -0,0 +1,13 @@
+/** Shrinks a tool result with a single inference call before it reaches the agent's context. */
+export async function compact(ctx, { prompt, content, focus, model, request }) {
+    const result = await ctx.api.complete({
+        model: model ?? ctx.model,
+        system: prompt,
+        prompt: focus ? `${content}\n\n---\nFocus: ${focus}` : content,
+        signal: ctx.signal,
+        request,
+    });
+    if (!result)
+        throw new Error('Compaction returned no content');
+    return result;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+export * from './loop.ts';
+export * from './tool.ts';
+export * from './tools/read.ts';
+export * from './tools/write.ts';
+export * from './tools/update.ts';
+export * from './tools/shell.ts';
+export * from './tools/fs.ts';
+export * from './tools/file-state.ts';
+export * from './compact.ts';
+export * from './tools/webfetch.ts';
+export * from './tools/parallel-search.ts';
+export * from './simple-ui.ts';
+export * from './provider.ts';
+export * from './providers/index.ts';

package/dist/src/index.js

@@ -0,0 +1,14 @@
+export * from './loop.js';
+export * from './tool.js';
+export * from './tools/read.js';
+export * from './tools/write.js';
+export * from './tools/update.js';
+export * from './tools/shell.js';
+export * from './tools/fs.js';
+export * from './tools/file-state.js';
+export * from './compact.js';
+export * from './tools/webfetch.js';
+export * from './tools/parallel-search.js';
+export * from './simple-ui.js';
+export * from './provider.js';
+export * from './providers/index.js';

package/dist/src/loop.d.ts

@@ -0,0 +1,92 @@
+import { EventEmitter } from 'node:events';
+import { type AssistantMessage, type Message, type Provider, type Usage } from './provider.ts';
+import { type ApiClient } from './providers/index.ts';
+import { type Toolset } from './tool.ts';
+export type { AssistantMessage, Message, Usage } from './provider.ts';
+export interface EndState {
+    /** Assistant message produced by the latest turn. */
+    message: AssistantMessage;
+    /** Full conversation so far, including `message`. */
+    messages: readonly Message[];
+    /** 1-based number of the turn that just finished. */
+    turn: number;
+}
+/** Return true to stop the loop. Checked after each assistant turn. */
+export type EndCriteria = (state: EndState) => boolean | Promise<boolean>;
+export declare const noToolCalls: EndCriteria;
+export interface LoopOptions {
+    endCriteria?: EndCriteria;
+    /** Run every tool call in the model's order, one at a time. Off by default. */
+    sequentialTools?: boolean;
+}
+export interface RunOptions {
+    model: string;
+    input: Message[];
+    /** Overrides the toolset given to the constructor for this run. */
+    toolset?: Toolset;
+    endCriteria?: EndCriteria;
+    signal?: AbortSignal;
+    /** Extra provider-specific request fields (temperature, llama.cpp sampling params, ...). */
+    request?: Record<string, unknown>;
+}
+export interface RunResult {
+    /** Final assistant message. */
+    message: AssistantMessage;
+    /** Full conversation, starting with the input. */
+    messages: Message[];
+    /** Tokens used by the run, including inference done by tools. */
+    usage: Usage;
+}
+export interface ToolCallEvent {
+    id: string;
+    name: string;
+    arguments: unknown;
+}
+export interface ToolResultEvent extends ToolCallEvent {
+    result: string;
+    isError: boolean;
+}
+export interface UsageEvent extends Usage {
+    model: string;
+    /** 1-based turn the call happened in. */
+    turn: number;
+    /** A model turn, or inference a tool ran itself (e.g. compaction). */
+    source: 'turn' | 'tool';
+    /** Name of the tool, for `source: 'tool'`. */
+    tool?: string;
+}
+export interface LoopEvents {
+    /** A request to the model is about to be made. */
+    turn: [turn: number];
+    /** Streamed reasoning/thinking delta. */
+    reasoning: [delta: string];
+    /** Streamed content delta. */
+    content: [delta: string];
+    /** A tool is about to be invoked. */
+    tool_call: [call: ToolCallEvent];
+    tool_result: [result: ToolResultEvent];
+    /** Tokens used by one model call. */
+    usage: [usage: UsageEvent];
+    /** A message was appended to the conversation (assistant, tool, or queued). */
+    message: [message: Message];
+    /** End criteria were met, or the model refused. */
+    end: [result: RunResult];
+}
+export declare class AgentLoop extends EventEmitter<LoopEvents> {
+    #private;
+    readonly api: Provider;
+    readonly toolset: Toolset;
+    readonly endCriteria: EndCriteria;
+    readonly sequentialTools: boolean;
+    constructor(api: ApiClient, toolset?: Toolset, options?: LoopOptions);
+    get running(): boolean;
+    /**
+     * Queues a message to be sent with the next request. While a run is in
+     * progress, a queued message also keeps the loop from ending. Messages queued
+     * between runs are sent after the next run's input.
+     */
+    queue(message: Message | string): void;
+    run(options: RunOptions): Promise<RunResult>;
+}
+/** `Loop(api, toolset)` from the spec; equivalent to `new AgentLoop(...)`. */
+export declare function Loop(api: ApiClient, toolset?: Toolset, options?: LoopOptions): AgentLoop;

package/dist/src/loop.js

@@ -0,0 +1,184 @@
+import { EventEmitter } from 'node:events';
+import { addUsage, emptyUsage, } from './provider.js';
+import { toProvider } from './providers/index.js';
+import { ToolInputError } from './tool.js';
+export const noToolCalls = ({ message }) => !message.tool_calls?.length;
+export class AgentLoop extends EventEmitter {
+    api;
+    toolset;
+    endCriteria;
+    sequentialTools;
+    #pending = [];
+    #running = false;
+    constructor(api, toolset = {}, options = {}) {
+        super();
+        this.api = toProvider(api);
+        this.toolset = toolset;
+        this.endCriteria = options.endCriteria ?? noToolCalls;
+        this.sequentialTools = options.sequentialTools ?? false;
+    }
+    get running() {
+        return this.#running;
+    }
+    /**
+     * Queues a message to be sent with the next request. While a run is in
+     * progress, a queued message also keeps the loop from ending. Messages queued
+     * between runs are sent after the next run's input.
+     */
+    queue(message) {
+        this.#pending.push(typeof message === 'string' ? { role: 'user', content: message } : message);
+    }
+    async run(options) {
+        if (this.#running)
+            throw new Error('AgentLoop is already running');
+        this.#running = true;
+        try {
+            return await this.#run(options);
+        }
+        finally {
+            this.#running = false;
+        }
+    }
+    async #run({ model, input, toolset = this.toolset, endCriteria = this.endCriteria, signal, request }) {
+        const messages = [...input];
+        const tools = toolSpecs(toolset);
+        let usage = emptyUsage();
+        let turn = 0;
+        const track = (used, info) => {
+            usage = addUsage(usage, used);
+            this.emit('usage', { ...used, ...info, turn });
+        };
+        for (turn = 1;; turn++) {
+            this.#drainQueue(messages);
+            signal?.throwIfAborted();
+            this.emit('turn', turn);
+            const message = await this.api.turn({ model, messages, tools, signal, request }, {
+                reasoning: (delta) => this.emit('reasoning', delta),
+                content: (delta) => this.emit('content', delta),
+                usage: (used) => track(used, { model, source: 'turn' }),
+            });
+            // SDKs may end an aborted stream quietly; don't act on a cut-off message.
+            signal?.throwIfAborted();
+            messages.push(message);
+            this.emit('message', message);
+            if (message.tool_calls?.length) {
+                // A refused or truncated turn's tool calls may be incomplete; answer them without running.
+                const skip = message.stop === 'refusal' || message.stop === 'max_tokens' ? message.stop : undefined;
+                const results = skip
+                    ? message.tool_calls.map((call) => this.#skip(call, skip))
+                    : await this.#invokeAll(message.tool_calls, toolset, { model, signal, track });
+                for (const result of results) {
+                    messages.push(result);
+                    this.emit('message', result);
+                }
+            }
+            const done = message.stop === 'refusal' || (await endCriteria({ message, messages, turn }));
+            if (done && (this.#pending.length === 0 || message.stop === 'refusal')) {
+                const result = { message, messages, usage };
+                this.emit('end', result);
+                return result;
+            }
+        }
+    }
+    #drainQueue(messages) {
+        for (const message of this.#pending.splice(0)) {
+            messages.push(message);
+            this.emit('message', message);
+        }
+    }
+    /**
+     * Runs a turn's calls concurrently, except sequential ones, which wait for
+     * everything before them and run alone. Results keep the model's order.
+     */
+    async #invokeAll(calls, toolset, context) {
+        const results = [];
+        let batch = [];
+        for (const call of calls) {
+            if (this.sequentialTools || toolset[call.function.name]?.sequential) {
+                results.push(...(await Promise.all(batch)));
+                batch = [];
+                results.push(await this.#invoke(call, toolset, context));
+            }
+            else {
+                batch.push(this.#invoke(call, toolset, context));
+            }
+        }
+        results.push(...(await Promise.all(batch)));
+        return results;
+    }
+    async #invoke(call, toolset, { model, signal, track }) {
+        const { id } = call;
+        const { name, arguments: raw } = call.function;
+        const args = parseArguments(raw);
+        this.emit('tool_call', { id, name, arguments: args ?? raw });
+        let result;
+        let isError = false;
+        try {
+            const tool = toolset[name];
+            if (!tool)
+                throw new ToolInputError(`Unknown tool "${name}"`);
+            if (!args)
+                throw new ToolInputError('Arguments must be a JSON object');
+            result = await tool.invoke(args, { api: attributed(this.api, name, track), model, signal });
+        }
+        catch (err) {
+            if (signal?.aborted)
+                throw err;
+            // Any failure goes back to the model as the tool result; it may be able to recover.
+            isError = true;
+            result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+        this.emit('tool_result', { id, name, arguments: args, result, isError });
+        return { role: 'tool', tool_call_id: id, content: result, ...(isError ? { is_error: true } : {}) };
+    }
+    #skip(call, reason) {
+        const { id } = call;
+        const { name, arguments: raw } = call.function;
+        const result = reason === 'max_tokens'
+            ? 'Error: not run; the response hit the output token limit, so the arguments may be incomplete'
+            : 'Error: not run; the response was declined';
+        this.emit('tool_call', { id, name, arguments: parseArguments(raw) ?? raw });
+        this.emit('tool_result', { id, name, arguments: parseArguments(raw), result, isError: true });
+        return { role: 'tool', tool_call_id: id, content: result, is_error: true };
+    }
+}
+/** `Loop(api, toolset)` from the spec; equivalent to `new AgentLoop(...)`. */
+export function Loop(api, toolset = {}, options = {}) {
+    return new AgentLoop(api, toolset, options);
+}
+/** The provider as a tool sees it: its own inference is reported as the tool's usage. */
+function attributed(api, tool, track) {
+    return {
+        name: api.name,
+        turn: (request, on) => api.turn(request, {
+            ...on,
+            usage: (used) => {
+                on.usage?.(used);
+                track(used, { model: request.model, source: 'tool', tool });
+            },
+        }),
+        complete: (request) => api.complete({
+            ...request,
+            onUsage: (used) => {
+                request.onUsage?.(used);
+                track(used, { model: request.model, source: 'tool', tool });
+            },
+        }),
+    };
+}
+function parseArguments(raw) {
+    if (!raw.trim())
+        return {};
+    try {
+        const args = JSON.parse(raw);
+        return typeof args === 'object' && args !== null && !Array.isArray(args)
+            ? args
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function toolSpecs(toolset) {
+    return Object.entries(toolset).map(([name, tool]) => ({ name, ...tool.schema() }));
+}

package/dist/src/provider.d.ts

@@ -0,0 +1,73 @@
+import type { ChatCompletionAssistantMessageParam, ChatCompletionMessageFunctionToolCall, ChatCompletionMessageParam, ChatCompletionToolMessageParam } from 'openai/resources/chat/completions';
+import type { JSONSchema } from './tool.ts';
+/** Why a model stopped, normalized across providers. */
+export type StopReason = 'end' | 'tool_use' | 'max_tokens' | 'refusal' | 'other';
+/**
+ * Assistant message as kept in history. Conversations use the OpenAI chat
+ * shape as the common format, with a few extensions:
+ * - `reasoning_content`: thinking text (llama.cpp's field; filled by every provider).
+ * - `stop`: why the model stopped.
+ * - `native`: the provider's raw content, replayed verbatim to the same provider
+ *   (e.g. Anthropic thinking blocks must be passed back unchanged).
+ */
+export type AssistantMessage = Omit<ChatCompletionAssistantMessageParam, 'tool_calls'> & {
+    tool_calls?: ChatCompletionMessageFunctionToolCall[];
+    reasoning_content?: string;
+    stop?: StopReason;
+    native?: {
+        provider: string;
+        content: unknown;
+    };
+};
+/** Tool result; `is_error` lets providers that support it flag failures. */
+export type ToolMessage = ChatCompletionToolMessageParam & {
+    is_error?: boolean;
+};
+export type Message = ChatCompletionMessageParam | AssistantMessage | ToolMessage;
+/** Token counts for one model call. `input` excludes cache reads and writes. */
+export interface Usage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    /** Part of `output` spent on reasoning, when the provider reports it. */
+    reasoning?: number;
+}
+export declare function addUsage(a: Usage, b: Usage): Usage;
+export declare const emptyUsage: () => Usage;
+export interface ToolSpec {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+}
+export interface TurnRequest {
+    model: string;
+    messages: readonly Message[];
+    tools: readonly ToolSpec[];
+    signal?: AbortSignal | undefined;
+    /** Extra provider-specific request fields. */
+    request?: Record<string, unknown> | undefined;
+}
+export interface TurnHandlers {
+    reasoning(delta: string): void;
+    content(delta: string): void;
+    usage?(usage: Usage): void;
+}
+export interface CompleteRequest {
+    model: string;
+    system?: string | undefined;
+    prompt: string;
+    signal?: AbortSignal | undefined;
+    onUsage?: ((usage: Usage) => void) | undefined;
+    /** Extra provider-specific request fields. */
+    request?: Record<string, unknown> | undefined;
+}
+/** What the loop and tools need from a model API. */
+export interface Provider {
+    readonly name: string;
+    /** Streams one assistant turn, reporting deltas as they arrive. */
+    turn(request: TurnRequest, on: TurnHandlers): Promise<AssistantMessage>;
+    /** Single non-streaming completion without tools, e.g. for compaction. */
+    complete(request: CompleteRequest): Promise<string>;
+}
+export declare function isProvider(value: unknown): value is Provider;

package/dist/src/provider.js

@@ -0,0 +1,15 @@
+export function addUsage(a, b) {
+    const sum = {
+        input: a.input + b.input,
+        output: a.output + b.output,
+        cacheRead: a.cacheRead + b.cacheRead,
+        cacheWrite: a.cacheWrite + b.cacheWrite,
+    };
+    if (a.reasoning !== undefined || b.reasoning !== undefined)
+        sum.reasoning = (a.reasoning ?? 0) + (b.reasoning ?? 0);
+    return sum;
+}
+export const emptyUsage = () => ({ input: 0, output: 0, cacheRead: 0, cacheWrite: 0 });
+export function isProvider(value) {
+    return typeof value === 'object' && value !== null && typeof value.turn === 'function';
+}

package/dist/src/providers/anthropic.d.ts

@@ -0,0 +1,37 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import type { BetaMessageParam } from '@anthropic-ai/sdk/resources/beta/messages/messages';
+import type { AssistantMessage, CompleteRequest, Message, Provider, TurnHandlers, TurnRequest } from '../provider.ts';
+export type Effort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export interface AnthropicProviderOptions {
+    /** Defaults to 64000; turns are streamed, so large values are fine. */
+    maxTokens?: number;
+    /** `output_config.effort`; unset uses the model's default (`medium` on Claude Opus 5.5). */
+    effort?: Effort;
+    /**
+     * Adaptive thinking display. `summarized` (default) returns readable thinking
+     * summaries; `false` omits the `thinking` parameter (e.g. for Claude Haiku 4.5).
+     */
+    thinking?: 'summarized' | 'omitted' | false;
+    /** Server-side fallback when a request is declined for policy reasons. On by default. */
+    fallbacks?: 'default' | false;
+    /** Automatic prompt caching of the conversation prefix. On by default. */
+    cache?: boolean;
+}
+/** Claude through the Messages API (`@anthropic-ai/sdk`). */
+export declare class AnthropicProvider implements Provider {
+    readonly name = "anthropic";
+    readonly client: Anthropic;
+    readonly options: AnthropicProviderOptions;
+    constructor(client: Anthropic, options?: AnthropicProviderOptions);
+    turn({ model, messages, tools, signal, request }: TurnRequest, on: TurnHandlers): Promise<AssistantMessage>;
+    complete({ model, system, prompt, signal, request, onUsage }: CompleteRequest): Promise<string>;
+}
+/**
+ * Converts the common history format. Leading system messages become the
+ * `system` prompt; tool results and any user text that follows are merged
+ * into one user message, since parallel results belong together.
+ */
+export declare function toAnthropic(messages: readonly Message[]): {
+    system: string | undefined;
+    messages: BetaMessageParam[];
+};