@bluecopa/harness 0.1.0-snapshot.60 → 0.1.0-snapshot.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluecopa/harness",
-  "version": "0.1.0-snapshot.60",
+  "version": "0.1.0-snapshot.62",
   "description": "Provider-agnostic TypeScript agent framework",
   "license": "UNLICENSED",
   "scripts": {

package/src/agent/types.ts

@@ -2,6 +2,8 @@ export interface ToolCallInfo {
   toolCallId: string;
   toolName: string;
   args: Record<string, unknown>;
+  /** Provider-specific metadata preserved across round-trips (e.g., Gemini thought signatures). */
+  providerMetadata?: Record<string, unknown>;
 }
 
 export interface ToolResultInfo {
@@ -20,6 +22,8 @@ export interface AgentMessage {
   content: string | ContentPart[];
   toolCalls?: ToolCallInfo[];      // assistant messages: what tools were called
   toolResults?: ToolResultInfo[];  // tool messages: results keyed by toolCallId
+  /** Provider-specific metadata preserved across round-trips (e.g., Gemini thought signatures). */
+  providerMetadata?: Record<string, unknown>;
 }
 
 /** Extract plain text from content (string or ContentPart[]). */

package/src/arc/agent-runner.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { generateText, generateObject } from 'ai';
+import { generateText, generateObject, tool as aiTool } from 'ai';
 import { anthropic as defaultAnthropicProvider } from '@ai-sdk/anthropic';
+import { z } from 'zod';
 import type { ModelFactory } from './types';
 import type { AgentMessage, ToolCallAction } from '../agent/types';
 import { getTextContent } from '../agent/types';
@@ -8,11 +9,13 @@ import type { ToolProvider, ToolResult } from '../interfaces/tool-provider';
 import type { HookRunner } from '../hooks/hook-runner';
 import type { PermissionManager } from '../permissions/permission-manager';
 import type { HarnessTelemetry } from '../observability/otel';
-import type { Activity, Process, ProcessEvent, ProcessRequest, ProcessResult, ArcLoopConfig } from './types';
+import type { Activity, Process, ProcessEvent, ProcessRequest, ProcessResult, ArcLoopConfig, ToolChoiceConfig } from './types';
+import { resolveToolChoice } from './types';
+import type { ResultPager } from './result-pager';
 import type { Episode, EpisodeStore, ModelTier } from './arc-types';
 import type { ResiliencePolicy, ExecutionContext } from './resilience/types';
 import { resolveModel, DEFAULT_MODEL_MAP } from './arc-types';
-import { toModelMessages } from './message-convert';
+import { toModelMessages, estimateTokens } from './message-convert';
 import { EpisodeCompressor } from './episode-compressor';
 import { pickDefined, normalizeTools } from './utils';
 
@@ -74,12 +77,21 @@ export async function firstEvent<T extends { type: string }>(
   throw new Error(`Stream ended without '${type}' event`);
 }
 
+// ── Constants ──
+
+/** Default character threshold above which tool results are paged externally. */
+export const DEFAULT_PAGE_THRESHOLD = 4_000;
+
+/** Hard cap on ReadFullResult output — never re-paged, prevents infinite recursion. */
+export const READ_FULL_RESULT_HARD_CAP = 32_000;
+
 // ── Process system prompt ──
 
 const PROCESS_SYSTEM_PROMPT = [
   'You are a focused execution thread within a larger agent system.',
   'Complete the assigned task using the available tools.',
   'Be efficient — accomplish the objective with minimal steps.',
+  'If your context includes the user\'s original message or attachment metadata, use that information directly.',
   'When done, provide a brief summary of what you accomplished.',
 ].join(' ');
 
@@ -212,6 +224,23 @@ export interface AgentRunnerConfig {
 
   /** Optional resilience policy applied to generateText calls. */
   resilience?: ResiliencePolicy;
+
+  /** Tool choice for LLM calls. Supports per-turn callbacks. Default: 'auto'. */
+  toolChoice?: ToolChoiceConfig;
+
+  /** ResultPager for storing large tool results externally. When set, enables context paging. */
+  resultPager?: ResultPager;
+  /** Character threshold above which tool results are paged. Default: 4000. */
+  resultPageThreshold?: number;
+  /** Tool names to never page (e.g., ['Read', 'Edit'] — filesystem tools return needed content). */
+  pagingExclude?: string[];
+  /** Hard cap on tool result length (chars) when no resultPager is configured. Truncates with a note. No default (unlimited). */
+  maxToolResultLength?: number;
+
+  /** Structured facts injected into the system prompt (e.g., from long-term memory). */
+  contextFacts?: string[];
+  /** Max context tokens before old messages are trimmed. When set, stubs old tool results to keep within budget. */
+  maxContextTokens?: number;
 }
 
 export interface AgentRunResult {
@@ -220,8 +249,6 @@ export interface AgentRunResult {
   steps: number;
   /** Structured output from generateObject when outputSchema is set. */
   structuredOutput?: Record<string, unknown>;
-  /** Token usage accumulated across all steps in this thread. */
-  usage?: { inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number };
 }
 
 export class AgentRunner {
@@ -231,9 +258,36 @@ export class AgentRunner {
       { role: 'user', content: config.prompt },
     ];
 
-    // AI SDK v6 `system` expects string or Array<{ type: 'text', text }>, not [{ role, content }]
-    const cachedSystem = config.systemPrompt;
-    const threadUsage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+    // Build system prompt with optional structured facts
+    const systemContent = config.contextFacts?.length
+      ? config.systemPrompt + '\n\n## Known Facts\n' + config.contextFacts.map(f => `- ${f}`).join('\n')
+      : config.systemPrompt;
+
+    const cachedSystem = [{
+      role: 'system' as const,
+      content: systemContent,
+    }];
+
+    // Pre-compute paging config (avoid per-iteration allocation)
+    const pageThreshold = config.resultPageThreshold ?? DEFAULT_PAGE_THRESHOLD;
+    const pagingExcludeSet = new Set(config.pagingExclude ?? []);
+
+    // Augment tools with ReadFullResult when paging is enabled
+    const effectiveTools = config.resultPager
+      ? {
+          ...config.tools,
+          ReadFullResult: aiTool({
+            description: 'Retrieve the full content of a paged tool result. Use when the summary is insufficient and you need the complete data.',
+            parameters: z.object({
+              ref: z.string().describe('The paged result reference from a previous tool output'),
+              lineRange: z.object({
+                start: z.number().int().min(1).describe('Start line (1-indexed, inclusive)'),
+                end: z.number().int().min(1).describe('End line (1-indexed, inclusive)'),
+              }).optional().describe('Optional line range to retrieve. Omit for full content.'),
+            }),
+          }),
+        }
+      : config.tools;
 
     for (let step = 0; step < config.maxSteps; step++) {
       config.signal.throwIfAborted();
@@ -244,12 +298,17 @@ export class AgentRunner {
         }
       }
 
+      // Context trimming: stub old tool results when context exceeds budget
+      if (config.maxContextTokens && step > 0) {
+        trimContext(messages, config.maxContextTokens);
+      }
+
       const callLLM = async (effectiveSignal: AbortSignal) =>
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (generateText as any)({
           model: (config.createModel ?? defaultAnthropicProvider)(config.model),
-          tools: normalizeTools(config.tools),
-          toolChoice: 'auto',
+          tools: normalizeTools(effectiveTools),
+          toolChoice: resolveToolChoice(config.toolChoice, step),
           messages: toModelMessages(messages),
           system: cachedSystem,
           abortSignal: effectiveSignal,
@@ -272,25 +331,40 @@ export class AgentRunner {
         result = await callLLM(config.signal);
       }
 
-      // Extract token usage from generateText result
-      try {
-        const usage = result.usage;
-        if (usage) {
-          threadUsage.inputTokens += usage.inputTokens ?? 0;
-          threadUsage.outputTokens += usage.outputTokens ?? 0;
-          const details = usage.inputTokenDetails ?? usage;
-          threadUsage.cacheReadTokens += details.cacheReadTokens ?? 0;
-          threadUsage.cacheWriteTokens += details.cacheWriteTokens ?? 0;
-        }
-      } catch { /* best-effort */ }
-
       const toolCalls: Array<{ toolName: string; input: Record<string, unknown>; toolCallId?: string }> =
         result.toolCalls ?? [];
 
       if (toolCalls.length === 0) {
-        const text = result.text?.trim() ?? 'Done.';
+        const rawText = result.text?.trim() ?? '';
+        // Detect empty response (potential billing/auth error — model returned nothing)
+        if (!rawText && step === 0) {
+          const text = 'ERROR: LLM returned empty response with no tool calls on first step. This may indicate an API billing issue, authentication error, or rate limit.';
+          messages.push({ role: 'assistant', content: text });
+          return { messages, output: text, steps: step + 1 };
+        }
+        const text = rawText || 'Done.';
         messages.push({ role: 'assistant', content: text });
 
+        // RunComplete hook: allow middleware to inspect and optionally continue
+        if (config.hookRunner) {
+          const decision = await config.hookRunner.run({
+            event: 'RunComplete',
+            metadata: {
+              messages,
+              steps: step + 1,
+              output: text,
+            },
+          });
+          if (!decision.allow) {
+            // Hook wants the agent to keep going — inject reason as user guidance
+            messages.push({
+              role: 'user',
+              content: decision.reason ?? 'Continue — a required post-completion step was not performed.',
+            });
+            continue; // re-enter the loop for one more LLM step
+          }
+        }
+
         // Structured output: use generateObject on terminal step when schema is set
         if (config.outputSchema) {
           try {
@@ -308,25 +382,39 @@ export class AgentRunner {
               system: config.systemPrompt,
               abortSignal: config.signal,
             });
-            return { messages, output: text, steps: step + 1, structuredOutput: structured.object, usage: threadUsage };
+            return { messages, output: text, steps: step + 1, structuredOutput: structured.object };
           } catch (err) {
             console.warn('[agent-runner] generateObject failed, falling back to text:', err instanceof Error ? err.message : err);
           }
         }
 
-        return { messages, output: text, steps: step + 1, usage: threadUsage };
+        return { messages, output: text, steps: step + 1 };
       }
 
-      const toolCallInfos = toolCalls.map(tc => ({
-        toolCallId: tc.toolCallId ?? randomUUID(),
-        toolName: tc.toolName,
-        args: (tc as { input?: Record<string, unknown> }).input ?? {},
-      }));
+      const toolCallInfos = toolCalls.map(tc => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const raw = tc as any;
+        const info: import('../agent/types').ToolCallInfo = {
+          toolCallId: raw.toolCallId ?? randomUUID(),
+          toolName: raw.toolName,
+          args: raw.input ?? {},
+        };
+        // Preserve provider-specific metadata (e.g., Gemini thought signatures)
+        if (raw.providerMetadata || raw.experimental_providerMetadata) {
+          info.providerMetadata = raw.providerMetadata ?? raw.experimental_providerMetadata;
+        }
+        return info;
+      });
+
+      // Preserve response-level provider metadata (e.g., Gemini thought signatures)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const responseMetadata = (result as any).providerMetadata ?? (result as any).experimental_providerMetadata;
 
       messages.push({
         role: 'assistant',
         content: toolCalls.map(tc => `${tc.toolName}(${JSON.stringify((tc as { input?: Record<string, unknown> }).input ?? {}).slice(0, 100)})`).join(', '),
         toolCalls: toolCallInfos,
+        ...(responseMetadata ? { providerMetadata: responseMetadata } : {}),
       });
 
       for (const tc of toolCallInfos) {
@@ -337,6 +425,44 @@ export class AgentRunner {
           toolCallId: tc.toolCallId,
         };
 
+        // ReadFullResult: retrieve paged tool result content
+        if (tc.toolName === 'ReadFullResult' && config.resultPager) {
+          const ref = String(tc.args.ref ?? '');
+          const content = await config.resultPager.retrieve(ref);
+          if (!content) {
+            const errorText = 'ERROR: Content expired or not found. Use the summary above.';
+            messages.push({
+              role: 'tool',
+              content: errorText,
+              toolResults: [{ toolCallId: tc.toolCallId, toolName: tc.toolName, result: errorText, isError: true }],
+            });
+            continue;
+          }
+          let output = content;
+          const lr = tc.args.lineRange;
+          if (lr && typeof lr === 'object' && 'start' in lr && 'end' in lr) {
+            const start = Number(lr.start);
+            const end = Number(lr.end);
+            if (Number.isFinite(start) && Number.isFinite(end) && start >= 1 && end >= start) {
+              const lines = content.split('\n');
+              output = lines.slice(start - 1, end).join('\n');
+            }
+          }
+          // Hard cap — ReadFullResult is NEVER re-paged (prevents infinite recursion)
+          if (output.length > READ_FULL_RESULT_HARD_CAP) {
+            output = output.slice(0, READ_FULL_RESULT_HARD_CAP)
+              + `\n\n[Showing first ${READ_FULL_RESULT_HARD_CAP} of ${output.length} chars. Use lineRange for specific sections.]`;
+          }
+          config.onActivity?.({ type: 'tool_start', name: tc.toolName, args: tc.args, ts: Date.now() });
+          config.onActivity?.({ type: 'tool_end', name: tc.toolName, ok: true, ms: 0, preview: output.slice(0, 200), ts: Date.now() });
+          messages.push({
+            role: 'tool',
+            content: output,
+            toolResults: [{ toolCallId: tc.toolCallId, toolName: tc.toolName, result: output, isError: false }],
+          });
+          continue;
+        }
+
         // Layer 2: executor-level tool validation (defense-in-depth)
         if (config.allowedToolNames && !config.allowedToolNames.includes(tc.toolName)) {
           const resultText = `ERROR: Tool "${tc.toolName}" is not available in this profile.`;
@@ -372,10 +498,12 @@ export class AgentRunner {
             ...(config.downloadRawFile != null ? { downloadRawFile: config.downloadRawFile } : {}),
           });
         } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
           toolResult = {
             success: false,
             output: '',
-            error: error instanceof Error ? error.message : String(error),
+            // Truncate error messages to prevent leaking long stack traces into context
+            error: errorMsg.length > 500 ? errorMsg.slice(0, 500) + '...' : errorMsg,
           };
         }
         const durationMs = Date.now() - start;
@@ -389,10 +517,42 @@ export class AgentRunner {
           ts: Date.now(),
         });
 
-        const resultText = toolResult.success
+        let resultText = toolResult.success
           ? toolResult.output
           : `ERROR: ${toolResult.error ?? 'unknown failure'}`;
 
+        // Context paging: store large results externally, keep summary in context
+        if (
+          config.resultPager &&
+          toolResult.success &&
+          resultText.length > pageThreshold &&
+          !pagingExcludeSet.has(tc.toolName) &&
+          tc.toolName !== 'ReadFullResult' // Never re-page ReadFullResult output
+        ) {
+          try {
+            const paged = await config.resultPager.page(resultText, {
+              toolName: tc.toolName,
+              toolCallId: tc.toolCallId,
+            });
+            resultText = [
+              paged.summary,
+              '',
+              `[Full result: ${paged.originalLength} chars — call ReadFullResult("${paged.ref}") to retrieve]`,
+            ].join('\n');
+          } catch {
+            // Storage failed — fall back to prefix truncation
+            resultText = resultText.slice(0, pageThreshold)
+              + `\n\n[Truncated — ${resultText.length} chars total. Storage unavailable.]`;
+          }
+        }
+
+        // Fallback hard cap when no pager is configured
+        if (config.maxToolResultLength && resultText.length > config.maxToolResultLength) {
+          const originalLength = resultText.length;
+          resultText = resultText.slice(0, config.maxToolResultLength)
+            + `\n\n[Truncated — ${originalLength} chars total, showing first ${config.maxToolResultLength}.]`;
+        }
+
         messages.push({
           role: 'tool',
           content: resultText,
@@ -406,7 +566,51 @@ export class AgentRunner {
       }
     }
 
-    return { messages, output: 'max steps reached', steps: config.maxSteps, usage: threadUsage };
+    // RunComplete hook at maxSteps boundary (e.g., enforce DownloadRawFile even if loop exhausted)
+    if (config.hookRunner) {
+      const decision = await config.hookRunner.run({
+        event: 'RunComplete',
+        metadata: { messages, steps: config.maxSteps, output: 'max steps reached' },
+      });
+      if (!decision.allow) {
+        messages.push({ role: 'user', content: decision.reason ?? 'Continue — a required post-completion step was not performed.' });
+        // One extra step to satisfy the hook
+        const extra = await (generateText as any)({
+          model: (config.createModel ?? defaultAnthropicProvider)(config.model),
+          tools: normalizeTools(effectiveTools),
+          messages: toModelMessages(messages),
+          system: cachedSystem,
+          abortSignal: config.signal,
+        });
+        const extraCalls: Array<{ toolName: string; input: Record<string, unknown>; toolCallId?: string }> =
+          extra.toolCalls ?? [];
+        if (extraCalls.length > 0) {
+          const tc = extraCalls[0]!;
+          const info: ToolCallInfo = {
+            toolCallId: (tc as any).toolCallId ?? randomUUID(),
+            toolName: tc.toolName,
+            args: tc.input ?? {},
+          };
+          messages.push({ role: 'assistant', content: '', toolCalls: [info] });
+          const toolResult = await executeTool(
+            { name: tc.toolName, args: tc.input ?? {} },
+            config.toolProvider,
+            {
+              ...(config.executeToolAction != null ? { executeToolAction: config.executeToolAction } : {}),
+              ...(config.hookRunner != null ? { hookRunner: config.hookRunner } : {}),
+              ...(config.downloadRawFile != null ? { downloadRawFile: config.downloadRawFile } : {}),
+            },
+          );
+          messages.push({
+            role: 'tool',
+            content: toolResult.output,
+            toolResults: [{ toolCallId: info.toolCallId, toolName: tc.toolName, result: toolResult.output, isError: !toolResult.success }],
+          });
+        }
+      }
+    }
+
+    return { messages, output: 'max steps reached', steps: config.maxSteps };
   }
 }
 
@@ -428,7 +632,10 @@ export interface CreateProcessConfig {
   /** Custom system prompt for this process (overrides PROCESS_SYSTEM_PROMPT). */
   processSystemPrompt?: string;
   /** Async skill instructions to prepend to system prompt (resolved during process startup). */
+  /** Async skill instructions to prepend to system prompt (resolved during process startup). */
   skillPromptPromise?: Promise<string | null>;
+  /** Skill reference with optional pre-loaded content and sub-guides. */
+  skillRefPromise?: Promise<{ name: string; path: string; content?: string; subGuides?: Record<string, string> } | null>;
   /** Allowed tool names for executor-level validation (defense-in-depth against hallucinated tool calls). */
   allowedToolNames?: string[];
   /** Zod schema for structured output on the terminal step. */
@@ -436,6 +643,23 @@ export interface CreateProcessConfig {
   outputSchema?: import('zod').ZodObject<any>;
   /** Few-shot demo messages prepended before context episodes. */
   demoMessages?: AgentMessage[];
+  /** Seed context messages injected into every process (user message, attachments, etc.). */
+  processSeedContext?: string | AgentMessage[];
+
+  /** Tool choice for process LLM calls. Default: 'auto'. */
+  toolChoice?: ToolChoiceConfig;
+  /** ResultPager for context paging. */
+  resultPager?: ResultPager;
+  /** Character threshold for paging. Default: 4000. */
+  resultPageThreshold?: number;
+  /** Tool names to never page. */
+  pagingExclude?: string[];
+  /** Hard cap on tool result length when no pager is configured. */
+  maxToolResultLength?: number;
+  /** Structured facts injected into the process system prompt. */
+  contextFacts?: string[];
+  /** Max context tokens for worker thread trimming. */
+  maxContextTokens?: number;
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -492,14 +716,38 @@ export function createProcess(
       const seed = [
         ...(config.demoMessages ?? []),
         ...(await seedPromise),
+        ...normalizeSeedContext(config.processSeedContext),
       ];
 
       // Build system prompt: base + optional skill instructions
       let systemPrompt = config.processSystemPrompt ?? PROCESS_SYSTEM_PROMPT;
-      if (config.skillPromptPromise) {
+
+      // Inject skill + pre-read sub-guides directly into system prompt
+      const skillRef = config.skillRefPromise ? await config.skillRefPromise : null;
+      if (skillRef) {
+        // Build sub-guide content blocks
+        const subGuideBlocks = skillRef.subGuides
+          ? Object.entries(skillRef.subGuides)
+              .map(([file, content]) => `\n### Sub-guide: ${file}\n\n${content}`)
+              .join('\n')
+          : '';
+
+        systemPrompt += `\n\n<skill_system>
+**Skill: ${skillRef.name}**
+
+Follow these skill instructions precisely. Do NOT use alternative tools or libraries.
+
+${skillRef.content ?? ''}
+${subGuideBlocks}
+</skill_system>`;
+      } else if (config.skillPromptPromise) {
+        // Legacy: full content injection (fallback)
         const skillInstructions = await config.skillPromptPromise;
         if (skillInstructions) {
-          systemPrompt += '\n\n## Skill Instructions\n' + skillInstructions;
+          systemPrompt += '\n\n<skill_instructions>\n'
+            + 'IMPORTANT: Follow the skill instructions below precisely. They contain tested, working patterns.\n\n'
+            + skillInstructions
+            + '\n</skill_instructions>';
         }
       }
 
@@ -528,6 +776,13 @@ export function createProcess(
             'downloadRawFile',
             'allowedToolNames',
             'outputSchema',
+            'toolChoice',
+            'resultPager',
+            'resultPageThreshold',
+            'pagingExclude',
+            'maxToolResultLength',
+            'contextFacts',
+            'maxContextTokens',
           ]),
         }),
         timeoutPromise(config.processTimeout),
@@ -564,7 +819,6 @@ export function createProcess(
         success: true,
         durationMs,
         resolvedModel: model,
-        usage: result.usage,
       };
 
       process.result = processResult;
@@ -633,6 +887,41 @@ export function createProcess(
   return process;
 }
 
+// ── Context trimming for worker threads ──
+
+const STUB_THRESHOLD = 500;
+
+/**
+ * Trim conversation context by stubbing large tool results in older messages.
+ * Preserves the most recent messages (hot zone) and stubs outputs in the cold zone.
+ */
+function trimContext(messages: AgentMessage[], maxTokens: number): void {
+  // Estimate current size using the same estimator as ContextWindow
+  let totalTokens = 0;
+  for (const m of messages) {
+    const text = typeof m.content === 'string' ? m.content : '';
+    totalTokens += estimateTokens(text);
+  }
+  if (totalTokens <= maxTokens) return;
+
+  // Preserve last 60% of messages as hot zone
+  const hotBoundary = Math.floor(messages.length * 0.6);
+
+  for (let i = 0; i < hotBoundary; i++) {
+    const m = messages[i]!;
+    if (m.role === 'tool' && typeof m.content === 'string' && m.content.length > STUB_THRESHOLD) {
+      const toolName = m.toolResults?.[0]?.toolName ?? 'tool';
+      const stubbed = `[${toolName}: output stubbed, ${m.content.length} chars]`;
+      m.content = stubbed;
+      if (m.toolResults) {
+        for (const tr of m.toolResults) {
+          tr.result = stubbed;
+        }
+      }
+    }
+  }
+}
+
 // ── Helpers ──
 
 async function getNextEpisodeIndex(store: EpisodeStore, taskId: string): Promise<number> {
@@ -678,6 +967,14 @@ async function buildSeedMessages(
   return messages;
 }
 
+function normalizeSeedContext(ctx: string | AgentMessage[] | undefined): AgentMessage[] {
+  if (!ctx) return [];
+  if (typeof ctx === 'string') {
+    return [{ role: 'system', content: ctx }];
+  }
+  return ctx;
+}
+
 function timeoutPromise(ms: number): Promise<never> {
   return new Promise((_, reject) =>
     setTimeout(() => reject(new Error(`Process timed out after ${ms}ms`)), ms)