@auvira.ai/sdk 0.2.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Than
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,414 @@
+# @auvira.ai/sdk
+
+Cursor-SDK-compatible TypeScript agent SDK with custom model support, local repo workspaces, GitLab cloning, visual context (screenshots + selected DOM), and safe post-edit validation.
+
+## Install
+
+### Option A — npm (recommended if you have npm Pro for private)
+
+**Private** (requires [npm Pro](https://www.npmjs.com/products), ~$7/mo):
+
+```bash
+npm publish --access restricted   # from this repo, after npm login
+npm install @auvira.ai/sdk   # in consuming projects (same npm account or granted access)
+```
+
+**Public** (free on npm):
+
+```bash
+npm publish --access public
+npm install @auvira.ai/sdk
+```
+
+### Option B — private GitHub repo (free, no npm publish)
+
+```bash
+npm install github:athan37/auvira-sdk
+```
+
+Requires GitHub auth (`gh auth login` or a PAT). Builds from source on install.
+
+For local development:
+
+```bash
+npm install
+npm run build
+```
+
+## Quick start (local repo)
+
+```ts
+import { Agent } from "@auvira.ai/sdk";
+
+const agent = await Agent.create({
+  apiKey: process.env.AUVIRA_AGENT_API_KEY,
+  model: {
+    id: "openrouter/minimax/minimax-m3",
+    provider: "openhands",
+    baseURL: process.env.CUSTOM_MODEL_BASE_URL,
+    apiKey: process.env.CUSTOM_MODEL_API_KEY,
+  },
+  local: {
+    cwd: "/path/to/repo",
+  },
+});
+
+const result = await agent.send(
+  "Change the hero headline to Fast Emergency AC Repair in Houston",
+  {
+    selectedDom: {
+      tagName: "h1",
+      text: "Reliable HVAC Service When You Need It",
+      componentHint: "Hero",
+      route: "/",
+    },
+    validation: {
+      command: "npm run build",
+    },
+  },
+);
+
+const runResult = await result.wait();
+console.log(runResult.status, runResult.summary, runResult.changedFiles);
+```
+
+## Streaming (Cursor SDK parity)
+
+```ts
+const agent = await Agent.create({ /* ... */ });
+
+const run = await agent.send("Update hero colors to match the reference image", {
+  validation: { skip: true },
+});
+
+for await (const event of run.stream()) {
+  if (event.type === "assistant") {
+    for (const block of event.message.content) {
+      if (block.type === "text") process.stdout.write(block.text);
+    }
+  }
+  if (event.type === "tool.start") {
+    console.log("tool:", event.name);
+  }
+}
+
+const result = await run.wait();
+console.log(result.status, result.id, result.changedFiles);
+
+// Follow-up keeps conversation context on the same agent instance.
+const run2 = await agent.send("Make the accent color warmer");
+await run2.wait();
+
+await agent.close();
+```
+
+`run.text()` blocks on `wait()` and returns the final assistant string. `run.iterText()` yields assistant text from stream events.
+
+## One-shot API
+
+```ts
+import { Agent } from "@auvira.ai/sdk";
+
+const result = await Agent.prompt(
+  "Change the hero headline to Fast Emergency AC Repair in Houston",
+  {
+    apiKey: process.env.AUVIRA_AGENT_API_KEY,
+    model: {
+      id: "openrouter/minimax/minimax-m3",
+      provider: "openhands",
+      baseURL: process.env.CUSTOM_MODEL_BASE_URL,
+      apiKey: process.env.CUSTOM_MODEL_API_KEY,
+    },
+    local: { cwd: "/path/to/repo" },
+    validation: { command: "npm run build" },
+  },
+);
+```
+
+## GitLab source
+
+Environment variables (`.env`):
+
+```bash
+GITLAB_TOKEN=...
+GITLAB_BASE_URL=https://gitlab.com/api/v4
+GITLAB_GROUP_ID=135136695
+```
+
+By project URL:
+
+```ts
+const agent = await Agent.create({
+  model: { id: "mock-model", provider: "openhands" },
+  gitlab: {
+    projectUrl: "https://gitlab.com/auvira-group/generated-site-o4rz7l-rehs.git",
+    token: process.env.GITLAB_TOKEN,
+    branch: "main",
+  },
+});
+```
+
+By GitLab numeric project ID (resolved via `GITLAB_BASE_URL` API; token from env):
+
+```ts
+const agent = await Agent.create({
+  model: { id: "mock-model", provider: "openhands" },
+  gitlab: {
+    projectId: 83611012,
+  },
+});
+```
+
+Auvira MongoDB project ID `6a382fe1e5fa82e481384836` maps to GitLab project `83611012` (`auvira-group/generated-site-o4rz7l-rehs`). Pass the GitLab numeric ID to `gitlab.projectId`.
+
+Skip validation when a repo has known pre-existing build issues:
+
+```ts
+await agent.send("Change the hero headline to ...", {
+  validation: { skip: true },
+});
+```
+
+GitLab mode clones over HTTPS, creates an `auvira/edit-*` branch, and returns a diff only (no push by default).
+
+## Custom model support
+
+Pass model settings inline or via `.env`:
+
+```bash
+CUSTOM_MODEL_BASE_URL=https://api.minimax.io/v1
+CUSTOM_MODEL_API_KEY=...
+CUSTOM_MODEL_ID=MiniMax-M3
+```
+
+```ts
+model: {
+  id: "MiniMax-M3",
+  provider: "openhands",
+  // baseURL and apiKey optional when CUSTOM_MODEL_* env vars are set
+}
+```
+
+| Provider route | `CUSTOM_MODEL_BASE_URL` | Model `id` |
+|----------------|-------------------------|------------|
+| MiniMax direct (global) | `https://api.minimax.io/v1` | `MiniMax-M3` |
+| MiniMax direct (China) | `https://api.minimaxi.com/v1` | `MiniMax-M3` |
+| OpenRouter | `https://openrouter.ai/api/v1` | `minimax/minimax-m3` |
+
+The SDK maps these to OpenHands CLI env vars internally (`LLM_MODEL`, `LLM_BASE_URL`, `LLM_API_KEY`) while also exposing `OPENHANDS_MODEL`, `CUSTOM_MODEL_BASE_URL`, and `CUSTOM_MODEL_API_KEY` to the provider process.
+
+## Mock mode
+
+Deterministic edits without OpenHands CLI:
+
+```bash
+export AUVIRA_AGENT_MOCK=1
+# or
+export OPENHANDS_MOCK_MODE=1
+```
+
+Mock mode supports headline edit prompts like `Change the hero headline to ...` and edits common Hero/page files.
+
+## OpenHands CLI mode
+
+When mock mode is off, the SDK runs OpenHands headless:
+
+```bash
+export OPENHANDS_CLI_COMMAND="openhands"   # optional override
+```
+
+Requires OpenHands CLI installed and available on `PATH`.
+
+## HTTP usage
+
+Optional built-in server:
+
+```bash
+npm run build
+node dist/server/server.js
+```
+
+`POST /agent/prompt` accepts the same JSON shape as `Agent.prompt` and returns `AgentRunResult`.
+
+`GET /health` returns `{ "ok": true }`.
+
+Bind to localhost or protect with a reverse proxy; v1 has no built-in auth.
+
+## Security notes
+
+- Validation commands are allowlisted (`npm/pnpm/yarn build|test` only).
+- Shell chaining, installs, curl pipes, and destructive commands are rejected.
+- GitLab URLs must be `https://gitlab.com/.../*.git` (no SSH, credentials in URL, or shell metacharacters).
+- Tokens and API keys are masked in error output and never logged.
+- Workspaces are copied/cloned to temp dirs; originals are not modified directly.
+
+## Test commands
+
+```bash
+# Unit + real integration (MiniMax M3 + GitLab; requires .env)
+npm run test
+
+# Real integration only
+npm run test:real
+
+npm run typecheck
+npm run build
+```
+
+Real tests require in `.env`:
+
+```bash
+GITLAB_TOKEN=...
+GITLAB_BASE_URL=https://gitlab.com/api/v4
+CUSTOM_MODEL_BASE_URL=https://api.minimax.io/v1
+CUSTOM_MODEL_API_KEY=...
+CUSTOM_MODEL_ID=MiniMax-M3
+```
+
+Mock mode (`AUVIRA_AGENT_MOCK`) is not used in the test suite. Real tests call **MiniMax-M3** via the `custom` provider and clone from **GitLab** when configured.
+
+## Harness integration (cursor-agent-edit-website)
+
+When embedding the SDK as a drop-in Cursor SDK replacement for the website edit harness:
+
+- Pass the full compiled harness prompt unchanged via `agent.send` (system rules + `ALLOWED WRITE PATHS` + owner request).
+- Pass **`selectedDom`** with `sectionIndex`, `sectionType`, `sectionTitle`, and `kind` when the host has structured pin metadata from the preview UI. DOM pin metadata wins over harness-only pin parsing and is required for reliable pinned section edits on single-page sites.
+- Pass **`validation: { skip: true }`** — the harness runs its own build gate via `validateWorkspace`; the SDK default `npm run build` conflicts with harness system rules ("Do not run npm/shell builds").
+
+```ts
+await agent.send(sendPayload, {
+  selectedDom: {
+    sectionIndex: 6,
+    sectionType: "services",
+    sectionTitle: "Our Services",
+    kind: "section",
+    componentHint: "Services · Our Services",
+  },
+  validation: { skip: true },
+});
+```
+
+## Agent modes (v0.2+)
+
+The `custom` provider supports two execution modes:
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **`agentic`** (default for harness prompts) | Harness `send` with compiled Cursor prompt | Multi-turn **grep → read → search_replace/write** tool loop (Cursor Agent parity) |
+| **`json`** (default for simple prompts) | Headline edits, unit tests | One-shot JSON `{ edits: [...] }` with repair loop |
+
+Override with env:
+
+```bash
+AUVIRA_AGENT_MODE=agentic   # force tool loop
+AUVIRA_AGENT_MODE=json      # force JSON edit path
+```
+
+Tool budget (harness mode):
+
+```bash
+AUVIRA_AGENT_MAX_TOOL_CALLS=25          # primary turn (default)
+AUVIRA_AGENT_REPAIR_MAX_TOOL_CALLS=12   # apply/build repair turns (default)
+AUVIRA_AGENT_HISTORY_TOOL_ROUNDS=3      # tool rounds kept in agent loop history
+AUVIRA_CONTEXT_TOKEN_BUDGET=32000       # Priompt-style context cap
+```
+
+MiniMax request tuning (custom provider):
+
+```bash
+CUSTOM_MODEL_THINKING=adaptive|disabled   # override thinking mode (default: adaptive for agentic, disabled for json)
+CUSTOM_MODEL_MAX_COMPLETION_TOKENS=...    # global cap override
+CUSTOM_MODEL_MAX_COMPLETION_TOKENS_AGENTIC=2048
+CUSTOM_MODEL_MAX_COMPLETION_TOKENS_VISION=4096
+CUSTOM_MODEL_MAX_COMPLETION_TOKENS_JSON=8192
+```
+
+All custom-provider chat requests default to `service_tier: "priority"`. Production should leave `CUSTOM_MODEL_API_COOLDOWN_MS` unset (0); tests set a 3s cooldown locally for rate-limit safety.
+
+### Stream events (v0.2.3+)
+
+Live `run.stream()` / `run.messages()` events are enriched for host UIs. **Model-facing tool `output` strings are unchanged** — sanitization applies only to emitted stream payloads.
+
+| Event | Purpose |
+|-------|---------|
+| `tool.start` / `tool.end` | Tool lifecycle; `tool.end.ok` reflects `ToolExecutionResult.ok` |
+| `tool.end.output` | Structured metadata (grep pattern/count, read preview, edit previews, etc.) |
+| `edit.diff` | Per-file unified patch after successful edit (`path`, `patch`, `truncated`, line stats) |
+| `edit.applied` | Edit outcome with optional `linesAdded` / `linesRemoved` / `errorMessage` |
+| `run.diff` | Run-level workspace checkpoint diff after agent run (agent-run changes only) |
+| `completion.evaluated` | Post-checkpoint LLM task completion verdict (`source`: `llm`, `cached`, `skipped`, `error`; includes `isComplete`, `confidence`, `reason`, `missingWork`) |
+| `run.early_finish` | Harness mode: emitted when an allowlisted checkpoint diff passes completion evaluation (`reason`: `diff_detected`, `completion_contract_met`, `completion_satisfied`, or `max_turns`) |
+| `run.continue` | Harness continues when completion is incomplete (`reason`: `style_only_incomplete`, `completion_callback`, `min_turns_pending`) |
+| `run.failed` | Optional `abortReason`, `toolCallCount`, `editsApplied`, `providerCode` (includes `INCOMPLETE_MULTI_STEP` when wiring never arrives) |
+
+Stream caps (env overrides):
+
+```bash
+AUVIRA_EVENT_DIFF_MAX_CHARS=12000   # edit.diff / run.diff patch cap (default 12000)
+AUVIRA_TASK_COMPLETION_TIMEOUT_MS=15000
+AUVIRA_TASK_COMPLETION_CONFIDENCE=0.75
+AUVIRA_COMPLETION_MAX_CONTINUES=2
+AUVIRA_TASK_COMPLETION_MODEL=          # optional override; defaults to agent model — use a fast/cheap model in production
+```
+
+**Completion evaluator performance (v0.2.9+):**
+
+- **Per-turn evaluation:** The LLM completion evaluator runs once at the end of each model tool batch (not after every mutating tool). Evaluation still runs if a later tool in the batch fails or aborts, as long as at least one mutating tool applied.
+- **Verdict cache:** Repeated identical evaluator inputs within a run reuse the last verdict (`completion.evaluated` with `source: "cached"`).
+- **Smaller diffs:** Checkpoint diffs use line-based hunks (not full-file replace) and are memoized until the next mutating tool or `restore()`.
+- **Vision gating:** Reference images are sent to the evaluator on the first check and on style-only diffs; subsequent wiring checks are text-only.
+- **Non-harness globs:** `includeGlobs` / `excludeGlobs` on workspace checkpoints filter full-repo snapshots.
+
+For production harness runs, set `AUVIRA_TASK_COMPLETION_MODEL` to a smaller/faster model than the main agent model to reduce evaluator latency and cost.
+
+**Workspace checkpoints (v0.2.8+):** Before the agent edits, the SDK snapshots allowed files into an in-memory checkpoint. No `git add`, `git commit`, or index mutation occurs. `changedFiles`, `run.diff`, `completion.evaluated`, and harness early finish all use **checkpoint diff** (agent-run changes only — not pre-existing dirty git state).
+
+**Post-checkpoint completion evaluation (v0.2.8+):** After a model turn produces an allowlisted checkpoint diff, the SDK calls a generic LLM evaluator with the owner request, selected DOM, reference images (when gated), diff patch, and recent tool results. If `isComplete` with confidence ≥ threshold → `run.early_finish` with `reason: "completion_satisfied"`. If incomplete → targeted user nudge and the loop continues. Opt out with `completion.auto: false` to use deterministic fallback only.
+
+```ts
+await agent.send(payload, {
+  selectedDom,
+  completion: {
+    auto: true, // default in harness mode
+    confidenceThreshold: 0.8, // optional override
+    // Explicit deterministic contract still supported (v0.2.7):
+    requireWiringAfterStyle: true,
+    isComplete: ({ changedFiles }) => /* in-process only */,
+  },
+});
+```
+
+**Harness early finish (v0.2.5+):** When `harnessPrompt` is active and a model turn produces an allowlisted checkpoint diff, the loop evaluates completion before stopping.
+
+Stream events emit Cursor-compatible tool names: `grep`, `read`, `glob`, `list_dir`, `search_replace`, `write`.
+
+## Current limitations
+
+- No HTTP SSE streaming (`POST /agent/run`); in-process `run.stream()` only.
+- No `Agent.resume` / cloud VM runtime (local cwd or GitLab clone only).
+- No MCP server configuration.
+- No cloud push or PR creation.
+- OpenHands CLI required when using the `openhands` provider in production.
+- GitLab sanitizer supports `gitlab.com` HTTPS URLs only in v1.
+- Validation is limited to build/test allowlist commands.
+- Local workspace copy excludes `node_modules`; SDK auto-runs `npm install` internally before build validation when needed.
+
+## Cursor SDK compatibility matrix
+
+| Cursor SDK | Auvira SDK |
+|------------|------------|
+| `Agent.create` | Yes (+ `close()` / `await using`) |
+| `Agent.prompt` | Yes |
+| `agent.send` → `AgentRun` | Yes |
+| `run.stream()` / `messages()` | Yes |
+| `run.wait()` | Yes (`status`, `id`) |
+| `run.text()` / `iterText()` | Yes |
+| `run.cancel()` | Yes |
+| `run.conversation()` | Yes (after first completed run) |
+| Native grep/read/edit tools | Yes (`agentic` mode) |
+| `Agent.resume` | No |
+| Cloud / MCP | No |
+
+## License
+
+MIT

package/dist/agent/Agent.d.ts

@@ -0,0 +1,27 @@
+import { AgentRun } from "./AgentRun.js";
+import { type AgentSendPayload } from "./parseSendPayload.js";
+import type { AgentCreateOptions, AgentPromptOptions, AgentRunResult, AgentSendOptions } from "./types.js";
+export { AgentNotFoundError } from "./AgentRegistry.js";
+/** Cursor-SDK-compatible Auvira agent. */
+export declare class Agent {
+    private readonly createOptions;
+    readonly agentId: string;
+    private readonly conversation;
+    private lastWorkspace;
+    private lastVisionImages?;
+    private readonly activeRuns;
+    private closed;
+    private constructor();
+    /** Creates a reusable agent instance without running a task. */
+    static create(options: AgentCreateOptions): Promise<Agent>;
+    /** Resumes an in-process agent by id (Cursor SDK parity). */
+    static resume(agentId: string, options: AgentCreateOptions): Promise<Agent>;
+    /** One-shot prompt that creates an agent and runs a single task. */
+    static prompt(payload: AgentSendPayload, options: AgentPromptOptions): Promise<AgentRunResult>;
+    /** Sends a prompt and returns a Cursor-SDK-compatible run handle. */
+    send(payload: AgentSendPayload, options?: AgentSendOptions): Promise<AgentRun>;
+    /** Releases resources and cancels in-flight runs. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+//# sourceMappingURL=Agent.d.ts.map

package/dist/agent/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/agent/Agent.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AASzC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,kBAAkB,EAElB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAUpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAyBxD,0CAA0C;AAC1C,qBAAa,KAAK;IAQd,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM;IAR1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2B;IACxD,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,gBAAgB,CAAC,CAAoB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO;IAKP,gEAAgE;WACnD,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,KAAK,CAAC;IAQhE,6DAA6D;WAChD,MAAM,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,KAAK,CAAC;IAKjB,oEAAoE;WACvD,MAAM,CACjB,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC;IAW1B,qEAAqE;IAC/D,IAAI,CACR,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,QAAQ,CAAC;IAgFpB,qDAAqD;IAC/C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBtB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7C"}

package/dist/agent/Agent.js

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { AgentRun } from "./AgentRun.js";
+import { ConversationStore } from "./ConversationStore.js";
+import { getRegisteredAgent, registerAgent, unregisterAgent, } from "./AgentRegistry.js";
+import { RunEventBus } from "./RunEventBus.js";
+import { runAgentTask } from "./runAgentTask.js";
+import { parseSendPayload, } from "./parseSendPayload.js";
+import { AgentConfigError } from "./types.js";
+import { resolveCreateOptions, splitPromptOptions, validateSendOptions, } from "./validateOptions.js";
+import { cleanupWorkspace } from "../workspace/cleanupWorkspace.js";
+import { resolveWorkspaceMode } from "../workspace/resolveWorkspaceMode.js";
+export { AgentNotFoundError } from "./AgentRegistry.js";
+function mergeAbortSignals(...signals) {
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (!signal) {
+            continue;
+        }
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            return controller.signal;
+        }
+        signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+    }
+    return controller.signal;
+}
+/** Cursor-SDK-compatible Auvira agent. */
+export class Agent {
+    createOptions;
+    agentId;
+    conversation = new ConversationStore();
+    lastWorkspace;
+    lastVisionImages;
+    activeRuns = new Set();
+    closed = false;
+    constructor(createOptions, agentId) {
+        this.createOptions = createOptions;
+        this.agentId = agentId;
+    }
+    /** Creates a reusable agent instance without running a task. */
+    static async create(options) {
+        const resolved = await resolveCreateOptions(options);
+        const agentId = randomUUID();
+        const agent = new Agent(resolved, agentId);
+        registerAgent(agent, agentId);
+        return agent;
+    }
+    /** Resumes an in-process agent by id (Cursor SDK parity). */
+    static async resume(agentId, options) {
+        await resolveCreateOptions(options);
+        return getRegisteredAgent(agentId);
+    }
+    /** One-shot prompt that creates an agent and runs a single task. */
+    static async prompt(payload, options) {
+        const { createOptions, sendOptions } = splitPromptOptions(options);
+        const agent = await Agent.create(createOptions);
+        try {
+            const run = await agent.send(payload, sendOptions);
+            return await run.wait();
+        }
+        finally {
+            await agent.close();
+        }
+    }
+    /** Sends a prompt and returns a Cursor-SDK-compatible run handle. */
+    async send(payload, options) {
+        if (this.closed) {
+            throw new AgentConfigError("Agent has been closed", "INVALID_CONFIG");
+        }
+        validateSendOptions(options);
+        const parsed = parseSendPayload(payload, options ?? {});
+        const images = parsed.images.length > 0
+            ? parsed.images
+            : this.lastVisionImages ?? [];
+        if (parsed.images.length > 0) {
+            this.lastVisionImages = parsed.images;
+        }
+        const mergedSendOptions = {
+            ...options,
+            screenshotBase64: parsed.screenshotBase64,
+        };
+        const secrets = [
+            this.createOptions.gitlab?.token,
+            this.createOptions.model.apiKey,
+        ];
+        const bus = new RunEventBus(undefined, secrets);
+        const abortController = new AbortController();
+        const signal = mergeAbortSignals(options?.signal, abortController.signal);
+        const reuseWorkspace = options?.reuseWorkspace === true ||
+            (options?.reuseWorkspace !== false && this.conversation.hasHistory());
+        const context = {
+            signal,
+            agentId: this.agentId,
+            images,
+            conversationHistory: this.conversation.getTurns(),
+            reuseWorkspace: reuseWorkspace ? this.lastWorkspace : undefined,
+            onWorkspacePrepared: (workspace) => {
+                this.lastWorkspace = workspace;
+            },
+            onRunComplete: (result, userPrompt) => {
+                if (result.status === "finished" && result.ok) {
+                    this.conversation.appendExchange({
+                        runId: result.id,
+                        userPrompt,
+                        assistantResponse: result.response,
+                    });
+                    bus.emit({
+                        type: "conversation.updated",
+                        turnCount: this.conversation.getTurns().length,
+                    });
+                }
+            },
+        };
+        const resultPromise = runAgentTask(this.createOptions, parsed.prompt, mergedSendOptions, bus, context);
+        const run = new AgentRun(bus, resultPromise, abortController, () => this.conversation.getTurns());
+        this.activeRuns.add(run);
+        void resultPromise.finally(() => {
+            this.activeRuns.delete(run);
+        });
+        return run;
+    }
+    /** Releases resources and cancels in-flight runs. */
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        await Promise.all([...this.activeRuns].map((run) => run.cancel().catch(() => undefined)));
+        this.activeRuns.clear();
+        if (this.lastWorkspace &&
+            resolveWorkspaceMode(this.createOptions) === "git_copy" &&
+            this.createOptions.cleanupWorkspace === false) {
+            await cleanupWorkspace(this.lastWorkspace.path).catch(() => undefined);
+        }
+        this.conversation.clear();
+        this.lastWorkspace = undefined;
+        this.lastVisionImages = undefined;
+        unregisterAgent(this.agentId);
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+}
+//# sourceMappingURL=Agent.js.map

package/dist/agent/Agent.js.map

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

package/dist/agent/AgentRegistry.d.ts

@@ -0,0 +1,13 @@
+import type { Agent } from "./Agent.js";
+import { AgentConfigError } from "./types.js";
+/** Registers an agent instance for Cursor-style resume. */
+export declare function registerAgent(agent: Agent, agentId?: `${string}-${string}-${string}-${string}-${string}`): string;
+/** Returns a previously registered agent or throws. */
+export declare function getRegisteredAgent(agentId: string): Agent;
+/** Removes an agent from the resume registry. */
+export declare function unregisterAgent(agentId: string): void;
+/** Cursor SDK parity — thrown when Agent.resume cannot find an agent id. */
+export declare class AgentNotFoundError extends AgentConfigError {
+    constructor(message: string);
+}
+//# sourceMappingURL=AgentRegistry.d.ts.map

package/dist/agent/AgentRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRegistry.d.ts","sourceRoot":"","sources":["../../src/agent/AgentRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAI9C,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,sDAAe,GAAG,MAAM,CAG1E;AAED,uDAAuD;AACvD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAMzD;AAED,iDAAiD;AACjD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAErD;AAED,4EAA4E;AAC5E,qBAAa,kBAAmB,SAAQ,gBAAgB;gBAC1C,OAAO,EAAE,MAAM;CAI5B"}

package/dist/agent/AgentRegistry.js

@@ -0,0 +1,28 @@
+import { randomUUID } from "node:crypto";
+import { AgentConfigError } from "./types.js";
+const agents = new Map();
+/** Registers an agent instance for Cursor-style resume. */
+export function registerAgent(agent, agentId = randomUUID()) {
+    agents.set(agentId, agent);
+    return agentId;
+}
+/** Returns a previously registered agent or throws. */
+export function getRegisteredAgent(agentId) {
+    const agent = agents.get(agentId.trim());
+    if (!agent) {
+        throw new AgentNotFoundError(`Agent not found: ${agentId}`);
+    }
+    return agent;
+}
+/** Removes an agent from the resume registry. */
+export function unregisterAgent(agentId) {
+    agents.delete(agentId);
+}
+/** Cursor SDK parity — thrown when Agent.resume cannot find an agent id. */
+export class AgentNotFoundError extends AgentConfigError {
+    constructor(message) {
+        super(message, "agent_not_found");
+        this.name = "AgentNotFoundError";
+    }
+}
+//# sourceMappingURL=AgentRegistry.js.map

package/dist/agent/AgentRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRegistry.js","sourceRoot":"","sources":["../../src/agent/AgentRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;AAExC,2DAA2D;AAC3D,MAAM,UAAU,aAAa,CAAC,KAAY,EAAE,OAAO,GAAG,UAAU,EAAE;IAChE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,kBAAkB,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED,4EAA4E;AAC5E,MAAM,OAAO,kBAAmB,SAAQ,gBAAgB;IACtD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}