yuangs 2.29.0 → 2.30.0

package/README.md

@@ -634,6 +634,296 @@ Then `yuangs` is for you.
 
 ## Status
 
+`yuangs` is actively evolving.  
+The core governance model is stable; interfaces are still sharpening.
+
+Contributions, ideas, and principled criticism are welcome.
+
+> **"AI should never appear smarter than input unless explicitly asked."**
+
+---
+
+# Phase 2: Explainability & Governance (v1)
+
+## 🎯 Overview
+
+Phase 2 introduces **system observability and control** without changing core behavior:
+- ✅ Explainability: Human-readable execution explanations
+- ✅ Replay++: Dry-run, explain, and diff capabilities
+- ✅ Skill Control: Enable/disable skills for fine-grained control
+
+---
+
+## 📦 New Commands
+
+### `yuangs explain [id | last]`
+
+**Purpose**: Explain why the system made a decision
+
+**Usage**:
+```bash
+# Explain the most recent execution
+yuangs explain last
+
+# Explain a specific execution by ID
+yuangs explain exec_1768820380225_rgts34981
+```
+
+**Output Format (v1)**:
+```
+=== Execution Explanation ===
+[1] Command
+- Name: ai-command
+- Args: echo "hello"
+
+[2] Decision
+- Strategy: capability-match
+- Selected Model: gemini-2.5-flash-lite
+- Reason: Capability-based selection with fallback support
+
+[3] Model
+- Name: gemini-2.5-flash-lite
+- Provider: aiproxy
+- Context Window: 8000
+- Cost Profile: low
+
+[4] Skills
+- (none)
+
+[5] Meta
+- Execution ID: exec_1768820380225_rgts34981
+- Timestamp: 2026-01-19T10:59:40.225Z
+- Replayable: true
+- Version: unknown
+=============================
+```
+
+**Key Features**:
+- ✅ Pure read-only operation (no side effects)
+- ✅ Stable, snapshot-able output
+- ✅ Future-proof for diff/audit workflows
+
+---
+
+### `yuangs replay <id> [options]`
+
+**Purpose**: Replay an execution with control flags
+
+**Options**:
+| Option | Description |
+|--------|-------------|
+| `-s, --strict` | Strict replay (use exact model) |
+| `-c, --compatible` | Compatible replay (allow fallback) |
+| `-r, --re-evaluate` | Re-evaluate with current config |
+| `-v, --verbose` | Verbose output |
+| `--dry` | Dry run - show what would happen without executing |
+| `--explain` | Show explanation before replay |
+| `--diff` | Show diff between original and current config |
+
+**Usage Examples**:
+```bash
+# Dry run with explanation
+yuangs replay exec_1768820380225_rgts34981 --dry --explain
+
+# Show diff only (no execution)
+yuangs replay exec_1768820380225_rgts34981 --diff --dry
+
+# Full replay with diff
+yuangs replay exec_1768820380225_rgts34981 --diff
+```
+
+**Replay Behavior Matrix**:
+| explain | dry | strict | Behavior |
+|--------|-----|--------|----------|
+| ✅ | ✅ | any | Explain only, no execution |
+| ✅ | ❌ | ✅ | Explain → Replay |
+| ❌ | ✅ | ✅ | Print strict info → Exit |
+| ❌ | ❌ | ✅ | Normal replay |
+
+**Diff Output**:
+```
+=== Replay Diff ===
+[Decision]
+- no change
+
+[Model]
+- no change
+
+[Skills]
+- no change
+===================
+```
+
+---
+
+### `yuangs skills <subcommand>`
+
+**Purpose**: Manage skill library
+
+**Subcommands**:
+```bash
+# List all skills with scores
+yuangs skills list
+
+# Explain a specific skill
+yuangs skills explain <skill-name>
+
+# Disable a skill
+yuangs skills disable <skill-name>
+
+# Enable a skill
+yuangs skills enable <skill-name>
+```
+
+**Output Example** (`skills list`):
+```
+📦 Skills (3)
+
+✔ deploy-production
+  Confidence: 72%
+  Success: 8 / Failure: 1
+  Last used: 2 days ago
+
+✔ cleanup-logs
+  Confidence: 41%
+  Success: 5 / Failure: 7
+  Last used: 1 day ago
+
+⊘ legacy-search (disabled)
+  Confidence: 23%
+  Success: 2 / Failure: 6
+  Last used: 7 days ago
+```
+
+**Key Features**:
+- ✅ Skills can be disabled without deletion
+- ✅ Skills are scored and sorted by relevance
+- ✅ Disabled skills don't affect new decisions
+- ✅ All skills remain visible in `explain` output
+
+---
+
+## 🧭 Explain Output Spec v1
+
+The explain output follows a strict format designed for:
+- ✅ Human readability
+- ✅ Stability and snapshot compatibility
+- ✅ Future diff/audit workflows
+- ✅ No implementation coupling
+
+**Structure** (5 sections, immutable order):
+1. `[1] Command` - User input layer
+2. `[2] Decision` - Decision-making core
+3. `[3] Model` - Execution environment
+4. `[4] Skills` - Skills that influenced decision
+5. `[5] Meta` - Audit/replay metadata
+
+**Important Notes**:
+- ⚠️ Do NOT change format without bumping spec version
+- ✅ Output is pure text (no color for snapshots)
+- ✅ Same execution record = 100% reproducible output
+
+---
+
+## 🔒 Skills & Enabled State
+
+Skills now have an `enabled` field that controls their participation in new decisions:
+
+**Default Behavior**:
+- ✅ New skills: `enabled: true`
+- ✅ Legacy skills: `enabled: true` (if field missing)
+- ❌ Disabled skills: Not included in `getRelevantSkills()`
+
+**Use Cases**:
+1. **Governance**: Temporarily disable risky skills
+2. **A/B Testing**: Compare different skill configurations
+3. **Rollback**: Disable a newly-added skill without deletion
+4. **Audit**: View disabled skills in explain output
+
+**CLI Commands**:
+```bash
+# Disable a skill
+yuangs skills disable risky-operation
+
+# List to verify
+yuangs skills list
+
+# Re-enable if needed
+yuangs skills enable risky-operation
+```
+
+---
+
+## 🧪 Testing & Snapshots
+
+### Creating Explain Snapshots
+
+```bash
+# Create a snapshot of the last execution
+yuangs replay exec_1768820380225_rgts34981 --explain --dry > snapshot.txt
+```
+
+Snapshots are useful for:
+- ✅ Regression testing
+- ✅ Output format verification
+- ✅ Documentation examples
+- ✅ Audit trails
+
+---
+
+## 📝 Implementation Notes
+
+### Explain Output v1
+
+**File**: `src/core/explain.ts`
+
+**Key Design**:
+- Pure function (no side effects)
+- No external dependencies on global state
+- Uses existing `ExecutionRecord` structure
+- Stable formatting (versioned)
+
+---
+
+### Replay Diff
+
+**File**: `src/core/replayDiff.ts`
+
+**Key Design**:
+- Compares Decision, Model, and Skills layers
+- Shows added/removed/changed skills
+- Semantic diff (not token-level)
+- Compatible with Explain v1 format
+
+---
+
+### Skills Control
+
+**File**: `src/agent/skills.ts`
+
+**Key Changes**:
+- Added `enabled: boolean` field to `Skill` interface
+- Exported `computeSkillScore()` for CLI usage
+- `getRelevantSkills()` filters disabled skills
+
+---
+
+## ✅ Phase 2 Completion
+
+All Phase 2 objectives are complete:
+
+- [x] Explainability (ExecutionRecord-level)
+- [x] Replay dry / explain / strict
+- [x] Skill scoring & enable flag
+- [x] CLI wiring for all three
+- [x] Replay diff implementation
+- [x] Skills enabled filtering
+- [x] Explain v1 specification
+- [x] Snapshot testing capability
+
+**Next Phase**: Phase 3 - Advanced governance & project-level intelligence
+
+
 `yuangs` is actively evolving.  
 The core governance model is stable; interfaces are still sharpening.
 

