@kilnai/core 0.1.0

package/dist/engine/domain/trigger.js

@@ -0,0 +1,39 @@
+// Engine primitive: Trigger -- event-driven workflow activation
+// 7th primitive: webhook, event, schedule trigger types
+/** Validate a trigger configuration */
+export function validateTrigger(trigger, teamNames) {
+    const errors = [];
+    if (!trigger.name || typeof trigger.name !== "string") {
+        errors.push({ field: "name", message: "must be a non-empty string" });
+    }
+    if (!teamNames.includes(trigger.team)) {
+        errors.push({ field: "team", message: `references unknown team "${trigger.team}"` });
+    }
+    switch (trigger.type) {
+        case "webhook":
+            if (!trigger.path || typeof trigger.path !== "string") {
+                errors.push({ field: "path", message: "must be a non-empty string" });
+            }
+            else if (!trigger.path.startsWith("/")) {
+                errors.push({ field: "path", message: "must start with /" });
+            }
+            if (trigger.method !== undefined && trigger.method !== "POST" && trigger.method !== "PUT") {
+                errors.push({ field: "method", message: 'must be "POST" or "PUT"' });
+            }
+            break;
+        case "event":
+            if (!trigger.event || typeof trigger.event !== "string") {
+                errors.push({ field: "event", message: "must be a non-empty string" });
+            }
+            break;
+        case "schedule":
+            if (!trigger.cron || typeof trigger.cron !== "string") {
+                errors.push({ field: "cron", message: "must be a non-empty string" });
+            }
+            break;
+        default:
+            errors.push({ field: "type", message: "must be webhook, event, or schedule" });
+    }
+    return errors;
+}
+//# sourceMappingURL=trigger.js.map

package/dist/engine/domain/trigger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger.js","sourceRoot":"","sources":["../../../src/engine/domain/trigger.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,wDAAwD;AAgDxD,uCAAuC;AACvC,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,SAA4B;IAC5E,MAAM,MAAM,GAA6B,EAAE,CAAC;IAE5C,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,OAAO,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,SAAS;YACZ,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;YACxE,CAAC;iBAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC,CAAC;YAC/D,CAAC;YACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;gBAC1F,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;YACvE,CAAC;YACD,MAAM;QACR,KAAK,OAAO;YACV,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACxD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;YACzE,CAAC;YACD,MAAM;QACR,KAAK,UAAU;YACb,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACtD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;YACxE,CAAC;YACD,MAAM;QACR;YACE,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/engine/domain/vector-store.d.ts

@@ -0,0 +1,27 @@
+/** A single entry in the vector store. */
+export interface VectorEntry {
+    readonly id: string;
+    readonly content: string;
+    readonly embedding: number[];
+    readonly metadata: Record<string, unknown>;
+}
+/** A query result from the vector store. */
+export interface VectorResult {
+    readonly id: string;
+    readonly content: string;
+    readonly score: number;
+    readonly metadata: Record<string, unknown>;
+}
+/** Query options for vector similarity search. */
+export interface VectorQueryOptions {
+    readonly topK: number;
+    readonly minScore?: number;
+    readonly filter?: Record<string, unknown>;
+}
+/** Provider-agnostic vector store interface. */
+export interface VectorStore {
+    upsert(entries: VectorEntry[]): Promise<void>;
+    query(embedding: number[], options: VectorQueryOptions): Promise<VectorResult[]>;
+    delete(ids: string[]): Promise<void>;
+}
+//# sourceMappingURL=vector-store.d.ts.map

package/dist/engine/domain/vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../../src/engine/domain/vector-store.ts"],"names":[],"mappings":"AAEA,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IACjF,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}

package/dist/engine/domain/vector-store.js

@@ -0,0 +1,3 @@
+// Engine primitive: VectorStore -- provider-agnostic interface for vector storage and similarity search
+export {};
+//# sourceMappingURL=vector-store.js.map

package/dist/engine/domain/vector-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../../src/engine/domain/vector-store.ts"],"names":[],"mappings":"AAAA,wGAAwG"}

