@ashlr/hub 2.2.0

package/dist/core/run/agent-loop.js

@@ -0,0 +1,291 @@
+/**
+ * agent-loop.ts — bounded ReAct-style loop for a single RunTask.
+ *
+ * Runs the task against a ProviderClient, handling tool calls when supported,
+ * enforcing the hard budget ceiling, and emitting RunStep events per step.
+ * Never throws out of runTask — all errors are captured into task.status/error.
+ *
+ * M11: accepts an optional StreamSink in ctx for live progress streaming.
+ * Emits model-delta events via client.chatStream() when available (falls back
+ * to client.chat() with a single delta of the full content). Also emits
+ * tool-call events per tool execution.
+ */
+import { addUsage, overBudget, newUsage } from './budget.js';
+import { nullSink } from './streaming.js';
+/** Maximum steps per task, regardless of budget (safety backstop). */
+const TASK_STEP_CAP = 20;
+/**
+ * Execute a single RunTask to completion using `client`.
+ *
+ * - Runs a bounded chat loop (ReAct-style).
+ * - When ctx.tools is present AND client.supportsTools, may issue tool calls
+ *   and feed results back as role:'tool' messages.
+ * - Accumulates per-step usage into ctx.usage (mutated in place via addUsage).
+ * - Emits one RunStep per model call (kind:'model') and per tool execution
+ *   batch (kind:'tool') via ctx.onStep.
+ * - M11: emits RunStreamEvents via ctx.sink for live CLI progress:
+ *     model-delta (via chatStream if available, else single onDelta of full content),
+ *     tool-call per tool execution.
+ * - HARD STOP: if overBudget(ctx.usage, ctx.budget) at any point, stops the
+ *   loop. Sets task.status='failed' (no result) or 'done' (partial result).
+ * - On success: task.status='done', task.result=<text>, task.usage=<delta>.
+ * - On error: task.status='failed', task.error=<message>.
+ * - Returns the SAME task object (mutated) for caller convenience.
+ */
+export async function runTask(task, client, ctx) {
+    // Track per-task usage delta so we can set task.usage at end.
+    let taskUsage = newUsage();
+    let stepCount = 0;
+    // M11: resolve sink — default to nullSink when not provided.
+    const sink = ctx.sink ?? nullSink();
+    // Helper: emit a RunStreamEvent. Never throws.
+    function emitStream(event) {
+        try {
+            sink({ ...event, ts: new Date().toISOString() });
+        }
+        catch {
+            // Sinks must never crash the loop.
+        }
+    }
+    // Helper: accumulate ONLY into the local per-task delta.
+    //
+    // IMPORTANT: ctx.usage is the orchestrator-owned cumulative usage object and
+    // the SINGLE source of truth. We deliberately do NOT write to it here.
+    // Instead the orchestrator mutates ctx.usage IN PLACE inside its onStep
+    // callback (orchestrator.ts) when it receives the model step we emit below.
+    // Keeping a single writer (a) prevents double-counting (previously the loop
+    // added the delta here AND the orchestrator added the same step.usage again),
+    // and (b) preserves the object identity that every in-flight runTask holds,
+    // so the in-loop hard-ceiling check overBudget(ctx.usage, ctx.budget) always
+    // reads the true global total even under --parallel > 1.
+    function accumulateUsage(delta) {
+        taskUsage = addUsage(taskUsage, delta);
+    }
+    // Helper: emit a RunStep.
+    function emitStep(kind, summary, usage) {
+        const step = {
+            ts: new Date().toISOString(),
+            taskId: task.id,
+            kind,
+            summary,
+            ...(usage !== undefined ? { usage } : {}),
+        };
+        try {
+            ctx.onStep(step);
+        }
+        catch {
+            // onStep must never crash the loop.
+        }
+    }
+    // Resolve tools: only use them if client supports them AND tools provided.
+    const useTools = client.supportsTools &&
+        ctx.tools !== undefined &&
+        ctx.tools.length > 0;
+    const toolSpecs = useTools ? ctx.tools : undefined;
+    // Build a tool executor map keyed by name (best-effort; tools may lack fn).
+    const toolExecutors = new Map();
+    if (useTools && ctx.tools) {
+        for (const t of ctx.tools) {
+            const spec = t;
+            if (spec.name && typeof spec.fn === 'function') {
+                toolExecutors.set(spec.name, spec.fn);
+            }
+        }
+    }
+    // Build the initial message list.
+    const messages = [
+        {
+            role: 'system',
+            content: 'You are an Ashlr sub-agent. Be concise and focused. ' +
+                'Complete the given task directly. ' +
+                (useTools
+                    ? 'You may call tools to gather information; always follow up with a final answer.'
+                    : 'Do not request tools — respond with a final textual answer only.'),
+        },
+        {
+            role: 'user',
+            content: task.goal,
+        },
+    ];
+    task.status = 'running';
+    try {
+        // Main agent loop.
+        while (true) {
+            // Pre-step budget check.
+            if (overBudget(ctx.usage, ctx.budget)) {
+                const partial = lastAssistantContent(messages);
+                if (partial) {
+                    task.status = 'done';
+                    task.result = `[budget exceeded — partial result]\n${partial}`;
+                }
+                else {
+                    task.status = 'failed';
+                    task.error = 'Budget exceeded before any result was produced.';
+                }
+                break;
+            }
+            // Per-task step cap (safety backstop independent of global budget).
+            if (stepCount >= TASK_STEP_CAP) {
+                const partial = lastAssistantContent(messages);
+                if (partial) {
+                    task.status = 'done';
+                    task.result = `[step cap reached — partial result]\n${partial}`;
+                }
+                else {
+                    task.status = 'failed';
+                    task.error = `Step cap of ${TASK_STEP_CAP} reached without producing a result.`;
+                }
+                break;
+            }
+            stepCount++;
+            // M11: Call the model via chatStream when available for live token streaming.
+            // Falls back to client.chat() when chatStream is not implemented.
+            let result;
+            try {
+                if (typeof client.chatStream === 'function') {
+                    // Stream mode: onDelta emits model-delta events for each token chunk.
+                    result = await client.chatStream(messages, toolSpecs, (chunk) => {
+                        if (chunk.length > 0) {
+                            emitStream({ kind: 'model-delta', taskId: task.id, text: chunk });
+                        }
+                    });
+                }
+                else {
+                    // Non-streaming fallback: emit the full content as a single delta.
+                    result = await client.chat(messages, toolSpecs);
+                    if (result.content.length > 0) {
+                        emitStream({ kind: 'model-delta', taskId: task.id, text: result.content });
+                    }
+                }
+            }
+            catch (err) {
+                task.status = 'failed';
+                task.error = `Model call failed: ${String(err)}`;
+                break;
+            }
+            // Accumulate usage for this model step.
+            const stepUsageDelta = {
+                tokensIn: result.usage.tokensIn,
+                tokensOut: result.usage.tokensOut,
+                steps: 1,
+            };
+            accumulateUsage(stepUsageDelta);
+            // Emit model step.
+            const modelSummary = result.content
+                ? truncate(result.content, 120)
+                : result.toolCalls && result.toolCalls.length > 0
+                    ? `tool calls: ${result.toolCalls.map((tc) => tc.name).join(', ')}`
+                    : '(empty response)';
+            emitStep('model', modelSummary, { ...newUsage(), ...stepUsageDelta, steps: 1 });
+            // Append assistant message.
+            messages.push({
+                role: 'assistant',
+                content: result.content,
+            });
+            // Post-step budget check.
+            if (overBudget(ctx.usage, ctx.budget)) {
+                const partial = result.content || lastAssistantContent(messages);
+                if (partial) {
+                    task.status = 'done';
+                    task.result = `[budget exceeded — partial result]\n${partial}`;
+                }
+                else {
+                    task.status = 'failed';
+                    task.error = 'Budget exceeded after model call; no usable result.';
+                }
+                break;
+            }
+            // Handle tool calls if present.
+            if (result.toolCalls && result.toolCalls.length > 0 && useTools) {
+                for (const tc of result.toolCalls) {
+                    // M11: emit tool-call stream event before execution.
+                    emitStream({
+                        kind: 'tool-call',
+                        taskId: task.id,
+                        text: tc.name,
+                        data: { name: tc.name, arguments: tc.arguments },
+                    });
+                    let toolResultContent;
+                    const executor = toolExecutors.get(tc.name);
+                    if (executor) {
+                        try {
+                            const rawResult = await executor(tc.arguments);
+                            toolResultContent =
+                                typeof rawResult === 'string'
+                                    ? rawResult
+                                    : JSON.stringify(rawResult);
+                        }
+                        catch (toolErr) {
+                            toolResultContent = `Tool execution error: ${String(toolErr)}`;
+                        }
+                    }
+                    else {
+                        // No executor — report the tool as unavailable.
+                        toolResultContent = `Tool '${tc.name}' is not available in this context. Please proceed without it.`;
+                    }
+                    messages.push({
+                        role: 'tool',
+                        content: toolResultContent,
+                        toolCallId: tc.id,
+                        name: tc.name,
+                    });
+                    // Emit a tool step.
+                    emitStep('tool', `${tc.name}: ${truncate(toolResultContent, 80)}`);
+                }
+                // Continue the loop to let the model react to tool results.
+                continue;
+            }
+            // If there were tool calls but tools are not supported by the client,
+            // ask the model to proceed without tools.
+            if (result.toolCalls && result.toolCalls.length > 0 && !useTools) {
+                messages.push({
+                    role: 'user',
+                    content: 'Tool calls are not available in this context. Please provide your final answer using only your existing knowledge.',
+                });
+                continue;
+            }
+            // No tool calls — this is a final answer.
+            if (result.content && result.content.trim().length > 0) {
+                task.status = 'done';
+                task.result = result.content;
+                break;
+            }
+            // Empty content and no tool calls — nudge the model once more.
+            messages.push({
+                role: 'user',
+                content: 'Please provide your answer.',
+            });
+        }
+    }
+    catch (unexpectedErr) {
+        // Catch-all: should not reach here, but ensure we never propagate.
+        task.status = 'failed';
+        task.error = `Unexpected error in agent loop: ${String(unexpectedErr)}`;
+    }
+    // Attach accumulated task-level usage.
+    task.usage = taskUsage;
+    return task;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Truncate a string to maxLen, appending '…' if cut. */
+function truncate(s, maxLen) {
+    if (s.length <= maxLen)
+        return s;
+    return s.slice(0, maxLen - 1) + '…';
+}
+/**
+ * Find the last assistant message content in the message list, if any.
+ * Used to preserve partial results when budget runs out mid-loop.
+ */
+function lastAssistantContent(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role === 'assistant' && m.content && m.content.trim().length > 0) {
+            return m.content;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=agent-loop.js.map

package/dist/core/run/agent-loop.js.map

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

package/dist/core/run/budget.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Budget accounting for `ashlr run`.
+ *
+ * Pure, deterministic functions — no I/O, no side effects. All functions
+ * return new objects; RunUsage is never mutated in place.
+ */
+import type { RunUsage, RunBudget } from '../types.js';
+/**
+ * Return a fresh, zeroed RunUsage.
+ */
+export declare function newUsage(): RunUsage;
+/**
+ * Return a NEW RunUsage = a + b.
+ * `b` is partial — missing fields are treated as 0.
+ * `estCostUsd` is RECOMPUTED from the merged token totals using a neutral
+ * provider label; callers that track the provider should use estCostUsd()
+ * directly and store the result, rather than relying on the summed field.
+ * In practice the orchestrator stores per-task provider and sets estCostUsd
+ * independently; this function sums the existing estCostUsd fields to
+ * preserve already-computed values.
+ */
+export declare function addUsage(a: RunUsage, b: Partial<RunUsage>): RunUsage;
+/**
+ * Returns true when usage has EXCEEDED the budget.
+ *
+ * Triggers:
+ *   - (tokensIn + tokensOut) >= budget.maxTokens, OR
+ *   - steps >= budget.maxSteps
+ *
+ * Using >= (not >) means: once we hit the ceiling we stop BEFORE attempting
+ * another step, which is the conservative / safe behaviour.
+ */
+export declare function overBudget(usage: RunUsage, budget: RunBudget): boolean;
+/**
+ * Estimated USD cost for a single model call.
+ *
+ * - Local providers (ollama, lmstudio) → always 0.
+ * - Cloud providers → looked up from the static price table by matching
+ *   the provider id (case-insensitive prefix match against known keys).
+ *   Falls back to a conservative $3/$15 per-M-token estimate when unknown.
+ *
+ * @param provider  Provider id string (e.g. 'ollama', 'anthropic', 'openai').
+ * @param tokensIn  Number of prompt/input tokens.
+ * @param tokensOut Number of completion/output tokens.
+ * @returns Estimated USD cost as a number (0 for local).
+ */
+export declare function estCostUsd(provider: string, tokensIn: number, tokensOut: number): number;

package/dist/core/run/budget.js

@@ -0,0 +1,113 @@
+/**
+ * Budget accounting for `ashlr run`.
+ *
+ * Pure, deterministic functions — no I/O, no side effects. All functions
+ * return new objects; RunUsage is never mutated in place.
+ */
+// ---------------------------------------------------------------------------
+// Static price table (rough $/M-token estimates for cloud providers).
+// Local providers always return 0. Cloud prices are ESTIMATES only — used
+// for informational cost summaries, not billing.
+// ---------------------------------------------------------------------------
+/** $/M input tokens */
+const PRICE_IN = {
+    // Anthropic Claude models
+    anthropic: 3.0, // conservative mid-tier estimate
+    claude: 3.0,
+    // OpenAI
+    openai: 2.5, // gpt-4o-mini ballpark
+    gpt: 2.5,
+    // Google
+    google: 1.25,
+    gemini: 1.25,
+    // Mistral
+    mistral: 2.0,
+    // Cohere
+    cohere: 1.0,
+};
+/** $/M output tokens */
+const PRICE_OUT = {
+    anthropic: 15.0,
+    claude: 15.0,
+    openai: 10.0,
+    gpt: 10.0,
+    google: 5.0,
+    gemini: 5.0,
+    mistral: 6.0,
+    cohere: 3.0,
+};
+/** Providers that are always local (zero cost). */
+const LOCAL_PROVIDERS = new Set(['ollama', 'lmstudio']);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Return a fresh, zeroed RunUsage.
+ */
+export function newUsage() {
+    return { tokensIn: 0, tokensOut: 0, steps: 0, estCostUsd: 0 };
+}
+/**
+ * Return a NEW RunUsage = a + b.
+ * `b` is partial — missing fields are treated as 0.
+ * `estCostUsd` is RECOMPUTED from the merged token totals using a neutral
+ * provider label; callers that track the provider should use estCostUsd()
+ * directly and store the result, rather than relying on the summed field.
+ * In practice the orchestrator stores per-task provider and sets estCostUsd
+ * independently; this function sums the existing estCostUsd fields to
+ * preserve already-computed values.
+ */
+export function addUsage(a, b) {
+    const tokensIn = a.tokensIn + (b.tokensIn ?? 0);
+    const tokensOut = a.tokensOut + (b.tokensOut ?? 0);
+    const steps = a.steps + (b.steps ?? 0);
+    const estCostUsdVal = a.estCostUsd + (b.estCostUsd ?? 0);
+    return { tokensIn, tokensOut, steps, estCostUsd: estCostUsdVal };
+}
+/**
+ * Returns true when usage has EXCEEDED the budget.
+ *
+ * Triggers:
+ *   - (tokensIn + tokensOut) >= budget.maxTokens, OR
+ *   - steps >= budget.maxSteps
+ *
+ * Using >= (not >) means: once we hit the ceiling we stop BEFORE attempting
+ * another step, which is the conservative / safe behaviour.
+ */
+export function overBudget(usage, budget) {
+    const totalTokens = usage.tokensIn + usage.tokensOut;
+    return totalTokens >= budget.maxTokens || usage.steps >= budget.maxSteps;
+}
+/**
+ * Estimated USD cost for a single model call.
+ *
+ * - Local providers (ollama, lmstudio) → always 0.
+ * - Cloud providers → looked up from the static price table by matching
+ *   the provider id (case-insensitive prefix match against known keys).
+ *   Falls back to a conservative $3/$15 per-M-token estimate when unknown.
+ *
+ * @param provider  Provider id string (e.g. 'ollama', 'anthropic', 'openai').
+ * @param tokensIn  Number of prompt/input tokens.
+ * @param tokensOut Number of completion/output tokens.
+ * @returns Estimated USD cost as a number (0 for local).
+ */
+export function estCostUsd(provider, tokensIn, tokensOut) {
+    const key = provider.toLowerCase();
+    // Fast path: known local providers
+    if (LOCAL_PROVIDERS.has(key))
+        return 0;
+    // Prefix match against the price table keys
+    let priceIn = 3.0; // conservative fallback
+    let priceOut = 15.0; // conservative fallback
+    for (const tableKey of Object.keys(PRICE_IN)) {
+        if (key.includes(tableKey) || tableKey.includes(key)) {
+            priceIn = PRICE_IN[tableKey];
+            priceOut = PRICE_OUT[tableKey] ?? priceOut;
+            break;
+        }
+    }
+    const costIn = (tokensIn / 1_000_000) * priceIn;
+    const costOut = (tokensOut / 1_000_000) * priceOut;
+    return costIn + costOut;
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/run/budget.js.map

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

package/dist/core/run/engines.d.ts

@@ -0,0 +1,75 @@
+/**
+ * engines.ts — M11: hardened per-engine adapters.
+ *
+ * Each engine maps a goal to its REAL CLI argv. This is the source of truth
+ * for external engine invocations and MUST be unit-tested for exact argv.
+ *
+ * Confirmed real CLIs (probed via --help where installed):
+ *   - claude (INSTALLED): `claude -p "<goal>" --model <M> --output-format json`
+ *   - aw (INSTALLED):     `aw auto "<goal>" --cwd <D>` [+ `--model <M>` when given]
+ *   - ashlrcode (ABSENT): `ac --goal "<goal>"` style (fallback to builtin when absent)
+ *
+ * GUARDRAILS:
+ *   - buildEngineCommand is PURE: no spawn, no PATH probe, no network.
+ *   - spawnEngine MUST NOT be called against a real delegated agent during
+ *     build/integrate/verify (unit-tests assert argv only, never spawn).
+ *   - phantomWrap is a pure arg transform; never logs secret values.
+ *   - withToolEnv is allowlist-only (no secrets in env).
+ */
+import type { AshlrConfig, EngineId, EngineCommand } from '../types.js';
+/**
+ * Whether the engine's real binary is on PATH.
+ * - 'builtin' => always true (no external binary needed).
+ * - 'claude'  => checks for 'claude' binary.
+ * - 'aw'      => checks for 'aw' binary.
+ * - 'ashlrcode' => checks for 'ac' (primary alias) or 'ashlrcode'.
+ *
+ * Best-effort, never throws.
+ */
+export declare function engineInstalled(engine: EngineId): boolean;
+/**
+ * Build the EXACT external command for an engine, or null for the builtin loop.
+ *
+ * Returns null when `engine === 'builtin'`.
+ * Returns a fully-resolved EngineCommand for 'ashlrcode' | 'aw' | 'claude'.
+ *
+ * This function is PURE: it does not spawn, probe PATH, or touch the network.
+ * opts.model is the hub-selected model; opts.cwd the target dir (default process.cwd()).
+ *
+ * EXACT argvs (asserted in unit tests):
+ *   claude:     bin='claude', args=['-p', G, '--model', M, '--output-format', 'json']
+ *   aw:         bin='aw',     args=['auto', G, '--cwd', D] [+ '--model', M when given]
+ *   ashlrcode:  bin='ac',     args=['--goal', G]
+ */
+export declare function buildEngineCommand(engine: EngineId, goal: string, _cfg: AshlrConfig, opts?: {
+    cwd?: string;
+    model?: string;
+}): EngineCommand | null;
+/**
+ * Wrap an EngineCommand to run under `phantom exec -- <bin> <args...>`.
+ *
+ * PURE arg transform — never logs secret values.
+ * Caller decides when to apply it (only when cfg.phantom?.enabled && phantomInstalled).
+ */
+export declare function phantomWrap(cmd: EngineCommand, _cfg: AshlrConfig): EngineCommand;
+/**
+ * Spawn a resolved EngineCommand and capture its result.
+ *
+ * - Applies withToolEnv(cfg) (M10 env-bridge; allowlist, NON-SECRET only).
+ * - Wraps via phantomWrap when cfg.phantom?.enabled AND phantom is installed.
+ * - Captures stdout as `output`.
+ * - For claude with --output-format json: parses usage/cost from stdout JSON.
+ * - Never throws; failures reported as { ok: false, error }.
+ *
+ * GUARDRAIL: MUST NOT be called against a real delegated agent during
+ * build/integrate/verify — unit tests assert argv builders only.
+ */
+export declare function spawnEngine(cmd: EngineCommand, cfg: AshlrConfig): {
+    ok: boolean;
+    output: string;
+    usage?: {
+        tokensIn: number;
+        tokensOut: number;
+    };
+    error?: string;
+};