@sensigo/realm 0.1.0

package/dist/types/workflow-definition.d.ts

@@ -0,0 +1,292 @@
+import type { McpServerConfig } from './mcp-types.js';
+export type ExecutionMode = 'auto' | 'agent';
+export interface ProtocolConfig {
+    /** Override for the generated quick-start paragraph. */
+    quick_start?: string;
+    /** Behavioral rules injected verbatim into the agent protocol. */
+    rules?: string[];
+}
+export type TrustLevel = 'auto' | 'human_notified' | 'human_confirmed' | 'human_reviewed';
+export type ServiceTrust = 'engine_delivered' | 'engine_managed' | 'agent_provided';
+export interface JsonSchema {
+    type?: string;
+    required?: string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    [key: string]: unknown;
+}
+export interface RateLimitConfig {
+    /** Maximum number of requests per second. Used as the token refill rate. */
+    requests_per_second?: number;
+    /** Initial token capacity (burst). Defaults to requests_per_second if omitted. */
+    burst?: number;
+    /**
+     * Fallback retry-after delay (seconds) when the service returns HTTP 429 with no header.
+     * Overrides adapter.defaultRetryAfterSeconds when set.
+     */
+    fallback_retry_seconds?: number;
+    /**
+     * Maximum retry-after window (seconds). When the resolved retry_after exceeds this value,
+     * the step fails immediately with agentAction: 'report_to_user' instead of waiting.
+     */
+    max_retry_seconds?: number;
+}
+export interface ServiceDefinition {
+    adapter: string;
+    auth?: {
+        token_from: string;
+    };
+    trust: ServiceTrust;
+    rate_limit?: RateLimitConfig;
+}
+/** A single parameter declaration in a template. */
+export interface TemplateParam {
+    required?: boolean;
+    default?: string;
+}
+/** A named reusable step group with parameter placeholders. */
+export interface TemplateDefinition {
+    params?: Record<string, TemplateParam>;
+    steps: Record<string, StepDefinition>;
+}
+export interface RetryConfig {
+    max_attempts: number;
+    backoff?: 'linear' | 'exponential' | 'fixed';
+    base_delay_ms?: number;
+    /** Cap on the computed backoff delay. When set, no single delay exceeds this value. */
+    max_delay_ms?: number;
+}
+/**
+ * Controls when a step becomes eligible based on its dependencies' outcomes.
+ * Default: 'all_success'.
+ */
+export type TriggerRule = 'all_success' | 'all_failed' | 'all_done' | 'one_failed' | 'one_success' | 'none_failed';
+export interface StepDefinition {
+    description: string;
+    execution: ExecutionMode;
+    /**
+     * Step IDs this step waits for. Empty array or omitted = eligible from run start
+     * (first tier of the DAG).
+     */
+    depends_on?: string[];
+    /**
+     * When to evaluate dependency satisfaction. Default: 'all_success'.
+     */
+    trigger_rule?: TriggerRule;
+    /**
+     * Optional condition expression evaluated against prior step evidence.
+     * Step is ineligible until this expression is truthy.
+     * Uses the same dot-path syntax as input_map.
+     * Example: "context.resources.classifier.category == 'billing'"
+     */
+    when?: string;
+    uses_service?: string;
+    /**
+     * Which adapter method to invoke for this service step.
+     * Defaults to 'fetch' if omitted.
+     */
+    service_method?: 'fetch' | 'create' | 'update' | 'delete';
+    /**
+     * Operation name passed as the first argument to the adapter method.
+     * Defaults to the step name if omitted.
+     */
+    operation?: string;
+    /**
+     * Static path-mapping that assembles this step's adapter params from run state.
+     * Each key is the param name passed to the adapter; each value is a dot-path:
+     *   run.params.FIELD            — from the run's initial params
+     *   context.resources.STEP.FIELD — from a prior step's evidence output
+     * Only valid on execution: 'auto' steps with uses_service.
+     */
+    input_map?: Record<string, string>;
+    handler?: string;
+    /**
+     * Static key-value configuration passed to the step handler via context.config.
+     * Only meaningful on execution: auto steps with a handler declaration.
+     */
+    config?: Record<string, unknown>;
+    input_schema?: JsonSchema;
+    /**
+     * Validates the agent's submitted output (the params passed to `execute_step`)
+     * against this JSON Schema before the engine claims the step.
+     * Only valid on `execution: 'agent'` steps. Declaring `output_schema` on an
+     * `execution: 'auto'` step is a loader error.
+     *
+     * Validation runs pre-claim. If it fails the engine returns
+     * `agent_action: 'provide_input'` and the step remains unclaimed —
+     * the agent can correct its output and re-submit without side effects.
+     *
+     * For gate steps (`trust: 'human_confirmed'` or `trust: 'human_reviewed'`),
+     * the schema validates before the gate opens. `submitHumanResponse` commits
+     * the previewed payload unchanged — the human always sees a schema-conformant
+     * payload.
+     */
+    output_schema?: JsonSchema;
+    /**
+     * JSON Schema validated against the canonical stored trace entries for this step.
+     * Only valid on `execution: 'agent'` steps.
+     * When `trace_validation_mode` is `'enforce'`, invalid trace fails pre-claim and the
+     * step remains unclaimed. When `'warn'` (default), a warning is added to the envelope.
+     */
+    trace_schema?: JsonSchema;
+    /**
+     * Controls how `trace_schema` failures are handled.
+     * Default when `trace_schema` is set and mode is omitted: `'warn'`.
+     * Ignored when no `trace_schema` is declared.
+     */
+    trace_validation_mode?: 'warn' | 'enforce';
+    preconditions?: string[];
+    trust?: TrustLevel;
+    timeout_seconds?: number;
+    retry?: RetryConfig;
+    /** Plain-English instructions for the agent at this step. */
+    instructions?: string;
+    /**
+     * Template-resolved task prompt delivered to the agent at step entry via next_actions[].prompt.
+     * Supports {{ context.resources.STEP.FIELD }} and {{ run.params.FIELD }} references.
+     * For human_confirmed steps, delivered as gate.prompt when the gate opens.
+     */
+    prompt?: string;
+    /**
+     * Optional Jinja-style display template rendered by the CLI against this step's
+     * output_summary for human-readable terminal output. Uses {{ field }} syntax where
+     * field is a dot-path into the step's output object. When absent, the CLI falls
+     * back to the existing headline/message and JSON rendering behaviour.
+     * No engine evaluation — rendered client-side at run completion.
+     */
+    display?: string;
+    /**
+     * When present, this entry is a template instantiation rather than a concrete step.
+     * Resolved by loadWorkflowFromString before validation — never present in a
+     * WorkflowDefinition returned to callers.
+     */
+    use_template?: string;
+    /** Gate configuration — choices available to the human reviewer. */
+    gate?: {
+        choices?: string[];
+        /**
+         * Slack user ID or handle of the person responsible for resolving this gate.
+         * Used for notification targeting and escalation.
+         * Optional — notifications work without it.
+         * Example: '@mihai.lupu' or 'U012AB3CD'
+         */
+        owner?: string;
+        /**
+         * Developer-authored template string presented to the human reviewer when this gate opens.
+         * Supports {{ context.resources.STEP.FIELD }} and {{ run.params.FIELD }} references.
+         * Resolved from run data at gate-open time. Fail-fast: unresolvable references cause
+         * a stop error rather than opening a gate with broken placeholder text.
+         * When absent, the Slack path falls back to formatGatePreviewForSlack(preview)
+         * and the MCP path falls back to step.prompt resolution (existing behavior).
+         */
+        message?: string;
+        /**
+         * Per-choice messages posted to the Slack thread when the gate resolves via Slack.
+         * Keys must match entries in `choices`. Values are plain text (not mrkdwn templates).
+         * Optional — when absent or when a choice has no entry, the generic fallback is used.
+         * Example:
+         *   resolution_messages:
+         *     send: "✅ Incident report sent to #incidents."
+         *     reject: "❌ Draft discarded. Run will not continue."
+         */
+        resolution_messages?: Record<string, string>;
+    };
+    /** Name of the agent profile for this step. Only valid on execution: 'agent' steps. */
+    agent_profile?: string;
+    /**
+     * Allow-list of tools this step may invoke, in 'server_id:tool_name' format.
+     * Only valid on execution: 'agent' steps without a handler. Requires input_schema.
+     */
+    tools?: string[];
+    /**
+     * Maximum number of tool-call iterations before the agentic loop terminates.
+     * Default: 20 (applied at runtime).
+     */
+    max_tool_calls?: number;
+    /**
+     * Timeout in seconds for each individual tool call.
+     * Default: 30 (applied at runtime).
+     */
+    tool_timeout?: number;
+}
+export interface WorkflowDefinition {
+    id: string;
+    name: string;
+    version: number;
+    /** JSON Schema describing the params accepted by start_run. */
+    params_schema?: JsonSchema;
+    /** Optional protocol customizations — overrides generated sections. */
+    protocol?: ProtocolConfig;
+    services?: Record<string, ServiceDefinition>;
+    /** MCP server configurations available to tool-enabled steps in this workflow. */
+    mcp_servers?: McpServerConfig[];
+    /** Optional named step groups with {{ param }} placeholders; resolved at load time. */
+    templates?: Record<string, TemplateDefinition>;
+    steps: Record<string, StepDefinition>;
+    /** Optional: directory containing shared profile markdown files.
+     *  Resolved relative to the workflow YAML file at load time.
+     *  Falls back to <workflow-dir>/profiles/ if omitted. */
+    profiles_dir?: string;
+    /**
+     * Map of resolved profile content keyed by profile name.
+     * Populated by loadWorkflowFromFile — absent when loaded from string.
+     * Do not serialize/write to workflow YAML — this is a runtime-only field.
+     */
+    resolved_profiles?: Record<string, {
+        content: string;
+        content_hash: string;
+    }>;
+    /**
+     * Schema version stamped by the loader at registration time.
+     * Used by JsonWorkflowStore.get() to reject stale registrations.
+     * Runtime-only — not a user-facing YAML field.
+     */
+    schema_version?: number;
+    /**
+     * Named context entries available in all step prompts via {{ workflow.context.NAME }}.
+     * Loaded once at run start. Separate from step evidence.
+     * Paths are resolved to absolute at registration time by the YAML loader.
+     */
+    workflow_context?: Record<string, WorkflowContextEntry>;
+    /**
+     * Wrapper format applied to {{ workflow.context.NAME }} template references.
+     * Does not affect {{ workflow.context.NAME.raw }}.
+     * Default: 'xml'
+     */
+    context_wrapper?: ContextWrapperFormat;
+    /**
+     * How the workflow was originally created. Stamped at registration time — runtime-only.
+     * Never write to workflow YAML.
+     * 'human' — registered via YAML file (CLI register / watch).
+     * 'agent'  — created at runtime via the create_workflow MCP tool.
+     */
+    origin?: 'human' | 'agent';
+    /**
+     * LLM model identifier used to create this workflow (e.g. "claude-sonnet-4-6", "gpt-4o").
+     * Only meaningful when origin is 'agent'. Self-reported — not verified.
+     * Runtime-only — do not write to workflow YAML.
+     */
+    model?: string;
+    /**
+     * Orchestrating tool or framework that called create_workflow
+     * (e.g. "cursor", "github-copilot"). Only meaningful when origin is 'agent'.
+     * Self-reported — not verified.
+     * Runtime-only — do not write to workflow YAML.
+     */
+    agent?: string;
+}
+/** A single named entry in the workflow_context section. */
+export interface WorkflowContextEntry {
+    /** Absolute file path — resolved from the YAML-relative path at registration time. */
+    source: {
+        path: string;
+    };
+    /** Optional human-readable description of what this context contains. */
+    description?: string;
+}
+/** Wrapper format applied to {{ workflow.context.NAME }} template references. */
+export type ContextWrapperFormat = 'xml' | 'brackets' | 'none';
+//# sourceMappingURL=workflow-definition.d.ts.map

