@purista/harness 1.0.0

package/dist/errors/catalog.d.ts

@@ -0,0 +1,185 @@
+import { HarnessError } from './harness-error.js';
+/** Configuration validation and assembly failures. */
+export declare class HarnessConfigError extends HarnessError {
+    constructor(message: string, meta: {
+        reason: string;
+        path?: string;
+        id?: string;
+    }, cause?: unknown);
+}
+/** Harness validation failures for inputs, outputs, and payload schemas. */
+export declare class ValidationError extends HarnessError {
+    constructor(message: string, meta: {
+        where: 
+        /** Agent input schema validation failed. */ 'agent_input'
+        /** Agent output schema validation failed. */  | 'agent_output'
+        /** Workflow input schema validation failed. */  | 'workflow_input'
+        /** Workflow output schema validation failed. */  | 'workflow_output'
+        /** Tool input schema validation failed. */  | 'tool_input'
+        /** Tool output schema validation failed. */  | 'tool_output'
+        /** MCP request schema validation failed. */  | 'mcp_input'
+        /** MCP response schema validation failed. */  | 'mcp_output'
+        /** Model provider response shape is invalid. */  | 'model_response'
+        /** Session memory key is invalid. */  | 'memory_key'
+        /** Session memory value is invalid or non-serializable. */  | 'memory_value'
+        /** Message envelope validation failed. */  | 'message'
+        /** Session history shape validation failed. */  | 'session_history'
+        /** Invocation options are invalid. */  | 'invoke_options';
+        issues: unknown;
+    }, cause?: unknown);
+}
+/** Tool execution denied by policy or approval hook. */
+export declare class PermissionDeniedError extends HarnessError {
+    constructor(message: string, meta: {
+        tool_name: string;
+        agent_id: string;
+        reason?: 'mode_deny' | 'hook_deny' | 'hook_failed';
+    }, cause?: unknown);
+}
+/** Sandbox filesystem or command execution failed. */
+export declare class SandboxError extends HarnessError {
+    constructor(message: string, meta: {
+        reason: 'invalid_path' | 'exec_failed' | 'fs_failed' | string;
+        stdout?: string;
+        stderr?: string;
+    }, cause?: unknown);
+}
+/** Sandbox session has no command executor available. */
+export declare class SandboxNoExecutorError extends HarnessError {
+    constructor(message: string, meta: {
+        session_id: string;
+    }, cause?: unknown);
+}
+/** Model/provider call failed or returned unsupported output shape. */
+export declare class ModelError extends HarnessError {
+    constructor(message: string, meta: {
+        provider: string;
+        model: string;
+        method: string;
+        status?: number;
+        reason?: 'http_error' | 'network' | 'unstructured_response' | 'malformed_response' | 'context_length_exceeded';
+        providerCode?: string;
+        providerType?: string;
+        providerParam?: string;
+        providerRequestId?: string;
+        providerMessage?: string;
+        providerBody?: unknown;
+        providerHeaders?: Record<string, string>;
+    }, cause?: unknown);
+}
+/** Requested model capability is not available for alias/provider method. */
+export declare class ModelCapabilityError extends HarnessError {
+    constructor(message: string, meta: {
+        alias: string;
+        method: string;
+        reason: 'missing_capability' | 'method_missing';
+    }, cause?: unknown);
+}
+/** Tool execution failed with wrapped/normalized cause information. */
+export declare class ToolError extends HarnessError {
+    constructor(message: string, meta: {
+        tool_id: string;
+        tool_kind: string;
+    }, cause?: unknown);
+}
+/** Tool reference was not found in registry, allowlist, or model response mapping. */
+export declare class ToolNotFoundError extends HarnessError {
+    constructor(message: string, meta: {
+        tool_id: string;
+        where: 'registry' | 'agent_allowlist' | 'model_response';
+    }, cause?: unknown);
+}
+/** Skill id was not found in configured skill set. */
+export declare class SkillNotFoundError extends HarnessError {
+    constructor(message: string, meta: {
+        skill_id: string;
+    }, cause?: unknown);
+}
+/** Skill manifest/frontmatter/config validation failure. */
+export declare class SkillManifestError extends HarnessError {
+    constructor(message: string, meta: {
+        directory: string;
+        reason: 'missing_skill_md' | 'invalid_frontmatter' | 'name_mismatch' | 'directory_missing' | 'reserved_name';
+        skill_id?: string;
+    }, cause?: unknown);
+}
+/** Workflow referenced an unknown agent id. */
+export declare class AgentNotFoundError extends HarnessError {
+    constructor(message: string, meta: {
+        agent_id: string;
+    }, cause?: unknown);
+}
+/** Agent exceeded configured loop iteration/step budget. */
+export declare class AgentLoopBudgetError extends HarnessError {
+    constructor(message: string, meta: {
+        agent_id: string;
+        reason: 'iterations_exceeded';
+        limit: number;
+    }, cause?: unknown);
+}
+/** Session attempted to invoke unknown workflow id. */
+export declare class WorkflowNotFoundError extends HarnessError {
+    constructor(message: string, meta: {
+        workflow_id: string;
+    }, cause?: unknown);
+}
+/** Session id not found in backing store. */
+export declare class SessionNotFoundError extends HarnessError {
+    constructor(message: string, meta: {
+        session_id: string;
+    }, cause?: unknown);
+}
+/** Session is currently busy and cannot accept concurrent mutation/run operations. */
+export declare class SessionBusyError extends HarnessError {
+    constructor(message: string, meta: {
+        session_id: string;
+        reason?: 'concurrent_run' | 'history_clear_during_run' | 'history_replace_during_run';
+    }, cause?: unknown);
+}
+/** State backend operation failed. */
+export declare class StateError extends HarnessError {
+    constructor(message: string, meta: {
+        op: 'getSession' | 'upsertSession' | 'closeSession' | 'appendMessages' | 'listMessages' | 'clearMessages' | 'createRun' | 'finishRun' | 'getRun' | 'listRuns' | 'appendEvents' | 'listEvents';
+        reason?: 'duplicate_message_id' | string;
+    }, cause?: unknown);
+}
+/** Timed execution budget expired. */
+export declare class OperationTimeoutError extends HarnessError {
+    constructor(message: string, meta: {
+        scope: 'run' | 'model' | 'tool' | 'sandbox_run';
+        timeout_ms: number;
+    }, cause?: unknown);
+}
+/** Operation cancelled by abort signal or explicit cancellation path. */
+export declare class OperationCancelledError extends HarnessError {
+    constructor(message: string, meta: {
+        scope: 'run' | 'workflow' | 'agent' | 'model' | 'tool' | 'sandbox';
+    }, cause?: unknown);
+}
+/** MCP transport/protocol failure. */
+export declare class McpProtocolError extends HarnessError {
+    constructor(message: string, meta: {
+        tool_id: string;
+        transport: 'stdio' | 'http';
+        phase: 'connect' | 'list' | 'call';
+    }, cause?: unknown);
+}
+/** Supported MCP HTTP authentication kinds. */
+export type McpAuthKind = 
+/** No authentication. */ 'none'
+/** Bearer token auth. */  | 'bearer'
+/** OAuth2 access token auth. */  | 'oauth2'
+/** API key auth. */  | 'api_key'
+/** Basic auth. */  | 'basic';
+/** MCP authentication/authorization failure. */
+export declare class McpAuthError extends HarnessError {
+    constructor(message: string, meta: {
+        tool_id: string;
+        auth_kind: McpAuthKind;
+        status?: number;
+    }, cause?: unknown);
+}
+/** Unexpected internal harness invariant failure. */
+export declare class InternalError extends HarnessError {
+    constructor(message: string, meta?: Record<string, unknown>, cause?: unknown);
+}

