@auvira.ai/sdk 0.2.9 → 0.3.0

package/dist/runner/validateJob.js

@@ -0,0 +1,158 @@
+export class SandboxJobValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SandboxJobValidationError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value, field) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new SandboxJobValidationError(`${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function validateModel(raw) {
+    if (!isRecord(raw)) {
+        throw new SandboxJobValidationError("model must be an object");
+    }
+    if ("apiKey" in raw && raw.apiKey !== undefined && raw.apiKey !== null) {
+        throw new SandboxJobValidationError("model.apiKey is not allowed in job.json — use environment variables");
+    }
+    const id = readString(raw.id, "model.id");
+    const model = { id };
+    if (raw.provider !== undefined) {
+        if (raw.provider !== "openhands" && raw.provider !== "custom") {
+            throw new SandboxJobValidationError('model.provider must be "openhands" or "custom"');
+        }
+        model.provider = raw.provider;
+    }
+    if (raw.baseURL !== undefined) {
+        model.baseURL = readString(raw.baseURL, "model.baseURL");
+    }
+    return model;
+}
+function validateImages(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(raw)) {
+        throw new SandboxJobValidationError("images must be an array");
+    }
+    return raw.map((item, index) => {
+        if (!isRecord(item)) {
+            throw new SandboxJobValidationError(`images[${index}] must be an object`);
+        }
+        return {
+            data: readString(item.data, `images[${index}].data`),
+            mimeType: readString(item.mimeType, `images[${index}].mimeType`),
+        };
+    });
+}
+function validateCompletion(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (!isRecord(raw)) {
+        throw new SandboxJobValidationError("completion must be an object");
+    }
+    if ("isComplete" in raw) {
+        throw new SandboxJobValidationError("completion.isComplete is not serializable — omit from job.json");
+    }
+    const completion = {};
+    if (raw.mode !== undefined) {
+        if (raw.mode !== "default" && raw.mode !== "multi_file_required") {
+            throw new SandboxJobValidationError('completion.mode must be "default" or "multi_file_required"');
+        }
+        completion.mode = raw.mode;
+    }
+    if (raw.requireWiringAfterStyle !== undefined) {
+        completion.requireWiringAfterStyle = Boolean(raw.requireWiringAfterStyle);
+    }
+    if (raw.auto !== undefined) {
+        completion.auto = Boolean(raw.auto);
+    }
+    if (raw.confidenceThreshold !== undefined) {
+        const threshold = Number(raw.confidenceThreshold);
+        if (!Number.isFinite(threshold)) {
+            throw new SandboxJobValidationError("completion.confidenceThreshold must be a number");
+        }
+        completion.confidenceThreshold = threshold;
+    }
+    if (raw.styleAssetPatterns !== undefined) {
+        if (!Array.isArray(raw.styleAssetPatterns)) {
+            throw new SandboxJobValidationError("completion.styleAssetPatterns must be an array");
+        }
+        completion.styleAssetPatterns = raw.styleAssetPatterns.map((p) => readString(p, "styleAssetPatterns[]"));
+    }
+    if (raw.wiringPatterns !== undefined) {
+        if (!Array.isArray(raw.wiringPatterns)) {
+            throw new SandboxJobValidationError("completion.wiringPatterns must be an array");
+        }
+        completion.wiringPatterns = raw.wiringPatterns.map((p) => readString(p, "wiringPatterns[]"));
+    }
+    if (raw.multiStep !== undefined) {
+        if (!isRecord(raw.multiStep)) {
+            throw new SandboxJobValidationError("completion.multiStep must be an object");
+        }
+        completion.multiStep = {};
+        for (const key of ["minToolCalls", "minModelTurns", "maxExtraTurnsAfterStyleOnly"]) {
+            if (raw.multiStep[key] !== undefined) {
+                const value = Number(raw.multiStep[key]);
+                if (!Number.isFinite(value)) {
+                    throw new SandboxJobValidationError(`completion.multiStep.${key} must be a number`);
+                }
+                completion.multiStep[key] = value;
+            }
+        }
+    }
+    return completion;
+}
+/** Validates and parses raw job JSON into SandboxAuviraJobInput v1. */
+export function validateSandboxJob(raw) {
+    if (!isRecord(raw)) {
+        throw new SandboxJobValidationError("job.json must be a JSON object");
+    }
+    if (raw.version !== 1) {
+        throw new SandboxJobValidationError("job.version must be 1");
+    }
+    if ("apiKey" in raw && raw.apiKey !== undefined) {
+        throw new SandboxJobValidationError("apiKey is not allowed in job.json");
+    }
+    const editJobId = readString(raw.editJobId, "editJobId");
+    const workspacePath = raw.workspacePath === undefined
+        ? "/vercel/sandbox"
+        : readString(raw.workspacePath, "workspacePath");
+    const promptText = readString(raw.promptText, "promptText");
+    const model = validateModel(raw.model);
+    const job = {
+        version: 1,
+        editJobId,
+        workspacePath,
+        promptText,
+        model,
+        images: validateImages(raw.images),
+        resumeAgentId: raw.resumeAgentId === undefined
+            ? undefined
+            : readString(raw.resumeAgentId, "resumeAgentId"),
+        selectedDom: isRecord(raw.selectedDom)
+            ? raw.selectedDom
+            : undefined,
+        completion: validateCompletion(raw.completion),
+        validation: isRecord(raw.validation)
+            ? {
+                skip: raw.validation.skip === undefined ? undefined : Boolean(raw.validation.skip),
+                command: raw.validation.command === undefined
+                    ? undefined
+                    : readString(raw.validation.command, "validation.command"),
+                timeoutMs: raw.validation.timeoutMs === undefined
+                    ? undefined
+                    : Number(raw.validation.timeoutMs),
+            }
+            : undefined,
+        reuseWorkspace: raw.reuseWorkspace === undefined ? undefined : Boolean(raw.reuseWorkspace),
+    };
+    return job;
+}
+//# sourceMappingURL=validateJob.js.map

package/dist/runner/validateJob.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateJob.js","sourceRoot":"","sources":["../../src/runner/validateJob.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,KAAa;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,yBAAyB,CAAC,GAAG,KAAK,6BAA6B,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,aAAa,CAAC,GAAY;IACjC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,CAAC,yBAAyB,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,QAAQ,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QACvE,MAAM,IAAI,yBAAyB,CACjC,qEAAqE,CACtE,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAC1C,MAAM,KAAK,GAAqB,EAAE,EAAE,EAAE,CAAC;IACvC,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,QAAQ,KAAK,WAAW,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,IAAI,yBAAyB,CAAC,gDAAgD,CAAC,CAAC;QACxF,CAAC;QACD,KAAK,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IAChC,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC9B,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAClC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,yBAAyB,CAAC,yBAAyB,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,yBAAyB,CAAC,UAAU,KAAK,qBAAqB,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO;YACL,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,KAAK,QAAQ,CAAC;YACpD,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,KAAK,YAAY,CAAC;SACjE,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CAAC,GAAY;IACtC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,CAAC,8BAA8B,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,YAAY,IAAI,GAAG,EAAE,CAAC;QACxB,MAAM,IAAI,yBAAyB,CACjC,gEAAgE,CACjE,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAqD,EAAE,CAAC;IACxE,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;YACjE,MAAM,IAAI,yBAAyB,CAAC,4DAA4D,CAAC,CAAC;QACpG,CAAC;QACD,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IAC7B,CAAC;IACD,IAAI,GAAG,CAAC,uBAAuB,KAAK,SAAS,EAAE,CAAC;QAC9C,UAAU,CAAC,uBAAuB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3B,UAAU,CAAC,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,yBAAyB,CAAC,iDAAiD,CAAC,CAAC;QACzF,CAAC;QACD,UAAU,CAAC,mBAAmB,GAAG,SAAS,CAAC;IAC7C,CAAC;IACD,IAAI,GAAG,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,yBAAyB,CAAC,gDAAgD,CAAC,CAAC;QACxF,CAAC;QACD,UAAU,CAAC,kBAAkB,GAAG,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,GAAG,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,yBAAyB,CAAC,4CAA4C,CAAC,CAAC;QACpF,CAAC;QACD,UAAU,CAAC,cAAc,GAAG,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,yBAAyB,CAAC,wCAAwC,CAAC,CAAC;QAChF,CAAC;QACD,UAAU,CAAC,SAAS,GAAG,EAAE,CAAC;QAC1B,KAAK,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,eAAe,EAAE,6BAA6B,CAAU,EAAE,CAAC;YAC5F,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;gBACrC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;gBACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC5B,MAAM,IAAI,yBAAyB,CAAC,wBAAwB,GAAG,mBAAmB,CAAC,CAAC;gBACtF,CAAC;gBACD,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACpC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,CAAC,gCAAgC,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,yBAAyB,CAAC,uBAAuB,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,QAAQ,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChD,MAAM,IAAI,yBAAyB,CAAC,mCAAmC,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACzD,MAAM,aAAa,GACjB,GAAG,CAAC,aAAa,KAAK,SAAS;QAC7B,CAAC,CAAC,iBAAiB;QACnB,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,UAAU,CAAC,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAEvC,MAAM,GAAG,GAA0B;QACjC,OAAO,EAAE,CAAC;QACV,SAAS;QACT,aAAa;QACb,UAAU;QACV,KAAK;QACL,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;QAClC,aAAa,EACX,GAAG,CAAC,aAAa,KAAK,SAAS;YAC7B,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,aAAa,EAAE,eAAe,CAAC;QACpD,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC,WAAW,CAAC;YACpC,CAAC,CAAE,GAAG,CAAC,WAAoD;YAC3D,CAAC,CAAC,SAAS;QACb,UAAU,EAAE,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC;QAC9C,UAAU,EAAE,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;YAClC,CAAC,CAAC;gBACE,IAAI,EAAE,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;gBAClF,OAAO,EACL,GAAG,CAAC,UAAU,CAAC,OAAO,KAAK,SAAS;oBAClC,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,oBAAoB,CAAC;gBAC9D,SAAS,EACP,GAAG,CAAC,UAAU,CAAC,SAAS,KAAK,SAAS;oBACpC,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC;aACvC;YACH,CAAC,CAAC,SAAS;QACb,cAAc,EACZ,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;KAC7E,CAAC;IAEF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/docs/sandbox-runner.md

@@ -0,0 +1,199 @@
+# Vercel Sandbox Runner
+
+Run Auvira agent edits inside a Vercel Sandbox VM while the host Next.js API stays in serverless Lambda. This mirrors the Cursor in-VM runner pattern: the host writes a job file, spawns the runner inside the sandbox, and polls NDJSON progress.
+
+## Architecture
+
+```mermaid
+sequenceDiagram
+  participant Host as Host_Lambda
+  participant VM as Sandbox_VM
+  participant Runner as auvira_sdk_run
+  participant Agent as Agent_in_place
+
+  Host->>VM: write job.json
+  Host->>VM: spawn auvira-sdk-run --job editJobId
+  Runner->>Agent: Agent.create cwd=/vercel/sandbox
+  Runner->>Agent: agent.send(job fields)
+  loop stream
+    Agent-->>Runner: AgentRunEvent
+    Runner-->>VM: append events.ndjson
+  end
+  Runner->>VM: result.json
+  Host->>VM: poll events.ndjson
+```
+
+The SDK package does **not** call the Vercel Sandbox SDK. The host app (~150 lines) writes jobs and spawns the runner command.
+
+## Directory layout
+
+Default jobs root: `/vercel/.auvira/auvira-jobs` (override with `AUVIRA_JOBS_ROOT`).
+
+```
+{AUVIRA_JOBS_ROOT}/
+  {editJobId}/
+    job.json          # input (no secrets)
+    events.ndjson     # append-only progress + final result line
+    result.json       # terminal outcome
+    abort.json        # host writes to cancel (optional)
+  sessions/
+    {agentId}.json    # conversation + vision state for resume
+```
+
+## Install and run
+
+```bash
+npm install @auvira.ai/sdk
+```
+
+Inside the sandbox VM:
+
+```bash
+CUSTOM_MODEL_API_KEY=... \
+CUSTOM_MODEL_JSON_MODE=1 \
+node node_modules/@auvira.ai/sdk/dist/runner/run.js --job <editJobId>
+```
+
+Or use the bin:
+
+```bash
+auvira-sdk-run --job <editJobId>
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CUSTOM_MODEL_API_KEY` | Yes | Model API key (MiniMax, OpenRouter, etc.) |
+| `CUSTOM_MODEL_BASE_URL` | No | Model base URL override |
+| `CUSTOM_MODEL_ID` | No | Model id override (default `MiniMax-M3`) |
+| `CUSTOM_MODEL_JSON_MODE` | Recommended | Set to `1` for JSON-mode harness |
+| `AUVIRA_JOBS_ROOT` | No | Jobs directory (default `/vercel/.auvira/auvira-jobs`) |
+| `AUVIRA_CURSOR_JOB_ID` | No | Job id if `--job` not passed |
+
+`CUSTOM_MODEL_API_KEY` is read from the environment only — never from `job.json`.
+
+## Job input (`SandboxAuviraJobInput` v1)
+
+```json
+{
+  "version": 1,
+  "editJobId": "abc123",
+  "workspacePath": "/vercel/sandbox",
+  "promptText": "CURSOR SYSTEM RULES\n\n---\n\nOWNER REQUEST:\nUpdate hero headline",
+  "images": [
+    { "data": "<base64>", "mimeType": "image/png" }
+  ],
+  "selectedDom": {
+    "sectionIndex": 6,
+    "sectionTitle": "Our Services",
+    "kind": "section"
+  },
+  "completion": {
+    "mode": "multi_file_required",
+    "requireWiringAfterStyle": true,
+    "auto": false
+  },
+  "validation": { "skip": true },
+  "reuseWorkspace": false,
+  "resumeAgentId": "optional-agent-uuid",
+  "model": {
+    "id": "openrouter/minimax/minimax-m3",
+    "provider": "custom",
+    "baseURL": "https://api.minimax.io/v1"
+  }
+}
+```
+
+- `promptText` must use harness format (`\n\n---\n\n` delimiter) for website edits.
+- `images` are base64 only — no host filesystem paths.
+- `completion.isComplete` is not allowed (not JSON-serializable).
+- `model.apiKey` is rejected by the validator.
+
+## Result (`SandboxAuviraJobResult`)
+
+Written to `result.json` and appended as the final `events.ndjson` line:
+
+```json
+{
+  "ok": true,
+  "agentId": "uuid",
+  "sessionResumed": false,
+  "runId": "run-uuid",
+  "summary": "Applied 2 edit(s)",
+  "tokenUsage": { "inputTokens": 100, "outputTokens": 50 },
+  "nativeToolCallCount": 8,
+  "cursorReportedSuccess": true
+}
+```
+
+`changedFiles` are computed by the host (workspace hash before/after), not returned by the runner.
+
+## NDJSON protocol
+
+Each line in `events.ndjson`:
+
+```json
+{"type":"progress","event":{"type":"step","id":"cursor_session","label":"Auvira agent ready","status":"completed"}}
+{"type":"progress","event":{"type":"activity_trace","entry":{"kind":"tool_start","toolName":"read"}}}
+{"type":"result","result":{"ok":true,"cursorReportedSuccess":true}}
+```
+
+Parse lines in the host with:
+
+```ts
+import { parseSandboxAuviraRunnerLine } from "@auvira.ai/sdk";
+
+const event = parseSandboxAuviraRunnerLine(line);
+```
+
+## Host spawn (pseudocode)
+
+```ts
+import { join } from "node:path";
+
+const jobsRoot = "/vercel/.auvira/auvira-jobs";
+const editJobId = "edit-abc";
+const jobDir = join(jobsRoot, editJobId);
+
+await sandbox.fs.writeFile(join(jobDir, "job.json"), JSON.stringify(job));
+
+await sandbox.runCommand({
+  cmd: "sh",
+  args: [
+    "-c",
+    `CUSTOM_MODEL_API_KEY='$KEY' CUSTOM_MODEL_JSON_MODE=1 node '${runnerPath}/run.js' --job '${editJobId}'`,
+  ],
+  cwd: "/vercel/.auvira/auvira-runner",
+});
+
+// Poll join(jobDir, "events.ndjson") for new lines; read result.json when done.
+```
+
+## Session resume
+
+When `resumeAgentId` is set, the runner loads `{jobsRoot}/sessions/{agentId}.json` and restores conversation + vision images across VM spawns. After a successful run, the runner updates the session file.
+
+## Security
+
+- Never put API keys, tokens, or secrets in `job.json`.
+- Reference images must be base64 in the job payload.
+- Stream output is secret-masked via the SDK event bus.
+
+## Package exports
+
+```ts
+import { parseSandboxAuviraRunnerLine, mapAuviraStreamEventToProgress } from "@auvira.ai/sdk";
+import type { SandboxAuviraJobInput, SandboxAuviraJobResult } from "@auvira.ai/sdk";
+```
+
+Subpath: `@auvira.ai/sdk/runner` (types + CLI module).
+
+## Changelog
+
+### 0.3.0
+
+- Added Vercel Sandbox runner CLI (`auvira-sdk-run`)
+- Added `@auvira.ai/sdk/runner` export
+- Added session-file resume (`agentId`, `initialConversation` on `Agent.create`)
+- Added NDJSON progress protocol for host polling

package/package.json

@@ -1,20 +1,28 @@
 {
   "name": "@auvira.ai/sdk",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "Cursor-SDK-compatible visual coding agent with custom model support",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "auvira-sdk-run": "./dist/runner/run.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./runner": {
+      "types": "./dist/runner/index.d.ts",
+      "import": "./dist/runner/run.js"
     }
   },
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs"
   ],
   "repository": {
     "type": "git",
@@ -33,7 +41,10 @@
     "test:unit": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__ --exclude 'src/__tests__/real/**' --exclude 'src/__tests__/flex/real-*.e2e.test.ts'",
     "test:flex": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/flex",
     "test:flex:unit": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/flex --exclude 'src/__tests__/flex/real-*.e2e.test.ts'",
-    "test:real": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/real src/__tests__/flex/real-*.e2e.test.ts"
+    "test:real": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/real src/__tests__/flex/real-*.e2e.test.ts src/__tests__/runner/run-cli.real.e2e.test.ts",
+    "test:runner": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/runner --exclude 'src/__tests__/runner/**/*.real.e2e.test.ts'",
+    "test:runner:real": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/runner/run-cli.real.e2e.test.ts src/__tests__/runner/run-cli-vibe-consumer.real.e2e.test.ts",
+    "test:runner:vibe": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/runner/run-cli-vibe-consumer.real.e2e.test.ts"
   },
   "keywords": [
     "agent",