@anthropic-field/core 0.1.0

package/dist/src/cognitive/runtime/envelope.js

@@ -0,0 +1,167 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Envelope Conversion
+ * Handles conversion between v2.1 and v2.2 envelope formats.
+ */
+import { aggregateRisk } from './risk-aggregator.js';
+// =============================================================================
+// v2.1 to v2.2 Conversion
+// =============================================================================
+/**
+ * Convert v2.1 envelope to v2.2 envelope.
+ * Adds meta field by extracting/computing from data.
+ */
+export function wrapV21ToV22(v21Response) {
+    // Already v2.2
+    if ('meta' in v21Response) {
+        return v21Response;
+    }
+    if (v21Response['ok'] === true) {
+        const data = (v21Response['data'] ?? {});
+        // Extract or compute meta fields
+        const confidence = typeof data['confidence'] === 'number' ? data['confidence'] : 0.5;
+        const rationale = typeof data['rationale'] === 'string' ? data['rationale'] : '';
+        return {
+            ok: true,
+            meta: {
+                confidence,
+                risk: aggregateRisk(data),
+                explain: rationale.substring(0, 280) || 'No explanation provided',
+            },
+            data,
+        };
+    }
+    else {
+        const error = (v21Response['error'] ?? {
+            code: 'UNKNOWN',
+            message: 'Unknown error',
+        });
+        return {
+            ok: false,
+            meta: {
+                confidence: 0.0,
+                risk: 'high',
+                explain: (error.message || 'An error occurred').substring(0, 280),
+            },
+            error,
+            partial_data: v21Response['partial_data'],
+        };
+    }
+}
+// =============================================================================
+// Legacy to Envelope Conversion
+// =============================================================================
+/**
+ * Convert legacy format (no envelope) to v2.2 envelope.
+ */
+export function convertLegacyToEnvelope(data, isError = false) {
+    if (isError || 'error' in data) {
+        const error = data['error'];
+        const errorMsg = typeof error === 'object' && error !== null
+            ? String(error['message'] ?? error)
+            : String(error ?? 'Unknown error');
+        return {
+            ok: false,
+            meta: {
+                confidence: 0.0,
+                risk: 'high',
+                explain: errorMsg.substring(0, 280),
+            },
+            error: {
+                code: typeof error === 'object' && error !== null
+                    ? String(error['code'] ?? 'UNKNOWN')
+                    : 'UNKNOWN',
+                message: errorMsg,
+            },
+            partial_data: null,
+        };
+    }
+    else {
+        // Legacy success response - data is the payload itself
+        const confidence = typeof data['confidence'] === 'number' ? data['confidence'] : 0.5;
+        const rationale = typeof data['rationale'] === 'string' ? data['rationale'] : '';
+        return {
+            ok: true,
+            meta: {
+                confidence,
+                risk: aggregateRisk(data),
+                explain: rationale.substring(0, 280) || 'No explanation provided',
+            },
+            data,
+        };
+    }
+}
+// =============================================================================
+// Envelope Factory
+// =============================================================================
+/**
+ * Create a success envelope.
+ */
+export function createSuccessEnvelope(data, meta = {}) {
+    const confidence = meta.confidence ?? (typeof data['confidence'] === 'number' ? data['confidence'] : 0.5);
+    const rationale = typeof data['rationale'] === 'string' ? data['rationale'] : '';
+    return {
+        ok: true,
+        meta: {
+            confidence,
+            risk: meta.risk ?? aggregateRisk(data),
+            explain: meta.explain ?? (rationale.substring(0, 280) || 'No explanation provided'),
+            ...meta,
+        },
+        data,
+    };
+}
+/**
+ * Create a failure envelope.
+ */
+export function createFailureEnvelope(code, message, meta = {}, partialData = null) {
+    return {
+        ok: false,
+        meta: {
+            confidence: meta.confidence ?? 0.0,
+            risk: meta.risk ?? 'high',
+            explain: meta.explain ?? message.substring(0, 280),
+            ...meta,
+        },
+        error: { code, message },
+        partial_data: partialData,
+    };
+}
+// =============================================================================
+// Standard Error Envelopes
+// =============================================================================
+export function createParseError(_rawResponse) {
+    return createFailureEnvelope('PARSE_ERROR', `Failed to parse LLM response as JSON`, { confidence: 0.0, risk: 'high', explain: 'Failed to parse LLM response as JSON.' });
+}
+export function createInvalidInputError(errors) {
+    return createFailureEnvelope('INVALID_INPUT', errors.join('; '), {
+        confidence: 1.0, // We're confident it's the caller's fault
+        risk: 'none',
+        explain: 'Input validation failed.',
+    });
+}
+export function createModuleNotFoundError(name) {
+    return createFailureEnvelope('MODULE_NOT_FOUND', `Module not found: ${name}`, {
+        confidence: 1.0,
+        risk: 'high',
+        explain: `Module '${name}' not found.`,
+    });
+}
+export function createSchemaValidationError(errors, partialData = null) {
+    return createFailureEnvelope('SCHEMA_VALIDATION_FAILED', errors.join('; '), {
+        confidence: 0.0,
+        risk: 'high',
+        explain: 'Schema validation failed after repair attempt.',
+    }, partialData);
+}
+export function createInternalError(message) {
+    return createFailureEnvelope('INTERNAL_ERROR', message, {
+        confidence: 0.0,
+        risk: 'high',
+        explain: 'An internal error occurred.',
+    });
+}
+//# sourceMappingURL=envelope.js.map