package/dist/errors/catalog.js

@@ -0,0 +1,144 @@
+import { HarnessError } from './harness-error.js';
+/** Configuration validation and assembly failures. */
+export class HarnessConfigError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'HARNESS_CONFIG_ERROR', category: 'config', retriable: false, message, meta, cause });
+    }
+}
+/** Harness validation failures for inputs, outputs, and payload schemas. */
+export class ValidationError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'VALIDATION_ERROR', category: 'validation', retriable: false, message, meta, cause });
+    }
+}
+/** Tool execution denied by policy or approval hook. */
+export class PermissionDeniedError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'PERMISSION_DENIED', category: 'permission', retriable: false, message, meta, cause });
+    }
+}
+/** Sandbox filesystem or command execution failed. */
+export class SandboxError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'SANDBOX_ERROR', category: 'sandbox', retriable: true, message, meta, cause });
+    }
+}
+/** Sandbox session has no command executor available. */
+export class SandboxNoExecutorError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'SANDBOX_NO_EXECUTOR', category: 'sandbox', retriable: false, message, meta, cause });
+    }
+}
+/** Model/provider call failed or returned unsupported output shape. */
+export class ModelError extends HarnessError {
+    constructor(message, meta, cause) {
+        const retriable = meta.reason === 'network'
+            || meta.status === 429
+            || (typeof meta.status === 'number' && meta.status >= 500);
+        super({ code: 'MODEL_ERROR', category: 'model', retriable, message, meta, cause });
+    }
+}
+/** Requested model capability is not available for alias/provider method. */
+export class ModelCapabilityError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'MODEL_CAPABILITY_ERROR', category: 'model', retriable: false, message, meta, cause });
+    }
+}
+/** Tool execution failed with wrapped/normalized cause information. */
+export class ToolError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({
+            code: 'TOOL_ERROR',
+            category: 'tool',
+            retriable: cause instanceof HarnessError ? cause.retriable : false,
+            message,
+            meta,
+            cause
+        });
+    }
+}
+/** Tool reference was not found in registry, allowlist, or model response mapping. */
+export class ToolNotFoundError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'TOOL_NOT_FOUND', category: 'tool', retriable: false, message, meta, cause });
+    }
+}
+/** Skill id was not found in configured skill set. */
+export class SkillNotFoundError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'SKILL_NOT_FOUND', category: 'skill', retriable: false, message, meta, cause });
+    }
+}
+/** Skill manifest/frontmatter/config validation failure. */
+export class SkillManifestError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'SKILL_MANIFEST_ERROR', category: 'config', retriable: false, message, meta, cause });
+    }
+}
+/** Workflow referenced an unknown agent id. */
+export class AgentNotFoundError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'AGENT_NOT_FOUND', category: 'validation', retriable: false, message, meta, cause });
+    }
+}
+/** Agent exceeded configured loop iteration/step budget. */
+export class AgentLoopBudgetError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'AGENT_LOOP_BUDGET_EXCEEDED', category: 'validation', retriable: false, message, meta, cause });
+    }
+}
+/** Session attempted to invoke unknown workflow id. */
+export class WorkflowNotFoundError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'WORKFLOW_NOT_FOUND', category: 'validation', retriable: false, message, meta, cause });
+    }
+}
+/** Session id not found in backing store. */
+export class SessionNotFoundError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'SESSION_NOT_FOUND', category: 'session', retriable: false, message, meta, cause });
+    }
+}
+/** Session is currently busy and cannot accept concurrent mutation/run operations. */
+export class SessionBusyError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'SESSION_BUSY', category: 'session', retriable: true, message, meta, cause });
+    }
+}
+/** State backend operation failed. */
+export class StateError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'STATE_ERROR', category: 'state', retriable: true, message, meta, cause });
+    }
+}
+/** Timed execution budget expired. */
+export class OperationTimeoutError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'OPERATION_TIMEOUT', category: 'timeout', retriable: true, message, meta, cause });
+    }
+}
+/** Operation cancelled by abort signal or explicit cancellation path. */
+export class OperationCancelledError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'OPERATION_CANCELLED', category: 'cancelled', retriable: false, message, meta, cause });
+    }
+}
+/** MCP transport/protocol failure. */
+export class McpProtocolError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'MCP_PROTOCOL_ERROR', category: 'tool', retriable: true, message, meta, cause });
+    }
+}
+/** MCP authentication/authorization failure. */
+export class McpAuthError extends HarnessError {
+    constructor(message, meta, cause) {
+        const retriable = typeof meta.status === 'number' ? meta.status >= 500 : false;
+        super({ code: 'MCP_AUTH_ERROR', category: 'tool', retriable, message, meta, cause });
+    }
+}
+/** Unexpected internal harness invariant failure. */
+export class InternalError extends HarnessError {
+    constructor(message, meta, cause) {
+        super({ code: 'INTERNAL_ERROR', category: 'internal', retriable: false, message, ...(meta ? { meta } : {}), cause });
+    }
+}

