@mindburn/helm-mastra 1.0.2

package/README.md

@@ -0,0 +1,44 @@
+# @mindburn/helm-mastra
+
+HELM governance adapter for [Mastra](https://mastra.ai) agent framework with native Daytona sandbox integration.
+
+## What it does
+
+Wraps Mastra's Daytona sandbox with HELM governance:
+
+1. Every sandbox `exec` is evaluated against HELM policy first
+2. Denied commands never reach the sandbox
+3. Receipts form a deterministic proof chain
+
+## Quick start
+
+```typescript
+import { HelmMastraSandbox } from "@mindburn/helm-mastra";
+
+const sandbox = new HelmMastraSandbox({
+  baseUrl: "http://localhost:8080",
+  daytonaApiKey: process.env.DAYTONA_API_KEY,
+});
+
+const result = await sandbox.exec({
+  command: ["python3", "-c", 'print("governed exec")'],
+});
+
+console.log(result.stdout); // "governed exec\n"
+console.log(result.receipt.requestHash); // "sha256:..."
+```
+
+## Configuration
+
+| Option            | Default                  | Description              |
+| ----------------- | ------------------------ | ------------------------ |
+| `baseUrl`         | required                 | HELM kernel URL          |
+| `daytonaApiKey`   | required                 | Daytona API key          |
+| `daytonaUrl`      | `https://api.daytona.io` | Daytona API URL          |
+| `failClosed`      | `true`                   | Deny on HELM errors      |
+| `defaultLanguage` | `python3`                | Default exec language    |
+| `execTimeout`     | `30000`                  | Per-command timeout (ms) |
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @mindburn/helm-mastra
+ *
+ * HELM governance adapter for Mastra agent framework.
+ * Wraps Mastra's Daytona sandbox integration with HELM governance,
+ * providing policy enforcement, receipt chains, and sandbox preflight.
+ *
+ * Architecture:
+ *   Mastra tool → HelmMastraSandbox → HELM governance → Daytona sandbox
+ *
+ * Usage:
+ * ```ts
+ * import { HelmMastraSandbox } from '@mindburn/helm-mastra';
+ *
+ * const sandbox = new HelmMastraSandbox({
+ *   helmUrl: 'http://localhost:8080',
+ *   daytonaApiKey: 'dtn-xxx',
+ * });
+ *
+ * // Use within Mastra tools
+ * const result = await sandbox.exec({
+ *   command: ['python3', '-c', 'print("hello")'],
+ * });
+ * ```
+ */
+import type { HelmClientConfig, Receipt } from '@mindburn/helm';
+/** Configuration for the HELM Mastra sandbox adapter. */
+export interface HelmMastraSandboxConfig extends HelmClientConfig {
+    /** Daytona API key for sandbox operations. */
+    daytonaApiKey: string;
+    /** Daytona API URL. Default: https://api.daytona.io */
+    daytonaUrl?: string;
+    /** If true, deny execution on governance errors (fail-closed). Default: true. */
+    failClosed?: boolean;
+    /** Default language for code execution. Default: 'python3'. */
+    defaultLanguage?: string;
+    /** Per-command timeout in milliseconds. Default: 30000. */
+    execTimeout?: number;
+    /** If true, collect receipts. Default: true. */
+    collectReceipts?: boolean;
+    /** Callback invoked after each successful execution with its receipt. */
+    onReceipt?: (receipt: SandboxReceipt) => void;
+    /** Callback invoked when execution is denied. */
+    onDeny?: (denial: SandboxDenial) => void;
+}
+/** A receipt for a governed sandbox execution. */
+export interface SandboxReceipt {
+    command: string[];
+    receipt: Receipt;
+    requestHash: string;
+    outputHash: string;
+    exitCode: number;
+    durationMs: number;
+}
+/** Details of a denied sandbox execution. */
+export interface SandboxDenial {
+    command: string[];
+    reasonCode: string;
+    message: string;
+}
+/** Sandbox execution request. */
+export interface ExecRequest {
+    command: string[];
+    env?: Record<string, string>;
+    workDir?: string;
+    timeout?: number;
+}
+/** Sandbox execution result. */
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    timedOut: boolean;
+    receipt: SandboxReceipt;
+}
+/** File operations. */
+export interface SandboxFile {
+    path: string;
+    content: string;
+}
+export declare class HelmSandboxDenyError extends Error {
+    readonly denial: SandboxDenial;
+    constructor(denial: SandboxDenial);
+}
+/**
+ * HelmMastraSandbox wraps Mastra's Daytona sandbox with HELM governance.
+ *
+ * Each sandbox operation goes through HELM's governance plane:
+ * 1. HELM evaluates the tool call intent against policy
+ * 2. If approved, the command is forwarded to Daytona
+ * 3. A receipt is produced for the execution
+ */
+export declare class HelmMastraSandbox {
+    private readonly helmClient;
+    private readonly daytonaUrl;
+    private readonly daytonaApiKey;
+    private readonly failClosed;
+    private readonly defaultLanguage;
+    private readonly execTimeout;
+    private readonly collectReceipts;
+    private readonly onReceipt?;
+    private readonly onDeny?;
+    private readonly receipts;
+    private sandboxId;
+    private lastLamportClock;
+    constructor(config: HelmMastraSandboxConfig);
+    /**
+     * Initialize the sandbox. Must be called before exec.
+     */
+    init(): Promise<void>;
+    /**
+     * Execute a command in the sandbox with HELM governance.
+     */
+    exec(req: ExecRequest): Promise<ExecResult>;
+    /**
+     * Write a file to the sandbox.
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Read a file from the sandbox.
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Destroy the sandbox.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get collected receipts.
+     */
+    getReceipts(): ReadonlyArray<SandboxReceipt>;
+    /**
+     * Clear collected receipts.
+     */
+    clearReceipts(): void;
+    private static resolveReceiptStatus;
+    private nextLamportClock;
+}
+export default HelmMastraSandbox;