package/dist/types/workflow-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-definition.d.ts","sourceRoot":"","sources":["../../src/types/workflow-definition.ts"],"names":[],"mappings":"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"}

package/dist/types/workflow-definition.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workflow-definition.js.map

package/dist/types/workflow-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-definition.js","sourceRoot":"","sources":["../../src/types/workflow-definition.ts"],"names":[],"mappings":""}

package/dist/types/workflow-error.d.ts

@@ -0,0 +1,26 @@
+export type ErrorCategory = 'NETWORK' | 'SERVICE' | 'STATE' | 'VALIDATION' | 'ENGINE' | 'RESOURCE';
+export type AgentAction = 'report_to_user' | 'provide_input' | 'resolve_precondition' | 'stop' | 'wait_for_human' | 'wait_and_proceed';
+export type ErrorCode = 'NETWORK_TIMEOUT' | 'NETWORK_UNREACHABLE' | 'NETWORK_DNS_FAILED' | 'NETWORK_CONNECTION_RESET' | 'SERVICE_HTTP_4XX' | 'SERVICE_HTTP_5XX' | 'SERVICE_RATE_LIMITED' | 'SERVICE_AUTH_FAILED' | 'SERVICE_NOT_FOUND' | 'SERVICE_RESPONSE_INVALID' | 'STATE_BLOCKED' | 'STATE_PRECONDITION_FAILED' | 'STATE_RUN_NOT_FOUND' | 'STATE_WORKFLOW_NOT_FOUND' | 'STATE_RUN_TERMINAL' | 'STATE_SNAPSHOT_MISMATCH' | 'STATE_RUN_LOCKED' | 'STATE_TRANSITION_DENIED' | 'STATE_LEGACY_FORMAT' | 'STATE_STEP_ALREADY_CLAIMED' | 'STATE_STEP_NOT_ELIGIBLE' | 'STATE_RUN_DIVERGED' | 'VALIDATION_INPUT_SCHEMA' | 'VALIDATION_OUTPUT_SCHEMA' | 'VALIDATION_TRACE_SCHEMA' | 'VALIDATION_WORKFLOW_SCHEMA' | 'VALIDATION_HASH_MISMATCH' | 'VALIDATION_QUOTE_NOT_FOUND' | 'VALIDATION_FIELD_UNKNOWN' | 'VALIDATION_FIELD_EXCLUDED' | 'VALIDATION_EMPTY_VALUE' | 'STEP_HANDLER_ERROR' | 'ENGINE_INTERNAL' | 'ENGINE_STORE_FAILED' | 'ENGINE_ADAPTER_FAILED' | 'ENGINE_PROCESSOR_FAILED' | 'ENGINE_HANDLER_FAILED' | 'ENGINE_STEP_FAILED' | 'ENGINE_GATE_OPEN_FAILED' | 'GATE_MESSAGE_UNRESOLVABLE' | 'FILTER_UNKNOWN' | 'ADAPTER_OP_UNSUPPORTED' | 'ADAPTER_VALIDATION_FAILED' | 'ADAPTER_REQUEST_FAILED' | 'STEP_TIMEOUT' | 'STEP_ABORTED' | 'STEP_RETRY_EXHAUSTED' | 'STATE_STEP_PENDING' | 'STEP_NOT_FOUND' | 'RESOURCE_FETCH_FAILED' | 'RESOURCE_TOO_LARGE' | 'RESOURCE_FORMAT_INVALID' | 'RESOURCE_NOT_ACCESSIBLE' | 'BUFFER_FULL' | 'MCP_CONNECTION_FAILED' | 'MCP_TOOL_NOT_FOUND' | 'MCP_TOOL_NAME_COLLISION';
+export interface WorkflowErrorOptions {
+    code: ErrorCode;
+    category: ErrorCategory;
+    agentAction: AgentAction;
+    retryable: boolean;
+    details?: Record<string, unknown>;
+    stepId?: string;
+    attempt?: number;
+    retry_after?: number;
+}
+export declare class WorkflowError extends Error {
+    readonly code: ErrorCode;
+    readonly category: ErrorCategory;
+    readonly agentAction: AgentAction;
+    readonly retryable: boolean;
+    readonly details: Record<string, unknown>;
+    readonly stepId?: string;
+    readonly timestamp: string;
+    readonly attempt: number;
+    readonly retry_after?: number;
+    constructor(message: string, options: WorkflowErrorOptions);
+}
+//# sourceMappingURL=workflow-error.d.ts.map