package/dist/src/cognitive/runtime/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../../src/cognitive/runtime/envelope.ts"],"names":[],"mappings":"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"}

package/dist/src/cognitive/runtime/executor.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Runtime Executor
+ * Core execution engine for cognitive modules.
+ *
+ * Flow:
+ *   Input → Validate Input → Build Prompt → Call Gemini
+ *   → Parse JSON → Validate Schema → Repair Pass → Return Envelope
+ */
+import type { CognitiveModule, EnvelopeResponse, RunModuleOptions } from '../types.js';
+/**
+ * Parse LLM response, handling potential markdown code blocks.
+ */
+export declare function parseLLMResponse(response: string): Record<string, unknown>;
+/**
+ * Interface for LLM calling - to be implemented by the actual Gemini client.
+ */
+export interface LLMCaller {
+    call(params: {
+        systemPrompt: string;
+        userPrompt: string;
+        model?: string;
+    }): Promise<string>;
+}
+/**
+ * Set the default LLM caller.
+ */
+export declare function setDefaultLLMCaller(caller: LLMCaller): void;
+/**
+ * Get the default LLM caller.
+ */
+export declare function getDefaultLLMCaller(): LLMCaller | null;
+export interface ExecuteModuleParams {
+    module: CognitiveModule;
+    input: Record<string, unknown>;
+    options?: RunModuleOptions;
+    llmCaller?: LLMCaller;
+}
+/**
+ * Execute a cognitive module with the given input.
+ * This is the core runtime that implements the full pipeline.
+ */
+export declare function executeModule(params: ExecuteModuleParams): Promise<EnvelopeResponse>;
+/**
+ * Run a cognitive module by name or path.
+ */
+export declare function runModule(nameOrPath: string, input: Record<string, unknown>, options?: RunModuleOptions & {
+    searchPaths?: string[];
+    llmCaller?: LLMCaller;
+}): Promise<EnvelopeResponse>;
+/**
+ * Extract meta from envelope for routing/logging.
+ */
+export declare function extractMeta(result: EnvelopeResponse): import("../types.js").EnvelopeMeta;
+/**
+ * Determine if result should be escalated to human review.
+ */
+export declare function shouldEscalate(result: EnvelopeResponse, confidenceThreshold?: number): boolean;
+/**
+ * Determine if confirmation is required before execution.
+ */
+export declare function requiresConfirmation(module: CognitiveModule, result: EnvelopeResponse): boolean;

package/dist/src/cognitive/runtime/executor.js

