@bluecopa/harness 0.1.0-snapshot.55 → 0.1.0-snapshot.56

package/package.json

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

package/src/agent/create-agent.ts

@@ -7,12 +7,14 @@ import type { HarnessTelemetry } from '../observability/otel';
 import { HookRunner } from '../hooks/hook-runner';
 import { PermissionManager } from '../permissions/permission-manager';
 import { VercelAgentLoop } from '../loop/vercel-agent-loop';
+export type { SystemPromptBlock, VercelAgentLoopConfig } from '../loop/vercel-agent-loop';
+export type { PrepareStepContext, PrepareStepResult } from './types';
 import { SkillManager } from '../skills/skill-manager';
 import { SkillRouter } from '../skills/skill-router';
 import type { SkillSummary } from '../skills/skill-types';
 import { SingleFlightStepExecutor } from './step-executor';
-import type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo } from './types';
-export type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo };
+import type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, StepUsage, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo } from './types';
+export type { AgentAction, AgentLoop, AgentMessage, AgentRunResult, AgentStreamEvent, StepUsage, ToolCallAction, ToolBatchAction, ToolCallInfo, ToolResultInfo };
 export { HookRunner } from '../hooks/hook-runner';
 export { PermissionManager } from '../permissions/permission-manager';
 export type { PermissionMode, PermissionResolver, PermissionRequest } from '../permissions/permission-manager';
@@ -220,9 +222,21 @@ function toStreamResult(r: ToolResult): { success: boolean; output: string; erro
   return base;
 }
 