package/dist/agent/index.d.ts

@@ -7,3 +7,5 @@ export { LLMAdapter } from './llmAdapter';
 export { GovernanceService } from './governance';
 export { ToolExecutor } from './executor';
 export { ContextManager } from './contextManager';
+export * from './policy';
+export * from './replay';

package/dist/agent/index.js

@@ -31,4 +31,6 @@ var executor_1 = require("./executor");
 Object.defineProperty(exports, "ToolExecutor", { enumerable: true, get: function () { return executor_1.ToolExecutor; } });
 var contextManager_1 = require("./contextManager");
 Object.defineProperty(exports, "ContextManager", { enumerable: true, get: function () { return contextManager_1.ContextManager; } });
+__exportStar(require("./policy"), exports);
+__exportStar(require("./replay"), exports);
 //# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AACtB,0CAAwB;AACxB,0CAAwB;AACxB,6BAAsC;AAA7B,oGAAA,aAAa,OAAA;AACtB,+BAA2C;AAAlC,yGAAA,iBAAiB,OAAA;AAC1B,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA;AAC1B,uCAA0C;AAAjC,wGAAA,YAAY,OAAA;AACrB,mDAAkD;AAAzC,gHAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AACtB,0CAAwB;AACxB,0CAAwB;AACxB,6BAAsC;AAA7B,oGAAA,aAAa,OAAA;AACtB,+BAA2C;AAAlC,yGAAA,iBAAiB,OAAA;AAC1B,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA;AAC1B,uCAA0C;AAAjC,wGAAA,YAAY,OAAA;AACrB,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AACvB,2CAAyB;AACzB,2CAAyB"}