package/dist/types/workflow-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-error.d.ts","sourceRoot":"","sources":["../../src/types/workflow-error.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEnG,MAAM,MAAM,WAAW,GACnB,gBAAgB,GAChB,eAAe,GACf,sBAAsB,GACtB,MAAM,GACN,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB,MAAM,MAAM,SAAS,GAEjB,iBAAiB,GACjB,qBAAqB,GACrB,oBAAoB,GACpB,0BAA0B,GAE1B,kBAAkB,GAClB,kBAAkB,GAClB,sBAAsB,GACtB,qBAAqB,GACrB,mBAAmB,GACnB,0BAA0B,GAE1B,eAAe,GACf,2BAA2B,GAC3B,qBAAqB,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,yBAAyB,GACzB,kBAAkB,GAClB,yBAAyB,GACzB,qBAAqB,GACrB,4BAA4B,GAC5B,yBAAyB,GACzB,oBAAoB,GAEpB,yBAAyB,GACzB,0BAA0B,GAC1B,yBAAyB,GACzB,4BAA4B,GAC5B,0BAA0B,GAC1B,4BAA4B,GAC5B,0BAA0B,GAC1B,2BAA2B,GAC3B,wBAAwB,GACxB,oBAAoB,GAEpB,iBAAiB,GACjB,qBAAqB,GACrB,uBAAuB,GACvB,yBAAyB,GACzB,uBAAuB,GACvB,oBAAoB,GACpB,yBAAyB,GACzB,2BAA2B,GAC3B,gBAAgB,GAChB,wBAAwB,GACxB,2BAA2B,GAC3B,wBAAwB,GACxB,cAAc,GACd,cAAc,GACd,sBAAsB,GACtB,oBAAoB,GACpB,gBAAgB,GAEhB,uBAAuB,GACvB,oBAAoB,GACpB,yBAAyB,GACzB,yBAAyB,GAEzB,aAAa,GAEb,uBAAuB,GACvB,oBAAoB,GACpB,yBAAyB,CAAC;AAE9B,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,oBAAoB;CAa3D"}

