@bluecopa/harness 0.1.0-snapshot.34 → 0.1.0-snapshot.35

package/package.json

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

package/src/arc/agent-runner.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { generateText } from 'ai';
+import { generateText, generateObject } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import type { AgentMessage, ToolCallAction } from '../agent/types';
 import { getTextContent } from '../agent/types';
@@ -195,6 +195,9 @@ export interface AgentRunnerConfig {
   onActivity?: (activity: Activity) => void;
   /** Allowed tool names for executor-level validation (defense-in-depth). */
   allowedToolNames?: string[];
+  /** Zod schema for structured output. When set, the terminal step uses generateObject instead of generateText. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSchema?: import('zod').ZodObject<any>;
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -213,6 +216,8 @@ export interface AgentRunResult {
   messages: AgentMessage[];
   output: string;
   steps: number;
+  /** Structured output from generateObject when outputSchema is set. */
+  structuredOutput?: Record<string, unknown>;
 }
 
 export class AgentRunner {
@@ -272,6 +277,24 @@ export class AgentRunner {
       if (toolCalls.length === 0) {
         const text = result.text?.trim() ?? 'Done.';
         messages.push({ role: 'assistant', content: text });
+
+        // Structured output: use generateObject on terminal step when schema is set
+        if (config.outputSchema) {
+          try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const structured = await (generateObject as any)({
+              model: anthropic(config.model),
+              schema: config.outputSchema,
+              messages: toModelMessages(messages),
+              system: [{ role: 'system' as const, content: config.systemPrompt }],
+              abortSignal: config.signal,
+            });
+            return { messages, output: text, steps: step + 1, structuredOutput: structured.object };
+          } catch {
+            // Structured extraction failed — fall back to text output
+          }
+        }
+
         return { messages, output: text, steps: step + 1 };
       }
 
@@ -388,6 +411,11 @@ export interface CreateProcessConfig {
   skillPromptPromise?: Promise<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. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSchema?: import('zod').ZodObject<any>;
+  /** Few-shot demo messages prepended before context episodes. */
+  demoMessages?: AgentMessage[];
 
   // Runtime extras
   hookRunner?: HookRunner;
@@ -441,7 +469,10 @@ export function createProcess(
   void (async () => {
     try {
       process.status = 'running';
-      const seed = await seedPromise;
+      const seed = [
+        ...(config.demoMessages ?? []),
+        ...(await seedPromise),
+      ];
 
       // Build system prompt: base + optional skill instructions
       let systemPrompt = config.processSystemPrompt ?? PROCESS_SYSTEM_PROMPT;
@@ -475,6 +506,7 @@ export function createProcess(
             'tellUser',
             'downloadRawFile',
             'allowedToolNames',
+            'outputSchema',
           ]),
         }),
         timeoutPromise(config.processTimeout),
@@ -496,6 +528,11 @@ export function createProcess(
 
       const { episode, trace, artifacts } = compressor.compress(compressInput);
 
+      // Attach structured output from generateObject if present
+      if (result.structuredOutput) {
+        episode.structuredOutput = result.structuredOutput;
+      }
+
       await config.episodeStore.addEpisode(episode);
       await config.episodeStore.addTrace(trace);
 

package/src/arc/arc-loop.ts

@@ -578,6 +578,8 @@ export class ArcLoop {
       processTools: (profile?.tools ?? globalTools) as any,
       processSystemPrompt: profile?.systemPrompt ?? this.config.processSystemPrompt,
       allowedToolNames: profile?.allowedToolNames,
+      outputSchema: profile?.outputSchema,
+      demoMessages: profile?.demoMessages,
       skillPromptPromise,
       parentSignal,
       ...pickDefined(this.config, [

package/src/arc/arc-types.ts

@@ -18,6 +18,8 @@ export interface Episode {
   success: boolean;
   createdAt: number;
   parentEpisodeIds: string[];
+  /** Typed output from generateObject when profile has a typed signature. */
+  structuredOutput?: Record<string, unknown>;
 }
 
 export interface EpisodeTrace {

package/src/arc/profile-builder.ts

@@ -8,6 +8,7 @@
 import type { AnyTool } from './arc-types';
 import type { ProfileDeclaration, ProcessProfile, ProfileConfig } from './types';
 import { isProfileDeclaration } from './types';
+import { parseSignature, signatureToSchema, isTypedSignature } from './sig';
 
 // ── Thread prompt generation ────────────────────────────────────
 
@@ -120,6 +121,20 @@ export function buildProcessProfile(
   };
   if (decl.model) profile.model = decl.model;
   if (decl.maxSteps) profile.maxSteps = decl.maxSteps;
+  // Generate output schema from typed signatures (e.g., 'question:string -> evidence:string[]')
+  if (isTypedSignature(decl.signature)) {
+    const parsed = parseSignature(decl.signature);
+    if (parsed.outputs.length > 0) {
+      profile.outputSchema = signatureToSchema(parsed);
+    }
+  }
+  // Render demos as user/assistant message pairs
+  if (decl.demos && decl.demos.length > 0) {
+    profile.demoMessages = decl.demos.flatMap(demo => [
+      { role: 'user' as const, content: Object.entries(demo.input).map(([k, v]) => `${k}: ${v}`).join('\n') },
+      { role: 'assistant' as const, content: JSON.stringify(demo.output) },
+    ]);
+  }
   return profile;
 }
 

package/src/arc/sig.ts

@@ -0,0 +1,120 @@
+/**
+ * DSPy-style signature parsing and schema generation.
+ *
+ * Parses signature strings like "question:string -> evidence:string[], confidence:number"
+ * into typed field definitions, and generates Zod schemas for structured output.
+ */
+
+import { z } from 'zod';
+
+// ── Types ──
+
+export interface SignatureField {
+  name: string;
+  type: 'string' | 'number' | 'boolean';
+  isArray: boolean;
+  isOptional: boolean;
+  description?: string;
+}
+
+export interface ParsedSignature {
+  inputs: SignatureField[];
+  outputs: SignatureField[];
+}
+
+// ── Parser ──
+
+const FIELD_RE = /^(\w+)(?::(\w+)(\[\])?)(\?)?(?:\s*\(([^)]+)\))?$/;
+
+function parseField(raw: string): SignatureField {
+  const trimmed = raw.trim();
+  const match = trimmed.match(FIELD_RE);
+
+  if (!match) {
+    // Bare field name — default to string
+    const name = trimmed.replace(/\?$/, '');
+    return {
+      name,
+      type: 'string',
+      isArray: false,
+      isOptional: trimmed.endsWith('?'),
+    };
+  }
+
+  const [, name, typeStr, arrayMark, optionalMark, desc] = match;
+  const type = (['string', 'number', 'boolean'].includes(typeStr!) ? typeStr : 'string') as SignatureField['type'];
+
+  const field: SignatureField = {
+    name: name!,
+    type,
+    isArray: arrayMark === '[]',
+    isOptional: optionalMark === '?',
+  };
+  if (desc) field.description = desc.trim();
+  return field;
+}
+
+/**
+ * Parse a signature string into typed input/output fields.
+ *
+ * @example
+ *   parseSignature('question:string -> evidence:string[], confidence:number')
+ *   // { inputs: [{ name: 'question', type: 'string', ... }],
+ *   //   outputs: [{ name: 'evidence', type: 'string', isArray: true, ... },
+ *   //             { name: 'confidence', type: 'number', ... }] }
+ *
+ *   parseSignature('query -> findings')
+ *   // All fields default to type 'string', isArray false
+ */
+export function parseSignature(sig: string): ParsedSignature {
+  const arrowIdx = sig.indexOf('->');
+  if (arrowIdx < 0) {
+    // No arrow — treat entire string as a single input, single output
+    const parts = sig.split(',').map(s => s.trim()).filter(Boolean);
+    return {
+      inputs: parts.length > 0 ? [parseField(parts[0]!)] : [],
+      outputs: parts.length > 1 ? [parseField(parts[1]!)] : [{ name: 'result', type: 'string', isArray: false, isOptional: false }],
+    };
+  }
+
+  const inputStr = sig.slice(0, arrowIdx).trim();
+  const outputStr = sig.slice(arrowIdx + 2).trim();
+
+  const inputs = inputStr.split(',').map(s => s.trim()).filter(Boolean).map(parseField);
+  const outputs = outputStr.split(',').map(s => s.trim()).filter(Boolean).map(parseField);
+
+  return { inputs, outputs };
+}
+
+// ── Schema generation ──
+
+/**
+ * Convert a parsed signature's output fields into a Zod schema.
+ * Used with ai-sdk's generateObject() for structured output extraction.
+ */
+export function signatureToSchema(sig: ParsedSignature): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const field of sig.outputs) {
+    let base: z.ZodTypeAny;
+    switch (field.type) {
+      case 'number': base = z.number(); break;
+      case 'boolean': base = z.boolean(); break;
+      default: base = z.string(); break;
+    }
+    if (field.isArray) base = z.array(base);
+    if (field.description) base = base.describe(field.description);
+    if (field.isOptional) base = base.optional();
+    shape[field.name] = base;
+  }
+
+  return z.object(shape);
+}
+
+/**
+ * Check if a signature string has typed fields (contains ':').
+ * Untyped signatures like 'query -> findings' are treated as cosmetic labels.
+ */
+export function isTypedSignature(sig: string): boolean {
+  return sig.includes(':');
+}

package/src/arc/stores/rxdb-setup.ts

@@ -22,6 +22,7 @@ const episodeSchema: RxJsonSchema<Episode> = {
     success: { type: 'boolean' },
     createdAt: { type: 'integer' },
     parentEpisodeIds: { type: 'array', items: { type: 'string' } },
+    structuredOutput: { type: 'object' },
   },
   required: ['id', 'taskId', 'sessionId', 'index', 'threadAction', 'summary', 'model', 'steps', 'success', 'createdAt'],
   indexes: ['taskId', 'sessionId', 'createdAt'],

package/src/arc/types.ts

@@ -187,6 +187,11 @@ export interface ProfileDeclaration {
   maxSteps?: number;
   /** Skill names this profile can use. SkillRouter is constrained to this set. Omit for all skills. */
   skills?: string[];
+  /** Few-shot demonstration examples. Rendered as user/assistant message pairs in the prompt. */
+  demos?: Array<{
+    input: Record<string, string>;
+    output: Record<string, unknown>;
+  }>;
 }
 
 /** A named process profile — runtime form with resolved prompt and tools. */
@@ -201,6 +206,11 @@ export interface ProcessProfile {
   maxSteps?: number;
   /** Allowed tool names for executor-level validation (populated from ProfileDeclaration.tools). */
   allowedToolNames?: string[];
+  /** Zod schema for structured output on the terminal step (generated from typed signatures). */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSchema?: import('zod').ZodObject<any>;
+  /** Few-shot demo messages rendered before the task prompt. */
+  demoMessages?: import('../agent/types').AgentMessage[];
 }
 
 /** A profile config can be either a declaration (new) or a raw ProcessProfile (backward compat). */