The AI Systems Engineering Harness for Claude & Cursor

from typing import Generic, TypeVar, Optional, Any
from pydantic import BaseModel, Field

T = TypeVar("T")

class HardenedToolResult(BaseModel, Generic[T]):
    """Standardized Layer 4 return envelope for autonomous error correction."""
    success: bool = Field(..., description="True if operation completed cleanly")
    result: Optional[T] = Field(None, description="Typed output payload")
    recovery_hint: Optional[str] = Field(
        None, 
        description="Deterministic guidance to LLM if execution failed. Prevents endless retry loops."
    )

# Example Usage in an MCP or LangChain Tool:
def update_user_record(user_id: str, new_tier: str) -> dict[str, Any]:
    try:
        updated = db.users.update(user_id, tier=new_tier)
        return HardenedToolResult(success=True, result=updated).model_dump()
    except DatabaseConnectionError:
        return HardenedToolResult(
            success=False,
            result=None,
            recovery_hint="Database connection timed out. Do NOT retry immediately. Ask user if secondary replica is permitted."
        ).model_dump()

import { z } from "zod";

/** Standardized Layer 4 Tool Result Envelope */
export const ToolResultEnvelopeSchema = z.object({
  success: z.boolean().describe("Execution outcome flag"),
  result: z.record(z.any()).nullable().describe("Operational payload"),
  recovery_hint: z.string().optional().describe(
    "Deterministic instructions directing model behavior on failure"
  )
});

export type ToolResultEnvelope<T = Record<string, any>> = {
  success: boolean;
  result: T | null;
  recovery_hint?: string;
};

// Safe helper for tool implementations
export function createRecoveryEnvelope(errorMsg: string, suggestedAction: string): ToolResultEnvelope {
  return {
    success: false,
    result: null,
    recovery_hint: `Tool encountered: ${errorMsg}. Next step: ${suggestedAction}`
  };
}