package/dist/types/workflow-error.js

@@ -0,0 +1,28 @@
+// Structured, categorized error class used throughout the engine.
+export class WorkflowError extends Error {
+    code;
+    category;
+    agentAction;
+    retryable;
+    details;
+    stepId;
+    timestamp;
+    attempt;
+    retry_after;
+    constructor(message, options) {
+        super(message);
+        this.name = 'WorkflowError';
+        this.code = options.code;
+        this.category = options.category;
+        this.agentAction = options.agentAction;
+        this.retryable = options.retryable;
+        this.details = options.details ?? {};
+        if (options.stepId !== undefined)
+            this.stepId = options.stepId;
+        this.timestamp = new Date().toISOString();
+        this.attempt = options.attempt ?? 1;
+        if (options.retry_after !== undefined)
+            this.retry_after = options.retry_after;
+    }
+}
+//# sourceMappingURL=workflow-error.js.map

package/dist/types/workflow-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-error.js","sourceRoot":"","sources":["../../src/types/workflow-error.ts"],"names":[],"mappings":"AAAA,kEAAkE;AA0FlE,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAY;IAChB,QAAQ,CAAgB;IACxB,WAAW,CAAc;IACzB,SAAS,CAAU;IACnB,OAAO,CAA0B;IACjC,MAAM,CAAU;IAChB,SAAS,CAAS;IAClB,OAAO,CAAS;IAChB,WAAW,CAAU;IAE9B,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/D,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;QACpC,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAChF,CAAC;CACF"}

