ocpipe 0.3.1 → 0.3.3

package/DESIGN.md

@@ -45,6 +45,20 @@ const AnalyzeCode = signature({
 - `field.nullable(field)` - Nullable wrapper
 - `field.custom(zodType, desc?)` - Custom Zod type
 
+**Type inference:**
+
+Use `InferInputs<S>` and `InferOutputs<S>` to extract TypeScript types from a signature:
+
+```typescript
+import { InferInputs, InferOutputs } from 'ocpipe'
+
+type AnalyzeInputs = InferInputs<typeof AnalyzeCode>
+// { code: string; language: 'typescript' | 'python' | 'rust' }
+
+type AnalyzeOutputs = InferOutputs<typeof AnalyzeCode>
+// { issues: { severity: 'error' | 'warning' | 'info'; message: string; line: number }[]; suggestions: string[]; score: number }
+```
+
 ### Predict
 
 `Predict` bridges a Signature and OpenCode. It handles prompt generation, response parsing, and validation.

package/GETTING_STARTED.md

@@ -355,6 +355,31 @@ field.enum(['a', 'b'] as const) // 'a' | 'b'
 field.optional(field.string()) // string | undefined
 ```
 
+### Type Inference
+
+Use `InferInputs` and `InferOutputs` to extract TypeScript types from a signature:
+
+```typescript
+import { signature, field, InferInputs, InferOutputs } from 'ocpipe'
+
+const Greet = signature({
+  doc: 'Generate a greeting.',
+  inputs: { name: field.string('Name to greet') },
+  outputs: { greeting: field.string('The greeting message') },
+})
+
+// Extract types from the signature
+type GreetInputs = InferInputs<typeof Greet> // { name: string }
+type GreetOutputs = InferOutputs<typeof Greet> // { greeting: string }
+
+// Use in functions
+function processGreeting(input: GreetInputs): void {
+  console.log(`Processing greeting for: ${input.name}`)
+}
+```
+
+This is useful for typing function parameters, return types, or when building generic utilities around signatures.
+
 ### Complex Modules
 
 For modules with multiple predictors or transformed outputs, use the base `Module` class:

package/README.md

@@ -40,6 +40,11 @@ const pipeline = new Pipeline(
 
 const result = await pipeline.run(module(Greet), { name: 'World' })
 console.log(result.data.greeting)
+
+// Extract types from signatures
+import { InferInputs, InferOutputs } from 'ocpipe'
+type GreetIn = InferInputs<typeof Greet> // { name: string }
+type GreetOut = InferOutputs<typeof Greet> // { greeting: string }
 ```
 
 OpenCode CLI is bundled — run `bun run opencode` or use your system `opencode` if installed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocpipe",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "SDK for LLM pipelines with OpenCode and Zod",
   "type": "module",
   "main": "src/index.ts",
@@ -29,20 +29,20 @@
     "bun": ">=1.0.0"
   },
   "dependencies": {
-    "opencode-ai": "latest"
+    "opencode-ai": "1.1.3"
   },
   "peerDependencies": {
-    "zod": "^4.0.0"
+    "zod": "4.3.5"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "bun-types": "^1.3.5",
     "eslint": "^9.39.2",
-    "globals": "^16.5.0",
+    "globals": "^17.0.0",
     "jiti": "^2.6.1",
     "prettier": "^3.7.4",
     "typescript": "^5.0.0",
-    "typescript-eslint": "^8.50.1",
+    "typescript-eslint": "^8.52.0",
     "vitest": "^4.0.0"
   },
   "scripts": {

package/src/.tmp/ocpipe-integration-test/mood-analysis_20251231_092022.json

@@ -0,0 +1,55 @@
+{
+  "sessionId": "20251231_092022",
+  "startedAt": "2025-12-31T09:20:22.199Z",
+  "phase": "init",
+  "steps": [
+    {
+      "stepName": "MoodAnalyzer",
+      "timestamp": "2025-12-31T09:20:25.808Z",
+      "result": {
+        "data": {
+          "mood": "happy",
+          "keywords": [
+            "happy",
+            "so",
+            "today"
+          ]
+        },
+        "stepName": "MoodAnalyzer",
+        "duration": 3608,
+        "sessionId": "ses_48c4aa762ffeP1pxFsOURK4cw2",
+        "model": {
+          "providerID": "github-copilot",
+          "modelID": "grok-code-fast-1"
+        },
+        "attempt": 1
+      }
+    },
+    {
+      "stepName": "ResponseSuggester",
+      "timestamp": "2025-12-31T09:20:30.186Z",
+      "result": {
+        "data": {
+          "suggestion": "That's wonderful! What's making you so happy today?"
+        },
+        "stepName": "ResponseSuggester",
+        "duration": 4377,
+        "sessionId": "ses_48c4aa762ffeP1pxFsOURK4cw2",
+        "model": {
+          "providerID": "github-copilot",
+          "modelID": "grok-code-fast-1"
+        },
+        "attempt": 1
+      }
+    }
+  ],
+  "subPipelines": [],
+  "inputText": "I am so happy today!",
+  "opencodeSessionId": "ses_48c4aa762ffeP1pxFsOURK4cw2",
+  "mood": "happy",
+  "keywords": [
+    "happy",
+    "so",
+    "today"
+  ]
+}

package/src/agent.ts

@@ -4,198 +4,187 @@
  * Wraps the OpenCode CLI for running LLM agents with session management.
  */
 
-import { spawn, execSync } from 'child_process'
-import { mkdir } from 'fs/promises'
-import { PROJECT_ROOT, TMP_DIR } from './paths.js'
-import type { RunAgentOptions, RunAgentResult } from './types.js'
+import { spawn, execSync } from "child_process";
+import { mkdir } from "fs/promises";
+import { PROJECT_ROOT, TMP_DIR } from "./paths.js";
+import type { RunAgentOptions, RunAgentResult } from "./types.js";
 
 /** Check if opencode is available in system PATH */
 function hasSystemOpencode(): boolean {
-  try {
-    execSync('which opencode', { stdio: 'ignore' })
-    return true
-  } catch {
-    return false
-  }
+	try {
+		execSync("which opencode", { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
 }
 
 /** Get command and args to invoke opencode */
 function getOpencodeCommand(args: string[]): { cmd: string; args: string[] } {
-  if (hasSystemOpencode()) {
-    return { cmd: 'opencode', args }
-  }
-  // Fallback to bunx with ocpipe package (which has opencode-ai as dependency)
-  return { cmd: 'bunx', args: ['-p', 'ocpipe', 'opencode', ...args] }
+	if (hasSystemOpencode()) {
+		return { cmd: "opencode", args };
+	}
+	// Fallback to bunx with ocpipe package (which has opencode-ai as dependency)
+	return { cmd: "bunx", args: ["-p", "ocpipe", "opencode", ...args] };
 }
 
 /** runAgent executes an OpenCode agent with a prompt, streaming output in real-time. */
-export async function runAgent(
-  options: RunAgentOptions,
-): Promise<RunAgentResult> {
-  const { prompt, agent, model, sessionId, timeoutSec = 300 } = options
-
-  const modelStr = `${model.providerID}/${model.modelID}`
-  const sessionInfo = sessionId ? `[session:${sessionId}]` : '[new session]'
-  const promptPreview = prompt.slice(0, 50).replace(/\n/g, ' ')
-
-  console.error(
-    `\n>>> OpenCode [${agent}] [${modelStr}] ${sessionInfo}: ${promptPreview}...`,
-  )
-
-  const args = [
-    'run',
-    '--format',
-    'default',
-    '--agent',
-    agent,
-    '--model',
-    modelStr,
-  ]
-
-  if (sessionId) {
-    args.push('--session', sessionId)
-  }
-
-  return new Promise((resolve, reject) => {
-    const opencodeCmd = getOpencodeCommand(args)
-    const proc = spawn(opencodeCmd.cmd, opencodeCmd.args, {
-      cwd: PROJECT_ROOT,
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-
-    let newSessionId = sessionId || ''
-    const stdoutChunks: string[] = []
-
-    // Stream stderr in real-time (OpenCode progress output)
-    proc.stderr.on('data', (data: Buffer) => {
-      const text = data.toString()
-
-      // Parse session ID from output
-      for (const line of text.split('\n')) {
-        if (line.startsWith('[session:')) {
-          newSessionId = line.trim().slice(9, -1)
-          continue
-        }
-        // Filter noise
-        if (line.includes('baseline-browser-mapping')) continue
-        if (line.startsWith('$ bun run')) continue
-        if (line.trim()) {
-          process.stderr.write(line + '\n')
-        }
-      }
-    })
-
-    // Collect stdout
-    proc.stdout.on('data', (data: Buffer) => {
-      const text = data.toString()
-      stdoutChunks.push(text)
-      process.stderr.write(text)
-    })
-
-    // Send prompt to stdin
-    proc.stdin.write(prompt)
-    proc.stdin.end()
-
-    // Timeout handling
-    const timeout = setTimeout(() => {
-      proc.kill()
-      reject(new Error(`Timeout after ${timeoutSec}s`))
-    }, timeoutSec * 1000)
-
-    proc.on('close', async (code) => {
-      clearTimeout(timeout)
-
-      if (code !== 0) {
-        reject(new Error(`OpenCode exited with code ${code}`))
-        return
-      }
-
-      // Export session to get structured response
-      let response = stdoutChunks.join('').trim()
-
-      if (newSessionId) {
-        const exported = await exportSession(newSessionId)
-        if (exported) {
-          response = exported
-        }
-      }
-
-      const sessionStr = newSessionId || 'none'
-      console.error(
-        `<<< OpenCode done (${response.length} chars) [session:${sessionStr}]`,
-      )
-
-      resolve({
-        text: response,
-        sessionId: newSessionId,
-      })
-    })
-
-    proc.on('error', (err) => {
-      clearTimeout(timeout)
-      reject(err)
-    })
-  })
+export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult> {
+	const { prompt, agent, model, sessionId, timeoutSec = 300 } = options;
+
+	const modelStr = `${model.providerID}/${model.modelID}`;
+	const sessionInfo = sessionId ? `[session:${sessionId}]` : "[new session]";
+	const promptPreview = prompt.slice(0, 50).replace(/\n/g, " ");
+
+	console.error(`\n>>> OpenCode [${agent}] [${modelStr}] ${sessionInfo}: ${promptPreview}...`);
+
+	const args = ["run", "--format", "default", "--agent", agent, "--model", modelStr];
+
+	if (sessionId) {
+		args.push("--session", sessionId);
+	}
+
+	return new Promise((resolve, reject) => {
+		const opencodeCmd = getOpencodeCommand(args);
+		const proc = spawn(opencodeCmd.cmd, opencodeCmd.args, {
+			cwd: PROJECT_ROOT,
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+
+		let newSessionId = sessionId || "";
+		const stdoutChunks: string[] = [];
+
+		// Stream stderr in real-time (OpenCode progress output)
+		proc.stderr.on("data", (data: Buffer) => {
+			const text = data.toString();
+
+			// Parse session ID from output
+			for (const line of text.split("\n")) {
+				if (line.startsWith("[session:")) {
+					newSessionId = line.trim().slice(9, -1);
+					continue;
+				}
+				// Filter noise
+				if (line.includes("baseline-browser-mapping")) continue;
+				if (line.startsWith("$ bun run")) continue;
+				if (line.trim()) {
+					process.stderr.write(line + "\n");
+				}
+			}
+		});
+
+		// Collect stdout
+		proc.stdout.on("data", (data: Buffer) => {
+			const text = data.toString();
+			stdoutChunks.push(text);
+			process.stderr.write(text);
+		});
+
+		// Send prompt to stdin
+		proc.stdin.write(prompt);
+		proc.stdin.end();
+
+		// Timeout handling (0 = no timeout)
+		const timeout =
+			timeoutSec > 0
+				? setTimeout(() => {
+						proc.kill();
+						reject(new Error(`Timeout after ${timeoutSec}s`));
+					}, timeoutSec * 1000)
+				: null;
+
+		proc.on("close", async (code) => {
+			if (timeout) clearTimeout(timeout);
+
+			if (code !== 0) {
+				reject(new Error(`OpenCode exited with code ${code}`));
+				return;
+			}
+
+			// Export session to get structured response
+			let response = stdoutChunks.join("").trim();
+
+			if (newSessionId) {
+				const exported = await exportSession(newSessionId);
+				if (exported) {
+					response = exported;
+				}
+			}
+
+			const sessionStr = newSessionId || "none";
+			console.error(`<<< OpenCode done (${response.length} chars) [session:${sessionStr}]`);
+
+			resolve({
+				text: response,
+				sessionId: newSessionId,
+			});
+		});
+
+		proc.on("error", (err) => {
+			if (timeout) clearTimeout(timeout);
+			reject(err);
+		});
+	});
 }
 
 /** exportSession exports a session and extracts assistant text responses. */
 async function exportSession(sessionId: string): Promise<string | null> {
-  const tmpPath = `${TMP_DIR}/opencode_export_${Date.now()}.json`
-
-  try {
-    await mkdir(TMP_DIR, { recursive: true })
-    const opencodeCmd = getOpencodeCommand([
-      'session',
-      'export',
-      sessionId,
-      '--format',
-      'json',
-      '-o',
-      tmpPath,
-    ])
-    const proc = Bun.spawn([opencodeCmd.cmd, ...opencodeCmd.args], {
-      cwd: PROJECT_ROOT,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    })
-
-    await proc.exited
-
-    const file = Bun.file(tmpPath)
-    if (!(await file.exists())) return null
-
-    const data = (await file.json()) as {
-      messages?: Array<{
-        info?: { role?: string }
-        parts?: Array<{ type?: string; text?: string }>
-      }>
-    }
-    await Bun.write(tmpPath, '') // Clean up
-
-    // Extract all assistant text parts
-    const messages = data.messages || []
-    const textParts: string[] = []
-
-    for (const msg of messages) {
-      if (msg.info?.role === 'assistant') {
-        for (const part of msg.parts || []) {
-          if (part.type === 'text' && part.text) {
-            textParts.push(part.text)
-          }
-        }
-      }
-    }
-
-    return textParts.length > 0 ? textParts.join('\n') : null
-  } catch {
-    return null
-  }
+	const tmpPath = `${TMP_DIR}/opencode_export_${Date.now()}.json`;
+
+	try {
+		await mkdir(TMP_DIR, { recursive: true });
+		const opencodeCmd = getOpencodeCommand([
+			"session",
+			"export",
+			sessionId,
+			"--format",
+			"json",
+			"-o",
+			tmpPath,
+		]);
+		const proc = Bun.spawn([opencodeCmd.cmd, ...opencodeCmd.args], {
+			cwd: PROJECT_ROOT,
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+
+		await proc.exited;
+
+		const file = Bun.file(tmpPath);
+		if (!(await file.exists())) return null;
+
+		const data = (await file.json()) as {
+			messages?: Array<{
+				info?: { role?: string };
+				parts?: Array<{ type?: string; text?: string }>;
+			}>;
+		};
+		await Bun.write(tmpPath, ""); // Clean up
+
+		// Extract all assistant text parts
+		const messages = data.messages || [];
+		const textParts: string[] = [];
+
+		for (const msg of messages) {
+			if (msg.info?.role === "assistant") {
+				for (const part of msg.parts || []) {
+					if (part.type === "text" && part.text) {
+						textParts.push(part.text);
+					}
+				}
+			}
+		}
+
+		return textParts.length > 0 ? textParts.join("\n") : null;
+	} catch {
+		return null;
+	}
 }
 
 /** logStep logs a step header for workflow progress. */
-export function logStep(step: number, title: string, detail = ''): void {
-  const detailStr = detail ? ` (${detail})` : ''
-  console.log(`\n${'='.repeat(60)}`)
-  console.log(`STEP ${step}: ${title}${detailStr}`)
-  console.log('='.repeat(60))
+export function logStep(step: number, title: string, detail = ""): void {
+	const detailStr = detail ? ` (${detail})` : "";
+	console.log(`\n${"=".repeat(60)}`);
+	console.log(`STEP ${step}: ${title}${detailStr}`);
+	console.log("=".repeat(60));
 }

package/src/parsing.ts

@@ -79,6 +79,7 @@ export function tryParseJson<T>(
       ok: false,
       errors: [
         {
+          code: 'no_json_found',
           path: '',
           message: 'No JSON found in response',
           expectedType: 'object',
@@ -96,6 +97,7 @@ export function tryParseJson<T>(
       ok: false,
       errors: [
         {
+          code: 'json_parse_failed',
           path: '',
           message: `JSON parse failed: ${parseErr.message}`,
           expectedType: 'object',
@@ -157,6 +159,7 @@ function zodErrorsToFieldErrors(
     }
 
     errors.push({
+      code: 'schema_validation_failed',
       path,
       message: issue.message,
       expectedType,
@@ -1060,3 +1063,41 @@ export function parseJsonFromResponse<T = Record<string, unknown>>(
     response,
   )
 }
+
+/** buildJsonRepairPrompt creates a prompt asking the model to fix malformed JSON. */
+export function buildJsonRepairPrompt(
+  malformedJson: string,
+  errorMessage: string,
+  schema: Record<string, FieldConfig>,
+): string {
+  const lines: string[] = []
+
+  lines.push(
+    'Your previous JSON output has a syntax error and cannot be parsed.',
+  )
+  lines.push('')
+  lines.push(`Error: ${errorMessage}`)
+  lines.push('')
+  lines.push('The malformed JSON (may be truncated):')
+  lines.push('```')
+  lines.push(malformedJson.slice(0, 2000))
+  if (malformedJson.length > 2000) {
+    lines.push('... (truncated)')
+  }
+  lines.push('```')
+  lines.push('')
+  lines.push('Please output the COMPLETE, VALID JSON that matches this schema:')
+  lines.push('```json')
+
+  // Build a simple schema description
+  const schemaDesc: Record<string, string> = {}
+  for (const [name, config] of Object.entries(schema)) {
+    schemaDesc[name] = config.desc ?? zodTypeToString(config.type)
+  }
+  lines.push(JSON.stringify(schemaDesc, null, 2))
+  lines.push('```')
+  lines.push('')
+  lines.push('Respond with ONLY the corrected JSON object, no explanation.')
+
+  return lines.join('\n')
+}

package/src/predict.ts

@@ -20,6 +20,8 @@ import type {
 import { runAgent } from './agent.js'
 import {
   tryParseResponse,
+  extractJsonString,
+  buildJsonRepairPrompt,
   // jq-style patches
   buildPatchPrompt,
   buildBatchPatchPrompt,
@@ -78,7 +80,7 @@ export class Predict<S extends AnySignature> {
     // Update context with new session ID for continuity
     ctx.sessionId = agentResult.sessionId
 
-    const parseResult = tryParseResponse<InferOutputs<S>>(
+    let parseResult = tryParseResponse<InferOutputs<S>>(
       agentResult.text,
       this.sig.outputs,
     )
@@ -94,7 +96,42 @@ export class Predict<S extends AnySignature> {
       }
     }
 
-    // Parsing failed - attempt correction if enabled
+    // Check if this is a JSON parse error (malformed JSON, not schema validation)
+    const isJsonParseError =
+      parseResult.errors?.some(
+        (e) => e.code === 'json_parse_failed' || e.code === 'no_json_found',
+      ) ?? false
+
+    // Attempt JSON repair if enabled and we have a parse error
+    if (this.config.correction !== false && isJsonParseError) {
+      const rawJson = extractJsonString(agentResult.text)
+      const repairedResult = await this.repairJson(
+        rawJson ?? agentResult.text,
+        parseResult.errors?.[0]?.message ?? 'JSON parse failed',
+        ctx,
+        agentResult.sessionId,
+      )
+
+      if (repairedResult) {
+        // Re-parse the repaired response
+        parseResult = tryParseResponse<InferOutputs<S>>(
+          repairedResult,
+          this.sig.outputs,
+        )
+
+        if (parseResult.ok && parseResult.data) {
+          return {
+            data: parseResult.data,
+            raw: agentResult.text,
+            sessionId: agentResult.sessionId,
+            duration: Date.now() - startTime,
+            model: this.config.model ?? ctx.defaultModel,
+          }
+        }
+      }
+    }
+
+    // Parsing failed - attempt field correction if enabled and we have parsed JSON
     if (
       this.config.correction !== false &&
       parseResult.errors &&
@@ -135,6 +172,62 @@ export class Predict<S extends AnySignature> {
     )
   }
 
+  /** repairJson asks the model to fix malformed JSON. */
+  private async repairJson(
+    malformedJson: string,
+    errorMessage: string,
+    ctx: ExecutionContext,
+    sessionId: string,
+  ): Promise<string | null> {
+    const correctionConfig =
+      typeof this.config.correction === 'object' ? this.config.correction : {}
+    const maxRounds = correctionConfig.maxRounds ?? 3
+    const correctionModel = correctionConfig.model
+
+    for (let round = 1; round <= maxRounds; round++) {
+      console.error(
+        `\n>>> JSON repair round ${round}/${maxRounds}: fixing malformed JSON...`,
+      )
+
+      const repairPrompt = buildJsonRepairPrompt(
+        malformedJson,
+        errorMessage,
+        this.sig.outputs,
+      )
+
+      // Use same session so the model has context of what it was trying to output
+      const repairResult = await runAgent({
+        prompt: repairPrompt,
+        model: correctionModel ?? ctx.defaultModel,
+        sessionId: correctionModel ? undefined : sessionId,
+        agent: ctx.defaultAgent,
+        timeoutSec: 60,
+      })
+
+      // Try to parse the repaired JSON
+      const repairedJson = extractJsonString(repairResult.text)
+      if (repairedJson) {
+        try {
+          JSON.parse(repairedJson)
+          console.error(`  JSON repair successful after ${round} round(s)!`)
+          return repairedJson
+        } catch (e) {
+          const parseErr = e as SyntaxError
+          console.error(`  Repair attempt ${round} failed: ${parseErr.message}`)
+          malformedJson = repairedJson
+          errorMessage = parseErr.message
+        }
+      } else {
+        console.error(
+          `  Repair attempt ${round} failed: no JSON found in response`,
+        )
+      }
+    }
+
+    console.error(`  JSON repair failed after ${maxRounds} rounds`)
+    return null
+  }
+
   /** correctFields attempts to fix field errors using same-session patches with retries. */
   private async correctFields(
     json: Record<string, unknown>,

package/src/types.ts

@@ -173,7 +173,12 @@ export type CorrectionMethod = 'json-patch' | 'jq'
 export interface CorrectionConfig {
   /** Correction method to use (default: 'json-patch'). */
   method?: CorrectionMethod
-  /** Use a different model for corrections (default: same model, same session). */
+  /**
+   * Use a different model for corrections.
+   * When specified, the correction runs in a new session (no context from the original model).
+   * When not specified, corrections reuse the original session so the model has context
+   * of what it was trying to output.
+   */
   model?: ModelConfig
   /** Maximum number of fields to attempt correcting per round (default: 5). */
   maxFields?: number
@@ -181,8 +186,16 @@ export interface CorrectionConfig {
   maxRounds?: number
 }
 
+/** Error codes for field errors, enabling robust error type detection. */
+export type FieldErrorCode =
+  | 'json_parse_failed'
+  | 'no_json_found'
+  | 'schema_validation_failed'
+
 /** A field-level error from schema validation. */
 export interface FieldError {
+  /** Error code for programmatic detection. */
+  code: FieldErrorCode
   /** The field path that failed (e.g., "issues.0.issue_type"). */
   path: string
   /** Human-readable error message. */