@@ -0,0 +1,245 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Runtime Executor
+ * Core execution engine for cognitive modules.
+ *
+ * Flow:
+ *   Input → Validate Input → Build Prompt → Call Gemini
+ *   → Parse JSON → Validate Schema → Repair Pass → Return Envelope
+ */
+import { loadModule, findModule } from '../loader/index.js';
+import { validateInput, validateData, validateMeta, isEnvelopeResponse, isV22Envelope, } from '../validator/index.js';
+import { wrapV21ToV22, convertLegacyToEnvelope, createParseError, createInvalidInputError, createModuleNotFoundError, createSchemaValidationError, createInternalError, } from './envelope.js';
+import { tryRepair } from './repair-pass.js';
+import { buildPrompt, buildSystemPrompt } from './prompt-builder.js';
+// =============================================================================
+// JSON Parsing
+// =============================================================================
+/**
+ * Parse LLM response, handling potential markdown code blocks.
+ */
+export function parseLLMResponse(response) {
+    let text = response.trim();
+    // Remove markdown code blocks if present
+    if (text.startsWith('```')) {
+        const lines = text.split('\n');
+        let start = 1;
+        let end = lines.length - 1;
+        // Skip the first line (```json or ```)
+        // Find the closing ```
+        for (let i = 1; i < lines.length; i++) {
+            if (lines[i].trim() === '```') {
+                end = i;
+                break;
+            }
+        }
+        text = lines.slice(start, end).join('\n');
+    }
+    return JSON.parse(text);
+}
+// Default placeholder - will be replaced with actual Gemini client
+let defaultLLMCaller = null;
+/**
+ * Set the default LLM caller.
+ */
+export function setDefaultLLMCaller(caller) {
+    defaultLLMCaller = caller;
+}
+/**
+ * Get the default LLM caller.
+ */
+export function getDefaultLLMCaller() {
+    return defaultLLMCaller;
+}
+/**
+ * Execute a cognitive module with the given input.
+ * This is the core runtime that implements the full pipeline.
+ */
+export async function executeModule(params) {
+    const { module, input, options = {}, llmCaller } = params;
+    const startTime = Date.now();
+    const { validateInput: shouldValidateInput = true, validateOutput: shouldValidateOutput = true, useEnvelope = true, useV22 = true, enableRepair = true, model, traceId, } = options;
+    // Get risk rule from module config
+    const riskRule = module.manifest.meta?.risk_rule || 'max_changes_risk';
+    // Step 1: Validate Input
+    if (shouldValidateInput) {
+        const inputResult = validateInput(module, input);
+        if (!inputResult.valid) {
+            return createInvalidInputError(inputResult.errors);
+        }
+    }
+    // Step 2: Build Prompt
+    const systemPrompt = buildSystemPrompt(module);
+    const userPrompt = buildPrompt(module, input, {
+        useEnvelope,
+        useV22,
+        includeSchemas: true,
+    });
+    // Step 3: Call LLM
+    const caller = llmCaller || defaultLLMCaller;
+    if (!caller) {
+        return createInternalError('No LLM caller configured');
+    }
+    let rawResponse;
+    try {
+        rawResponse = await caller.call({
+            systemPrompt,
+            userPrompt,
+            model,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createInternalError(`LLM call failed: ${message}`);
+    }
+    // Step 4: Parse JSON
+    let parsed;
+    try {
+        parsed = parseLLMResponse(rawResponse);
+    }
+    catch (error) {
+        return createParseError(rawResponse);
+    }
+    // Step 5: Convert to v2.2 Envelope
+    let envelope;
+    if (isV22Envelope(parsed)) {
+        envelope = parsed;
+    }
+    else if (isEnvelopeResponse(parsed)) {
+        // v2.1 envelope -> v2.2
+        envelope = wrapV21ToV22(parsed);
+    }
+    else {
+        // Legacy format -> v2.2
+        envelope = convertLegacyToEnvelope(parsed);
+    }
+    // Add latency and trace info
+    const latencyMs = Date.now() - startTime;
+    envelope.meta.latency_ms = latencyMs;
+    if (traceId) {
+        envelope.meta.trace_id = traceId;
+    }
+    if (model) {
+        envelope.meta.model = model;
+    }
+    // Step 6: Validate and Repair (for success responses)
+    if (envelope.ok && shouldValidateOutput) {
+        // Validate data
+        const dataResult = validateData(module, envelope.data);
+        if (!dataResult.valid) {
+            if (enableRepair) {
+                // Attempt repair
+                const repairResult = tryRepair(envelope, riskRule);
+                if (repairResult) {
+                    envelope = repairResult.repaired;
+                    // Re-validate after repair
+                    const revalidateResult = validateData(module, envelope.data);
+                    if (!revalidateResult.valid) {
+                        return createSchemaValidationError(revalidateResult.errors, envelope.data);
+                    }
+                }
+                else {
+                    // Cannot repair
+                    return createSchemaValidationError(dataResult.errors, envelope.data);
+                }
+            }
+            else {
+                return createSchemaValidationError(dataResult.errors, envelope.data);
+            }
+        }
+        // Validate meta
+        const metaResult = validateMeta(module, envelope.meta);
+        if (!metaResult.valid) {
+            if (enableRepair) {
+                const repairResult = tryRepair(envelope, riskRule);
+                if (repairResult) {
+                    envelope = repairResult.repaired;
+                }
+            }
+        }
+    }
+    return envelope;
+}
+// =============================================================================
+// High-Level API
+// =============================================================================
+/**
+ * Run a cognitive module by name or path.
+ */
+export async function runModule(nameOrPath, input, options = {}) {
+    const { searchPaths = [], llmCaller, ...runOptions } = options;
+    // Try to load module
+    let module = null;
+    // Check if it's a path
+    try {
+        const fs = await import('node:fs');
+        if (fs.existsSync(nameOrPath)) {
+            module = loadModule(nameOrPath);
+        }
+    }
+    catch {
+        // Not a valid path, try as name
+    }
+    // Try to find by name
+    if (!module) {
+        module = findModule(nameOrPath, searchPaths);
+    }
+    if (!module) {
+        return createModuleNotFoundError(nameOrPath);
+    }
+    return executeModule({
+        module,
+        input,
+        options: runOptions,
+        llmCaller,
+    });
+}
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Extract meta from envelope for routing/logging.
+ */
+export function extractMeta(result) {
+    return result.meta;
+}
+/**
+ * Determine if result should be escalated to human review.
+ */
+export function shouldEscalate(result, confidenceThreshold = 0.7) {
+    // Escalate if low confidence
+    if (result.meta.confidence < confidenceThreshold) {
+        return true;
+    }
+    // Escalate if high risk
+    if (result.meta.risk === 'high') {
+        return true;
+    }
+    // Escalate if error
+    if (!result.ok) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Determine if confirmation is required before execution.
+ */
+export function requiresConfirmation(module, result) {
+    // exec tier always requires confirmation for mutating operations
+    if (module.tier === 'exec') {
+        return true;
+    }
+    // High risk requires confirmation
+    if (result.meta.risk === 'high') {
+        return true;
+    }
+    // Medium risk with low confidence requires confirmation
+    if (result.meta.risk === 'medium' && result.meta.confidence < 0.8) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=executor.js.map

package/dist/src/cognitive/runtime/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../../src/cognitive/runtime/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AASH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EACL,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EACzB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAErE,gFAAgF;AAChF,eAAe;AACf,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,IAAI,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAE3B,yCAAyC;IACzC,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QAE3B,uCAAuC;QACvC,uBAAuB;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;gBAC9B,GAAG,GAAG,CAAC,CAAC;gBACR,MAAM;YACR,CAAC;QACH,CAAC;QAED,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAiBD,mEAAmE;AACnE,IAAI,gBAAgB,GAAqB,IAAI,CAAC;AAE9C;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,gBAAgB,GAAG,MAAM,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAaD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAA2B;IAE3B,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,MAAM,EACJ,aAAa,EAAE,mBAAmB,GAAG,IAAI,EACzC,cAAc,EAAE,oBAAoB,GAAG,IAAI,EAC3C,WAAW,GAAG,IAAI,EAClB,MAAM,GAAG,IAAI,EACb,YAAY,GAAG,IAAI,EACnB,KAAK,EACL,OAAO,GACR,GAAG,OAAO,CAAC;IAEZ,mCAAmC;IACnC,MAAM,QAAQ,GAAa,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,IAAI,kBAAkB,CAAC;IAEjF,yBAAyB;IACzB,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO,uBAAuB,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,MAAM,YAAY,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC/C,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,EAAE,KAAK,EAAE;QAC5C,WAAW;QACX,MAAM;QACN,cAAc,EAAE,IAAI;KACrB,CAAC,CAAC;IAEH,mBAAmB;IACnB,MAAM,MAAM,GAAG,SAAS,IAAI,gBAAgB,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,mBAAmB,CAAC,0BAA0B,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC;YAC9B,YAAY;YACZ,UAAU;YACV,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,mBAAmB,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,qBAAqB;IACrB,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAED,mCAAmC;IACnC,IAAI,QAA0B,CAAC;IAC/B,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,QAAQ,GAAG,MAA0B,CAAC;IACxC,CAAC;SAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,wBAAwB;QACxB,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,wBAAwB;QACxB,QAAQ,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,6BAA6B;IAC7B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IACrC,IAAI,OAAO,EAAE,CAAC;QACZ,QAAQ,CAAC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;IACnC,CAAC;IACD,IAAI,KAAK,EAAE,CAAC;QACV,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED,sDAAsD;IACtD,IAAI,QAAQ,CAAC,EAAE,IAAI,oBAAoB,EAAE,CAAC;QACxC,gBAAgB;QAChB,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEvD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,IAAI,YAAY,EAAE,CAAC;gBACjB,iBAAiB;gBACjB,MAAM,YAAY,GAAG,SAAS,CAAC,QAA8C,EAAE,QAAQ,CAAC,CAAC;gBAEzF,IAAI,YAAY,EAAE,CAAC;oBACjB,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;oBAEjC,2BAA2B;oBAC3B,MAAM,gBAAgB,GAAG,YAAY,CAAC,MAAM,EAAG,QAA4B,CAAC,IAAI,CAAC,CAAC;oBAElF,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;wBAC5B,OAAO,2BAA2B,CAChC,gBAAgB,CAAC,MAAM,EACtB,QAA4B,CAAC,IAAI,CACnC,CAAC;oBACJ,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,gBAAgB;oBAChB,OAAO,2BAA2B,CAChC,UAAU,CAAC,MAAM,EAChB,QAA4B,CAAC,IAAI,CACnC,CAAC;gBACJ,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,OAAO,2BAA2B,CAChC,UAAU,CAAC,MAAM,EAChB,QAA4B,CAAC,IAAI,CACnC,CAAC;YACJ,CAAC;QACH,CAAC;QAED,gBAAgB;QAChB,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;YACtB,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,YAAY,GAAG,SAAS,CAAC,QAA8C,EAAE,QAAQ,CAAC,CAAC;gBACzF,IAAI,YAAY,EAAE,CAAC;oBACjB,QAAQ,GAAG,YAAY,CAAC,QAAQ,CAAC;gBACnC,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,UAAkB,EAClB,KAA8B,EAC9B,UAGI,EAAE;IAEN,MAAM,EAAE,WAAW,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;IAE/D,qBAAqB;IACrB,IAAI,MAAM,GAA2B,IAAI,CAAC;IAE1C,uBAAuB;IACvB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QACnC,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9B,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gCAAgC;IAClC,CAAC;IAED,sBAAsB;IACtB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,UAAU,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,yBAAyB,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,aAAa,CAAC;QACnB,MAAM;QACN,KAAK;QACL,OAAO,EAAE,UAAU;QACnB,SAAS;KACV,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAwB;IAClD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAwB,EACxB,mBAAmB,GAAG,GAAG;IAEzB,6BAA6B;IAC7B,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,GAAG,mBAAmB,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wBAAwB;IACxB,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,oBAAoB;IACpB,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAuB,EACvB,MAAwB;IAExB,iEAAiE;IACjE,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kCAAkC;IAClC,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wDAAwD;IACxD,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,GAAG,GAAG,EAAE,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/cognitive/runtime/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Runtime - Public API
+ */
+export { executeModule, runModule, parseLLMResponse, setDefaultLLMCaller, getDefaultLLMCaller, extractMeta, shouldEscalate, requiresConfirmation, type ExecuteModuleParams, type LLMCaller, } from './executor.js';
+export { wrapV21ToV22, convertLegacyToEnvelope, createSuccessEnvelope, createFailureEnvelope, createParseError, createInvalidInputError, createModuleNotFoundError, createSchemaValidationError, createInternalError, } from './envelope.js';
+export { aggregateRisk, aggregateRiskFromList, compareRisk, maxRisk, requiresReview, requiresConfirmation as riskRequiresConfirmation, } from './risk-aggregator.js';
+export { repairEnvelope, repairErrorEnvelope, tryRepair, isMetaRepairable, type RepairResult, } from './repair-pass.js';
+export { buildPrompt, buildSystemPrompt, substituteArguments, formatConstraints, type BuildPromptOptions, } from './prompt-builder.js';

package/dist/src/cognitive/runtime/index.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Runtime - Public API
+ */
+// Executor
+export { executeModule, runModule, parseLLMResponse, setDefaultLLMCaller, getDefaultLLMCaller, extractMeta, shouldEscalate, requiresConfirmation, } from './executor.js';
+// Envelope
+export { wrapV21ToV22, convertLegacyToEnvelope, createSuccessEnvelope, createFailureEnvelope, createParseError, createInvalidInputError, createModuleNotFoundError, createSchemaValidationError, createInternalError, } from './envelope.js';
+// Risk Aggregation
+export { aggregateRisk, aggregateRiskFromList, compareRisk, maxRisk, requiresReview, requiresConfirmation as riskRequiresConfirmation, } from './risk-aggregator.js';
+// Repair Pass
+export { repairEnvelope, repairErrorEnvelope, tryRepair, isMetaRepairable, } from './repair-pass.js';
+// Prompt Builder
+export { buildPrompt, buildSystemPrompt, substituteArguments, formatConstraints, } from './prompt-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/src/cognitive/runtime/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cognitive/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,WAAW;AACX,OAAO,EACL,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,oBAAoB,GAGrB,MAAM,eAAe,CAAC;AAEvB,WAAW;AACX,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,yBAAyB,EACzB,2BAA2B,EAC3B,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,mBAAmB;AACnB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,WAAW,EACX,OAAO,EACP,cAAc,EACd,oBAAoB,IAAI,wBAAwB,GACjD,MAAM,sBAAsB,CAAC;AAE9B,cAAc;AACd,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,gBAAgB,GAEjB,MAAM,kBAAkB,CAAC;AAE1B,iBAAiB;AACjB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,GAElB,MAAM,qBAAqB,CAAC"}

package/dist/src/cognitive/runtime/prompt-builder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cognitive Prompt Builder
+ * Builds the complete prompt for LLM execution.
+ */
+import type { CognitiveModule } from '../types.js';
+/**
+ * Substitute $ARGUMENTS and $N placeholders in text.
+ */
+export declare function substituteArguments(text: string, input: Record<string, unknown>): string;
+/**
+ * Format constraints as YAML-like text for the prompt.
+ */
+export declare function formatConstraints(module: CognitiveModule): string;
+/**
+ * Format JSON schema for prompt inclusion.
+ */
+export declare function formatSchema(schema: Record<string, unknown>, label: string): string;
+export interface BuildPromptOptions {
+    useEnvelope?: boolean;
+    useV22?: boolean;
+    includeSchemas?: boolean;
+}
+/**
+ * Build the complete prompt for the LLM.
+ */
+export declare function buildPrompt(module: CognitiveModule, input: Record<string, unknown>, options?: BuildPromptOptions): string;
+/**
+ * Generate a system prompt for the cognitive module.
+ */
+export declare function buildSystemPrompt(module: CognitiveModule): string;