package/dist/utils/schema-skeleton.d.ts

@@ -0,0 +1,11 @@
+type JsonSchema = Record<string, unknown>;
+/**
+ * Returns a minimal skeleton value for the given JSON Schema.
+ * Only required properties are included for object types.
+ * Enums produce a "<val1|val2>" placeholder string.
+ * Arrays produce a one-element array of the item skeleton.
+ * Nested objects are recursed.
+ */
+export declare function generateSchemaSkeleton(schema: JsonSchema): unknown;
+export {};
+//# sourceMappingURL=schema-skeleton.d.ts.map

package/dist/utils/schema-skeleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-skeleton.d.ts","sourceRoot":"","sources":["../../src/utils/schema-skeleton.ts"],"names":[],"mappings":"AAGA,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CA+BlE"}

package/dist/utils/schema-skeleton.js

@@ -0,0 +1,40 @@
+// Generates a minimal conforming skeleton from a JSON Schema object.
+// Used to populate call_with placeholders in NextAction instructions.
+/**
+ * Returns a minimal skeleton value for the given JSON Schema.
+ * Only required properties are included for object types.
+ * Enums produce a "<val1|val2>" placeholder string.
+ * Arrays produce a one-element array of the item skeleton.
+ * Nested objects are recursed.
+ */
+export function generateSchemaSkeleton(schema) {
+    const type = schema['type'];
+    const properties = schema['properties'];
+    if (type === 'object' || (type === undefined && properties !== undefined)) {
+        if (properties === undefined)
+            return {};
+        const required = schema['required'] ?? Object.keys(properties);
+        const result = {};
+        for (const key of required) {
+            const propSchema = properties[key];
+            if (propSchema !== undefined) {
+                result[key] = generateSchemaSkeleton(propSchema);
+            }
+        }
+        return result;
+    }
+    if (type === 'array') {
+        const items = schema['items'];
+        return items !== undefined ? [generateSchemaSkeleton(items)] : [];
+    }
+    if (type === 'string') {
+        const enumValues = schema['enum'];
+        return enumValues !== undefined ? `<${enumValues.join('|')}>` : '';
+    }
+    if (type === 'number' || type === 'integer')
+        return 0;
+    if (type === 'boolean')
+        return false;
+    return null;
+}
+//# sourceMappingURL=schema-skeleton.js.map