package/dist/engine/domain/workflow.d.ts

@@ -0,0 +1,11 @@
+/** A quality gate that must pass before phase transition */
+export interface Gate {
+    readonly requires: readonly string[];
+}
+/** A configurable sequence of phases with quality gates */
+export interface Workflow {
+    readonly phases: readonly string[];
+    readonly gates: Record<string, Gate>;
+    readonly maxIterations?: number;
+}
+//# sourceMappingURL=workflow.d.ts.map

package/dist/engine/domain/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../src/engine/domain/workflow.ts"],"names":[],"mappings":"AAGA,4DAA4D;AAC5D,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC"}

package/dist/engine/domain/workflow.js

@@ -0,0 +1,4 @@
+// Engine primitive: Workflow -- a configurable phase sequence with gates
+// Ehrlich #6: domain-agnostic config (string phases, not hardcoded enums)
+export {};
+//# sourceMappingURL=workflow.js.map

package/dist/engine/domain/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../../src/engine/domain/workflow.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,0EAA0E"}

package/dist/engine/error-catalog.d.ts

@@ -0,0 +1,8 @@
+import type { KilnErrorCode } from "./errors.js";
+export interface ErrorSuggestion {
+    readonly suggestion: string;
+    readonly docUrl?: string;
+}
+/** Returns a developer-friendly suggestion and doc link for a given error code. */
+export declare function getErrorSuggestion(code: KilnErrorCode, context?: Record<string, unknown>): ErrorSuggestion;
+//# sourceMappingURL=error-catalog.d.ts.map

package/dist/engine/error-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-catalog.d.ts","sourceRoot":"","sources":["../../src/engine/error-catalog.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD,mFAAmF;AACnF,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,aAAa,EACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,eAAe,CAybjB"}

package/dist/engine/error-catalog.js

