@auvira.ai/sdk 0.6.1 → 0.6.3

package/dist/util/minimaxImageClient.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { sniffImageMime } from "../agent/tools/assetPathValidation.js";
 import { postJsonWithRetry } from "./modelApiClient.js";
+import { getGlobalModelCallQueue } from "./modelCallQueue.js";
 const GLOBAL_IMAGE_BASE = "https://api.minimax.io/v1";
 const CN_IMAGE_BASE = "https://api.minimaxi.com/v1";
 /** Returns true when image generation is enabled (`AUVIRA_IMAGE_GEN_ENABLED=true`). */
@@ -73,7 +74,7 @@ async function callImageGeneration(input) {
     if (input.subjectReference?.length) {
         body.subject_reference = input.subjectReference;
     }
-    const result = await postJsonWithRetry({
+    const result = await getGlobalModelCallQueue().run("image_generation", () => postJsonWithRetry({
         url: `${baseUrl}/image_generation`,
         headers: {
             Authorization: `Bearer ${input.apiKey}`,
@@ -82,7 +83,7 @@ async function callImageGeneration(input) {
         body,
         timeoutMs: input.timeoutMs ?? 120_000,
         signal: input.signal,
-    }, 0);
+    }, 0));
     if (!result.ok || !result.data) {
         const rateLimit = result.rateLimit;
         throw new Error(rateLimit?.message ?? result.errorMessage ?? "Image generation request failed");

package/dist/util/minimaxImageClient.js.map

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

package/dist/util/modelCallQueue.d.ts

@@ -0,0 +1,38 @@
+export interface ModelCallQueueOptions {
+    maxConcurrent?: number;
+    cooldownMs?: number;
+}
+/** Reads max concurrent API slots from env (primary + legacy aliases). Default 3. */
+export declare function getApiMaxConcurrent(): number;
+/** Reads API cooldown ms from env (primary + legacy aliases). Default 0. */
+export declare function getApiCooldownMs(): number;
+/** Global queue for all external model-like API calls (chat, evaluator, image, judges). */
+export declare class ModelCallQueue {
+    private activeCalls;
+    private readonly waitQueue;
+    private readonly maxConcurrent;
+    private readonly cooldownMs;
+    constructor(options?: ModelCallQueueOptions);
+    /** Acquires a queue slot and returns fn result. Use when queue wait time is not needed. */
+    run<T>(label: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Acquires a slot, measures wait time, invokes fn(queueWaitMs), returns result + wait.
+     * queueWaitMs is measured after slot acquire and before fn runs.
+     */
+    runWithMetrics<T>(label: string, fn: (queueWaitMs: number) => Promise<T>): Promise<{
+        value: T;
+        queueWaitMs: number;
+    }>;
+    /** Returns current queue settings for diagnostics. */
+    getConfig(): {
+        maxConcurrent: number;
+        cooldownMs: number;
+        activeCalls: number;
+        queuedCalls: number;
+    };
+}
+/** Shared queue for all external model-like API calls in this process. */
+export declare function getGlobalModelCallQueue(): ModelCallQueue;
+/** Resets the global queue (tests only). */
+export declare function resetGlobalModelCallQueue(): void;
+//# sourceMappingURL=modelCallQueue.d.ts.map

package/dist/util/modelCallQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelCallQueue.d.ts","sourceRoot":"","sources":["../../src/util/modelCallQueue.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,qFAAqF;AACrF,wBAAgB,mBAAmB,IAAI,MAAM,CAQ5C;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,IAAI,MAAM,CAQzC;AAED,2FAA2F;AAC3F,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,GAAE,qBAA0B;IAK/C,2FAA2F;IACrF,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAK7D;;;OAGG;IACG,cAAc,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IA+B7C,sDAAsD;IACtD,SAAS,IAAI;QACX,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB;CAQF;AAID,0EAA0E;AAC1E,wBAAgB,uBAAuB,IAAI,cAAc,CAKxD;AAED,4CAA4C;AAC5C,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/util/modelCallQueue.js

@@ -0,0 +1,88 @@
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Reads max concurrent API slots from env (primary + legacy aliases). Default 3. */
+export function getApiMaxConcurrent() {
+    const raw = process.env.AUVIRA_API_MAX_CONCURRENT?.trim() ??
+        process.env.AUVIRA_MODEL_MAX_CONCURRENT?.trim() ??
+        process.env.CUSTOM_MODEL_MAX_CONCURRENT?.trim() ??
+        "3";
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 3;
+}
+/** Reads API cooldown ms from env (primary + legacy aliases). Default 0. */
+export function getApiCooldownMs() {
+    const raw = process.env.AUVIRA_API_COOLDOWN_MS?.trim() ??
+        process.env.AUVIRA_MODEL_API_COOLDOWN_MS?.trim() ??
+        process.env.CUSTOM_MODEL_API_COOLDOWN_MS?.trim() ??
+        "0";
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+/** Global queue for all external model-like API calls (chat, evaluator, image, judges). */
+export class ModelCallQueue {
+    activeCalls = 0;
+    waitQueue = [];
+    maxConcurrent;
+    cooldownMs;
+    constructor(options = {}) {
+        this.maxConcurrent = options.maxConcurrent ?? getApiMaxConcurrent();
+        this.cooldownMs = options.cooldownMs ?? getApiCooldownMs();
+    }
+    /** Acquires a queue slot and returns fn result. Use when queue wait time is not needed. */
+    async run(label, fn) {
+        const { value } = await this.runWithMetrics(label, async () => fn());
+        return value;
+    }
+    /**
+     * Acquires a slot, measures wait time, invokes fn(queueWaitMs), returns result + wait.
+     * queueWaitMs is measured after slot acquire and before fn runs.
+     */
+    async runWithMetrics(label, fn) {
+        const queueStartedAt = Date.now();
+        while (this.activeCalls >= this.maxConcurrent) {
+            await new Promise((resolve) => this.waitQueue.push(resolve));
+        }
+        const queueWaitMs = Date.now() - queueStartedAt;
+        if (queueWaitMs > 1000) {
+            console.warn(`[auvira-agent] Waiting for API slot (${label}, ${queueWaitMs}ms, active=${this.activeCalls}/${this.maxConcurrent}).`);
+        }
+        this.activeCalls += 1;
+        try {
+            const value = await fn(queueWaitMs);
+            return { value, queueWaitMs };
+        }
+        finally {
+            this.activeCalls -= 1;
+            const next = this.waitQueue.shift();
+            if (next) {
+                next();
+            }
+            if (this.cooldownMs > 0) {
+                await sleep(this.cooldownMs);
+            }
+        }
+    }
+    /** Returns current queue settings for diagnostics. */
+    getConfig() {
+        return {
+            maxConcurrent: this.maxConcurrent,
+            cooldownMs: this.cooldownMs,
+            activeCalls: this.activeCalls,
+            queuedCalls: this.waitQueue.length,
+        };
+    }
+}
+let globalQueue;
+/** Shared queue for all external model-like API calls in this process. */
+export function getGlobalModelCallQueue() {
+    if (!globalQueue) {
+        globalQueue = new ModelCallQueue();
+    }
+    return globalQueue;
+}
+/** Resets the global queue (tests only). */
+export function resetGlobalModelCallQueue() {
+    globalQueue = undefined;
+}
+//# sourceMappingURL=modelCallQueue.js.map

package/dist/util/modelCallQueue.js.map

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

package/docs/host-integration-image-placement.md

@@ -15,6 +15,94 @@ This guide maps the generic image-placement architecture to **SDK APIs (v0.6+)**
 | Vision bytes for model | Optional | `images[]` on send payload |
 | Serializable multi-file completion | Configures | `completion.rules` |
 | Built-in `get_attachment_urls` | Can override | Shipped generic tool |
+| `classifyImageEditMode` / `runImageEditPipeline` | Yes — runs **before** `Agent.send` | No |
+| Deterministic image applier + embedding verify/retry | Yes | No |
+| Plan → Apply → Polish routing by intent | Yes | Speed + completion only |
+
+## Plan → Apply → Polish (host-owned pipeline)
+
+For fast image edits, the **host orchestrator runs before `Agent.send`**. It classifies intent, applies images deterministically when possible, and calls the SDK agent only for polish or full creative work. The SDK stays generic — it does not know `siteConfig`, placement targets, or applier logic.
+
+```mermaid
+flowchart TD
+  hostOrch[Host orchestrator before Agent.send]
+  direct[direct_embed]
+  plan[placement_plan]
+  style[embed_then_style]
+  creative[full_creative]
+
+  hostOrch --> direct
+  hostOrch --> plan
+  hostOrch --> style
+  hostOrch --> creative
+
+  direct --> hostApply1[Host deterministic applier]
+  plan --> hostPlan[Host JSON plan call]
+  hostPlan --> hostApply2[Host deterministic applier]
+  style --> hostApply3[Host deterministic applier]
+  style --> sdkPolish[SDK agent polish pass]
+  creative --> sdkAgent[SDK full agentic loop]
+```
+
+| Mode | Host responsibility | SDK involvement |
+| --- | --- | --- |
+| **`direct_embed`** | Deterministic applier; **0 agent tools**; usually **no `Agent.send`** | Attachments / completion types only if a follow-up turn is needed |
+| **`placement_plan`** | One JSON planning call (host LLM + schema); deterministic applier; **no SDK agentic file tools** | Not required for planning (host may use its own LLM client) |
+| **`embed_then_style`** | Deterministic apply first (image URL already wired) | Short polish/style `Agent.send`; `completion.rules` must keep the wired URL present |
+| **`full_creative`** | Classify + optional pre-context | Full agentic loop; v0.6.2 parallel read batches speed discovery |
+
+**SDK owns:** attachments, host tools, completion rules, agentic loop, API queue, parallel read-only tools.
+
+**Host owns:** image classification, placement mapping, deterministic applying, embedding verification, retry logic.
+
+### Example: `embed_then_style` polish pass
+
+After the host applies the image (no agent file tools), call the SDK for animation/style only. Most consumers wire hero URLs in `siteConfig.ts`; some use `page.tsx` or a component — tune `pathPattern` to your repo.
+
+**Recommended:** inject the exact URL the host just wired — strongest gate for the polish pass:
+
+```ts
+const uploadedImagePublicUrl = attachments[0].publicUrl; // e.g. "/uploads/hero-abc.png"
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+await agent.send(
+  {
+    text: styleOnWiredBaselinePrompt, // host-owned
+    attachments, // already wired by host applier
+  },
+  {
+    completion: {
+      mode: "multi_file_required",
+      multiStep: { minToolCalls: 1, maxExtraTurnsAfterStyleOnly: 2 },
+      rules: {
+        requiredContent: [
+          {
+            // siteConfig.ts is the common case; extend for inline page/component wiring
+            pathPattern: "(siteConfig\\.ts|page\\.tsx|.*components/.*\\.(tsx|ts))",
+            contentPattern: escapeRegex(uploadedImagePublicUrl),
+            nudge: `Keep the wired image URL ${uploadedImagePublicUrl}; add animation/style only.`,
+          },
+        ],
+      },
+    },
+  },
+);
+```
+
+**Alternative** (prefix-only, when `/uploads/` or `/assets/` is enough):
+
+```ts
+contentPattern: 'backgroundImageUrl\\s*:\\s*["\']/(uploads|assets)/',
+```
+
+For **`full_creative`**, use the normal agentic path with tuned `completion.rules`. v0.6.2 parallel read tools (`grep`, `read`, `glob`, etc.) reduce discovery latency when the model batches exploration.
+
+**Not in SDK:** `classifyImageEditMode`, `runImageEditPipeline`, `ImagePlacementTarget`, `applyImageToConfig`, embedding verification, or gallery `ImagePlacementPlan` replacement — implement these in the consumer repo.
+
+**Optional later:** a generic `planOnly` send mode (single structured JSON call, no tool loop) if the host wants to drop duplicated planner LLM client code. Defer until the consumer pipeline proves that need.
 
 ## Layer 1 — Attachments vs vision images
 

package/docs/sandbox-runner.md

@@ -75,6 +75,9 @@ auvira-sdk-run --job <editJobId>
 | `AUVIRA_IMAGE_GEN_MAX_PER_RUN` | No | Max image generations per run (default `2`) |
 | `AUVIRA_IMAGE_BASE_URL` | No | Override image API base (default global `api.minimax.io/v1` or CN from chat host) |
 | `AUVIRA_IMAGE_MODEL` | No | Image model id (default `image-01`) |
+| `AUVIRA_PARALLEL_READ_TOOLS` | No | Parallelize read-only tool batches (default `true`) |
+| `AUVIRA_MAX_PARALLEL_READ_TOOLS` | No | Max concurrent read tools per batch (default `8`) |
+| `AUVIRA_API_MAX_CONCURRENT` | No | Global in-flight limit for external API calls — chat, evaluator, image gen (default `3`; aliases: `AUVIRA_MODEL_MAX_CONCURRENT`, `CUSTOM_MODEL_MAX_CONCURRENT`) |
 
 `CUSTOM_MODEL_API_KEY` is read from the environment only — never from `job.json`.
 
@@ -134,7 +137,9 @@ auvira-sdk-run --job <editJobId>
 - `hostTools` are **not** supported in `job.json` v1 — register them in-process via `Agent.create` / `Agent.send`.
 - `model.apiKey` is rejected by the validator.
 
-See [host-integration-image-placement.md](./host-integration-image-placement.md) for the full SDK vs website-repo split.
+See [host-integration-image-placement.md](./host-integration-image-placement.md) for the full SDK vs website-repo split, including the **Plan → Apply → Polish** host pipeline (`direct_embed`, `placement_plan`, `embed_then_style`, `full_creative`).
+
+For image edits routed by the host orchestrator: Cases 1–3 (deterministic apply / plan-then-apply) typically **do not** spawn a sandbox job or call `Agent.send`. Case 4 (`full_creative`) uses this runner; v0.6.2 parallel read tools and `AUVIRA_API_MAX_CONCURRENT` apply inside the VM the same as in-process runs.
 
 ## Result (`SandboxAuviraJobResult`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auvira.ai/sdk",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Cursor-SDK-compatible visual coding agent with custom model support",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,13 +42,14 @@
     "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 src/__tests__/runner/run-cli.real.e2e.test.ts",
+    "test:real:smoke": "node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/real/minimax-api.test.ts src/__tests__/real/agent-run-stream.e2e.test.ts src/__tests__/real/agent-parallel-read-tools.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:asset": "AUVIRA_REAL_ASSET_E2E=true node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/runner/run-cli-asset.real.e2e.test.ts",
     "test:runner:image-gen": "AUVIRA_REAL_IMAGE_GEN_E2E=true AUVIRA_IMAGE_GEN_ENABLED=true node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/runner/run-cli-generate-image.real.e2e.test.ts",
     "test:real:image-api": "AUVIRA_REAL_IMAGE_API=true AUVIRA_IMAGE_GEN_ENABLED=true node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/real/minimax-image-api.real.test.ts",
     "test:real:multi-image": "AUVIRA_REAL_MULTI_IMAGE_E2E=true node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/real/agent-multi-image.e2e.test.ts src/__tests__/runner/run-cli-multi-image.real.e2e.test.ts",
-    "test:real:attachment-placement": "AUVIRA_REAL_ATTACHMENT_E2E=true node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/real/agent-attachment-placement.e2e.test.ts src/__tests__/runner/run-cli-attachment-placement.real.e2e.test.ts",
+    "test:real:attachment-placement": "AUVIRA_REAL_ATTACHMENT_E2E=true node --env-file=.env ./node_modules/vitest/vitest.mjs run src/__tests__/real/agent-attachment-placement.e2e.test.ts src/__tests__/real/agent-attachment-animation.e2e.test.ts src/__tests__/runner/run-cli-attachment-placement.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": [