package/dist/utils/schema-skeleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-skeleton.js","sourceRoot":"","sources":["../../src/utils/schema-skeleton.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sEAAsE;AAItE;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAkB;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAA2C,CAAC;IAElF,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS,CAAC,EAAE,CAAC;QAC1E,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAI,MAAM,CAAC,UAAU,CAA0B,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACzF,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YACnC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,sBAAsB,CAAC,UAAU,CAAC,CAAC;YACnD,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAA2B,CAAC;QACxD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpE,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAyB,CAAC;QAC1D,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACtD,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAErC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/validation/input-schema.d.ts

@@ -0,0 +1,26 @@
+import type { JsonSchema } from '../types/workflow-definition.js';
+import type { TraceEntry } from '../types/run-record.js';
+/**
+ * Validates input against the step's declared JSON Schema.
+ * Throws WorkflowError(VALIDATION_INPUT_SCHEMA) on failure.
+ */
+export declare function validateInputSchema(input: Record<string, unknown>, schema: JsonSchema, stepId: string): void;
+/**
+ * Validates the agent's submitted output against the step's declared JSON Schema.
+ * Throws WorkflowError(VALIDATION_OUTPUT_SCHEMA) on failure.
+ */
+export declare function validateOutputSchema(output: Record<string, unknown>, schema: JsonSchema, stepId: string): void;
+export interface TraceSchemaWarnResult {
+    errorCount: number;
+    warning: string;
+}
+/**
+ * Validates canonical trace entries against the step's declared trace_schema.
+ *
+ * In 'enforce' mode: throws WorkflowError(VALIDATION_TRACE_SCHEMA, agentAction: 'provide_input').
+ * In 'warn' mode: returns a result with errorCount and a human-readable warning string.
+ * Returns { errorCount: 0, warning: '' } when validation passes in warn mode.
+ */
+export declare function validateTraceSchema(entries: TraceEntry[], schema: JsonSchema, stepId: string, mode: 'enforce'): void;
+export declare function validateTraceSchema(entries: TraceEntry[], schema: JsonSchema, stepId: string, mode: 'warn'): TraceSchemaWarnResult;
+//# sourceMappingURL=input-schema.d.ts.map

package/dist/validation/input-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-schema.d.ts","sourceRoot":"","sources":["../../src/validation/input-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,IAAI,CAaN;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,IAAI,CAaN;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,GACd,IAAI,CAAC;AACR,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,UAAU,EAAE,EACrB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,qBAAqB,CAAC"}

package/dist/validation/input-schema.js