@@ -0,0 +1,335 @@
+// Error catalog: maps KilnErrorCode to developer-friendly suggestions and doc links
+// Pure functions -- no side effects, no external dependencies
+function docUrl(code) {
+    return `https://kilnai.dev/docs/errors/${code.toLowerCase().replace(/_/g, "-")}`;
+}
+/** Returns a developer-friendly suggestion and doc link for a given error code. */
+export function getErrorSuggestion(code, context) {
+    switch (code) {
+        case "APP_YAML_INVALID":
+            return {
+                suggestion: "Check your app.yaml syntax. Ensure all required fields (name, teams, router) are present.",
+                docUrl: docUrl(code),
+            };
+        case "PRESET_LOAD_FAILED":
+            return {
+                suggestion: "The app configuration could not be loaded. Verify the YAML file exists and is valid.",
+                docUrl: docUrl(code),
+            };
+        case "GATEWAY_YAML_INVALID":
+            return {
+                suggestion: "Check your gateway.yaml syntax. Ensure port and apps[] are configured correctly.",
+                docUrl: docUrl(code),
+            };
+        case "MODE_B_CONFIG_INVALID":
+            return {
+                suggestion: "Check Mode B configuration. Ensure provider name, model, and apiKeyEnv are set.",
+                docUrl: docUrl(code),
+            };
+        case "DOMAIN_YAML_INVALID":
+            return {
+                suggestion: "Check your domain.yaml syntax. Required fields: name, displayName, detectPatterns, toolTags, qualityGates.",
+                docUrl: docUrl(code),
+            };
+        case "DOMAIN_KIT_INVALID":
+            return {
+                suggestion: "The domain kit file is invalid. Ensure it follows the DomainYaml schema.",
+                docUrl: docUrl(code),
+            };
+        case "TENANT_NOT_FOUND": {
+            const tenantId = context?.tenantId;
+            const base = "The specified tenant was not found. Use the admin API to list available tenants.";
+            return {
+                suggestion: tenantId ? `${base} Tenant ID: ${tenantId}` : base,
+                docUrl: docUrl(code),
+            };
+        }
+        case "TENANT_VALIDATION_FAILED":
+            return {
+                suggestion: "Tenant configuration is invalid. Check required fields: id, appId, name.",
+                docUrl: docUrl(code),
+            };
+        case "PROVIDER_UNAVAILABLE":
+            return {
+                suggestion: "The LLM provider is not responding. Check your network connection and try again.",
+                docUrl: docUrl(code),
+            };
+        case "PROVIDER_RATE_LIMITED": {
+            let suggestion = "Rate limited by the LLM provider. Wait a moment and retry.";
+            if (context?.provider === "anthropic") {
+                suggestion += " Check your Anthropic usage dashboard.";
+            }
+            return { suggestion, docUrl: docUrl(code) };
+        }
+        case "PROVIDER_AUTH_FAILED": {
+            let suggestion;
+            switch (context?.provider) {
+                case "anthropic":
+                    suggestion = "Set ANTHROPIC_API_KEY environment variable.";
+                    break;
+                case "openai":
+                    suggestion = "Set OPENAI_API_KEY environment variable.";
+                    break;
+                case "deepseek":
+                    suggestion = "Set DEEPSEEK_API_KEY environment variable.";
+                    break;
+                default:
+                    suggestion = "Check your API key configuration.";
+            }
+            return { suggestion, docUrl: docUrl(code) };
+        }
+        case "BUDGET_CHECK_FAILED":
+            return {
+                suggestion: "Budget check failed. Verify billing configuration in your gateway.yaml.",
+                docUrl: docUrl(code),
+            };
+        case "BUDGET_EXCEEDED":
+            return {
+                suggestion: "Token budget exceeded. Increase the budget limit in billing config or optimize your prompts.",
+                docUrl: docUrl(code),
+            };
+        case "CONFIG_MISSING_ENV": {
+            const envVar = context?.envVar;
+            const base = "Required environment variable is missing.";
+            return {
+                suggestion: envVar ? `${base} Set ${envVar} in your environment.` : base,
+                docUrl: docUrl(code),
+            };
+        }
+        case "CONFIG_INVALID":
+            return {
+                suggestion: "Configuration is invalid. Check the relevant YAML file for syntax errors.",
+                docUrl: docUrl(code),
+            };
+        case "CIRCUIT_OPEN":
+            return {
+                suggestion: "Service circuit breaker is open due to repeated failures. The service will retry automatically.",
+                docUrl: docUrl(code),
+            };
+        case "GUARDRAIL_FAILED":
+            return {
+                suggestion: "Structured output failed validation. The agent's response did not match the expected schema.",
+                docUrl: docUrl(code),
+            };
+        case "STRUCTURED_OUTPUT_INVALID":
+            return {
+                suggestion: "The LLM returned output that doesn't match the JSON schema. Try simplifying the schema or using a more capable model.",
+                docUrl: docUrl(code),
+            };
+        case "HANDOFF_FAILED":
+            return {
+                suggestion: "Agent handoff failed. Verify that the target agent exists and can accept handoffs.",
+                docUrl: docUrl(code),
+            };
+        case "INTERRUPT_TIMEOUT":
+            return {
+                suggestion: "The interrupt timed out waiting for external input. Resume the session or increase the timeout.",
+                docUrl: docUrl(code),
+            };
+        case "INJECTION_DETECTED":
+            return {
+                suggestion: "Potential prompt injection detected in user input. The input was blocked for safety.",
+                docUrl: docUrl(code),
+            };
+        case "GUARDIAN_BLOCKED":
+            return {
+                suggestion: "Guardian review blocked a destructive operation. Review the capability's risk level.",
+                docUrl: docUrl(code),
+            };
+        case "GUARDIAN_UNAVAILABLE":
+            return {
+                suggestion: "Guardian review service is unavailable. Destructive operations are blocked until the Guardian is reachable.",
+                docUrl: docUrl(code),
+            };
+        case "SECRET_DECRYPTION_FAILED":
+            return {
+                suggestion: "Failed to decrypt a secret. The encryption key may have changed. Try rotating keys.",
+                docUrl: docUrl(code),
+            };
+        case "SECRET_NOT_FOUND":
+            return {
+                suggestion: "The requested secret was not found in the secret store.",
+                docUrl: docUrl(code),
+            };
+        case "AUDIT_WRITE_FAILED":
+            return {
+                suggestion: "Failed to write audit log entry. Check file permissions on the audit log path.",
+                docUrl: docUrl(code),
+            };
+        case "AUDIT_CHAIN_BROKEN":
+            return {
+                suggestion: "Audit log hash chain verification failed. The log may have been tampered with.",
+                docUrl: docUrl(code),
+            };
+        case "TENANT_ISOLATION_VIOLATED":
+            return {
+                suggestion: "A tenant isolation boundary was violated. This is a security event.",
+                docUrl: docUrl(code),
+            };
+        case "UNAUTHORIZED":
+            return {
+                suggestion: "Authentication required. Provide a valid API key or token.",
+                docUrl: docUrl(code),
+            };
+        case "FORBIDDEN":
+            return {
+                suggestion: "You don't have permission to perform this action.",
+                docUrl: docUrl(code),
+            };
+        case "RATE_LIMIT_EXCEEDED":
+            return {
+                suggestion: "Too many requests. Wait before trying again.",
+                docUrl: docUrl(code),
+            };
+        case "SKILL_YAML_INVALID":
+            return {
+                suggestion: "The skill YAML file is invalid. Ensure it follows the skill schema with required fields: name, description, steps.",
+                docUrl: docUrl(code),
+            };
+        case "SKILL_NOT_FOUND":
+            return {
+                suggestion: "The requested skill was not found. Check the skill name and ensure it is registered.",
+                docUrl: docUrl(code),
+            };
+        case "PACKAGE_YAML_INVALID":
+            return {
+                suggestion: "The package YAML is invalid. Ensure it has type (\"domain\" or \"skill\"), version, and author fields.",
+                docUrl: docUrl(code),
+            };
+        case "TRIGGER_FAILED":
+            return {
+                suggestion: "A trigger failed to execute. Check the trigger configuration and target team.",
+                docUrl: docUrl(code),
+            };
+        case "WEBHOOK_VALIDATION_FAILED":
+            return {
+                suggestion: "Webhook signature validation failed. Verify the HMAC secret matches the sender's configuration.",
+                docUrl: docUrl(code),
+            };
+        case "SCHEDULE_PARSE_FAILED":
+            return {
+                suggestion: "Invalid cron expression. Use 5-field format: minute hour day-of-month month day-of-week (e.g., \"0 2 * * *\").",
+                docUrl: docUrl(code),
+            };
+        case "EVAL_YAML_INVALID":
+            return {
+                suggestion: "Check your eval.yaml against the schema. Ensure datasets, scorers, and experiments are all valid.",
+                docUrl: docUrl(code),
+            };
+        case "EVAL_DATASET_NOT_FOUND":
+            return {
+                suggestion: "Verify the dataset JSONL file exists and each line is valid JSON with 'id' and 'input' fields.",
+                docUrl: docUrl(code),
+            };
+        case "EVAL_DATASET_INVALID":
+            return {
+                suggestion: "The dataset file exists but has invalid content. Check JSON syntax and ensure all entries have 'id' and 'input' fields.",
+                docUrl: docUrl(code),
+            };
+        case "EVAL_SCORER_FAILED":
+            return {
+                suggestion: "Check scorer configuration. LLM scorers require a ScorerLLM instance.",
+                docUrl: docUrl(code),
+            };
+        case "EVAL_EXPERIMENT_FAILED":
+            return {
+                suggestion: "Ensure the experiment references valid datasets and scorers.",
+                docUrl: docUrl(code),
+            };
+        case "A2A_INVALID_REQUEST":
+            return {
+                suggestion: "The incoming A2A JSON-RPC request is malformed. Check the request body against the A2A specification.",
+                docUrl: docUrl(code),
+            };
+        case "A2A_TASK_NOT_FOUND":
+            return {
+                suggestion: "The requested A2A task ID does not exist. Tasks are ephemeral and may have been cleaned up.",
+                docUrl: docUrl(code),
+            };
+        case "A2A_TASK_FAILED":
+            return {
+                suggestion: "The A2A task failed during execution. Check the target team and orchestrator logs.",
+                docUrl: docUrl(code),
+            };
+        case "A2A_CLIENT_FAILED":
+            return {
+                suggestion: "Failed to communicate with a remote A2A agent. Verify the agent URL and network connectivity.",
+                docUrl: docUrl(code),
+            };
+        case "MCP_CONNECTION_FAILED":
+            return {
+                suggestion: "Cannot connect to MCP server. Check the server URL/command and ensure the server is running.",
+                docUrl: docUrl(code),
+            };
+        case "MCP_DISCOVERY_FAILED":
+            return {
+                suggestion: "Failed to discover tools from MCP server. The server may not implement tools/list correctly.",
+                docUrl: docUrl(code),
+            };
+        case "MCP_SERVER_ERROR":
+            return {
+                suggestion: "The MCP server returned an error. Check server logs for details.",
+                docUrl: docUrl(code),
+            };
+        case "TOOL_RAG_FAILED":
+            return {
+                suggestion: "Tool retrieval failed. Check the embedding adapter configuration and vector store availability.",
+                docUrl: docUrl(code),
+            };
+        case "UNSUPPORTED_MODALITY": {
+            const modality = context?.modality;
+            const provider = context?.provider;
+            let suggestion = "The requested content modality is not supported by the provider.";
+            if (modality && provider) {
+                suggestion = `${provider} does not support "${modality}" content. Use a provider that supports this modality or remove it from the agent's modalities.`;
+            }
+            return { suggestion, docUrl: docUrl(code) };
+        }
+        case "CONTENT_PART_INVALID":
+            return {
+                suggestion: "A content part is invalid. Binary parts (image, audio, file) must have exactly one of 'data' or 'url'.",
+                docUrl: docUrl(code),
+            };
+        case "VOICE_CONFIG_INVALID":
+            return {
+                suggestion: "Voice configuration is invalid. Check STT/TTS provider settings and ensure required fields (provider, apiKeyEnv) are set.",
+                docUrl: docUrl(code),
+            };
+        case "STT_FAILED":
+            return {
+                suggestion: "Speech-to-text transcription failed. Check the audio format, API key, and provider availability.",
+                docUrl: docUrl(code),
+            };
+        case "TTS_FAILED":
+            return {
+                suggestion: "Text-to-speech synthesis failed. Check the TTS provider configuration and API key.",
+                docUrl: docUrl(code),
+            };
+        case "PII_DETECTED":
+            return {
+                suggestion: "Personally identifiable information was detected in the message. Configure allowlist in safety.pii.allowlist or adjust the action.",
+                docUrl: docUrl(code),
+            };
+        case "CONTENT_POLICY_VIOLATED":
+            return {
+                suggestion: "Message content violated the content safety policy. Review the content categories and thresholds in safety.content.categories.",
+                docUrl: docUrl(code),
+            };
+        case "SAFETY_RAIL_BLOCKED":
+            return {
+                suggestion: "A safety rail blocked the message. Check the rail configuration in safety.rails to adjust blocked topics or responses.",
+                docUrl: docUrl(code),
+            };
+        case "SAFETY_SCAN_FAILED":
+            return {
+                suggestion: "The safety scan encountered an error. This is non-fatal -- the pipeline uses fail-open behavior for deep scans.",
+                docUrl: docUrl(code),
+            };
+        case "INTERNAL_ERROR":
+            return {
+                suggestion: "An unexpected internal error occurred. If this persists, please file an issue.",
+                docUrl: docUrl(code),
+            };
+    }
+}
+//# sourceMappingURL=error-catalog.js.map

