@runsynapse/sdk 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# @synapserun/sdk
+
+**281x faster code execution for AI agents.** Sub-millisecond Wasm execution on bare metal.
+
+## Install
+
+```bash
+npm i @synapserun/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Synapse } from '@synapserun/sdk';
+
+const client = new Synapse({ apiKey: 'sk_live_...' });
+
+// Execute .syn code — returns in <1ms (p99)
+const result = await client.execute('@f 0 main [ + 21 21 ]');
+console.log(result.result);     // 42
+console.log(result.latencyMs);  // 0.52
+
+// Batch execute — up to 1000 jobs
+const batch = await client.executeBatch([
+  { code: '@f 0 main [ + 1 2 ]' },
+  { code: '@f 0 main [ * 3 4 ]' },
+  { code: '@f 0 main [ - 100 58 ]' },
+]);
+batch.results.forEach(r => console.log(r.result)); // 3, 12, 42
+
+// Validate without executing
+const meta = await client.validate('@f 0 main [ + 1 1 ]');
+console.log(meta); // { valid: true, wasm_size: 89, ... }
+
+// Natural language computation
+const answer = await client.compute('calculate fibonacci of 10');
+console.log(answer);
+```
+
+## Performance
+
+Proven with 100,000 sequential executions on Hetzner AX102:
+
+| Metric | Value |
+|--------|-------|
+| **p50 latency** | 0.53ms |
+| **p99 latency** | 0.72ms |
+| **vs E2B** | 281x faster |
+| **vs Blaxel** | 47x faster |
+| **Correctness** | 100,000/100,000 |
+
+## API Reference
+
+### `new Synapse(config)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `apiKey` | `string` | — | Your API key |
+| `baseUrl` | `string` | `https://api.synapse.dev` | Gateway URL |
+| `timeout` | `number` | `15000` | Timeout in ms |
+| `maxRetries` | `number` | `3` | Retry count |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `execute(code)` | Execute .syn source code |
+| `executeWasm(bytes)` | Execute pre-compiled .wasm binary |
+| `executeBatch(jobs)` | Execute up to 1000 jobs in parallel |
+| `validate(code)` | Validate .syn syntax |
+| `compute(intent)` | Natural language → computation |
+| `health()` | Check gateway health |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Synapse SDK — 281x faster code execution for AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { Synapse } from '@synapserun/sdk';
+ *
+ * const client = new Synapse({ apiKey: 'sk_live_...' });
+ * const result = await client.execute('@f 0 main [ + 21 21 ]');
+ * console.log(result.result); // 42
+ * console.log(result.latencyMs); // 0.52
+ * ```
+ */
+export interface SynapseConfig {
+    /** API key starting with sk_live_ */
+    apiKey: string;
+    /** Gateway URL (default: https://api.synapse.dev) */
+    baseUrl?: string;
+    /** Request timeout in ms (default: 15000) */
+    timeout?: number;
+    /** Max retries for transient errors (default: 3) */
+    maxRetries?: number;
+}
+export interface ExecutionResult {
+    /** Integer return value from the Wasm module */
+    result: number;
+    /** Captured stdout output */
+    stdout: string;
+    /** Arena memory position */
+    arenaPos: number;
+    /** End-to-end latency in milliseconds */
+    latencyMs: number;
+    /** Unique execution ID */
+    executionId: string;
+    /** Compile time in milliseconds */
+    compileTimeMs: number;
+    /** Wasm binary size in bytes */
+    wasmSize: number;
+    /** SHA-256 hash of the Wasm binary */
+    deterministicHash: string;
+    /** Cost in USD */
+    costUsd: number;
+}
+export interface BatchResult {
+    /** Total jobs in batch */
+    total: number;
+    /** Successfully executed */
+    succeeded: number;
+    /** Failed executions */
+    failed: number;
+    /** Total batch latency in ms */
+    batchLatencyMs: number;
+    /** Per-job results */
+    results: Array<{
+        result: number;
+        stdout: string;
+        latencyMs: number;
+        status: string;
+    }>;
+}
+export interface HealthStatus {
+    status: string;
+    version: string;
+    kernelConnected: boolean;
+    endpoints: string[];
+}
+export declare class SynapseError extends Error {
+    statusCode: number;
+    errorType: string;
+    constructor(statusCode: number, message: string, errorType?: string);
+}
+export declare class Synapse {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private maxRetries;
+    constructor(config: SynapseConfig);
+    private request;
+    /**
+     * Execute .syn source code on bare-metal Wasm engine.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.execute('@f 0 main [ + 21 21 ]');
+     * console.log(result.result); // 42
+     * ```
+     */
+    execute(code: string): Promise<ExecutionResult>;
+    /**
+     * Execute a pre-compiled .wasm binary.
+     */
+    executeWasm(wasmBytes: Uint8Array): Promise<ExecutionResult>;
+    /**
+     * Execute up to 1000 jobs in a single batch.
+     *
+     * @example
+     * ```typescript
+     * const batch = await client.executeBatch([
+     *   { code: '@f 0 main [ + 1 2 ]' },
+     *   { code: '@f 0 main [ * 3 4 ]' },
+     * ]);
+     * batch.results.forEach(r => console.log(r.result)); // 3, 12
+     * ```
+     */
+    executeBatch(jobs: Array<{
+        code: string;
+    }>): Promise<BatchResult>;
+    /**
+     * Validate .syn syntax without executing.
+     */
+    validate(code: string): Promise<Record<string, unknown>>;
+    /**
+     * Natural language computation — describe what you want and get results.
+     */
+    compute(intent: string): Promise<Record<string, unknown>>;
+    /**
+     * Check gateway health and kernel connectivity.
+     */
+    health(): Promise<HealthStatus>;
+}
+export default Synapse;