package/dist/agent/policy/engine.d.ts

@@ -0,0 +1,14 @@
+import { Policy, PolicyContext, PolicyResult } from './types';
+import { RiskLevel } from '../state';
+export declare class PolicyEngine {
+    private policies;
+    registerPolicy(policy: Policy): void;
+    unregisterPolicy(name: string): void;
+    evaluate(context: PolicyContext): Promise<PolicyResult>;
+    evaluateRisk(action: {
+        type: string;
+        payload: any;
+    }): RiskLevel;
+    private containsDangerousCommand;
+}
+export declare const policyEngine: PolicyEngine;

package/dist/agent/policy/engine.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.policyEngine = exports.PolicyEngine = void 0;
+class PolicyEngine {
+    policies = new Map();
+    registerPolicy(policy) {
+        this.policies.set(policy.name, policy);
+    }
+    unregisterPolicy(name) {
+        this.policies.delete(name);
+    }
+    async evaluate(context) {
+        let finalResult = {
+            allowed: true,
+            reason: 'All policies passed'
+        };
+        for (const [name, policy] of this.policies) {
+            const result = await policy.evaluate(context);
+            if (!result.allowed) {
+                return {
+                    allowed: false,
+                    reason: `Policy "${name}" blocked: ${result.reason}`,
+                    requiresEscalation: result.requiresEscalation || false,
+                    suggestedActions: result.suggestedActions
+                };
+            }
+            if (result.requiresEscalation) {
+                finalResult.requiresEscalation = true;
+                finalResult.suggestedActions = result.suggestedActions;
+            }
+        }
+        return finalResult;
+    }
+    evaluateRisk(action) {
+        const { type, payload } = action;
+        if (type === 'tool_call') {
+            const toolName = payload.tool_name;
+            const lowRiskTools = ['read_file', 'list_files', 'web_search'];
+            if (lowRiskTools.includes(toolName)) {
+                return 'low';
+            }
+            const mediumRiskTools = ['write_file', 'shell'];
+            if (mediumRiskTools.includes(toolName)) {
+                const cmd = payload.parameters?.command || payload.command || '';
+                if (this.containsDangerousCommand(cmd)) {
+                    return 'high';
+                }
+                return 'medium';
+            }
+            return 'medium';
+        }
+        if (type === 'shell_cmd') {
+            const cmd = payload.command || '';
+            if (this.containsDangerousCommand(cmd)) {
+                return 'high';
+            }
+            return 'medium';
+        }
+        return 'low';
+    }
+    containsDangerousCommand(cmd) {
+        const dangerousPatterns = [
+            /rm\s+-rf\s+\//,
+            /rm\s+-rf\s+~/,
+            />\s*\/dev\/null/,
+            /dd\s+if=/,
+            /mkfs/,
+            /format/,
+            /sudo\s+rm/
+        ];
+        return dangerousPatterns.some(pattern => pattern.test(cmd));
+    }
+}
+exports.PolicyEngine = PolicyEngine;
+exports.policyEngine = new PolicyEngine();
+//# sourceMappingURL=engine.js.map

package/dist/agent/policy/engine.js.map

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

package/dist/agent/policy/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './engine';
+export * from './policies/noDangerousShell';

package/dist/agent/policy/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./engine"), exports);
+__exportStar(require("./policies/noDangerousShell"), exports);
+//# sourceMappingURL=index.js.map

package/dist/agent/policy/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/policy/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,2CAAyB;AACzB,8DAA4C"}

package/dist/agent/policy/policies/noDangerousShell.d.ts

@@ -0,0 +1,7 @@
+import { Policy, PolicyContext, PolicyResult } from '../types';
+export declare class NoDangerousShellPolicy implements Policy {
+    name: string;
+    description: string;
+    evaluate(context: PolicyContext): PolicyResult;
+}
+export declare const noDangerousShellPolicy: NoDangerousShellPolicy;

