@auvira.ai/sdk 0.6.2 → 0.6.3

package/README.md

@@ -45,7 +45,7 @@ auvira-sdk-run --job <editJobId>
 
 See [docs/sandbox-runner.md](docs/sandbox-runner.md) for job schema, NDJSON protocol, host integration, and session resume.
 
-For image placement (attachments, completion rules, host tools), see [docs/host-integration-image-placement.md](docs/host-integration-image-placement.md).
+For image placement (attachments, completion rules, host tools, **Plan → Apply → Polish** host pipeline), see [docs/host-integration-image-placement.md](docs/host-integration-image-placement.md).
 
 ## Quick start (local repo)
 

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

@@ -137,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.2",
+  "version": "0.6.3",
   "description": "Cursor-SDK-compatible visual coding agent with custom model support",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
     "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": [