package/dist/index.js

@@ -0,0 +1,176 @@
+"use strict";
+/**
+ * Synapse SDK — 281x faster code execution for AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { Synapse } from '@synapserun/sdk';
+ *
+ * const client = new Synapse({ apiKey: 'sk_live_...' });
+ * const result = await client.execute('@f 0 main [ + 21 21 ]');
+ * console.log(result.result); // 42
+ * console.log(result.latencyMs); // 0.52
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Synapse = exports.SynapseError = void 0;
+class SynapseError extends Error {
+    constructor(statusCode, message, errorType = '') {
+        super(`Synapse API error ${statusCode}: ${message}`);
+        this.name = 'SynapseError';
+        this.statusCode = statusCode;
+        this.errorType = errorType;
+    }
+}
+exports.SynapseError = SynapseError;
+class Synapse {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl || 'https://api.synapse.dev').replace(/\/$/, '');
+        this.timeout = config.timeout || 15000;
+        this.maxRetries = config.maxRetries || 3;
+    }
+    async request(endpoint, payload) {
+        const url = `${this.baseUrl}${endpoint}`;
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timer = setTimeout(() => controller.abort(), this.timeout);
+                const resp = await fetch(url, {
+                    method: payload ? 'POST' : 'GET',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${this.apiKey}`,
+                    },
+                    body: payload ? JSON.stringify(payload) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                const body = await resp.json();
+                if (!resp.ok) {
+                    const errMsg = body.error || `HTTP ${resp.status}`;
+                    if (resp.status >= 400 && resp.status < 500) {
+                        throw new SynapseError(resp.status, errMsg, body.error_type || '');
+                    }
+                    throw new SynapseError(resp.status, errMsg);
+                }
+                return body;
+            }
+            catch (e) {
+                if (e instanceof SynapseError && e.statusCode >= 400 && e.statusCode < 500) {
+                    throw e; // Don't retry client errors
+                }
+                lastError = e;
+                if (attempt < this.maxRetries) {
+                    await new Promise(r => setTimeout(r, Math.min(2 ** attempt * 100, 5000)));
+                }
+            }
+        }
+        throw lastError || new SynapseError(0, 'Unknown error');
+    }
+    /**
+     * Execute .syn source code on bare-metal Wasm engine.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.execute('@f 0 main [ + 21 21 ]');
+     * console.log(result.result); // 42
+     * ```
+     */
+    async execute(code) {
+        const body = await this.request('/v1/execute', { code });
+        if (body.status === 'error') {
+            throw new SynapseError(400, body.error || 'execution_failed');
+        }
+        return {
+            result: body.result || 0,
+            stdout: body.stdout || '',
+            arenaPos: body.arena_pos || 0,
+            latencyMs: body.latency_ms || 0,
+            executionId: body.execution_id || '',
+            compileTimeMs: body.compile_time_ms || 0,
+            wasmSize: body.wasm_size || 0,
+            deterministicHash: body.deterministic_hash || '',
+            costUsd: body.cost_usd || 0,
+        };
+    }
+    /**
+     * Execute a pre-compiled .wasm binary.
+     */
+    async executeWasm(wasmBytes) {
+        const base64 = Buffer.from(wasmBytes).toString('base64');
+        const body = await this.request('/v1/execute', { wasm: base64 });
+        if (body.status === 'error') {
+            throw new SynapseError(400, body.error || 'execution_failed');
+        }
+        return {
+            result: body.result || 0,
+            stdout: body.stdout || '',
+            arenaPos: body.arena_pos || 0,
+            latencyMs: body.latency_ms || 0,
+            executionId: body.execution_id || '',
+            compileTimeMs: body.compile_time_ms || 0,
+            wasmSize: body.wasm_size || 0,
+            deterministicHash: body.deterministic_hash || '',
+            costUsd: body.cost_usd || 0,
+        };
+    }
+    /**
+     * Execute up to 1000 jobs in a single batch.
+     *
+     * @example
+     * ```typescript
+     * const batch = await client.executeBatch([
+     *   { code: '@f 0 main [ + 1 2 ]' },
+     *   { code: '@f 0 main [ * 3 4 ]' },
+     * ]);
+     * batch.results.forEach(r => console.log(r.result)); // 3, 12
+     * ```
+     */
+    async executeBatch(jobs) {
+        const body = await this.request('/v1/execute/batch', { jobs });
+        if (body.status === 'error') {
+            throw new SynapseError(400, body.error || 'batch_failed');
+        }
+        const results = body.results || [];
+        return {
+            total: body.total || 0,
+            succeeded: body.succeeded || 0,
+            failed: body.failed || 0,
+            batchLatencyMs: body.batch_latency_ms || 0,
+            results: results.map(r => ({
+                result: r.result || 0,
+                stdout: r.stdout || '',
+                latencyMs: r.latency_ms || 0,
+                status: r.status || 'unknown',
+            })),
+        };
+    }
+    /**
+     * Validate .syn syntax without executing.
+     */
+    async validate(code) {
+        return this.request('/v1/validate', { code });
+    }
+    /**
+     * Natural language computation — describe what you want and get results.
+     */
+    async compute(intent) {
+        return this.request('/v1/compute', { intent });
+    }
+    /**
+     * Check gateway health and kernel connectivity.
+     */
+    async health() {
+        const body = await this.request('/');
+        return {
+            status: body.status || 'unknown',
+            version: body.version || '',
+            kernelConnected: body.kernel_connected || false,
+            endpoints: body.endpoints || [],
+        };
+    }
+}
+exports.Synapse = Synapse;
+exports.default = Synapse;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@runsynapse/sdk",
+  "version": "0.1.0",
+  "description": "Synapse SDK — 281x faster code execution for AI agents. Sub-millisecond Wasm execution on bare metal.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "synapse",
+    "wasm",
+    "ai",
+    "agents",
+    "sandbox",
+    "mcp",
+    "execution",
+    "bare-metal"
+  ],
+  "license": "MIT",
+  "author": "Synapse",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/synapse-dev/synapse-sdk"
+  },
+  "homepage": "https://synapserun.dev",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.0.0"
+  }
+}