package/dist/agent/policy/policies/noDangerousShell.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noDangerousShellPolicy = exports.NoDangerousShellPolicy = void 0;
+class NoDangerousShellPolicy {
+    name = 'no-dangerous-shell';
+    description = 'Prevents execution of dangerous shell commands';
+    evaluate(context) {
+        const { action } = context;
+        if (action.type === 'shell_cmd') {
+            const command = action.payload?.command || '';
+            const dangerousPatterns = [
+                { pattern: /rm\s+-rf\s+\//, name: 'rm -rf /', risk: 'high' },
+                { pattern: /rm\s+-rf\s+~/, name: 'rm -rf ~', risk: 'high' },
+                { pattern: />\s*\/dev\/null/, name: 'Redirect to /dev/null', risk: 'medium' },
+                { pattern: /dd\s+if=/, name: 'dd command', risk: 'high' },
+                { pattern: /mkfs/, name: 'mkfs (filesystem creation)', risk: 'high' },
+                { pattern: /format/, name: 'format command', risk: 'high' },
+                { pattern: /sudo\s+rm/, name: 'sudo rm', risk: 'high' },
+                { pattern: /chmod\s+777\s+\/(?!dev)/, name: 'chmod 777 on system', risk: 'high' },
+                { pattern: /:\s*~\(\)/, name: 'fork bomb', risk: 'high' }
+            ];
+            for (const { pattern, name, risk } of dangerousPatterns) {
+                if (pattern.test(command)) {
+                    return {
+                        allowed: false,
+                        reason: `Dangerous command detected: ${name} (${risk} risk)`,
+                        requiresEscalation: risk === 'high',
+                        suggestedActions: [
+                            `Review the command: "${command}"`,
+                            'Consider using safer alternatives',
+                            'Break down the operation into smaller, safer steps'
+                        ]
+                    };
+                }
+            }
+        }
+        return {
+            allowed: true,
+            reason: 'No dangerous patterns detected'
+        };
+    }
+}
+exports.NoDangerousShellPolicy = NoDangerousShellPolicy;
+exports.noDangerousShellPolicy = new NoDangerousShellPolicy();
+//# sourceMappingURL=noDangerousShell.js.map

package/dist/agent/policy/policies/noDangerousShell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noDangerousShell.js","sourceRoot":"","sources":["../../../../src/agent/policy/policies/noDangerousShell.ts"],"names":[],"mappings":";;;AAGA,MAAa,sBAAsB;IACjC,IAAI,GAAG,oBAAoB,CAAC;IAC5B,WAAW,GAAG,gDAAgD,CAAC;IAE/D,QAAQ,CAAC,OAAsB;QAC7B,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAE3B,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAChC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC;YAE9C,MAAM,iBAAiB,GAAG;gBACxB,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE;gBAC5D,EAAE,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE;gBAC3D,EAAE,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,uBAAuB,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC7E,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE;gBACzD,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,4BAA4B,EAAE,IAAI,EAAE,MAAM,EAAE;gBACrE,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE;gBAC3D,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE;gBACvD,EAAE,OAAO,EAAE,yBAAyB,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,EAAE;gBACjF,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE;aAC1D,CAAC;YAEF,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,iBAAiB,EAAE,CAAC;gBACxD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC1B,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,MAAM,EAAE,+BAA+B,IAAI,KAAK,IAAI,QAAQ;wBAC5D,kBAAkB,EAAE,IAAI,KAAK,MAAM;wBACnC,gBAAgB,EAAE;4BAChB,wBAAwB,OAAO,GAAG;4BAClC,mCAAmC;4BACnC,oDAAoD;yBACrD;qBACF,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,gCAAgC;SACzC,CAAC;IACJ,CAAC;CACF;AA3CD,wDA2CC;AAEY,QAAA,sBAAsB,GAAG,IAAI,sBAAsB,EAAE,CAAC"}

package/dist/agent/policy/types.d.ts

@@ -0,0 +1,23 @@
+export interface PolicyContext {
+    action: {
+        type: string;
+        payload: any;
+    };
+    user?: {
+        permissions: string[];
+    };
+    environment?: {
+        isProduction: boolean;
+    };
+}
+export interface PolicyResult {
+    allowed: boolean;
+    reason?: string;
+    requiresEscalation?: boolean;
+    suggestedActions?: string[];
+}
+export interface Policy {
+    name: string;
+    description: string;
+    evaluate(context: PolicyContext): PolicyResult | Promise<PolicyResult>;
+}

package/dist/agent/policy/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/agent/policy/types.js.map

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

package/dist/agent/replay/events.d.ts

@@ -0,0 +1,21 @@
+export type EventType = 'state_transition' | 'llm_call' | 'tool_execution' | 'governance_decision' | 'observation_recorded' | 'evaluation_result' | 'error_occurred';
+export interface RuntimeEvent {
+    id: string;
+    timestamp: number;
+    executionId: string;
+    type: EventType;
+    data: {
+        from?: string;
+        to?: string;
+        action?: any;
+        decision?: any;
+        result?: any;
+        error?: string;
+    };
+    metadata?: Record<string, any>;
+}
+export interface EventRecorder {
+    record(event: RuntimeEvent): void;
+    flush(): Promise<void>;
+    getEvents(executionId?: string): RuntimeEvent[];
+}

package/dist/agent/replay/events.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=events.js.map

package/dist/agent/replay/events.js.map

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

package/dist/agent/replay/index.d.ts

@@ -0,0 +1,3 @@
+export * from './events';
+export * from './recorder';
+export * from './replayer';

package/dist/agent/replay/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./events"), exports);
+__exportStar(require("./recorder"), exports);
+__exportStar(require("./replayer"), exports);
+//# sourceMappingURL=index.js.map

package/dist/agent/replay/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/replay/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,6CAA2B;AAC3B,6CAA2B"}

package/dist/agent/replay/recorder.d.ts

@@ -0,0 +1,11 @@
+import { RuntimeEvent, EventRecorder } from './events';
+export declare class FileEventRecorder implements EventRecorder {
+    private events;
+    private logFile;
+    private flushInterval;
+    constructor(logDir?: string);
+    record(event: RuntimeEvent): Promise<void>;
+    flush(): Promise<void>;
+    getEvents(executionId?: string): RuntimeEvent[];
+}
+export declare const createEvent: (executionId: string, type: RuntimeEvent["type"], data: RuntimeEvent["data"], metadata?: RuntimeEvent["metadata"]) => RuntimeEvent;

package/dist/agent/replay/recorder.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEvent = exports.FileEventRecorder = void 0;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+class FileEventRecorder {
+    events = [];
+    logFile;
+    flushInterval = 1000;
+    constructor(logDir = '.yuangs_events') {
+        this.logFile = path_1.default.join(logDir, `events_${Date.now()}.jsonl`);
+    }
+    async record(event) {
+        this.events.push(event);
+        if (this.events.length >= this.flushInterval) {
+            await this.flush();
+        }
+    }
+    async flush() {
+        if (this.events.length === 0)
+            return;
+        const logDir = path_1.default.dirname(this.logFile);
+        await promises_1.default.mkdir(logDir, { recursive: true });
+        const content = this.events
+            .map(e => JSON.stringify(e))
+            .join('\n') + '\n';
+        await promises_1.default.appendFile(this.logFile, content, 'utf8');
+        this.events = [];
+    }
+    getEvents(executionId) {
+        if (!executionId) {
+            return [...this.events];
+        }
+        return this.events.filter(e => e.executionId === executionId);
+    }
+}
+exports.FileEventRecorder = FileEventRecorder;
+const createEvent = (executionId, type, data, metadata) => ({
+    id: (0, crypto_1.randomUUID)(),
+    timestamp: Date.now(),
+    executionId,
+    type,
+    data,
+    metadata
+});
+exports.createEvent = createEvent;
+//# sourceMappingURL=recorder.js.map

package/dist/agent/replay/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../../src/agent/replay/recorder.ts"],"names":[],"mappings":";;;;;;AACA,2DAA6B;AAC7B,gDAAwB;AACxB,mCAAoC;AAEpC,MAAa,iBAAiB;IACpB,MAAM,GAAmB,EAAE,CAAC;IAC5B,OAAO,CAAS;IAChB,aAAa,GAAW,IAAI,CAAC;IAErC,YAAY,SAAiB,gBAAgB;QAC3C,IAAI,CAAC,OAAO,GAAG,cAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACjE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,KAAmB;QAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAExB,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YAC7C,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,MAAM,MAAM,GAAG,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,kBAAE,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAE5C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM;aACxB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;aAC3B,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAErB,MAAM,kBAAE,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACnB,CAAC;IAED,SAAS,CAAC,WAAoB;QAC5B,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,WAAW,CAAC,CAAC;IAChE,CAAC;CACF;AAtCD,8CAsCC;AAEM,MAAM,WAAW,GAAG,CACzB,WAAmB,EACnB,IAA0B,EAC1B,IAA0B,EAC1B,QAAmC,EACrB,EAAE,CAAC,CAAC;IAClB,EAAE,EAAE,IAAA,mBAAU,GAAE;IAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;IACrB,WAAW;IACX,IAAI;IACJ,IAAI;IACJ,QAAQ;CACT,CAAC,CAAC;AAZU,QAAA,WAAW,eAYrB"}