-/** Format a display-friendly content string for tool results (used in content field). */
+/** Build the text the LLM sees for a tool result.
+ *  Success: prefer modelOutput (compact) over raw output.
+ *  Failure: prefer modelOutput (structured fix guidance) → error → output → generic fallback.
+ *  This ensures custom tools can feed actionable error feedback to the model via modelOutput
+ *  so the agent can self-correct instead of stopping with "unknown failure". */
+function resultTextForLLM(result: ToolResult): string {
+  if (result.success) return result.modelOutput ?? result.output;
+  return result.modelOutput ?? result.error ?? result.output ?? 'unknown failure';
+}
+
+/** Format content string for LLM context. Uses modelOutput (compact summary) when available. */
 function formatToolResultContent(call: ToolCallAction, result: ToolResult): string {
-  const content = result.success ? result.output : `ERROR: ${result.error ?? 'unknown failure'}`;
+  const content = result.success
+    ? resultTextForLLM(result)
+    : `ERROR: ${resultTextForLLM(result)}`;
   switch (call.name) {
     case 'Write':
       return `Write(${call.args.path}): ${result.success ? 'ok' : content}`;
@@ -517,6 +531,11 @@ export function createAgent(runtime: AgentRuntime) {
       ? { nextAction: runtime.nextAction }
       : new VercelAgentLoop());
 
+  /** Read lastUsage from the loop if it's a VercelAgentLoop. */
+  function getLoopUsage(): StepUsage | undefined {
+    return loop instanceof VercelAgentLoop ? loop.lastUsage : undefined;
+  }
+
   async function resolveSkillContext(prompt: string): Promise<string> {
     if (!skillManager || !skillIndexPath) return '';
 
@@ -609,7 +628,7 @@ export function createAgent(runtime: AgentRuntime) {
                 if (!r.success) {
                   recordAgentError(runtime.telemetry);
                 }
-                const resultText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+                const resultText = r.success ? resultTextForLLM(r) : `ERROR: ${resultTextForLLM(r)}`;
                 messages.push({
                   role: 'tool',
                   content: formatToolResultContent(call, r),
@@ -684,7 +703,7 @@ export function createAgent(runtime: AgentRuntime) {
           if (!result.success) {
             recordAgentError(runtime.telemetry);
           }
-          const singleResultText = result.success ? result.output : `ERROR: ${result.error ?? 'unknown failure'}`;
+          const singleResultText = result.success ? resultTextForLLM(result) : `ERROR: ${resultTextForLLM(result)}`;
           messages.push({
             role: 'tool',
             content: formatToolResultContent(action, result),
@@ -746,7 +765,7 @@ export function createAgent(runtime: AgentRuntime) {
           // If no tools → final response
           if (pendingTools.length === 0) {
             messages.push({ role: 'assistant', content: finalText });
-            yield { type: 'step_end', step };
+            { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
             yield { type: 'done', output: finalText, steps: step };
             return;
           }
@@ -772,7 +791,7 @@ export function createAgent(runtime: AgentRuntime) {
             if (action.type === 'final') {
               yield { type: 'text_delta', text: action.content };
               messages.push({ role: 'assistant', content: action.content });
-              yield { type: 'step_end', step };
+              { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
               yield { type: 'done', output: action.content, steps: step };
               return;
             }
@@ -784,7 +803,7 @@ export function createAgent(runtime: AgentRuntime) {
                 try {
                   const r = await executeTool(runtime.toolProvider, call, runtime);
                   yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-                  const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+                  const rText = r.success ? resultTextForLLM(r) : `ERROR: ${resultTextForLLM(r)}`;
                   messages.push({
                     role: 'tool',
                     content: formatToolResultContent(call, r),
@@ -806,7 +825,7 @@ export function createAgent(runtime: AgentRuntime) {
               try {
                 const r = await executeTool(runtime.toolProvider, action, runtime);
                 yield { type: 'tool_end', name: action.name, result: toStreamResult(r) };
-                const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+                const rText = r.success ? resultTextForLLM(r) : `ERROR: ${resultTextForLLM(r)}`;
                 messages.push({
                   role: 'tool',
                   content: formatToolResultContent(action, r),
@@ -822,7 +841,7 @@ export function createAgent(runtime: AgentRuntime) {
                 });
               }
             }
-            yield { type: 'step_end', step };
+            { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
             continue;
           }
 
@@ -832,7 +851,7 @@ export function createAgent(runtime: AgentRuntime) {
             const call = pendingTools[i]!;
             const r = results[i]!;
             yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-            const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+            const rText = r.success ? resultTextForLLM(r) : `ERROR: ${resultTextForLLM(r)}`;
             messages.push({
               role: 'tool',
               content: formatToolResultContent(call, r),
@@ -850,7 +869,7 @@ export function createAgent(runtime: AgentRuntime) {
 
           if (action.type === 'final') {
             messages.push({ role: 'assistant', content: action.content });
-            yield { type: 'step_end', step };
+            { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
             yield { type: 'done', output: action.content, steps: step };
             return;
           }
@@ -874,7 +893,7 @@ export function createAgent(runtime: AgentRuntime) {
             const call = calls[i]!;
             const r = results[i]!;
             yield { type: 'tool_end', name: call.name, result: toStreamResult(r) };
-            const rText = r.success ? r.output : `ERROR: ${r.error ?? 'unknown failure'}`;
+            const rText = r.success ? resultTextForLLM(r) : `ERROR: ${resultTextForLLM(r)}`;
             messages.push({
               role: 'tool',
               content: formatToolResultContent(call, r),
@@ -888,7 +907,7 @@ export function createAgent(runtime: AgentRuntime) {
           }
         }
 
-        yield { type: 'step_end', step };
+        { const u = getLoopUsage(); yield u ? { type: 'step_end' as const, step, usage: u } : { type: 'step_end' as const, step }; }
       }
 
       yield { type: 'done', output: 'ERROR: max steps exceeded', steps: maxSteps };

package/src/agent/types.ts

@@ -2,8 +2,6 @@ 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 {
@@ -22,8 +20,6 @@ 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[]). */
@@ -60,15 +56,36 @@ export interface AgentRunResult {
   steps: number;
 }
 
+/** Token usage breakdown for a single LLM step. */
+export interface StepUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number;
+}
+
 export type AgentStreamEvent =
   | { type: 'text_delta'; text: string }
   | { type: 'tool_start'; name: string; args: Record<string, unknown>; toolCallId?: string }
   | { type: 'tool_end'; name: string; result: { success: boolean; output: string; error?: string; [key: string]: unknown } }
   | { type: 'step_start'; step: number }
-  | { type: 'step_end'; step: number }
+  | { type: 'step_end'; step: number; usage?: StepUsage }
   | { type: 'done'; output: string; steps: number };
 
 export interface AgentLoop {
   nextAction(messages: AgentMessage[]): Promise<AgentAction>;
   streamAction?(messages: AgentMessage[]): AsyncIterable<AgentStreamEvent>;
 }
+
+/** Context passed to `prepareStep` before each LLM call. */
+export interface PrepareStepContext {
+  stepNumber: number;
+  toolCallHistory: string[];
+}
+
+/** Overrides returned by `prepareStep`. All fields optional — omit to keep defaults. */
+export interface PrepareStepResult {
+  model?: string;
+  activeTools?: string[];
+}