illustrator_execute_task

Execute structured SOC operations or a compatibility callback pipeline.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Prefer params.batch for all 48 JSX operations; the nine pilot models retain stronger nested typing. {operation_index}

• Compatibility params.payload remains supported for ordered mixed sequences under payload.params.ops; it uses the same static validation pipeline.

• The payload route also accepts compatibility callback hooks: collect_fn selects a callable, while compute_fn and apply_fn are arbitrary ExtendScript callback bodies. They have the same File, Folder, and OS access as raw ExtendScript, so this tool is open-world while they exist.

• Provide exactly one of params.batch or params.payload.

EXAMPLES: One structured operation (the preferred form): { "params": { "batch": { "operations": [ { "task": "element_create", "params": { "type": "rect", "x": 40, "y": 40, "width": 200, "height": 120, "fill": { "r": 0, "g": 150, "b": 136 } } } ] } } } Several operations, stopping at the first failure: { "params": { "batch": { "operations": [ { "task": "element_create", "params": { "type": "ellipse", "x": 0, "y": 0, "width": 60, "height": 60, "id": "dot" } }, { "task": "element_modify", "targets": { "type": "id", "ids": [ "dot" ] }, "params": { "x": 120 } } ], "stopOnError": true } } } Validate a batch without applying it: { "params": { "batch": { "operations": [ { "task": "element_create", "params": { "type": "star", "x": 100, "y": 100, "numPoints": 5, "outerRadius": 40, "innerRadius": 18 } } ], "mode": "validate" } } } Create a layer through the compatibility route: {"params": {"payload": {"task": "layer_create", "params": {"name": "Background"}}}} Create a layer, then a rectangle on it, in one batch: { "params": { "batch": { "operations": [ { "task": "layer_create", "params": { "name": "Background" } }, { "task": "element_create", "params": { "type": "rect", "x": 0, "y": 0, "width": 800, "height": 600, "layer": "Background" } } ], "stopOnError": true } } }

TARGET SELECTORS: {type: "selection"} — current selection (default) {type: "layer", layer: "Layer 1"} — all items on layer {type: "query", itemType: "PathItem", pattern: "axis_*"} — pattern match {type: "all", recursive: true} — all items in document {type: "id", ids: ["A1", "A2"]} — stable MCP ID targeting

OPTIONS: batch.stopOnError and payload.options.stopOnError stop after the first failed operation. They preserve earlier edits and do not provide transactional rollback. payload.options.mode and stopOnError are honored by the default structured SOC route. trace is honored by both structured and callback routes. payload.options.kind, skipCollect, minCreated, idPolicy, and the deprecated assignIds alias are callback-pipeline controls. The default SOC route forces kind="creation", resolves per-op targets, and has no apply callback. retry, idempotency, and timeout are compatibility fields that still validate but are currently ignored by this executor. It does not call the retry wrapper or use payload.options.timeout as its host deadline. dryRun — NOT SUPPORTED; rejected before execution. It could not prevent mutation (batch ops run during compute) and reported otherwise. To inspect without changing anything, use query_items, preflight_check, or get_document. rollback, snapshot, and recompute — NOT SUPPORTED; enabled requests are rejected before host dispatch. Explicit false/null disabled forms remain valid. Unknown task, payload, batch, operation, option, and nested retry fields are rejected. Use stopOnError instead of the internal strict spelling.

RESULT: structuredContent carries the canonical result object: execution status, data, effects, verification, recovery, warnings and truncation. isError reflects the EXECUTION outcome only — a failed or unavailable visual check never turns a successful edit into a tool error.

NOTES:

• With the default SOC executor (no custom compute function), the server injects payload.options.kind="creation" so outer collection is skipped while each operation resolves its own targets. Callers may omit kind.

• Both SOC routes validate the complete operation tree before dispatch. Availability, required fields, broad types, enums and unknown keys are checked from the shared contract. Pilot nested models remain stronger.

• Path handles and mirror modifiers normalize once for single operations, batch operations and compound children. Runtime fields and targets stay deferred; stopOnError does not promise rollback or successful assertions.

• Static request limits: 1000 operations, JSON depth 32, selector depth 16, 10000 expanded items and 100000 expanded geometry points. Dynamic values remain subject to host limits when evaluated.

• For boolean ops use illustrator_path_boolean, not execute_task

• For raw SVG path data use illustrator_path_import_svg