@@ -0,0 +1,67 @@
+// Input schema validation — validates step input against a declared JSON Schema using Ajv.
+import { Ajv } from 'ajv';
+import { WorkflowError } from '../types/workflow-error.js';
+/**
+ * Validates input against the step's declared JSON Schema.
+ * Throws WorkflowError(VALIDATION_INPUT_SCHEMA) on failure.
+ */
+export function validateInputSchema(input, schema, stepId) {
+    const ajv = new Ajv();
+    const valid = ajv.validate(schema, input);
+    if (!valid) {
+        throw new WorkflowError(`Invalid input for step '${stepId}'`, {
+            code: 'VALIDATION_INPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+            details: { errors: ajv.errors ?? [] },
+            stepId,
+        });
+    }
+}
+/**
+ * Validates the agent's submitted output against the step's declared JSON Schema.
+ * Throws WorkflowError(VALIDATION_OUTPUT_SCHEMA) on failure.
+ */
+export function validateOutputSchema(output, schema, stepId) {
+    const ajv = new Ajv();
+    const valid = ajv.validate(schema, output);
+    if (!valid) {
+        throw new WorkflowError(`Output validation failed for step '${stepId}'`, {
+            code: 'VALIDATION_OUTPUT_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+            details: { errors: ajv.errors ?? [] },
+            stepId,
+        });
+    }
+}
+export function validateTraceSchema(entries, schema, stepId, mode) {
+    const ajv = new Ajv();
+    const valid = ajv.validate(schema, entries);
+    if (valid) {
+        if (mode === 'warn')
+            return { errorCount: 0, warning: '' };
+        return;
+    }
+    if (mode === 'enforce') {
+        throw new WorkflowError(`Trace schema validation failed for step '${stepId}'`, {
+            code: 'VALIDATION_TRACE_SCHEMA',
+            category: 'VALIDATION',
+            agentAction: 'provide_input',
+            retryable: false,
+            details: { errors: ajv.errors ?? [] },
+            stepId,
+        });
+    }
+    // warn mode — return error details without throwing
+    const errorSummary = (ajv.errors ?? [])
+        .map((e) => `${e.instancePath !== '' ? e.instancePath + ' ' : ''}${e.message ?? ''}`.trim())
+        .join('; ');
+    return {
+        errorCount: (ajv.errors ?? []).length,
+        warning: `Trace schema violation for step '${stepId}': ${errorSummary}`,
+    };
+}
+//# sourceMappingURL=input-schema.js.map

package/dist/validation/input-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-schema.js","sourceRoot":"","sources":["../../src/validation/input-schema.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG3D;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA8B,EAC9B,MAAkB,EAClB,MAAc;IAEd,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IACtB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAgB,EAAE,KAAK,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,aAAa,CAAC,2BAA2B,MAAM,GAAG,EAAE;YAC5D,IAAI,EAAE,yBAAyB;YAC/B,QAAQ,EAAE,YAAY;YACtB,WAAW,EAAE,eAAe;YAC5B,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE;YACrC,MAAM;SACP,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAA+B,EAC/B,MAAkB,EAClB,MAAc;IAEd,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IACtB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAgB,EAAE,MAAM,CAAC,CAAC;IACrD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,aAAa,CAAC,sCAAsC,MAAM,GAAG,EAAE;YACvE,IAAI,EAAE,0BAA0B;YAChC,QAAQ,EAAE,YAAY;YACtB,WAAW,EAAE,eAAe;YAC5B,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE;YACrC,MAAM;SACP,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AA0BD,MAAM,UAAU,mBAAmB,CACjC,OAAqB,EACrB,MAAkB,EAClB,MAAc,EACd,IAAwB;IAExB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IACtB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAgB,EAAE,OAAO,CAAC,CAAC;IACtD,IAAI,KAAK,EAAE,CAAC;QACV,IAAI,IAAI,KAAK,MAAM;YAAE,OAAO,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QAC3D,OAAO;IACT,CAAC;IAED,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,aAAa,CAAC,4CAA4C,MAAM,GAAG,EAAE;YAC7E,IAAI,EAAE,yBAAyB;YAC/B,QAAQ,EAAE,YAAY;YACtB,WAAW,EAAE,eAAe;YAC5B,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE;YACrC,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED,oDAAoD;IACpD,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;SACpC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;SAC3F,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO;QACL,UAAU,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,MAAM;QACrC,OAAO,EAAE,oCAAoC,MAAM,MAAM,YAAY,EAAE;KACxE,CAAC;AACJ,CAAC"}

package/dist/workflow/registrar.d.ts

@@ -0,0 +1,20 @@
+import type { WorkflowDefinition } from '../types/workflow-definition.js';
+export interface WorkflowRegistrar {
+    /** Persist a WorkflowDefinition under its id, overwriting any previous registration. */
+    register(definition: WorkflowDefinition): Promise<void>;
+    /** Retrieve a WorkflowDefinition by id. Throws WorkflowError if not found. */
+    get(workflowId: string): Promise<WorkflowDefinition>;
+    /** List all registered workflows. */
+    list(): Promise<WorkflowDefinition[]>;
+}
+/**
+ * Stores WorkflowDefinition objects as JSON files at ~/.realm/workflows/{id}.json.
+ */
+export declare class JsonWorkflowStore implements WorkflowRegistrar {
+    private readonly dir;
+    constructor(baseDir?: string);
+    register(definition: WorkflowDefinition): Promise<void>;
+    get(workflowId: string): Promise<WorkflowDefinition>;
+    list(): Promise<WorkflowDefinition[]>;
+}
+//# sourceMappingURL=registrar.d.ts.map