package/dist/index.js

@@ -0,0 +1,323 @@
+/**
+ * @mindburn/helm-mastra
+ *
+ * HELM governance adapter for Mastra agent framework.
+ * Wraps Mastra's Daytona sandbox integration with HELM governance,
+ * providing policy enforcement, receipt chains, and sandbox preflight.
+ *
+ * Architecture:
+ *   Mastra tool → HelmMastraSandbox → HELM governance → Daytona sandbox
+ *
+ * Usage:
+ * ```ts
+ * import { HelmMastraSandbox } from '@mindburn/helm-mastra';
+ *
+ * const sandbox = new HelmMastraSandbox({
+ *   helmUrl: 'http://localhost:8080',
+ *   daytonaApiKey: 'dtn-xxx',
+ * });
+ *
+ * // Use within Mastra tools
+ * const result = await sandbox.exec({
+ *   command: ['python3', '-c', 'print("hello")'],
+ * });
+ * ```
+ */
+import { HelmClient, HelmApiError } from '@mindburn/helm';
+import { createHash } from 'node:crypto';
+// ── Errors ──────────────────────────────────────────────────────
+export class HelmSandboxDenyError extends Error {
+    denial;
+    constructor(denial) {
+        super(`HELM denied sandbox exec: ${denial.reasonCode} — ${denial.message}`);
+        this.name = 'HelmSandboxDenyError';
+        this.denial = denial;
+    }
+}
+// ── Sandbox ─────────────────────────────────────────────────────
+/**
+ * HelmMastraSandbox wraps Mastra's Daytona sandbox with HELM governance.
+ *
+ * Each sandbox operation goes through HELM's governance plane:
+ * 1. HELM evaluates the tool call intent against policy
+ * 2. If approved, the command is forwarded to Daytona
+ * 3. A receipt is produced for the execution
+ */
+export class HelmMastraSandbox {
+    helmClient;
+    daytonaUrl;
+    daytonaApiKey;
+    failClosed;
+    defaultLanguage;
+    execTimeout;
+    collectReceipts;
+    onReceipt;
+    onDeny;
+    receipts = [];
+    sandboxId = null;
+    lastLamportClock = -1;
+    constructor(config) {
+        this.helmClient = new HelmClient(config);
+        this.daytonaUrl = config.daytonaUrl ?? 'https://api.daytona.io';
+        this.daytonaApiKey = config.daytonaApiKey;
+        this.failClosed = config.failClosed ?? true;
+        this.defaultLanguage = config.defaultLanguage ?? 'python3';
+        this.execTimeout = config.execTimeout ?? 30_000;
+        this.collectReceipts = config.collectReceipts ?? true;
+        this.onReceipt = config.onReceipt;
+        this.onDeny = config.onDeny;
+    }
+    /**
+     * Initialize the sandbox. Must be called before exec.
+     */
+    async init() {
+        // Create a Daytona sandbox.
+        const resp = await fetch(`${this.daytonaUrl}/sandbox`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.daytonaApiKey}`,
+            },
+            body: JSON.stringify({
+                language: this.defaultLanguage,
+                timeout: Math.floor(this.execTimeout / 1000),
+            }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Daytona sandbox creation failed: ${resp.status}`);
+        }
+        const data = (await resp.json());
+        this.sandboxId = data.sandboxId;
+    }
+    /**
+     * Execute a command in the sandbox with HELM governance.
+     */
+    async exec(req) {
+        if (!this.sandboxId) {
+            await this.init();
+        }
+        const startMs = Date.now();
+        // Step 1: HELM governance evaluation.
+        // Use chatCompletionsWithReceipt to get kernel-issued governance metadata.
+        let governanceStatus = '';
+        let governanceReasonCode = '';
+        let kernelReceiptId = '';
+        let kernelDecisionId = '';
+        let kernelProofGraphNode = '';
+        let kernelLamportClock = 0;
+        let kernelSignature = '';
+        let kernelOutputHash = '';
+        let governanceEvaluated = false;
+        try {
+            const { response: governanceResp, governance } = await this.helmClient.chatCompletionsWithReceipt({
+                model: 'helm-governance',
+                messages: [
+                    {
+                        role: 'user',
+                        content: JSON.stringify({
+                            type: 'sandbox_exec_intent',
+                            provider: 'daytona',
+                            sandbox_id: this.sandboxId,
+                            command: req.command,
+                            env: req.env,
+                        }),
+                    },
+                ],
+                tools: [
+                    {
+                        type: 'function',
+                        function: {
+                            name: 'sandbox_exec',
+                            description: 'Execute command in Daytona sandbox',
+                            parameters: {
+                                type: 'object',
+                                properties: {
+                                    command: { type: 'array', items: { type: 'string' } },
+                                },
+                            },
+                        },
+                    },
+                ],
+            });
+            // Extract kernel governance metadata
+            governanceStatus = governance.status;
+            governanceReasonCode = governance.reasonCode;
+            kernelReceiptId = governance.receiptId;
+            kernelDecisionId = governance.decisionId;
+            kernelProofGraphNode = governance.proofGraphNode;
+            kernelLamportClock = governance.lamportClock;
+            kernelSignature = governance.signature;
+            kernelOutputHash = governance.outputHash;
+            const choice = governanceResp.choices?.[0];
+            const kernelDenied = governanceStatus === 'DENIED' || governanceStatus === 'PEP_VALIDATION_FAILED';
+            if (kernelDenied || (!choice || (choice.finish_reason === 'stop' && !choice.message?.tool_calls))) {
+                const denial = {
+                    command: req.command,
+                    reasonCode: governanceReasonCode || 'DENY_POLICY_VIOLATION',
+                    message: choice?.message?.content ?? 'Sandbox exec denied by HELM governance',
+                };
+                this.onDeny?.(denial);
+                throw new HelmSandboxDenyError(denial);
+            }
+            governanceEvaluated = true;
+        }
+        catch (error) {
+            if (error instanceof HelmSandboxDenyError)
+                throw error;
+            if (error instanceof HelmApiError) {
+                const denial = {
+                    command: req.command,
+                    reasonCode: error.reasonCode,
+                    message: error.message,
+                };
+                this.onDeny?.(denial);
+                if (this.failClosed)
+                    throw new HelmSandboxDenyError(denial);
+                governanceStatus = 'PENDING';
+                governanceReasonCode = error.reasonCode;
+            }
+            if (this.failClosed)
+                throw error;
+            governanceStatus = governanceStatus || 'PENDING';
+            governanceReasonCode = governanceReasonCode || 'ERROR_INTERNAL';
+        }
+        // Step 2: Execute on Daytona.
+        const cmd = req.command.join(' ');
+        const execResp = await fetch(`${this.daytonaUrl}/sandbox/${this.sandboxId}/process/execute`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.daytonaApiKey}`,
+            },
+            body: JSON.stringify({
+                command: cmd,
+                env: req.env,
+                cwd: req.workDir,
+                timeout: req.timeout ? Math.floor(req.timeout / 1000) : Math.floor(this.execTimeout / 1000),
+            }),
+        });
+        if (!execResp.ok) {
+            throw new Error(`Daytona exec failed: ${execResp.status}`);
+        }
+        const result = (await execResp.json());
+        // Step 3: Build receipt from kernel-issued data (NOT fabricated).
+        const durationMs = Date.now() - startMs;
+        const requestHash = 'sha256:' + createHash('sha256').update(JSON.stringify(req)).digest('hex');
+        const outputHash = 'sha256:' + createHash('sha256').update(result.output || '').digest('hex');
+        const lamportClock = this.nextLamportClock(kernelLamportClock);
+        const receiptStatus = HelmMastraSandbox.resolveReceiptStatus(governanceStatus, governanceEvaluated);
+        const receiptToken = `${requestHash.slice(7, 19)}-${lamportClock}`;
+        const receipt = {
+            command: req.command,
+            receipt: {
+                receipt_id: kernelReceiptId || `mastra-${receiptToken}`,
+                decision_id: kernelDecisionId || `decision-${receiptToken}`,
+                effect_id: kernelProofGraphNode || `exec-${receiptToken}`,
+                status: receiptStatus,
+                reason_code: governanceReasonCode || (governanceEvaluated ? 'ALLOW' : 'ERROR_INTERNAL'),
+                output_hash: kernelOutputHash || outputHash,
+                blob_hash: '',
+                prev_hash: '',
+                lamport_clock: lamportClock,
+                signature: kernelSignature || '',
+                timestamp: new Date().toISOString(),
+                principal: governanceEvaluated ? 'helm-kernel' : 'helm-fail-open',
+            },
+            requestHash,
+            outputHash,
+            exitCode: result.exitCode,
+            durationMs,
+        };
+        if (this.collectReceipts) {
+            this.receipts.push(receipt);
+        }
+        this.onReceipt?.(receipt);
+        return {
+            exitCode: result.exitCode,
+            stdout: result.output,
+            stderr: result.errors,
+            durationMs: result.durationMs,
+            timedOut: result.timedOut,
+            receipt,
+        };
+    }
+    /**
+     * Write a file to the sandbox.
+     */
+    async writeFile(path, content) {
+        if (!this.sandboxId)
+            await this.init();
+        const resp = await fetch(`${this.daytonaUrl}/sandbox/${this.sandboxId}/filesystem?path=${encodeURIComponent(path)}`, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/octet-stream',
+                Authorization: `Bearer ${this.daytonaApiKey}`,
+            },
+            body: content,
+        });
+        if (!resp.ok) {
+            throw new Error(`Daytona write file failed: ${resp.status}`);
+        }
+    }
+    /**
+     * Read a file from the sandbox.
+     */
+    async readFile(path) {
+        if (!this.sandboxId)
+            await this.init();
+        const resp = await fetch(`${this.daytonaUrl}/sandbox/${this.sandboxId}/filesystem?path=${encodeURIComponent(path)}`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${this.daytonaApiKey}`,
+            },
+        });
+        if (!resp.ok) {
+            throw new Error(`Daytona read file failed: ${resp.status}`);
+        }
+        return resp.text();
+    }
+    /**
+     * Destroy the sandbox.
+     */
+    async destroy() {
+        if (!this.sandboxId)
+            return;
+        await fetch(`${this.daytonaUrl}/sandbox/${this.sandboxId}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${this.daytonaApiKey}` },
+        });
+        this.sandboxId = null;
+    }
+    /**
+     * Get collected receipts.
+     */
+    getReceipts() {
+        return this.receipts;
+    }
+    /**
+     * Clear collected receipts.
+     */
+    clearReceipts() {
+        this.receipts.length = 0;
+    }
+    static resolveReceiptStatus(governanceStatus, governanceEvaluated) {
+        if (!governanceEvaluated) {
+            return 'PENDING';
+        }
+        if (governanceStatus === 'DENIED' || governanceStatus === 'PEP_VALIDATION_FAILED') {
+            return 'DENIED';
+        }
+        if (governanceStatus === 'PENDING') {
+            return 'PENDING';
+        }
+        return 'APPROVED';
+    }
+    nextLamportClock(kernelLamportClock) {
+        const nextLamportClock = kernelLamportClock > this.lastLamportClock
+            ? kernelLamportClock
+            : this.lastLamportClock + 1;
+        this.lastLamportClock = nextLamportClock;
+        return nextLamportClock;
+    }
+}
+export default HelmMastraSandbox;

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,379 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { HelmMastraSandbox, HelmSandboxDenyError } from './index.js';
+// ── Helpers ─────────────────────────────────────────────────────
+function jsonResponse(body, status = 200) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+function createSandboxResponse(sandboxId = 'sbx-1234') {
+    return jsonResponse({ sandboxId });
+}
+function execResponse(output = 'hello\n', exitCode = 0) {
+    return jsonResponse({
+        output,
+        errors: '',
+        exitCode,
+        timedOut: false,
+        durationMs: 42,
+    });
+}
+function governanceApproveResponse() {
+    return jsonResponse({
+        id: `chatcmpl-${Date.now()}`,
+        object: 'chat.completion',
+        created: Date.now(),
+        model: 'helm-governance',
+        choices: [
+            {
+                index: 0,
+                message: {
+                    role: 'assistant',
+                    content: null,
+                    tool_calls: [
+                        {
+                            id: `call_${Date.now()}`,
+                            type: 'function',
+                            function: { name: 'sandbox_exec', arguments: '{}' },
+                        },
+                    ],
+                },
+                finish_reason: 'tool_calls',
+            },
+        ],
+    });
+}
+function governanceDenyResponse(reason = 'Sandbox exec denied by HELM governance') {
+    return jsonResponse({
+        id: `chatcmpl-${Date.now()}`,
+        object: 'chat.completion',
+        created: Date.now(),
+        model: 'helm-governance',
+        choices: [
+            {
+                index: 0,
+                message: { role: 'assistant', content: reason },
+                finish_reason: 'stop',
+            },
+        ],
+    });
+}
+function helmApiErrorResponse(status, reasonCode = 'DENY_POLICY_VIOLATION', message = 'denied') {
+    return jsonResponse({
+        error: {
+            message,
+            type: 'permission_denied',
+            code: 'DENY',
+            reason_code: reasonCode,
+        },
+    }, status);
+}
+// ── Tests ───────────────────────────────────────────────────────
+describe('HelmMastraSandbox', () => {
+    let fetchSpy;
+    beforeEach(() => {
+        fetchSpy = vi.fn();
+        vi.stubGlobal('fetch', fetchSpy);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    function makeSandbox(overrides = {}) {
+        return new HelmMastraSandbox({
+            baseUrl: 'http://helm:8080',
+            daytonaApiKey: 'dtn-test-key',
+            daytonaUrl: 'http://daytona:3000',
+            ...overrides,
+        });
+    }
+    // ── Sandbox creation ───────────────────────────────────
+    describe('init', () => {
+        it('creates a Daytona sandbox with correct auth', async () => {
+            fetchSpy.mockResolvedValue(createSandboxResponse());
+            const sandbox = makeSandbox();
+            await sandbox.init();
+            expect(fetchSpy).toHaveBeenCalledWith('http://daytona:3000/sandbox', expect.objectContaining({
+                method: 'POST',
+                headers: expect.objectContaining({
+                    Authorization: 'Bearer dtn-test-key',
+                }),
+            }));
+        });
+        it('throws on Daytona creation failure', async () => {
+            fetchSpy.mockResolvedValue(new Response('fail', { status: 500 }));
+            const sandbox = makeSandbox();
+            await expect(sandbox.init()).rejects.toThrow('Daytona sandbox creation failed: 500');
+        });
+    });
+    // ── Governance-approved execution ──────────────────────
+    describe('exec (approved)', () => {
+        it('executes command through HELM governance then Daytona', async () => {
+            // Call 1: Daytona create (auto-init)
+            // Call 2: HELM governance
+            // Call 3: Daytona exec
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse('sbx-1'))
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse('world\n', 0));
+            const sandbox = makeSandbox();
+            const result = await sandbox.exec({ command: ['echo', 'world'] });
+            expect(result.stdout).toBe('world\n');
+            expect(result.exitCode).toBe(0);
+            expect(result.timedOut).toBe(false);
+        });
+        it('sends governance intent with sandbox provider metadata', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse('sbx-meta'))
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse());
+            const sandbox = makeSandbox();
+            await sandbox.exec({ command: ['ls', '-la'] });
+            // Call index 1 is HELM governance
+            const helmBody = JSON.parse(fetchSpy.mock.calls[1][1].body);
+            const intent = JSON.parse(helmBody.messages[0].content);
+            expect(intent.type).toBe('sandbox_exec_intent');
+            expect(intent.provider).toBe('daytona');
+            expect(intent.sandbox_id).toBe('sbx-meta');
+            expect(intent.command).toEqual(['ls', '-la']);
+        });
+    });
+    // ── Denial path ────────────────────────────────────────
+    describe('exec (denied)', () => {
+        it('throws HelmSandboxDenyError when governance denies', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceDenyResponse('Not allowed'));
+            const sandbox = makeSandbox();
+            await expect(sandbox.exec({ command: ['rm', '-rf', '/'] })).rejects.toThrow(HelmSandboxDenyError);
+        });
+        it('denial error contains command and reason', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceDenyResponse('Blocked by policy'));
+            const sandbox = makeSandbox();
+            try {
+                await sandbox.exec({ command: ['dangerous'] });
+                expect.unreachable('should have thrown');
+            }
+            catch (e) {
+                const err = e;
+                expect(err.denial.command).toEqual(['dangerous']);
+                expect(err.denial.reasonCode).toBe('DENY_POLICY_VIOLATION');
+                expect(err.name).toBe('HelmSandboxDenyError');
+            }
+        });
+        it('invokes onDeny callback', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceDenyResponse());
+            const denials = [];
+            const sandbox = makeSandbox({ onDeny: (d) => denials.push(d) });
+            try {
+                await sandbox.exec({ command: ['test'] });
+            }
+            catch { /* expected */ }
+            expect(denials).toHaveLength(1);
+        });
+        it('never reaches Daytona on denial', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceDenyResponse());
+            const sandbox = makeSandbox();
+            try {
+                await sandbox.exec({ command: ['test'] });
+            }
+            catch { /* expected */ }
+            // Only 2 calls: Daytona create + HELM governance. No Daytona exec.
+            expect(fetchSpy).toHaveBeenCalledTimes(2);
+        });
+    });
+    // ── Fail-closed behavior ───────────────────────────────
+    describe('fail-closed', () => {
+        it('throws on HELM API 500 when failClosed=true (default)', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(helmApiErrorResponse(500));
+            const sandbox = makeSandbox();
+            await expect(sandbox.exec({ command: ['echo'] })).rejects.toThrow();
+        });
+        it('throws on HELM network error when failClosed=true', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockRejectedValueOnce(new Error('ECONNREFUSED'));
+            const sandbox = makeSandbox();
+            await expect(sandbox.exec({ command: ['echo'] })).rejects.toThrow('ECONNREFUSED');
+        });
+        it('marks fail-open execution as pending instead of approved', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(helmApiErrorResponse(500))
+                .mockResolvedValueOnce(execResponse('ok', 0));
+            const sandbox = makeSandbox({ failClosed: false });
+            const result = await sandbox.exec({ command: ['echo', 'ok'] });
+            expect(result.stdout).toBe('ok');
+            expect(result.receipt.receipt.status).toBe('PENDING');
+            expect(result.receipt.receipt.principal).toBe('helm-fail-open');
+        });
+    });
+    // ── Receipt collection ─────────────────────────────────
+    describe('receipt collection', () => {
+        it('collects receipt with deterministic request hash', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse('out', 0));
+            const sandbox = makeSandbox();
+            const result = await sandbox.exec({ command: ['echo', 'out'] });
+            expect(result.receipt).toBeDefined();
+            expect(result.receipt.requestHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+            expect(result.receipt.outputHash).toMatch(/^sha256:[a-f0-9]{64}$/);
+            expect(result.receipt.receipt.status).toBe('APPROVED');
+        });
+        it('same input produces same request hash', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse('a'))
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse('a'));
+            const sandbox = makeSandbox();
+            const r1 = await sandbox.exec({ command: ['echo', 'deterministic'] });
+            const r2 = await sandbox.exec({ command: ['echo', 'deterministic'] });
+            expect(r1.receipt.requestHash).toBe(r2.receipt.requestHash);
+        });
+        it('different output produces different output hash', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse('output_A'))
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse('output_B'));
+            const sandbox = makeSandbox();
+            const r1 = await sandbox.exec({ command: ['echo', 'A'] });
+            const r2 = await sandbox.exec({ command: ['echo', 'B'] });
+            expect(r1.receipt.outputHash).not.toBe(r2.receipt.outputHash);
+        });
+        it('invokes onReceipt callback', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse());
+            const receipts = [];
+            const sandbox = makeSandbox({ onReceipt: (r) => receipts.push(r) });
+            await sandbox.exec({ command: ['echo'] });
+            expect(receipts).toHaveLength(1);
+        });
+        it('getReceipts returns accumulated receipts', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse());
+            const sandbox = makeSandbox();
+            await sandbox.exec({ command: ['cmd1'] });
+            await sandbox.exec({ command: ['cmd2'] });
+            expect(sandbox.getReceipts()).toHaveLength(2);
+        });
+        it('clearReceipts empties the collection', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse());
+            const sandbox = makeSandbox();
+            await sandbox.exec({ command: ['echo'] });
+            expect(sandbox.getReceipts()).toHaveLength(1);
+            sandbox.clearReceipts();
+            expect(sandbox.getReceipts()).toHaveLength(0);
+        });
+        it('receipt lamport clock increments', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse())
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse());
+            const sandbox = makeSandbox();
+            await sandbox.exec({ command: ['echo', 'a'] });
+            await sandbox.exec({ command: ['echo', 'b'] });
+            const receipts = sandbox.getReceipts();
+            expect(receipts[0].receipt.lamport_clock).toBe(0);
+            expect(receipts[1].receipt.lamport_clock).toBe(1);
+        });
+    });
+    // ── Sandbox lifecycle ──────────────────────────────────
+    describe('lifecycle', () => {
+        it('auto-initializes on first exec', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse('auto-init'))
+                .mockResolvedValueOnce(governanceApproveResponse())
+                .mockResolvedValueOnce(execResponse());
+            const sandbox = makeSandbox();
+            // Don't call init() explicitly
+            await sandbox.exec({ command: ['echo'] });
+            // First call should be Daytona create
+            expect(fetchSpy.mock.calls[0][0]).toBe('http://daytona:3000/sandbox');
+        });
+        it('destroy() sends DELETE and clears sandbox ID', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse('destroy-me'))
+                .mockResolvedValueOnce(new Response(null, { status: 204 }));
+            const sandbox = makeSandbox();
+            await sandbox.init();
+            await sandbox.destroy();
+            const deleteCall = fetchSpy.mock.calls[1];
+            expect(deleteCall[0]).toBe('http://daytona:3000/sandbox/destroy-me');
+            expect(deleteCall[1].method).toBe('DELETE');
+        });
+        it('destroy() is idempotent when not initialized', async () => {
+            const sandbox = makeSandbox();
+            await sandbox.destroy(); // should not throw
+            expect(fetchSpy).not.toHaveBeenCalled();
+        });
+    });
+    // ── File operations ────────────────────────────────────
+    describe('file operations', () => {
+        it('writeFile sends PUT with content', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse('fs-test'))
+                .mockResolvedValueOnce(new Response(null, { status: 200 }));
+            const sandbox = makeSandbox();
+            await sandbox.init();
+            await sandbox.writeFile('/app/test.py', 'print("hello")');
+            const writeCall = fetchSpy.mock.calls[1];
+            expect(writeCall[0]).toContain('/sandbox/fs-test/filesystem');
+            expect(writeCall[0]).toContain('path=%2Fapp%2Ftest.py');
+            expect(writeCall[1].method).toBe('PUT');
+            expect(writeCall[1].body).toBe('print("hello")');
+        });
+        it('readFile sends GET and returns content', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse('fs-read'))
+                .mockResolvedValueOnce(new Response('file content', { status: 200 }));
+            const sandbox = makeSandbox();
+            await sandbox.init();
+            const content = await sandbox.readFile('/app/out.txt');
+            expect(content).toBe('file content');
+            const readCall = fetchSpy.mock.calls[1];
+            expect(readCall[0]).toContain('path=%2Fapp%2Fout.txt');
+            expect(readCall[1].method).toBe('GET');
+        });
+        it('writeFile throws on failure', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(new Response('fail', { status: 500 }));
+            const sandbox = makeSandbox();
+            await sandbox.init();
+            await expect(sandbox.writeFile('/bad', 'data')).rejects.toThrow('Daytona write file failed: 500');
+        });
+        it('readFile throws on failure', async () => {
+            fetchSpy
+                .mockResolvedValueOnce(createSandboxResponse())
+                .mockResolvedValueOnce(new Response('fail', { status: 404 }));
+            const sandbox = makeSandbox();
+            await sandbox.init();
+            await expect(sandbox.readFile('/missing')).rejects.toThrow('Daytona read file failed: 404');
+        });
+    });
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mindburn/helm-mastra",
+  "version": "1.0.2",
+  "description": "HELM governance adapter for Mastra agent framework — sandbox-aware",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest",
+    "lint": "biome lint ."
+  },
+  "dependencies": {
+    "@mindburn/helm": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@mastra/core": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.1",
+    "typescript": "^5.4.0",
+    "vitest": "^4.0.18"
+  },
+  "overrides": {
+    "rollup": "^4.59.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mindburn-Labs/helm-oss",
+    "directory": "sdk/ts/mastra"
+  },
+  "keywords": ["helm", "mastra", "daytona", "governance", "sandbox"]
+}