@sensigo/realm 0.1.0

package/dist/store/trace-buffer-store.js

@@ -0,0 +1,113 @@
+import { WorkflowError } from '../types/workflow-error.js';
+export const BUFFER_LIMIT_COUNT = 200;
+export const BUFFER_LIMIT_BYTES = 100 * 1024; // 100 KB
+export const FINAL_LIMIT_ENTRIES = 100;
+export const FINAL_LIMIT_BYTES = 50 * 1024; // 50 KB (must match MAX_BYTES in trace-normalizer.ts)
+const MAX_EVENT_LENGTH = 100;
+const RESERVED_PREFIX = 'trace.';
+const MAX_DATA_KEYS = 20;
+const MAX_STRING_VALUE = 500;
+/**
+ * Per-entry normalization run at append time (not at finalization).
+ * Mirrors the normalization in normalizeTrace for the parts that don't need seq or byte-budget context.
+ * Returns null if the entry should be dropped (reserved prefix).
+ */
+export function normalizeEntryForBuffer(entry) {
+    // Normalize event: trim, replace empty with 'unknown_event', cap to MAX_EVENT_LENGTH.
+    let event = (entry.event ?? '').trim();
+    if (event.length === 0)
+        event = 'unknown_event';
+    if (event.length > MAX_EVENT_LENGTH)
+        event = event.slice(0, MAX_EVENT_LENGTH);
+    // Drop if event starts with reserved prefix.
+    if (event.startsWith(RESERVED_PREFIX))
+        return null;
+    // Normalize data: keep first 20 keys, cap string values to 500 chars, drop non-primitive values.
+    let data;
+    if (entry.data !== undefined) {
+        const keys = Object.keys(entry.data).slice(0, MAX_DATA_KEYS);
+        const normalized = {};
+        for (const key of keys) {
+            const val = entry.data[key];
+            if (val === null || typeof val === 'boolean' || typeof val === 'number') {
+                normalized[key] = val;
+            }
+            else if (typeof val === 'string') {
+                normalized[key] = val.length > MAX_STRING_VALUE ? val.slice(0, MAX_STRING_VALUE) : val;
+            }
+            // Drop non-primitive values (objects, arrays, undefined).
+        }
+        data = Object.keys(normalized).length > 0 ? normalized : undefined;
+    }
+    return {
+        event,
+        ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
+        ...(data !== undefined ? { data } : {}),
+    };
+}
+/**
+ * In-memory TraceBufferStore for use in tests and non-persistent environments.
+ * Entries are lost on process restart (no file I/O).
+ */
+export class InMemoryTraceBufferStore {
+    buffers = new Map();
+    key(runId, stepId) {
+        return `${runId}:${stepId}`;
+    }
+    async append(runId, stepId, entries) {
+        const k = this.key(runId, stepId);
+        const existing = this.buffers.get(k) ?? [];
+        if (entries.length === 0) {
+            const bytes = Buffer.byteLength(JSON.stringify(existing));
+            return {
+                buffer_count: existing.length,
+                buffer_bytes: bytes,
+                limit_count: BUFFER_LIMIT_COUNT,
+                limit_bytes: BUFFER_LIMIT_BYTES,
+                final_limit_entries: FINAL_LIMIT_ENTRIES,
+                final_limit_bytes: FINAL_LIMIT_BYTES,
+            };
+        }
+        const ts = Date.now();
+        const normalized = entries
+            .map((e) => normalizeEntryForBuffer(e))
+            .filter((e) => e !== null)
+            .map((e) => ({ ...e, _internalTs: ts }));
+        const proposed = [...existing, ...normalized];
+        const proposedBytes = Buffer.byteLength(JSON.stringify(proposed));
+        if (proposed.length > BUFFER_LIMIT_COUNT || proposedBytes > BUFFER_LIMIT_BYTES) {
+            const existingBytes = Buffer.byteLength(JSON.stringify(existing));
+            throw new WorkflowError('Trace buffer full for step', {
+                code: 'BUFFER_FULL',
+                category: 'ENGINE',
+                agentAction: 'provide_input',
+                retryable: false,
+                details: { buffer_count: existing.length, buffer_bytes: existingBytes },
+            });
+        }
+        this.buffers.set(k, proposed);
+        const bytes = Buffer.byteLength(JSON.stringify(proposed));
+        return {
+            buffer_count: proposed.length,
+            buffer_bytes: bytes,
+            limit_count: BUFFER_LIMIT_COUNT,
+            limit_bytes: BUFFER_LIMIT_BYTES,
+            final_limit_entries: FINAL_LIMIT_ENTRIES,
+            final_limit_bytes: FINAL_LIMIT_BYTES,
+        };
+    }
+    async read(runId, stepId) {
+        return this.buffers.get(this.key(runId, stepId)) ?? [];
+    }
+    async delete(runId, stepId) {
+        this.buffers.delete(this.key(runId, stepId));
+    }
+    async deleteAllForRun(runId) {
+        for (const key of [...this.buffers.keys()]) {
+            if (key.startsWith(`${runId}:`)) {
+                this.buffers.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=trace-buffer-store.js.map

package/dist/store/trace-buffer-store.js.map

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

package/dist/types/mcp-types.d.ts

@@ -0,0 +1,17 @@
+export interface ToolCallRecord {
+    server_id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    result: string | null;
+    duration_ms: number;
+    error?: string;
+}
+export interface McpServerConfig {
+    id: string;
+    transport: 'stdio';
+    command?: string;
+    args?: string[];
+    /** Values support "${VAR}" expansion from process.env at connect time */
+    env?: Record<string, string>;
+}
+//# sourceMappingURL=mcp-types.d.ts.map

package/dist/types/mcp-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-types.d.ts","sourceRoot":"","sources":["../../src/types/mcp-types.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B"}

package/dist/types/mcp-types.js

@@ -0,0 +1,5 @@
+// ToolCallRecord and McpServerConfig live in core because they are referenced by core types
+// (EvidenceSnapshot, ExecuteChainOptions, WorkflowDefinition). Defining them in cli would
+// create a circular import: core → cli → core.
+export {};
+//# sourceMappingURL=mcp-types.js.map

package/dist/types/mcp-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-types.js","sourceRoot":"","sources":["../../src/types/mcp-types.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,0FAA0F;AAC1F,+CAA+C"}

package/dist/types/response-envelope.d.ts

@@ -0,0 +1,96 @@
+import type { EvidenceSnapshot } from './run-record.js';
+import type { AgentAction, ErrorCode } from './workflow-error.js';
+export interface NextAction {
+    instruction: {
+        tool: string;
+        params: Record<string, unknown>;
+        /**
+         * Ready-to-use flat argument object for calling the tool.
+         * Agent-supplied params appear as placeholder strings (e.g. "<YOUR_PARAMS>", "<approve|reject>").
+         * Copy this object, replace the placeholder(s), and call the tool.
+         */
+        call_with: Record<string, unknown>;
+    } | null;
+    human_readable: string;
+    /** Current state orientation — describes what state the run is in and what just happened. */
+    orientation: string;
+    expected_timeout?: string;
+    /** The step's declared input schema — use this to structure the params argument of your execute_step call. */
+    input_schema?: Record<string, unknown>;
+    /** Template-resolved step prompt, delivered to the agent at step entry. */
+    prompt?: string;
+}
+export type RunStatus = 'ok' | 'error' | 'blocked' | 'confirm_required';
+export interface BlockedReason {
+    /** Step names currently eligible for execution. */
+    eligible_steps: string[];
+    suggestion?: string;
+}
+export interface GateInfo {
+    gate_id: string;
+    step_name: string;
+    preview: Record<string, unknown>;
+    choices: string[];
+    /** Template-resolved display content for this gate step — present to the human verbatim before asking for their choice. */
+    display?: string;
+    /** Agent-facing instructions for this gate step — how the agent should present the gate to the human. */
+    agent_hint?: string;
+    /** Structured response specification — the choices the human may select. */
+    response_spec?: {
+        choices: string[];
+    };
+}
+export interface ResponseEnvelope {
+    command: string;
+    run_id: string;
+    /** Integer version of the run record at time of response. For observability only — not required as input to any tool. */
+    run_version: number;
+    /**
+     * Chain progress status.
+     * - 'ok': the chain made forward progress; follow next_actions for what to do next.
+     *   Does NOT imply the original requested step succeeded — a recovery path also returns 'ok' with a warning.
+     * - 'error': unrecoverable failure; agent_action tells you how to respond.
+     * - 'blocked': wrong step for current state; next_actions redirects.
+     * - 'confirm_required': a human gate is open; gate carries the display content.
+     */
+    status: RunStatus;
+    data: Record<string, unknown>;
+    /** Audit trail of step executions in this response. For debugging and CLI inspection only. */
+    evidence: EvidenceSnapshot[];
+    warnings: string[];
+    errors: string[];
+    /**
+     * The canonical error code from the WorkflowError that produced this envelope.
+     * Only present when status === 'error'.
+     */
+    error_code?: ErrorCode;
+    /**
+     * Additional structured context from the WorkflowError. Only present when
+     * error_code is set and the error carries non-empty details.
+     */
+    error_details?: Record<string, unknown>;
+    agent_action?: AgentAction;
+    /**
+     * When present and agent_action is 'wait_and_proceed', the number of seconds
+     * the consumer should wait before following next_actions. Not set for other
+     * agent_action values.
+     */
+    retry_after?: number;
+    /** Current state orientation. Always populated — describes what just happened and what state the run is in. */
+    context_hint: string;
+    /** Steps available for execution. Empty array means terminal or blocked — check status and run_phase. */
+    next_actions: NextAction[];
+    blocked_reason?: BlockedReason;
+    gate?: GateInfo;
+    /**
+     * Names and run_phase values of auto steps that ran silently as part of an executeChain call.
+     * Only present when at least one auto step was chained. Useful for debugging and orientation
+     * after start_run or after an agent step that triggers subsequent auto steps.
+     */
+    chained_auto_steps?: Array<{
+        step: string;
+        run_phase: string;
+        branched_via?: string;
+    }>;
+}
+//# sourceMappingURL=response-envelope.d.ts.map

package/dist/types/response-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-envelope.d.ts","sourceRoot":"","sources":["../../src/types/response-envelope.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC;;;;WAIG;QACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,IAAI,CAAC;IACT,cAAc,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8GAA8G;IAC9G,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAExE,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2HAA2H;IAC3H,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,aAAa,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,yHAAyH;IACzH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+GAA+G;IAC/G,YAAY,EAAE,MAAM,CAAC;IACrB,yGAAyG;IACzG,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,cAAc,CAAC,EAAE,aAAa,CAAC;IAC/B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxF"}

package/dist/types/response-envelope.js

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

package/dist/types/response-envelope.js.map

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

package/dist/types/run-record.d.ts

@@ -0,0 +1,169 @@
+import type { ToolCallRecord } from './mcp-types.js';
+/**
+ * A single trace entry submitted by the agent. Submitted as-is; the engine
+ * canonicalizes and assigns seq before persisting.
+ */
+export interface AgentTraceEntry {
+    event: string;
+    timestamp?: string | undefined;
+    data?: Record<string, string | number | boolean | null> | undefined;
+}
+/**
+ * A single stored trace entry after canonicalization.
+ * seq is engine-assigned: 1-based, monotonically increasing in stored order.
+ */
+export interface TraceEntry {
+    seq: number;
+    event: string;
+    timestamp?: string;
+    data?: Record<string, string | number | boolean | null>;
+}
+/** Discard and truncation accounting produced by the trace normalizer. */
+export interface TraceNormalizationSummary {
+    submitted_entries: number;
+    stored_entries: number;
+    discarded_entries: number;
+    discarded_reserved_event_entries: number;
+    discarded_overflow_entries: number;
+    truncated: boolean;
+    truncation_reason?: 'count_limit' | 'byte_limit';
+    /** Whether trace_schema validation was applied to the canonical entries. */
+    schema_applied?: boolean;
+    /** Validation mode that was applied ('warn' or 'enforce'). Present when schema_applied is true. */
+    validation_mode?: 'warn' | 'enforce';
+    /** Number of Ajv validation errors found. Zero means schema-conformant. Present when schema_applied is true. */
+    validation_errors?: number;
+}
+/** Diagnostic metadata captured during step execution. Written once; read by inspect. */
+export interface StepDiagnostics {
+    /** Rough token count estimate: Math.ceil(JSON.stringify(input).length / 4) */
+    input_token_estimate: number;
+    /** Ordered list of precondition evaluations for this step. Empty array if no preconditions. */
+    precondition_trace: Array<{
+        expression: string;
+        passed: boolean;
+        resolved_value: unknown;
+    }>;
+}
+export interface EvidenceSnapshot {
+    step_id: string;
+    started_at: string;
+    completed_at: string;
+    duration_ms: number;
+    input_summary: Record<string, unknown>;
+    output_summary: Record<string, unknown>;
+    status: 'success' | 'error' | 'skipped';
+    error?: string;
+    evidence_hash: string;
+    attempt?: number;
+    /** Distinguishes computation records from human decision records. Absent on pre-existing entries. */
+    kind?: 'execution' | 'gate_response';
+    /**
+     * Verbatim message presented to the human reviewer when they made this gate choice.
+     * Present only on gate_response evidence entries when gate.message was configured.
+     * This is an evidence integrity field: it records exactly what the human read.
+     */
+    gate_message?: string;
+    /** Diagnostic metadata. Present on snapshots captured after Week 7. */
+    diagnostics?: StepDiagnostics;
+    /** Name of the agent profile active at this step, if any. */
+    agent_profile?: string;
+    /** SHA-256 hash of the profile content at register time. Auditable even if the file changes. */
+    agent_profile_hash?: string;
+    /** MCP tool calls made during this step, if any. */
+    tool_calls?: ToolCallRecord[];
+    /**
+     * Present only when the step used input_map. Records the concrete params the engine
+     * derived from run state and passed to the service adapter. Absent for all other step types.
+     */
+    resolved_params?: Record<string, unknown>;
+    /**
+     * Canonical stored trace entries for this step. Present only on agent execution steps
+     * when the agent submitted a non-empty trace that survived normalization.
+     * Excludes evidence_hash computation — integrity is tracked separately via trace_digest.
+     */
+    trace?: TraceEntry[];
+    /**
+     * SHA-256 hex digest of JSON.stringify(trace). Present when trace is non-empty.
+     * Separate from evidence_hash, which covers output_summary only.
+     */
+    trace_digest?: string;
+    /**
+     * Discard and truncation accounting from the trace normalizer.
+     * Present whenever the agent submitted a trace (even if all entries were dropped).
+     * Absent when no trace was submitted.
+     */
+    trace_summary?: TraceNormalizationSummary;
+}
+export interface PendingGate {
+    gate_id: string;
+    step_name: string;
+    /** Output produced by the step dispatcher; presented to the human for review. */
+    preview: Record<string, unknown>;
+    choices: string[];
+    opened_at: string;
+    /**
+     * Slack user ID or handle declared on the step's gate config.
+     * Optional — absent when the workflow step has no owner field.
+     */
+    owner?: string;
+    /**
+     * Developer-authored gate message resolved from run data at gate-open time.
+     * Present only when gate.message is configured on the step. Never derived from step.prompt.
+     * Preserved into EvidenceSnapshot.gate_message at gate resolution for audit purposes.
+     */
+    resolved_message?: string;
+    /**
+     * Per-choice messages for Slack thread resolution confirmation.
+     * Copied verbatim from gate.resolution_messages on the step definition.
+     * The CLI reads the message for the chosen key and posts it to the thread.
+     */
+    resolution_messages?: Record<string, string>;
+}
+/**
+ * Derived phase of a workflow run. Always computed from the four step sets and run state;
+ * never set directly by callers outside the engine.
+ */
+export type RunPhase = 'running' | 'gate_waiting' | 'completed' | 'failed' | 'abandoned';
+/** Snapshot of a single workflow context entry taken at run start. */
+export interface WorkflowContextSnapshot {
+    /** Absolute path the content was read from. */
+    source_path: string;
+    /** Raw file content. Empty string if the file could not be read. */
+    content: string;
+    /** SHA-256 hex hash of content. Empty string if the file could not be read. */
+    content_hash: string;
+    /** ISO timestamp when the snapshot was taken. */
+    loaded_at: string;
+    /** Set when the file could not be read. Content and hash will be empty strings. */
+    error?: string;
+}
+export interface RunRecord {
+    id: string;
+    workflow_id: string;
+    workflow_version: number;
+    completed_steps: string[];
+    in_progress_steps: string[];
+    failed_steps: string[];
+    /** Steps whose trigger_rule can no longer be satisfied; recorded for auditability. */
+    skipped_steps: string[];
+    /**
+     * Derived convenience field — set by the engine on every write, read by CLI and get_run_state.
+     * Always computable from the four step sets, terminal_state, and pending_gate.
+     */
+    run_phase: RunPhase;
+    version: number;
+    params: Record<string, unknown>;
+    evidence: EvidenceSnapshot[];
+    /**
+     * Snapshots of workflow context files loaded at run start.
+     * Keyed by entry name. Separate from step evidence — not in evidence[].
+     */
+    workflow_context_snapshots?: Record<string, WorkflowContextSnapshot>;
+    created_at: string;
+    updated_at: string;
+    terminal_state: boolean;
+    terminal_reason?: string;
+    pending_gate?: PendingGate;
+}
+//# sourceMappingURL=run-record.d.ts.map

package/dist/types/run-record.d.ts.map

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

package/dist/types/run-record.js

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

package/dist/types/run-record.js.map

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