diff --git a/catalog.json b/catalog.json index b44f932..d00569f 100644 --- a/catalog.json +++ b/catalog.json @@ -32,7 +32,7 @@ "fr": "Lire et modifier la scène ouverte dans Blender grâce à l'extension OpenCode Link : changements typés en un pas d'annulation, inspection du Blender lancé, rendus de vérification et en arrière-plan." }, "app": { "name": "Blender", "versions": ">=5.3" }, - "host": { "protocol": 1, "range": "^0.4.6" }, + "host": { "protocol": 1, "range": "^0.4.7" }, "docs": "https://github.com/NeuralNomadsAI/opencode-integrations/blob/main/integrations/blender/plugin/README.md", "status": "preview", "sources": { "git": ["github:NeuralNomadsAI/opencode-integrations#main::path:integrations/blender/plugin"] } diff --git a/integrations/blender/host/opencode_link/blender_manifest.toml b/integrations/blender/host/opencode_link/blender_manifest.toml index af7a2d1..32c0f6f 100644 --- a/integrations/blender/host/opencode_link/blender_manifest.toml +++ b/integrations/blender/host/opencode_link/blender_manifest.toml @@ -1,7 +1,7 @@ schema_version = "1.0.0" id = "opencode_link" -version = "0.4.6" +version = "0.4.7" name = "OpenCode Link" tagline = "Lets OpenCode work on this Blender session" maintainer = "NeuralNomads" diff --git a/integrations/blender/host/ops.json b/integrations/blender/host/ops.json index 1786fde..64b9808 100644 --- a/integrations/blender/host/ops.json +++ b/integrations/blender/host/ops.json @@ -1,6 +1,6 @@ { "addon": "opencode_link", - "version": "0.4.6", + "version": "0.4.7", "protocol": 1, "method": "apply", "wire": "params.operations: [{op, args}] with every op below (an edit batch); unknown ops and fields are refused", diff --git a/integrations/blender/plugin/README.md b/integrations/blender/plugin/README.md index 864b32e..9732ad1 100644 --- a/integrations/blender/plugin/README.md +++ b/integrations/blender/plugin/README.md @@ -39,7 +39,7 @@ The **Plugins** section lists OpenCode for Blender as an integration: its versio - **Which Blender.** `blender_hosts` and `blender_context` name the Blender this conversation acts on (`attached_to`: offer and label). Other conversations attaching or detaching other Blenders, or Blenders appearing, never make this conversation's ownership unverifiable; a permission prompt is refused only when this conversation's own Blender changed meanwhile. - **Across an OpenCode restart.** The plugin keeps each conversation's attachment in its storage (the Blender's offer key only as a SHA-256 digest, with the label; never a token, port or script handle). When the same Blender offers itself again after a restart, the conversation is attached back without asking, once its ownership is verified at its Location; never inside a read. A kept attachment lasts while its Blender is offered and two minutes after it stops; detaching removes it at once. A Blender restarted itself is a new offer: the conversation attaches again as above. - **Upgrading without restarting OpenCode.** A daemon that loads a newer version of the plugin without restarting can keep the older one in memory. Each version keeps its own list of offered Blenders, named after the add-on versions it accepts, so a Blender is always judged by the version that lists it; it offers itself again within 5 seconds. -- **The working method.** When a conversation attaches a Blender, a short method joins it (an instructions entry, about 250 tokens): read the Blender version first, inspect the exact element before coding it (`blender_inspect`, its `search` to find where a setting lives), read an error's hint and inspect again instead of guessing, give operators their context with `temp_override`, turn the acceptance criteria into checks run with `blender_verify` (`criteria`, `visible`) and report the measured values, and write down what you discover. +- **The working method.** When a conversation attaches a Blender, a short method joins it (an instructions entry, about 250 tokens): read the Blender version first, inspect the exact element before coding it, read an error's hint and inspect again instead of guessing, turn each requirement of the task into a check, run every check on the saved file (`blender_verify` with `saved: true`: the file is what is delivered), and report each requirement with its measured value, saying what failed or was not checked. - **Session binding.** Clients read `bindingRead({ sessionID })` at the session's current OpenCode Location: `attached` identifies its live offer and safe label, `none` confirms a verified session without a binding, and `unknown` keeps the state unverified. `status_changed {}` invalidates the read; `detachHost({ sessionID })` detaches. See the [draft 0.2 RPC contract](../../../spec/rpc-contract.md). ## Tools @@ -55,7 +55,7 @@ The **Plugins** section lists OpenCode for Blender as an integration: its versio | `blender_inspect` | What this Blender really exposes: `search` (words found in its types, properties, functions and operators, with their paths and the properties that lead to a type), a type (properties, functions; a node type's real sockets, made in the `tree` named), an operator (parameters, the element type of its collections, its poll here with Blender's reason) or live data; entries beyond `limit` are named, `match` takes a glob or words. With the links to the API docs, manual and release notes of its version. | | `blender_verify` | `criteria`: the agent's checks (a read-only expression or a `bpy.data` path, a comparison, a value, frames), each measured on the evaluated scene and passed or failed with the value; `visible`: whether an object shows in the render at a frame, otherwise every reason found (out of frame, hidden in render, collection excluded, view layer not rendered, holdout, transparent or zero-density material, no geometry, hidden behind another object). Without them, or with `render` or `view`: a low-resolution render of the scene's final output, or from a free viewpoint (`view`: location, target, lens), with facts: black or transparent, brightness, the camera used and why, strips, instances. `frames` returns several frames as one contact sheet; `scene` chooses the scene (the facts name the one read, and warn when it is a shot of a montage). `geometry` says what is wrong with the meshes in view (closed meshes with inward normals, open or non-manifold edges, zero-area faces, faces of two objects on one plane toward the camera), and a render names its near-black areas with the object a camera ray meets there; `caches` names the simulation caches the checked frames read without a current bake (not baked, outdated, frames outside it) (Blender marks a rigid body bake outdated whenever its file is opened, and says so in `note`); `unsaved`, what the saved file lacks; `saved` reads the file as written on disk instead (a background Blender opens it: same criteria, `visible` and render; `read` names the file). Settings, cameras and frame are restored; the revision stays. | | `blender_render` | A render in a separate background Blender to an exact output (an image, a frame pattern or an H.264 video, with the montage's sound when it has any; the result lists the streams written), followed as a task (`task`, `wait_s` up to an hour, `cancel`). It renders the saved file (`unsaved`). | -| `blender_save` | Saves the file, under a path, or a copy, and says what it wrote (bytes; `wrote_steps`, the OpenCode steps now in the file, an empty list when none was pending) and, after a copy, what the open file still lacks (`unsaved`); a save that failed because another process held the file a moment is retried once and says so (`retried`). | +| `blender_save` | Saves the file, under a path, or a copy, and says what it wrote (bytes; `wrote_steps`, the OpenCode steps now in the file, an empty list when none was pending) and, after a copy, what the open file still lacks (`unsaved`), with `check`, the `blender_verify` call that reads the file back (a code run that saved the open file says it too); a save that failed because another process held the file a moment is retried once and says so (`retried`). | | `blender_import` | BlenderKit and Sketchfab searches, and imports from them or from a file (glTF, FBX, OBJ, USD; a path or an https URL), followed as a task (`task`, `wait_s`, `cancel`). BlenderKit and Sketchfab need their add-ons. | `blender_inspect`, `blender_verify`, `blender_render` and `blender_save` send fixed programs of the package (`programs/*.py`) through the host's code execution, read only, with their parameters as JSON data; they ask no permission because they run no code from the model. Without `if_revision` and `command_id`, `blender_apply` applies to the document as it is now under a new `command_id`; with them it is refused when the scene changed, and a replayed `command_id` applies nothing. diff --git a/integrations/blender/plugin/host/blender/opencode_link-0.4.6.zip b/integrations/blender/plugin/host/blender/opencode_link-0.4.7.zip similarity index 99% rename from integrations/blender/plugin/host/blender/opencode_link-0.4.6.zip rename to integrations/blender/plugin/host/blender/opencode_link-0.4.7.zip index 46aaa7c..24e6ab0 100644 Binary files a/integrations/blender/plugin/host/blender/opencode_link-0.4.6.zip and b/integrations/blender/plugin/host/blender/opencode_link-0.4.7.zip differ diff --git a/integrations/blender/plugin/methods/tools/blender_save.json b/integrations/blender/plugin/methods/tools/blender_save.json index 026fff2..ac145d3 100644 --- a/integrations/blender/plugin/methods/tools/blender_save.json +++ b/integrations/blender/plugin/methods/tools/blender_save.json @@ -1,7 +1,7 @@ { "name": "blender_save", "domain": "tools", - "description": "Save the open file; with path, save it under that .blend (as the open file, or a copy with copy true). Relative paths are next to the current file; an existing other file needs overwrite. Says what it wrote (bytes, wrote_steps: the OpenCode steps now in the file) and, after a copy, what the open file still lacks (unsaved).", + "description": "Save the open file; with path, save it under that .blend (as the open file, or a copy with copy true). Relative paths are next to the current file; an existing other file needs overwrite. Says what it wrote (bytes, wrote_steps: the OpenCode steps now in the file) and, after a copy, what the open file still lacks (unsaved). blender_verify with saved reads the file back.", "kind": "host-backed", "risk": "write", "args": { diff --git a/integrations/blender/plugin/methods/tools/blender_verify.json b/integrations/blender/plugin/methods/tools/blender_verify.json index 3298851..db70d4b 100644 --- a/integrations/blender/plugin/methods/tools/blender_verify.json +++ b/integrations/blender/plugin/methods/tools/blender_verify.json @@ -18,7 +18,7 @@ }, "saved": { "type": "any", - "description": "true: read the open file as saved on disk (a background Blender opens it; same criteria, visible and render), or a .blend path. Compare it with the open document." + "description": "true: read the open file as saved on disk (a background Blender opens it; same criteria, visible and render), or a .blend path. The file is what is delivered: check its requirements here before reporting." }, "render": { "type": "boolean", diff --git a/integrations/blender/plugin/package.json b/integrations/blender/plugin/package.json index 4f9b4eb..ccec4cf 100644 --- a/integrations/blender/plugin/package.json +++ b/integrations/blender/plugin/package.json @@ -1,6 +1,6 @@ { "name": "@neuralnomads/opencode-blender", - "version": "0.4.6", + "version": "0.4.7", "description": "OpenCode for Blender: lets OpenCode read and change an open Blender scene through an authenticated local host, with typed edits, inspection, verification renders and background renders.", "license": "MIT AND GPL-3.0-or-later", "type": "module", @@ -60,10 +60,10 @@ "host": { "app": "blender", "protocol": 1, - "range": "^0.4.6", + "range": "^0.4.7", "appVersions": ">=5.3", - "payload": "host/blender/opencode_link-0.4.6.zip", - "sha256": "c5defc03b74f70744899f16c02d95be76769582cf8f04d3fec75ff0efa7184ac" + "payload": "host/blender/opencode_link-0.4.7.zip", + "sha256": "5ff8ba71be6cd7e146e8e1367e082d323c30817c1a6ed38af3743a2470c397dc" } } } diff --git a/integrations/blender/plugin/src/integration.ts b/integrations/blender/plugin/src/integration.ts index f8b2b81..c2814fd 100644 --- a/integrations/blender/plugin/src/integration.ts +++ b/integrations/blender/plugin/src/integration.ts @@ -144,6 +144,11 @@ function bounded(text: string) { : text } +// After a save: what reads the file back, as written on disk (the open document can differ from it). +export function verifySavedHint(saved: true | string) { + return `blender_verify with saved: ${saved === true ? "true" : JSON.stringify(saved)} reads what this file holds.` +} + function json(value: unknown) { return bounded(JSON.stringify(value)) } @@ -428,11 +433,13 @@ export async function setupBlender(ctx: Plugin.Context, deps: BlenderDeps = {}) // (a copy leaves the open file as it was). const save = async (context: ToolContext, args: Record) => { const out = await programRun(context, "save", args) + const result = out.result as Record return { - ...(out.result as Record), + ...result, // A save of the open file always says what it wrote of OpenCode's (none: an empty list). ...(out.saved ? { wrote_steps: out.saved_steps ?? [] } : {}), ...(out.unsaved ? { unsaved: out.unsaved } : {}), + check: verifySavedHint(result.copy === true ? String(result.saved) : true), } } @@ -554,19 +561,19 @@ export async function setupBlender(ctx: Plugin.Context, deps: BlenderDeps = {}) code: code.length > 4_000 ? `${code.slice(0, 4_000)}\n…` : code, }) const seconds = typeof args.timeout_s === "number" ? Math.min(Math.max(args.timeout_s, 1), 3_600) : undefined - return json( - await callHost( - context, - "execute_code", - { - code, - ...(script ? { filename: script.path } : {}), - ...(args.read_only === true ? { read_only: true } : {}), - }, - seconds ? seconds * 1_000 : undefined, - held, - ), - ) + const out = (await callHost( + context, + "execute_code", + { + code, + ...(script ? { filename: script.path } : {}), + ...(args.read_only === true ? { read_only: true } : {}), + }, + seconds ? seconds * 1_000 : undefined, + held, + )) as Record + // A run that saved the open file: how to read back what the file now holds (a fact, not a step to take). + return json(out.saved === true ? { ...out, check: verifySavedHint(true) } : out) }, async blender_lab(args, context) { diff --git a/integrations/blender/plugin/src/method.ts b/integrations/blender/plugin/src/method.ts index 47525e4..dc60fc7 100644 --- a/integrations/blender/plugin/src/method.ts +++ b/integrations/blender/plugin/src/method.ts @@ -5,10 +5,11 @@ export const METHOD_KEY = "blender.method" export const METHOD_TEXT = [ "Working on the open Blender:", "- Your knowledge of its Python API may be older than it: read its version (blender_hosts, blender_inspect).", - "- Inspect the exact element before coding it: blender_inspect search (words) finds where a setting lives; then its type, operator, node type in its tree or live data.", - "- After an error, read its hint (closest names, real signature, keys, sockets) and inspect again; never guess twice.", - "- An operator that needs a context gets it from bpy.context.temp_override(window, area, region, id, ...).", - "- Before finishing, turn your acceptance criteria into checks (value, comparison, frames): blender_verify criteria, and visible for what must be seen. Report measured values; a failed check is not done.", + "- Inspect the exact element before coding it (blender_inspect search, type, operator, node type in its tree, data).", + "- After an error, read its hint and inspect again; never guess twice. A refused operator's hint names the context that passes.", + "- Turn each requirement of your task into a check (value, comparison, frames; visible for what must be seen).", + "- The saved file is what you deliver: save, then run every check on it with blender_verify saved: true.", + "- Report each requirement with its measured value from the file. A failed or unchecked one is not done: say so.", "- Still unclear: the docs and Python API release notes of THIS version (links in blender_inspect).", "- Write down what you discover (a recent change, a silent failure) in your report, with the Blender version.", ].join("\n") diff --git a/integrations/blender/test/plugin.test.ts b/integrations/blender/test/plugin.test.ts index 7c79127..5e370bd 100644 --- a/integrations/blender/test/plugin.test.ts +++ b/integrations/blender/test/plugin.test.ts @@ -27,7 +27,7 @@ async function plugin(input: Parameters[0] = {}): Promise { assert.equal(calls, 5, "not retried") }) + it("a save says how to read the file back: blender_save, a copy, and a code run that saved (0.4.7)", async () => { + const answers = [ + { + status: "executed", + saved: true, + saved_steps: ["OpenCode: code"], + result: { saved: "D:/shots/ex06.blend", bytes: 9 }, + }, + { status: "executed", result: { saved: "D:/shots/copy.blend", bytes: 9, copy: true } }, + { status: "executed", saved: true, result: {} }, + { status: "executed", result: { z: 1 } }, + ] + let calls = 0 + const { loaded } = await attached({ execute_code: () => answers[calls++] }) + const saved = content(await loaded.tool("blender_save", {})) + assert.deepEqual(saved.wrote_steps, ["OpenCode: code"]) + assert.equal(saved.check, "blender_verify with saved: true reads what this file holds.") + const copy = content(await loaded.tool("blender_save", { path: "copy.blend", copy: true })) + assert.equal(copy.check, 'blender_verify with saved: "D:/shots/copy.blend" reads what this file holds.') + const code = content(await loaded.tool("blender_execute_code", { code: "import bpy\nbpy.ops.wm.save_mainfile()" })) + assert.equal(code.check, "blender_verify with saved: true reads what this file holds.") + const plain = content(await loaded.tool("blender_execute_code", { code: "result = {'z': 1}" })) + assert.equal(plain.check, undefined, "only after a save") + }) + it("inspect, verify and save run their fixed programs read only, asking nothing", async () => { const sent: Array> = [] const results = [ @@ -820,7 +845,7 @@ describe("tools", () => { const other = await plugin() await other.rpc("advertise", announcement(old.endpoint, old.scriptHandle)) other.registry.attach(other.registry.hosts().offers[0]?.offerID as string, "ses_test") - await assert.rejects(other.tool("blender_context"), /no scene method: install OpenCode Link 0\.4\.6/) + await assert.rejects(other.tool("blender_context"), /no scene method: install OpenCode Link 0\.4\.7/) assert.ok(loaded) }) }) diff --git a/integrations/blender/test/publication.test.ts b/integrations/blender/test/publication.test.ts index c16f6e7..520c0fe 100644 --- a/integrations/blender/test/publication.test.ts +++ b/integrations/blender/test/publication.test.ts @@ -6,7 +6,7 @@ test("only Blender is publishable, with public access and trusted-publishing met const plugin = new URL("../plugin/", import.meta.url) const pkg = JSON.parse(readFileSync(new URL("package.json", plugin), "utf8")) assert.equal(pkg.name, "@neuralnomads/opencode-blender") - assert.equal(pkg.version, "0.4.6") + assert.equal(pkg.version, "0.4.7") assert.equal(pkg.private, undefined) assert.equal(pkg.publishConfig.access, "public") assert.equal(pkg.repository.url, "https://github.com/NeuralNomadsAI/opencode-integrations") diff --git a/integrations/blender/test/unit.test.ts b/integrations/blender/test/unit.test.ts index d86ab1f..3ecab58 100644 --- a/integrations/blender/test/unit.test.ts +++ b/integrations/blender/test/unit.test.ts @@ -183,6 +183,10 @@ describe("a Blender that closed", () => { describe("the working method", () => { it("is short, joins a conversation once, and never fails a Blender call", async () => { assert.ok(METHOD_TEXT.split("\n").length <= 10 && METHOD_TEXT.length < 1_000) + // 0.4.7: each requirement checked on the saved file before reporting, and what is not proven said. + assert.match(METHOD_TEXT, /each requirement of your task into a check/) + assert.match(METHOD_TEXT, /blender_verify saved: true/) + assert.match(METHOD_TEXT, /unchecked one is not done: say so/) resetMethodForTests() let calls = 0 const failing = methodAttacher(async () => { diff --git a/package-lock.json b/package-lock.json index 35cef54..f24d2eb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -39,7 +39,7 @@ }, "integrations/blender/plugin": { "name": "@neuralnomads/opencode-blender", - "version": "0.4.6", + "version": "0.4.7", "license": "MIT AND GPL-3.0-or-later", "devDependencies": { "@opencode/plugin": "2.2.5", diff --git a/spec/README.md b/spec/README.md index 41de3a4..9565430 100644 --- a/spec/README.md +++ b/spec/README.md @@ -19,9 +19,9 @@ The integration's `package.json` carries a marker under `opencodeIntegration`, r "host": { "app": "blender", "protocol": 1, - "range": "^0.4.6", + "range": "^0.4.7", "appVersions": ">=5.3", - "payload": "host/blender/opencode_link-0.4.6.zip", + "payload": "host/blender/opencode_link-0.4.7.zip", "sha256": "" } }