package/dist/errors/harness-error.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Canonical harness error categories.
+ *
+ * Use these values for machine-readable error routing and operational dashboards.
+ */
+export type ErrorCategory = 
+/** Invalid or inconsistent harness configuration. */
+'config'
+/** Input/output validation failures. */
+ | 'validation'
+/** Permission and approval denials. */
+ | 'permission'
+/** Sandbox filesystem or execution failures. */
+ | 'sandbox'
+/** Model/provider invocation failures. */
+ | 'model'
+/** Tool execution failures. */
+ | 'tool'
+/** Skill discovery, loading, or manifest failures. */
+ | 'skill'
+/** Session lifecycle failures. */
+ | 'session'
+/** State-store persistence failures. */
+ | 'state'
+/** Timeout budget failures. */
+ | 'timeout'
+/** Cooperative cancellation events. */
+ | 'cancelled'
+/** Unclassified internal harness bugs. */
+ | 'internal';
+/** Construction options for {@link HarnessError}. */
+export interface HarnessErrorOptions {
+    code: string;
+    category: ErrorCategory;
+    message: string;
+    retriable: boolean;
+    meta?: Record<string, unknown>;
+    cause?: unknown;
+}
+/**
+ * Base class for all exported harness errors.
+ *
+ * Carries stable machine-readable fields (`code`, `category`, `retriable`, `meta`) for
+ * API mapping, log processing, and operator automation.
+ */
+export declare class HarnessError extends Error {
+    readonly code: string;
+    readonly category: ErrorCategory;
+    readonly retriable: boolean;
+    readonly meta: Record<string, unknown> | undefined;
+    readonly cause: unknown;
+    constructor(opts: HarnessErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/** Harness type guard for {@link HarnessError}. */
+export declare function isHarnessError(value: unknown): value is HarnessError;
+/** Converts unknown thrown values into a stable serializable error envelope. */
+export declare function serializeError(error: unknown): {
+    code: string;
+    category: string;
+    retriable: boolean;
+    message: string;
+    meta?: Record<string, unknown>;
+};

package/dist/errors/harness-error.js

@@ -0,0 +1,58 @@
+import { sanitizeMeta } from './redaction.js';
+/**
+ * Base class for all exported harness errors.
+ *
+ * Carries stable machine-readable fields (`code`, `category`, `retriable`, `meta`) for
+ * API mapping, log processing, and operator automation.
+ */
+export class HarnessError extends Error {
+    code;
+    category;
+    retriable;
+    meta;
+    cause;
+    constructor(opts) {
+        super(opts.message, { cause: opts.cause });
+        this.name = new.target.name;
+        this.code = opts.code;
+        this.category = opts.category;
+        this.retriable = opts.retriable;
+        this.meta = opts.meta;
+        this.cause = opts.cause;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            category: this.category,
+            retriable: this.retriable,
+            message: this.message,
+            ...(this.meta ? { meta: sanitizeMeta(this.meta) } : {})
+        };
+    }
+}
+/** Harness type guard for {@link HarnessError}. */
+export function isHarnessError(value) {
+    return value instanceof HarnessError;
+}
+/** Converts unknown thrown values into a stable serializable error envelope. */
+export function serializeError(error) {
+    if (error instanceof HarnessError) {
+        const serialized = {
+            code: error.code,
+            category: error.category,
+            retriable: error.retriable,
+            message: error.message
+        };
+        const meta = sanitizeMeta(error.meta);
+        if (meta)
+            serialized.meta = meta;
+        return serialized;
+    }
+    return {
+        code: 'INTERNAL_ERROR',
+        category: 'internal',
+        retriable: false,
+        message: error instanceof Error ? error.message : String(error)
+    };
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,3 @@
+export * from './harness-error.js';
+export * from './catalog.js';
+export * from './redaction.js';

package/dist/errors/index.js

@@ -0,0 +1,3 @@
+export * from './harness-error.js';
+export * from './catalog.js';
+export * from './redaction.js';

package/dist/errors/redaction.d.ts

@@ -0,0 +1,5 @@
+export type RedactionMode = 'log' | 'provider_body';
+export declare function sanitizeForLog(value: unknown): unknown;
+export declare function sanitizeProviderBody(value: unknown): unknown;
+export declare function sanitizeMeta(meta: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+export declare function sanitizeProviderMessage(message: string): string;

package/dist/errors/redaction.js

@@ -0,0 +1,64 @@
+const REDACTED = '[redacted]';
+const TRUNCATED = '[truncated]';
+const SENSITIVE_KEY_PATTERN = /(?:^|[-_.])(authorization|cookie|set-cookie|token|accesstoken|refreshtoken|apikey|api_key|x-api-key|secret|password|credential|privatekey|clientsecret)(?:$|[-_.])/i;
+const CONTENT_KEY_PATTERN = /^(prompt|prompts|messages|input|inputs|output|outputs|content|contents|text|data|body)$/i;
+const SAFE_PROVIDER_ERROR_KEYS = new Set(['code', 'type', 'param', 'message']);
+export function sanitizeForLog(value) {
+    return sanitizeValue(value, { mode: 'log', seen: new WeakSet(), depth: 0 });
+}
+export function sanitizeProviderBody(value) {
+    return sanitizeValue(value, { mode: 'provider_body', seen: new WeakSet(), depth: 0 });
+}
+export function sanitizeMeta(meta) {
+    const sanitized = sanitizeForLog(meta);
+    return isRecord(sanitized) ? sanitized : undefined;
+}
+export function sanitizeProviderMessage(message) {
+    return redactString(message).slice(0, 500);
+}
+function sanitizeValue(value, opts) {
+    if (opts.key && isSensitiveKey(opts.key))
+        return REDACTED;
+    if (opts.mode === 'provider_body' && opts.key && isContentKey(opts.key) && !SAFE_PROVIDER_ERROR_KEYS.has(opts.key))
+        return REDACTED;
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'string')
+        return redactString(value).slice(0, 4000);
+    if (typeof value === 'symbol' || typeof value === 'function')
+        return String(value).slice(0, 4000);
+    if (opts.depth >= 4)
+        return TRUNCATED;
+    if (Array.isArray(value))
+        return value.slice(0, 20).map((item) => sanitizeValue(item, { mode: opts.mode, seen: opts.seen, depth: opts.depth + 1 }));
+    if (!isRecord(value))
+        return String(value).slice(0, 4000);
+    if (opts.seen.has(value))
+        return '[circular]';
+    opts.seen.add(value);
+    const out = {};
+    for (const [key, item] of Object.entries(value).slice(0, 40)) {
+        out[key] = sanitizeValue(item, { ...opts, depth: opts.depth + 1, key });
+    }
+    opts.seen.delete(value);
+    return out;
+}
+function redactString(value) {
+    return value
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [redacted]')
+        .replace(/\bBasic\s+[A-Za-z0-9+/=-]+/gi, 'Basic [redacted]')
+        .replace(/\b(sk|pk|rk|sess|key|token|secret)_[A-Za-z0-9._-]{8,}/gi, '$1_[redacted]');
+}
+function isSensitiveKey(key) {
+    return SENSITIVE_KEY_PATTERN.test(key.replace(/[A-Z]/g, (char) => `_${char.toLowerCase()}`));
+}
+function isContentKey(key) {
+    return CONTENT_KEY_PATTERN.test(key);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}