@auvira.ai/sdk 0.6.2 → 0.6.4

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** and **Preset → Apply → Polish** host pipelines, polish helpers), see [docs/host-integration-image-placement.md](docs/host-integration-image-placement.md).
 
 ## Quick start (local repo)
 

package/dist/agent/polishCompletion.d.ts

@@ -0,0 +1,17 @@
+import type { AgentCompletionOptions, CompletionContentRequirement, SerializableCompletionRules } from "./types.js";
+/** Escapes a string for safe use inside a RegExp source (e.g. contentPattern literals). */
+export declare function escapeRegexLiteral(value: string): string;
+/** Builds a requiredContent rule that preserves an exact wired literal (URL, class, keyframe name). */
+export declare function createRequiredContentFromLiteral(input: {
+    pathPattern: string;
+    literal: string;
+    nudge?: string;
+}): CompletionContentRequirement;
+/** Completion options for short style/animation polish passes after host deterministic apply. */
+export declare function createPolishCompletionOptions(input: {
+    requiredContent?: CompletionContentRequirement[];
+    rules?: SerializableCompletionRules;
+    minToolCalls?: number;
+    maxExtraTurns?: number;
+}): AgentCompletionOptions;
+//# sourceMappingURL=polishCompletion.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"polishCompletion.d.ts","sourceRoot":"","sources":["../../src/agent/polishCompletion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,4BAA4B,EAC5B,2BAA2B,EAC5B,MAAM,YAAY,CAAC;AAEpB,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,uGAAuG;AACvG,wBAAgB,gCAAgC,CAAC,KAAK,EAAE;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,4BAA4B,CAO/B;AAED,iGAAiG;AACjG,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,eAAe,CAAC,EAAE,4BAA4B,EAAE,CAAC;IACjD,KAAK,CAAC,EAAE,2BAA2B,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,sBAAsB,CAqBzB"}

package/dist/agent/polishCompletion.js

@@ -0,0 +1,35 @@
+/** Escapes a string for safe use inside a RegExp source (e.g. contentPattern literals). */
+export function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Builds a requiredContent rule that preserves an exact wired literal (URL, class, keyframe name). */
+export function createRequiredContentFromLiteral(input) {
+    return {
+        pathPattern: input.pathPattern,
+        contentPattern: escapeRegexLiteral(input.literal),
+        required: true,
+        nudge: input.nudge,
+    };
+}
+/** Completion options for short style/animation polish passes after host deterministic apply. */
+export function createPolishCompletionOptions(input) {
+    const mergedRequiredContent = [
+        ...(input.rules?.requiredContent ?? []),
+        ...(input.requiredContent ?? []),
+    ];
+    const mergedRules = {
+        ...(input.rules ?? {}),
+        ...(mergedRequiredContent.length
+            ? { requiredContent: mergedRequiredContent }
+            : {}),
+    };
+    return {
+        mode: "multi_file_required",
+        multiStep: {
+            minToolCalls: input.minToolCalls ?? 1,
+            maxExtraTurnsAfterStyleOnly: input.maxExtraTurns ?? 2,
+        },
+        ...(Object.keys(mergedRules).length > 0 ? { rules: mergedRules } : {}),
+    };
+}
+//# sourceMappingURL=polishCompletion.js.map