package/dist/engine/error-catalog.js.map

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

package/dist/engine/errors.d.ts

@@ -0,0 +1,18 @@
+/** Error codes for all Kiln errors. Grouped by bounded context. */
+export type KilnErrorCode = "APP_YAML_INVALID" | "PRESET_LOAD_FAILED" | "GATEWAY_YAML_INVALID" | "MODE_B_CONFIG_INVALID" | "DOMAIN_YAML_INVALID" | "DOMAIN_KIT_INVALID" | "TENANT_NOT_FOUND" | "TENANT_VALIDATION_FAILED" | "PROVIDER_UNAVAILABLE" | "PROVIDER_RATE_LIMITED" | "PROVIDER_AUTH_FAILED" | "BUDGET_CHECK_FAILED" | "BUDGET_EXCEEDED" | "CONFIG_MISSING_ENV" | "CONFIG_INVALID" | "CIRCUIT_OPEN" | "GUARDRAIL_FAILED" | "STRUCTURED_OUTPUT_INVALID" | "HANDOFF_FAILED" | "INTERRUPT_TIMEOUT" | "INJECTION_DETECTED" | "GUARDIAN_BLOCKED" | "GUARDIAN_UNAVAILABLE" | "SECRET_DECRYPTION_FAILED" | "SECRET_NOT_FOUND" | "AUDIT_WRITE_FAILED" | "AUDIT_CHAIN_BROKEN" | "TENANT_ISOLATION_VIOLATED" | "UNAUTHORIZED" | "FORBIDDEN" | "RATE_LIMIT_EXCEEDED" | "SKILL_YAML_INVALID" | "SKILL_NOT_FOUND" | "PACKAGE_YAML_INVALID" | "TRIGGER_FAILED" | "WEBHOOK_VALIDATION_FAILED" | "SCHEDULE_PARSE_FAILED" | "EVAL_YAML_INVALID" | "EVAL_DATASET_NOT_FOUND" | "EVAL_DATASET_INVALID" | "EVAL_SCORER_FAILED" | "EVAL_EXPERIMENT_FAILED" | "A2A_INVALID_REQUEST" | "A2A_TASK_NOT_FOUND" | "A2A_TASK_FAILED" | "A2A_CLIENT_FAILED" | "MCP_CONNECTION_FAILED" | "MCP_DISCOVERY_FAILED" | "MCP_SERVER_ERROR" | "TOOL_RAG_FAILED" | "UNSUPPORTED_MODALITY" | "CONTENT_PART_INVALID" | "VOICE_CONFIG_INVALID" | "STT_FAILED" | "TTS_FAILED" | "PII_DETECTED" | "CONTENT_POLICY_VIOLATED" | "SAFETY_RAIL_BLOCKED" | "SAFETY_SCAN_FAILED" | "INTERNAL_ERROR";
+/** Base error for all Kiln errors. Provides code, context, retryable flag, and developer hints. */
+export declare class KilnError extends Error {
+    readonly code: KilnErrorCode;
+    readonly context: Record<string, unknown>;
+    readonly retryable: boolean;
+    readonly suggestion?: string;
+    readonly docUrl?: string;
+    constructor(code: KilnErrorCode, message: string, options?: {
+        context?: Record<string, unknown>;
+        retryable?: boolean;
+        cause?: unknown;
+        suggestion?: string;
+        docUrl?: string;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/engine/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAGA,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAErB,kBAAkB,GAClB,oBAAoB,GACpB,sBAAsB,GACtB,uBAAuB,GAEvB,qBAAqB,GAErB,oBAAoB,GAEpB,kBAAkB,GAClB,0BAA0B,GAE1B,sBAAsB,GACtB,uBAAuB,GACvB,sBAAsB,GAEtB,qBAAqB,GACrB,iBAAiB,GAEjB,oBAAoB,GACpB,gBAAgB,GAEhB,cAAc,GAEd,kBAAkB,GAClB,2BAA2B,GAC3B,gBAAgB,GAChB,mBAAmB,GAEnB,oBAAoB,GACpB,kBAAkB,GAClB,sBAAsB,GACtB,0BAA0B,GAC1B,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,GACpB,2BAA2B,GAC3B,cAAc,GACd,WAAW,GACX,qBAAqB,GAErB,oBAAoB,GACpB,iBAAiB,GAEjB,sBAAsB,GAEtB,gBAAgB,GAChB,2BAA2B,GAC3B,uBAAuB,GAEvB,mBAAmB,GACnB,wBAAwB,GACxB,sBAAsB,GACtB,oBAAoB,GACpB,wBAAwB,GAExB,qBAAqB,GACrB,oBAAoB,GACpB,iBAAiB,GACjB,mBAAmB,GACnB,uBAAuB,GACvB,sBAAsB,GACtB,kBAAkB,GAClB,iBAAiB,GAEjB,sBAAsB,GACtB,sBAAsB,GACtB,sBAAsB,GACtB,YAAY,GACZ,YAAY,GAEZ,cAAc,GACd,yBAAyB,GACzB,qBAAqB,GACrB,oBAAoB,GAEpB,gBAAgB,CAAC;AAErB,mGAAmG;AACnG,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAGvB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;CAUJ"}

package/dist/engine/errors.js

@@ -0,0 +1,20 @@
+// KilnError: unified error hierarchy for all Kiln errors
+// Provides code, context, and retryable flag for consistent error handling
+/** Base error for all Kiln errors. Provides code, context, retryable flag, and developer hints. */
+export class KilnError extends Error {
+    code;
+    context;
+    retryable;
+    suggestion;
+    docUrl;
+    constructor(code, message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = "KilnError";
+        this.code = code;
+        this.context = options?.context ?? {};
+        this.retryable = options?.retryable ?? false;
+        this.suggestion = options?.suggestion;
+        this.docUrl = options?.docUrl;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/engine/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,2EAA2E;AAmF3E,mGAAmG;AACnG,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAgB;IACpB,OAAO,CAA0B;IACjC,SAAS,CAAU;IACnB,UAAU,CAAU;IACpB,MAAM,CAAU;IAEzB,YACE,IAAmB,EACnB,OAAe,EACf,OAMC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,KAAK,CAAC;QAC7C,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,UAAU,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAChC,CAAC;CACF"}

package/dist/engine/gateway/delegation-config.d.ts

@@ -0,0 +1,52 @@
+import type { Capability } from "../domain/capability.js";
+/** Error codes for delegation failures */
+export type DelegationErrorCode = "TIMEOUT" | "SCHEMA_VALIDATION_FAILED" | "TARGET_APP_NOT_FOUND" | "TARGET_APP_NOT_READY" | "PROVIDER_ERROR";
+/** A cross-app delegation request */
+export interface AppDelegation {
+    readonly fromApp: string;
+    readonly toApp: string;
+    readonly task: string;
+    readonly schema: Record<string, unknown>;
+    readonly context?: string;
+    readonly priority?: number;
+    readonly timeout?: number;
+}
+/** Token usage reported after a delegation call */
+export interface DelegationTokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cacheReadTokens: number;
+    readonly cacheWriteTokens: number;
+}
+/** Successful result of a delegation call */
+export interface AppDelegationResult {
+    readonly delegationId: string;
+    readonly fromApp: string;
+    readonly toApp: string;
+    readonly result: Record<string, unknown>;
+    readonly tokenUsage: DelegationTokenUsage;
+    readonly durationMs: number;
+}
+/** Error returned when a delegation call fails */
+export interface DelegationError {
+    readonly code: DelegationErrorCode;
+    readonly message: string;
+    readonly delegationId?: string;
+    readonly fromApp?: string;
+    readonly toApp?: string;
+}
+/** Validation error for an AppDelegation */
+export interface DelegationValidationError {
+    readonly field: string;
+    readonly message: string;
+}
+/**
+ * Type guard: returns true when the capability is a delegation capability.
+ * Requires type === "delegation", non-empty targetApp, and non-empty task.
+ */
+export declare function isDelegationCapability(cap: Capability): boolean;
+/**
+ * Validate an AppDelegation. Returns an array of errors; empty means valid.
+ */
+export declare function validateDelegation(delegation: AppDelegation): DelegationValidationError[];
+//# sourceMappingURL=delegation-config.d.ts.map

package/dist/engine/gateway/delegation-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-config.d.ts","sourceRoot":"","sources":["../../../src/engine/gateway/delegation-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,0BAA0B,GAC1B,sBAAsB,GACtB,sBAAsB,GACtB,gBAAgB,CAAC;AAErB,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAQ/D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,aAAa,GAAG,yBAAyB,EAAE,CA2CzF"}

package/dist/engine/gateway/delegation-config.js

@@ -0,0 +1,48 @@
+// Engine type: Delegation -- cross-app cognitive delegation (Phase 24)
+/**
+ * Type guard: returns true when the capability is a delegation capability.
+ * Requires type === "delegation", non-empty targetApp, and non-empty task.
+ */
+export function isDelegationCapability(cap) {
+    return (cap.type === "delegation" &&
+        typeof cap.targetApp === "string" &&
+        cap.targetApp !== "" &&
+        typeof cap.task === "string" &&
+        cap.task !== "");
+}
+/**
+ * Validate an AppDelegation. Returns an array of errors; empty means valid.
+ */
+export function validateDelegation(delegation) {
+    const errors = [];
+    if (!delegation.fromApp || delegation.fromApp === "") {
+        errors.push({ field: "fromApp", message: "must be a non-empty string" });
+    }
+    if (!delegation.toApp || delegation.toApp === "") {
+        errors.push({ field: "toApp", message: "must be a non-empty string" });
+    }
+    if (delegation.fromApp &&
+        delegation.toApp &&
+        delegation.fromApp !== "" &&
+        delegation.toApp !== "" &&
+        delegation.fromApp === delegation.toApp) {
+        errors.push({ field: "toApp", message: "self-delegation is not allowed (fromApp === toApp)" });
+    }
+    if (!delegation.task || delegation.task === "") {
+        errors.push({ field: "task", message: "must be a non-empty string" });
+    }
+    if (delegation.schema === null ||
+        delegation.schema === undefined ||
+        typeof delegation.schema !== "object" ||
+        Array.isArray(delegation.schema)) {
+        errors.push({ field: "schema", message: "must be a non-null, non-array object" });
+    }
+    if (delegation.timeout !== undefined && delegation.timeout <= 0) {
+        errors.push({ field: "timeout", message: "must be greater than 0" });
+    }
+    if (delegation.priority !== undefined && (delegation.priority < 0 || delegation.priority > 10)) {
+        errors.push({ field: "priority", message: "must be between 0 and 10" });
+    }
+    return errors;
+}
+//# sourceMappingURL=delegation-config.js.map

package/dist/engine/gateway/delegation-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-config.js","sourceRoot":"","sources":["../../../src/engine/gateway/delegation-config.ts"],"names":[],"mappings":"AAAA,uEAAuE;AAwDvE;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAe;IACpD,OAAO,CACL,GAAG,CAAC,IAAI,KAAK,YAAY;QACzB,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QACjC,GAAG,CAAC,SAAS,KAAK,EAAE;QACpB,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAC5B,GAAG,CAAC,IAAI,KAAK,EAAE,CAChB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,UAAyB;IAC1D,MAAM,MAAM,GAAgC,EAAE,CAAC;IAE/C,IAAI,CAAC,UAAU,CAAC,OAAO,IAAI,UAAU,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,IACE,UAAU,CAAC,OAAO;QAClB,UAAU,CAAC,KAAK;QAChB,UAAU,CAAC,OAAO,KAAK,EAAE;QACzB,UAAU,CAAC,KAAK,KAAK,EAAE;QACvB,UAAU,CAAC,OAAO,KAAK,UAAU,CAAC,KAAK,EACvC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,oDAAoD,EAAE,CAAC,CAAC;IACjG,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,UAAU,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,IACE,UAAU,CAAC,MAAM,KAAK,IAAI;QAC1B,UAAU,CAAC,MAAM,KAAK,SAAS;QAC/B,OAAO,UAAU,CAAC,MAAM,KAAK,QAAQ;QACrC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAChC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,UAAU,CAAC,OAAO,KAAK,SAAS,IAAI,UAAU,CAAC,OAAO,IAAI,CAAC,EAAE,CAAC;QAChE,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,UAAU,CAAC,QAAQ,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/F,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}