@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/agent/agent-loop.js

@@ -0,0 +1,167 @@
+/**
+ * Agent loop: multi-turn tool-use conversation with an LLM.
+ *
+ * Dispatches to provider-specific implementations (Anthropic / OpenAI) based on
+ * the `provider` field in options (required — routes validate before calling).
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { AGENT_MAX_TOOL_CALLS, AGENT_MAX_TOKENS, shouldUseThinking } from "./agent-provider.js";
+import { runOpenAIAgentLoop } from "./agent-loop-openai.js";
+import { anthropicSystemPromptWithCache, anthropicToolWithCache, ANTHROPIC_FINE_GRAINED_STREAM_HEADERS } from "../chat/anthropic-cache.js";
+export const consoleAgentLogger = {
+    info: (obj, msg) => msg ? console.log(msg, obj) : console.log(obj),
+    warn: (obj, msg) => msg ? console.warn(msg, obj) : console.warn(obj),
+    error: (obj, msg) => msg ? console.error(msg, obj) : console.error(obj),
+};
+/** Provider-agnostic entry point — dispatches to Anthropic or OpenAI loop. */
+export async function* runAgentLoop(options) {
+    if (_runAgentLoopOverride) {
+        yield* _runAgentLoopOverride(options);
+        return;
+    }
+    if (options.provider === "openai") {
+        yield* runOpenAIAgentLoop(options);
+        return;
+    }
+    yield* runAnthropicAgentLoop(options);
+}
+// ---------------------------------------------------------------------------
+// Test injection point (follows setGeneratePlanWithOpenAIForTests pattern)
+// ---------------------------------------------------------------------------
+let _runAgentLoopOverride;
+export function setRunAgentLoopForTests(fn) {
+    _runAgentLoopOverride = fn;
+}
+async function* runAnthropicAgentLoop(options) {
+    const { apiKey, model, systemPrompt, tools, userMessage, maxToolCalls = AGENT_MAX_TOOL_CALLS, signal, logger, } = options;
+    const log = logger ?? consoleAgentLogger;
+    const client = new Anthropic({ apiKey });
+    // Apply prompt caching to system prompt and the *first* tool. Caching the
+    // first tool (rather than rotating to the last) keeps the cached tool prefix
+    // stable when callers pass tools in a different order or subset.
+    const cachedSystem = anthropicSystemPromptWithCache(systemPrompt);
+    const toolDefs = tools.map((t, i) => i === 0 ? anthropicToolWithCache(t.definition) : t.definition);
+    const handlerMap = new Map(tools.map((t) => [t.definition.name, t.handler]));
+    const messages = [
+        { role: "user", content: userMessage },
+    ];
+    let toolCallCount = 0;
+    let fullSummary = "";
+    const totalUsage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheCreationTokens: 0 };
+    // Tool-use loop
+    while (toolCallCount < maxToolCalls) {
+        if (signal?.aborted) {
+            yield { type: "error", message: "Canceled" };
+            return;
+        }
+        let response;
+        const textParts = [];
+        const toolUseBlocks = [];
+        try {
+            // Enable thinking on first turn only for complex requests
+            const useThinking = toolCallCount === 0 && shouldUseThinking(userMessage);
+            if (useThinking) {
+                log.info(`[agent-loop] Adaptive thinking enabled (effort: high)`);
+            }
+            log.info(`[agent-loop] Calling Anthropic API (streaming), turn ${toolCallCount + 1}`);
+            // No `temperature`: it is rejected (400) on Opus 4.8 / Sonnet 5. Adaptive
+            // thinking + output_config.effort replaces the legacy budget_tokens shape.
+            // Effort is capped at "high" (not "max") to stay cost-efficient on the
+            // token-heavier agentic loop; thinking blocks are not surfaced, so the
+            // default "omitted" display is fine.
+            const stream = client.messages.stream({
+                model,
+                max_tokens: AGENT_MAX_TOKENS,
+                system: cachedSystem,
+                tools: toolDefs,
+                messages,
+                ...(useThinking ? { thinking: { type: "adaptive" }, output_config: { effort: "high" } } : {}),
+            }, { headers: ANTHROPIC_FINE_GRAINED_STREAM_HEADERS });
+            const emittedToolStarts = new Set();
+            for await (const event of stream) {
+                // Skip thinking blocks (internal reasoning — not shown to user)
+                if (event.type === "content_block_start" && event.content_block?.type === "thinking")
+                    continue;
+                if (event.type === "content_block_delta" && event.delta?.type === "thinking_delta")
+                    continue;
+                if (event.type === "content_block_start" && event.content_block?.type === "tool_use") {
+                    const { id, name } = event.content_block;
+                    if (!emittedToolStarts.has(id)) {
+                        emittedToolStarts.add(id);
+                        yield { type: "tool_start", toolName: name, toolUseId: id };
+                    }
+                }
+                if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+                    const { text } = event.delta;
+                    textParts.push(text);
+                    yield { type: "text_delta", text };
+                }
+            }
+            response = await stream.finalMessage();
+            for (const block of response.content) {
+                if (block.type === "tool_use") {
+                    toolUseBlocks.push({ id: block.id, name: block.name, input: block.input });
+                    // Fallback for non-fine-grained: emit tool_start if not already emitted
+                    if (!emittedToolStarts.has(block.id)) {
+                        yield { type: "tool_start", toolName: block.name, toolUseId: block.id };
+                    }
+                }
+                else if (block.type === "text" && !textParts.length) {
+                    textParts.push(block.text);
+                }
+            }
+            // Accumulate token usage
+            const u = response.usage;
+            if (u) {
+                totalUsage.inputTokens += u.input_tokens ?? 0;
+                totalUsage.outputTokens += u.output_tokens ?? 0;
+                totalUsage.cacheReadTokens += u.cache_read_input_tokens ?? 0;
+                totalUsage.cacheCreationTokens += u.cache_creation_input_tokens ?? 0;
+            }
+            log.info(`[agent-loop] Stream complete, stop_reason: ${response.stop_reason} content blocks: ${response.content.length} tools: ${toolUseBlocks.map(b => b.name).join(",")}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error(`[agent-loop] API error: ${msg}`);
+            yield { type: "error", message: msg };
+            return;
+        }
+        messages.push({ role: "assistant", content: response.content });
+        if (response.stop_reason === "end_turn" || toolUseBlocks.length === 0) {
+            fullSummary += textParts.join("");
+            yield { type: "done", summary: fullSummary, toolCallCount, usage: totalUsage };
+            return;
+        }
+        // Execute tool calls
+        const toolResults = [];
+        for (const toolUse of toolUseBlocks) {
+            toolCallCount++;
+            log.info(`[agent-loop] Executing tool: ${toolUse.name} input: ${JSON.stringify(toolUse.input).slice(0, 200)}`);
+            const handler = handlerMap.get(toolUse.name);
+            if (!handler) {
+                const errorResult = `Unknown tool: ${toolUse.name}`;
+                toolResults.push({
+                    type: "tool_result",
+                    tool_use_id: toolUse.id,
+                    content: errorResult,
+                    is_error: true,
+                });
+                yield { type: "tool_done", toolName: toolUse.name, toolUseId: toolUse.id, result: errorResult, isError: true };
+                continue;
+            }
+            const { result, isError } = await handler(toolUse.input);
+            toolResults.push({
+                type: "tool_result",
+                tool_use_id: toolUse.id,
+                content: result,
+                ...(isError ? { is_error: true } : {}),
+            });
+            yield { type: "tool_done", toolName: toolUse.name, toolUseId: toolUse.id, result, isError };
+        }
+        if (textParts.length > 0) {
+            fullSummary += textParts.join("");
+        }
+        messages.push({ role: "user", content: toolResults });
+    }
+    yield { type: "done", summary: `Completed with ${toolCallCount} tool calls (limit reached).`, toolCallCount, usage: totalUsage };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Agent provider detection and configuration.
+ * Strict prefix matching — no async probing, no fallback.
+ *
+ * All AGENT_* env vars configure agent mode specifically (user-supplied API key).
+ * They do NOT affect the regular chat pipeline.
+ */
+import type { AIProvider } from "../state/session-state.ts";
+/** Providers currently supported in agent mode. */
+export type AgentProvider = Extract<AIProvider, "anthropic" | "openai">;
+/**
+ * Detect AI provider from API key prefix.
+ * Returns null for unrecognized formats — caller should reject with a descriptive error.
+ */
+export declare function detectProviderFromKey(key: string): AgentProvider | null;
+/** Max tool calls before the agent loop stops. */
+export declare const AGENT_MAX_TOOL_CALLS: number;
+/** Max tokens for agent responses. Higher allows longer reasoning and multi-step summaries. */
+export declare const AGENT_MAX_TOKENS: number;
+/** Adaptive-thinking gate for agent mode. 0 = thinking disabled entirely. */
+export declare const AGENT_THINKING_BUDGET: number;
+/** Resolve a concrete model ID for the given provider, falling back to provider default. */
+export declare function resolveAgentModel(provider: AgentProvider, requestedModel?: string): string;
+/**
+ * Detect whether a user message is complex enough to benefit from extended thinking.
+ * Returns true for multi-step structural edits, false for simple field updates.
+ */
+export declare function shouldUseThinking(message: string): boolean;

package/dist/agent/agent-provider.js

@@ -0,0 +1,63 @@
+/**
+ * Agent provider detection and configuration.
+ * Strict prefix matching — no async probing, no fallback.
+ *
+ * All AGENT_* env vars configure agent mode specifically (user-supplied API key).
+ * They do NOT affect the regular chat pipeline.
+ */
+/**
+ * Detect AI provider from API key prefix.
+ * Returns null for unrecognized formats — caller should reject with a descriptive error.
+ */
+export function detectProviderFromKey(key) {
+    if (key.startsWith("sk-ant-"))
+        return "anthropic";
+    if (key.startsWith("sk-"))
+        return "openai";
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Agent mode defaults (env-configurable)
+// ---------------------------------------------------------------------------
+const DEFAULT_MODELS = {
+    anthropic: process.env.AGENT_ANTHROPIC_MODEL ?? "claude-sonnet-5",
+    openai: process.env.AGENT_OPENAI_MODEL ?? "gpt-4o",
+};
+/** Max tool calls before the agent loop stops. */
+export const AGENT_MAX_TOOL_CALLS = Number(process.env.AGENT_MAX_TOOL_CALLS) || 20;
+/** Max tokens for agent responses. Higher allows longer reasoning and multi-step summaries. */
+export const AGENT_MAX_TOKENS = Number(process.env.AGENT_MAX_TOKENS) || 16384;
+// NOTE: A former AGENT_TEMPERATURE knob was removed — `temperature` is rejected
+// (400) on Opus 4.8 / Sonnet 5, and the OpenAI agent path never consumed it.
+// Steer agent behavior via prompting and adaptive-thinking effort instead.
+/** Adaptive-thinking gate for agent mode. 0 = thinking disabled entirely. */
+export const AGENT_THINKING_BUDGET = Number(process.env.AGENT_THINKING_BUDGET) || 10000;
+/** Resolve a concrete model ID for the given provider, falling back to provider default. */
+export function resolveAgentModel(provider, requestedModel) {
+    if (requestedModel?.trim())
+        return requestedModel.trim();
+    return DEFAULT_MODELS[provider];
+}
+// ---------------------------------------------------------------------------
+// Complexity detection for extended thinking
+// ---------------------------------------------------------------------------
+const STRUCTURAL_KEYWORDS = /\b(redesign|restructure|rewrite\s+all|create\s+(?:a\s+)?(?:new\s+)?page|build\s+(?:a\s+)?(?:new\s+)?page|add\s+\w+\s+sections?|overhaul|rework|redo\s+the)\b/i;
+const MULTI_BLOCK_HINTS = /\b(hero\s+and\s+\w+|all\s+(?:the\s+)?(?:sections?|blocks?|pages?)|every\s+(?:section|block|page)|each\s+(?:section|block|page)|multiple\s+(?:sections?|blocks?)|across\s+(?:the\s+)?(?:site|page))\b/i;
+const STRUCTURAL_VERBS = /\b(add|create|move|reorder|replace|remove|duplicate|insert)\b/i;
+/**
+ * Detect whether a user message is complex enough to benefit from extended thinking.
+ * Returns true for multi-step structural edits, false for simple field updates.
+ */
+export function shouldUseThinking(message) {
+    if (AGENT_THINKING_BUDGET <= 0)
+        return false;
+    // Extract just the user request part (after "User request:" if present)
+    const userPart = message.includes("User request:") ? message.split("User request:").pop() : message;
+    if (STRUCTURAL_KEYWORDS.test(userPart))
+        return true;
+    if (MULTI_BLOCK_HINTS.test(userPart))
+        return true;
+    if (userPart.length > 120 && STRUCTURAL_VERBS.test(userPart))
+        return true;
+    return false;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Agent tool definitions for Anthropic tool-use.
+ * These are the tools Claude can call to modify the website.
+ *
+ * Three categories:
+ * 1. Compound tools (edit_page, batch_update_props, add_block_with_content)
+ * 2. Atomic tools (remove_block, move_block, create_page, etc.)
+ * 3. Read-only context tools (get_page, list_pages, get_block_schema)
+ */
+import type Anthropic from "@anthropic-ai/sdk";
+import { type BlockManifest } from "@avocadostudio-ai/shared";
+import { type AgentLogger } from "./agent-loop.ts";
+type ToolHandler = (input: Record<string, unknown>) => Promise<{
+    result: string;
+    isError?: boolean;
+}>;
+export type AgentTool = {
+    definition: Anthropic.Messages.Tool;
+    handler: ToolHandler;
+};
+/**
+ * Create all agent tools bound to a specific session.
+ */
+export declare function createAgentTools(session: string, options?: {
+    manifest?: BlockManifest;
+    logger?: AgentLogger;
+}): AgentTool[];
+export {};