package/dist/agent/polishCompletion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polishCompletion.js","sourceRoot":"","sources":["../../src/agent/polishCompletion.ts"],"names":[],"mappings":"AAMA,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,OAAO,KAAK,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACtD,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,gCAAgC,CAAC,KAIhD;IACC,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,cAAc,EAAE,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC;QACjD,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,6BAA6B,CAAC,KAK7C;IACC,MAAM,qBAAqB,GAAG;QAC5B,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,eAAe,IAAI,EAAE,CAAC;QACvC,GAAG,CAAC,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC;KACjC,CAAC;IAEF,MAAM,WAAW,GAAgC;QAC/C,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;QACtB,GAAG,CAAC,qBAAqB,CAAC,MAAM;YAC9B,CAAC,CAAC,EAAE,eAAe,EAAE,qBAAqB,EAAE;YAC5C,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,qBAAqB;QAC3B,SAAS,EAAE;YACT,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,CAAC;YACrC,2BAA2B,EAAE,KAAK,CAAC,aAAa,IAAI,CAAC;SACtD;QACD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { formatAttachmentsContextBlock, writeAttachmentsManifest, readAttachment
 export type { HostToolDefinition, HostToolContext, HostToolHandler, HostToolHandlerResult, HostToolRegistration, } from "./agent/hostTools.js";
 export { validateHostToolRegistrations, mergeHostToolRegistrations, resolveHostToolsForRun, createGetAttachmentUrlsHostTool, buildHostToolParallelSafeMap, hostToolsToOpenAiDefinitions, } from "./agent/hostTools.js";
 export { buildWiringHintNudge, pathExistsUnderRepo, shouldRequirePublicAssetPublish, getOrphanComponentNudge, } from "./agent/editCompletion.js";
+export { createPolishCompletionOptions, createRequiredContentFromLiteral, escapeRegexLiteral, } from "./agent/polishCompletion.js";
 export type { HarnessPinnedTarget } from "./providers/custom/harnessPinTypes.js";
 export type { WorkspaceCheckpoint, WorkspaceDiffResult } from "./workspace/workspaceCheckpoint.js";
 export type { TaskCompletionDecision } from "./agent/evaluateTaskCompletion.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,yBAAyB,EACzB,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,EACrB,2BAA2B,EAC3B,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AACjF,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACnG,YAAY,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAChF,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,EACxB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC9B,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,kCAAkC,EAClC,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,yBAAyB,EACzB,yBAAyB,EACzB,4BAA4B,EAC5B,qBAAqB,EACrB,2BAA2B,EAC3B,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AACjF,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACnG,YAAY,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAChF,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,wBAAwB,EACxB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC9B,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,kCAAkC,EAClC,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@ export { AgentNotFoundError } from "./agent/AgentRegistry.js";
 export { formatAttachmentsContextBlock, writeAttachmentsManifest, readAttachmentsManifest, ATTACHMENTS_MANIFEST_RELATIVE, } from "./agent/attachmentContext.js";
 export { validateHostToolRegistrations, mergeHostToolRegistrations, resolveHostToolsForRun, createGetAttachmentUrlsHostTool, buildHostToolParallelSafeMap, hostToolsToOpenAiDefinitions, } from "./agent/hostTools.js";
 export { buildWiringHintNudge, pathExistsUnderRepo, shouldRequirePublicAssetPublish, getOrphanComponentNudge, } from "./agent/editCompletion.js";
+export { createPolishCompletionOptions, createRequiredContentFromLiteral, escapeRegexLiteral, } from "./agent/polishCompletion.js";
 export { AGENT_TOOL_NAMES, isToolEvent, isAssistantEvent, } from "./agent/events.js";
 export { emitAgentPlanningThinking, emitAgentToolSelectionThinking, emitAgentCompletionCheckThinking, emitAgentReflectionThinking, emitAgentRawModelTrace, isRawModelTraceEnabled, } from "./agent/emitAgentThinking.js";
 export { getAssistantEventText } from "./agent/assistantEvent.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAsB9D,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,8BAA8B,CAAC;AAQtC,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AAkBnC,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC9B,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAsB9D,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,8BAA8B,CAAC;AAQtC,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,sBAAsB,EACtB,+BAA+B,EAC/B,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AAkBrC,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC9B,gCAAgC,EAChC,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,mBAAmB,EACnB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}

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

@@ -15,6 +15,172 @@ 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 |
+| `classifyAnimationEditMode` / `runAnimationEditPipeline` | Yes — runs **before** `Agent.send` | No |
+| Deterministic animation applier + preset apply | Yes | No |
+| Preset → Apply → Polish routing by intent | Yes | Polish helpers only |
+| Polish completion helpers | Consumes | `createPolishCompletionOptions`, `createRequiredContentFromLiteral`, `escapeRegexLiteral` |
+
+## Host-owned deterministic pipelines
+
+The **host orchestrator runs before `Agent.send`**. It classifies intent, applies image or animation changes 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, animation presets, or applier logic.
+
+**When to call the SDK:** only for polish or full creative. Deterministic apply paths (image Cases 1–3, animation preset-only) typically skip `Agent.send` entirely.
+
+**SDK owns:** attachments, host tools, completion rules, agentic loop, API queue, parallel read-only tools, polish completion helpers.
+
+**Host owns:** intent classification, placement/animation target resolution, `siteConfig`/page mutation, embedding verification, retry logic, chip UX.
+
+### Image: Plan → Apply → Polish
+
+```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 |
+
+### Animation: Preset → Apply → Polish
+
+For animation edits, the host applies motion presets deterministically (Tailwind class, `@keyframes`, motion token, etc.) before optionally calling the SDK for refinement.
+
+```mermaid
+flowchart TD
+  hostAnimOrch[Host orchestrator before Agent.send]
+  presetOnly[preset_apply only]
+  presetPolish[preset_apply_then_polish]
+  animCreative[full_creative]
+
+  hostAnimOrch --> presetOnly
+  hostAnimOrch --> presetPolish
+  hostAnimOrch --> animCreative
+
+  presetOnly --> hostAnimApply1[Host deterministic animation applier]
+  presetPolish --> hostAnimApply2[Host deterministic animation applier]
+  presetPolish --> sdkAnimPolish[SDK agent polish pass]
+  animCreative --> sdkAgentAnim[SDK full agentic loop]
+```
+
+| Mode | Host responsibility | SDK involvement |
+| --- | --- | --- |
+| **Preset apply only** | Classify preset, apply class/CSS deterministically; **0 agent tools**; usually **no `Agent.send`** | None |
+| **Preset + polish** | Deterministic apply first (class/keyframes already wired) | Short polish `Agent.send`; preserve wired class/URL |
+| **Full creative** | Classify + optional pre-context | Full agentic loop |
+
+### Polish completion helpers (v0.6.4+)
+
+Use SDK helpers for short polish passes after host deterministic apply. Image polish examples reflect **CDN/GCS-hosted URLs** (consumer applies the URL before `Agent.send`; polish preserves it):
+
+```ts
+import {
+  createPolishCompletionOptions,
+  createRequiredContentFromLiteral,
+} from "@auvira.ai/sdk";
+
+// Image polish (after host wired CDN/GCS URL deterministically)
+await agent.send(
+  { text: styleOnWiredBaselinePrompt, attachments },
+  {
+    completion: createPolishCompletionOptions({
+      requiredContent: [
+        createRequiredContentFromLiteral({
+          pathPattern: "(siteConfig\\.ts|page\\.tsx|.*components/.*\\.(tsx|ts))",
+          literal: uploadedImagePublicUrl, // e.g. https://storage.googleapis.com/... or CDN URL
+          nudge: "Keep the wired CDN/GCS image URL; only add animation/style.",
+        }),
+      ],
+    }),
+  },
+);
+
+// Animation polish (after host applied preset class)
+await agent.send(
+  { text: animationPolishPrompt },
+  {
+    completion: createPolishCompletionOptions({
+      requiredContent: [
+        createRequiredContentFromLiteral({
+          pathPattern: "(globals\\.css|page\\.tsx|.*components/.*\\.(tsx|ts))",
+          literal: "animate-fade-in", // or @keyframes name host applied
+          nudge: "Keep the preset animation class; refine timing/easing only.",
+        }),
+      ],
+    }),
+  },
+);
+```
+
+`createPolishCompletionOptions` also accepts optional `rules` (`requiredPaths`, `requireAssetPublish`, etc.). Top-level `requiredContent` is **concatenated** with `rules.requiredContent` (base guards preserved, polish guards appended).
+
+### Example: `embed_then_style` polish pass (manual completion)
+
+After the host applies the image (no agent file tools), call the SDK for animation/style only. Prefer `createPolishCompletionOptions` + `createRequiredContentFromLiteral` (see above). Manual equivalent:
+
+```ts
+const uploadedImagePublicUrl = "https://storage.googleapis.com/bucket/hero.png"; // CDN/GCS URL wired by host applier
+
+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 CDN/GCS 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`, `classifyAnimationEditMode`, `runAnimationEditPipeline`, `applyAnimationPreset`, `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 **Host-owned deterministic pipelines** (image Plan → Apply → Polish, animation Preset → Apply → Polish).
+
+Host-owned deterministic pipelines (image Cases 1–3, animation preset-only apply) typically **do not** spawn a sandbox job or call `Agent.send`. Polish and full-creative paths use the runner; `completion.rules.requiredContent` (including polish preserve guards) is JSON-serializable in `job.json` (see [`validateJob.ts`](../src/runner/validateJob.ts)). 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.4",
   "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": [