package/dist/workflow/registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registrar.d.ts","sourceRoot":"","sources":["../../src/workflow/registrar.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAI1E,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,8EAA8E;IAC9E,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrD,qCAAqC;IACrC,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,CAAC,EAAE,MAAM;IAKtB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvD,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgCpD,IAAI,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAa5C"}

package/dist/workflow/registrar.js

@@ -0,0 +1,61 @@
+// JsonWorkflowStore — persists registered WorkflowDefinition objects to ~/.realm/workflows/.
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { WorkflowError } from '../types/workflow-error.js';
+import { CURRENT_WORKFLOW_SCHEMA_VERSION } from './yaml-loader.js';
+/**
+ * Stores WorkflowDefinition objects as JSON files at ~/.realm/workflows/{id}.json.
+ */
+export class JsonWorkflowStore {
+    dir;
+    constructor(baseDir) {
+        this.dir = baseDir ?? join(homedir(), '.realm', 'workflows');
+        mkdirSync(this.dir, { recursive: true });
+    }
+    async register(definition) {
+        writeFileSync(join(this.dir, `${definition.id}.json`), JSON.stringify(definition, null, 2), 'utf8');
+    }
+    async get(workflowId) {
+        const filePath = join(this.dir, `${workflowId}.json`);
+        let raw;
+        try {
+            raw = readFileSync(filePath, 'utf8');
+        }
+        catch {
+            throw new WorkflowError(`Workflow not found: ${workflowId}`, {
+                code: 'STATE_WORKFLOW_NOT_FOUND',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+        const parsed = JSON.parse(raw);
+        if (parsed.schema_version === undefined ||
+            parsed.schema_version < CURRENT_WORKFLOW_SCHEMA_VERSION) {
+            throw new WorkflowError('This workflow was registered with an older version of Realm. ' +
+                'Re-register it with: realm workflow register <path-to-workflow>', {
+                code: 'STATE_LEGACY_FORMAT',
+                category: 'STATE',
+                agentAction: 'report_to_user',
+                retryable: false,
+            });
+        }
+        return parsed;
+    }
+    async list() {
+        const entries = readdirSync(this.dir).filter((f) => f.endsWith('.json'));
+        const results = [];
+        for (const entry of entries) {
+            try {
+                const raw = readFileSync(join(this.dir, entry), 'utf8');
+                results.push(JSON.parse(raw));
+            }
+            catch {
+                // Skip files that fail to parse
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=registrar.js.map

package/dist/workflow/registrar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registrar.js","sourceRoot":"","sources":["../../src/workflow/registrar.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,+BAA+B,EAAE,MAAM,kBAAkB,CAAC;AAWnE;;GAEG;AACH,MAAM,OAAO,iBAAiB;IACX,GAAG,CAAS;IAE7B,YAAY,OAAgB;QAC1B,IAAI,CAAC,GAAG,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC7D,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,UAA8B;QAC3C,aAAa,CACX,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAC,EAAE,OAAO,CAAC,EACvC,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,EACnC,MAAM,CACP,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,UAAkB;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,OAAO,CAAC,CAAC;QACtD,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,aAAa,CAAC,uBAAuB,UAAU,EAAE,EAAE;gBAC3D,IAAI,EAAE,0BAA0B;gBAChC,QAAQ,EAAE,OAAO;gBACjB,WAAW,EAAE,gBAAgB;gBAC7B,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAuB,CAAC;QACrD,IACE,MAAM,CAAC,cAAc,KAAK,SAAS;YACnC,MAAM,CAAC,cAAc,GAAG,+BAA+B,EACvD,CAAC;YACD,MAAM,IAAI,aAAa,CACrB,+DAA+D;gBAC7D,iEAAiE,EACnE;gBACE,IAAI,EAAE,qBAAqB;gBAC3B,QAAQ,EAAE,OAAO;gBACjB,WAAW,EAAE,gBAAgB;gBAC7B,SAAS,EAAE,KAAK;aACjB,CACF,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QACzE,MAAM,OAAO,GAAyB,EAAE,CAAC;QACzC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;gBACxD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAuB,CAAC,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,gCAAgC;YAClC,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}