# Shade -- Agent API > Shade is a browser app that writes shaders with a person. They describe a > visual in the chat, and Shade's agent (a state machine of model requests on > Shade's server) researches, plans, writes and fixes a Noisemaker custom > effect (definition.json, GLSL and WGSL shaders) and the program (Polymorphic > DSL) that runs it. An agent can join the person's own open Shade over Seance, > the Noise Factor collaboration service: read, write and run the program and > the effect, look at the canvas, chat as the person does, and take over from > Shade's own model, answering every request of Shade's state machine itself. > This file is the contract for software agents that control Shade. The full contract adds a reference for every command and its arguments: https://shade.noisedeck.app/llms-full.txt The DSL and the effect format are specified by the Noisemaker contract: https://noisemaker.app/llms-full.txt. Foundry's contract collects Noisemaker's conventions for writing effects (looping, argument binding, dead branch pruning), each with its source: https://foundry.noisedeck.app/llms.txt For the roles and control paths of the other Noise Factor products, including Timeline's project-folder CLI and Layers' separate document, start from the platform guide at https://noisefactor.io/llms.txt. ## Connect to the person's Shade Use this route when you can run shell commands. It works with the Shade the person already has open: their program, their effect, their chat. 1. Ask the person to open https://shade.noisedeck.app, choose **connect agent...** at the end of the effect menu, click **Go Online**, then **Copy Prompt**, and paste the prompt to you. The prompt names this contract and the session link. (Without that dialog: **live collab...**, **Take Online**, then send the link or the six-character code.) 2. Get the agent tool. It needs Node 22.4 or later and nothing else: `curl -fsSLO https://noisedeck.app/agent/seance-agent.mjs` 3. Join: `node seance-agent.mjs join `. It prints the session name (`shade`), the open app tabs and the session documents. A background process keeps the session joined between commands. | Command | What it does | |---|---| | `node seance-agent.mjs commands` | Lists Shade's commands and their arguments. | | `node seance-agent.mjs program [--json]` | Prints the session's program text (`--json` adds its `rev`). | | `node seance-agent.mjs validate ` | Checks a program (`-` reads standard input). | | `node seance-agent.mjs set ` | Runs a program in the person's tab (setProgram). | | `node seance-agent.mjs look [--size N] [--format png\|jpg] [--out FILE]` | Saves an image of the person's canvas. Its path is `result.envelope.result.image.path`; open the file with your image tool. | | `node seance-agent.mjs call [JSON]` | Runs any command, for example `call nextRequest '{"waitSeconds":25}'`. | | `node seance-agent.mjs wait [--since REV] [--timeout S]` | Waits for the person to change the program, then prints it. `--doc effect` waits for a change to the custom effect instead. | | `node seance-agent.mjs image-put ` | Adds a PNG, JPEG, GIF or WebP file to the session. `result.ref` is its `image:`. | | `node seance-agent.mjs transfer ` | Copies the program and its images from one joined session to another, and its custom effect where the target takes one. | | `node seance-agent.mjs leave` / `stop` | Leaves the session / stops the background process. | Every command prints JSON, except `program` and `commands`, which print text (`--json` gives JSON). A result drops the state snapshot unless you add `--state`. The exit code is 0 for success, 1 when Shade refused the command (read `result.envelope.error.code`), and 2 when the tool could not run it (read `error.code`; the codes are listed below). `node seance-agent.mjs help` lists every option. `set` takes the effect too: `--args '{"effect":{...}}'`. Agent tool errors (exit code 2, `error.code`): - `NO_SESSION`: no session is joined, or more than one and none was named. - `UNKNOWN_SESSION`, `SESSION_LOCKED`, `REFUSED`: the session code is wrong or expired, the session is locked, or the session refused the join. - `NO_APP_TAB`: the tab that took the session online did not answer. Ask the person to keep it open, or to go online again and send the new code. - `TIMEOUT`: the tab did not answer in time. Check `status`, then try again. The tab runs at most eight of your commands at once and drops the others, which then end in `TIMEOUT`. - `READONLY`: the session lets this agent only read the program text: `program`, `wait` and `status` work, and every app command, `commands` and `look` included, is refused. Ask the person to allow guests to edit. - `SESSION_CLOSED`, `SESSION_REFUSED`: the connection closed, or the session server refused a request (the message says why). - `ISLAND`: a `transfer` to or from a Layers session. Layers shares nothing with the other apps. - `IMAGE_FAILED`, `NO_DOCUMENT`, `USAGE`, `INVALID_JSON`: an image transfer failed, a document is missing, or the command line was wrong. - `CONNECT_FAILED`, `RATE_LIMITED`: `join` could not reach the session server, or the server is limiting joins from this address. Wait a minute, then join again. - `INVALID_IMAGE`, `BAD_RESPONSE`: an image id is malformed, or the app sent an answer that the tool could not read. - `DAEMON_FAILED`, `INTERNAL_ERROR`: the tool's background process did not start, or the tool failed. If it happens again, run `stop` and join again. - A file that the tool cannot read gives the system's code, such as `ENOENT`. How it works, so you can explain it to the person: - The tool joins the session as an anonymous participant, which the person sees join, and the connect-agent dialog confirms it. It runs commands in the tab that took the work online, through the session, with the same paths as the person's own actions. No other tab answers, even one that becomes the session's owner after the person's tab leaves. - The session holds two documents: `main`, the program, and `effect`, the custom effect as Portable effect JSON (empty when there is none). Through the session, getProgram, listFiles and readFile answer from those documents. The person's chat history, account and credits stay in their tab. - Everyone in the session receives every answer, and anyone who can edit the session can send commands to that tab. So the chat history (`getChat`), the saved effects (`listSavedEffects`, `loadSavedEffect`, `saveEffect`, `deleteSavedEffect`), the ZIP download (`exportZip`) and `loadEffect`, which would replace the person's whole workspace with its images and undo history, answer `REMOTE_UNAVAILABLE` there, and `commands` marks them. Through a session, set an effect with `setProgram({ dsl, effect })` instead. A model request you take over carries the person's current work (their message, the effect, the rendered frame), and everyone in the session receives it too. Suggest that the person goes offline when you are done: **stop live collab** in the effect menu opens the session dialog, which has **Go Offline**. - Through a session, `sendMessage` and `answerAsk` work only after `takeOver` (`CONFLICT_NOT_DELEGATED` until then): otherwise Shade's own model would answer, on the person's credits. See "When Shade's own model answers" below. - `look` asks the tab for an image of its canvas as it is; the tab adds the image to the session as its own bytes, and the tool saves it as a file. A session holds at most 32 images; the tab takes at most 16 images in ten minutes (`IMAGE_LIMIT`, with `details.retryAfter` in seconds), and the images of `getRequestImage` count too. - Images travel only as bytes. The tab refuses any command whose arguments hold an image as base64 text (`IMAGE_AS_TEXT`) or name media by an outside link such as `url: "https://..."` (`OUTSIDE_LINK`), which would make the person's browser fetch it: a program, a file you write and an answer you give alike. Add the image with `image-put` and name it `media(url: "image:")`. ## Take over from Shade's agent `takeOver` makes you Shade's model for the runs you start. A run you start after `takeOver` (with `sendMessage`, or `answerAsk`) sends every model request it makes to you, from its first request to its end, instead of to Shade's model, and Shade applies your answer as it applies its model's: the same prompts, the same tool loops, the same parsing, the same transitions. Those requests do not call Shade's own model and spend none of the person's credits. The person sees the run as always: progress, tool calls, the "Does this look right?" question. The public Shade app runs its own agent mostly on open-weight models. A person who brings their own agent on a frontier model and has it take over may get better results. 1. `call takeOver`. 2. Start a run: `call sendMessage '{"text":"..."}'` (`intent` `create` makes or changes the effect; `ask` asks a question). A message while a run you started is running steers that run, as the person's would. 3. Loop: `call nextRequest '{"waitSeconds":25}'` returns the oldest request that waits for you, or `request: null` after the wait. Answer it with `call respond '{"id":"...","content":[...]}'`. Follow the run with `call getState` (`agent.state`, `agent.running`, `agent.asking`). 4. When `agent.asking` is true, Shade asks whether the effect looks right. `call answerAsk '{"approved":true}'` (or `false` with `feedback`, which starts the fix loop, with you). If the person answers instead, the rest of the run is theirs and goes on with Shade's own model. 5. `call handBack` ends the takeover. Going offline, the connection to Shade dropping, Shade restarting, or another tab of the person taking over end it too (`delegate.active` turns false). Then a run you started stops, as the Stop button stops it: the request that waited for you fails, and Shade's own model does not take the run over. To go on, `takeOver` again and start a new run. A run's tools change the program and the effect in the person's tab between your commands, under the person's name, so `wait` reports those changes as the person's. While a run you started goes on, follow it with `getState`. ### When Shade's own model answers Shade's own model answers, and the person's credits pay for it: - every run the person starts in their tab, even while you have taken over: a message typed in the chat (a question too, with the workspace files it sends), or an answer with the "Does this look right?" buttons; - every run started before `takeOver`, or after the takeover ended; - in the page (window.ShadeAgent, WebMCP), `sendMessage` and `answerAsk` without `takeOver`. Through a session you act only on runs you started under your current takeover. `sendMessage` and `answerAsk` without `takeOver`, `sendMessage` into any other run in progress, `answerAsk` on any other run's question, and `stopGeneration` of any other run are refused with `CONFLICT_NOT_DELEGATED`: you cannot make Shade's own model work, steer or answer its work, or stop it, on the person's credits. The person answers and stops those runs. A request is exactly what Shade's model would have received: ``` { id, endpoint, call, state, tier, model, stream, system, messages, tools, tool_choice, max_tokens, thinking, effort, temperature, images: [{ index, mimeType, bytes }] } // bytes: the image's size ``` - `endpoint` is the Shade route that asks (see the map below); `call` counts its requests; `state` is the state machine's state; `tier` is HAIKU, SONNET or OPUS, the size of model Shade chose for the work. The map gives the usual tier; Shade's model setup can change it, so read `tier` on each request. - `system` and `messages` are the prompt. Follow the system prompt as the model would: it says what to produce and in what form (a JSON array, a JSON plan, GLSL, a tool call). - An image in `messages` is `{ type: "image", source: { type: "delegate", index, media_type } }`. Fetch it with `call getRequestImage '{"id":"...","index":0}'`; the tool saves it as a file. - `tools` are the tools you may call; `tool_choice` `{ type: "tool", name }` forces one. A tool with a `type` (web_search) is run by Shade's model provider, not by Shade: do that research yourself and answer in text. - In a run you start through a session, the tab's tools change only the effect's files (`definition.json`, `help.md`, `glsl/*.glsl`, `wgsl/*.wgsl`): `create_effect` replaces those and keeps the person's other files, images and undo history, and `modify_file` and `replace_in_file` refuse any other file (`success: false`). An answer is the content blocks a model returns: `{ "type": "text", "text": "..." }` and `{ "type": "tool_use", "name": "...", "input": { ... } }` (an `id` is optional). Shade checks an answer as a model provider's API guarantees one: only text and tool_use blocks, only offered tools, the forced tool when tool_choice forces one. A refused answer fails with `INVALID_ANSWER`, and the request still waits for a good one. The next request of a tool loop carries your tool call and its result as `tool_result` blocks, as the model would see them. A request waits for your answer for as long as its route can stay open, and Shade waits ten minutes at most. In production a proxy sits in front of Shade: it closes a request that sends nothing for five minutes. A route that answers as an event stream sends a keepalive every 15 seconds while it waits for you; one that answers in JSON sends nothing until you answer. So answer, by `endpoint`, within: | Answer within | Endpoints | |---|---| | up to ten minutes | `/api/chat/answer-question`, `/api/chat/research`, `/api/chat/plan`, `/api/chat/generate`, `/api/chat/apply-fix`, `/api/chat/convert` | | five minutes | `/api/chat/classify-intent`, `/api/chat/understand`, `/api/chat/quick-fix`, `/api/chat/research-fix`, `/api/chat/plan-fix`, `/api/diagnose-vision/` | A request that runs out of time fails, and the run goes on as after a model timeout: its next request comes to you again. At most four requests wait for you at once; Shade refuses a fifth. `nextRequest`, `getRequestImage` and `respond` run at once, beside other commands; every other command runs in turn. ### Shade's state machine A run starts from the chat. With no effect in the workspace, `create` runs the creation loop; with one, it runs the iteration loop. A message typed during a run is classified, and a fix request jumps to DIAGNOSE. | State | What happens | Model requests (`endpoint`, `tier`) | |---|---|---| | (start) | Shade restates the request in one sentence | `/api/chat/understand`, HAIKU: one sentence that starts "So you want" | | RESEARCH | finds and studies reference effects | `/api/chat/research`: HAIKU, a JSON array of 3-5 search queries; then SONNET, a written synthesis that guides planning | | PLAN | designs the effect | `/api/chat/plan`, SONNET: a JSON generation plan | | GENERATE | writes the effect | `/api/chat/generate`: a tool loop that starts with `create_effect` (the effect's specification); the server then builds the GLSL stanza by stanza, one request per stanza and per repair, and the loop goes on to `compile_dsl` and `validate_effect` | | COMPILE | compiles the effect in the tab | `/api/chat/quick-fix`, SONNET, only after a compile error: the whole corrected GLSL | | VALIDATE | renders and checks the output in the tab | none | | ASK | waits for "Does this look right?" | none | | DIAGNOSE | looks at the output | `/api/diagnose-vision/`, HAIKU: a description of the rendered frame (image 0) and what is wrong | | RESEARCH_FIX | studies how to fix it | `/api/chat/research-fix`, SONNET: a written fix guide | | PLAN_FIX | plans the fix | `/api/chat/plan-fix`, SONNET: a JSON fix plan, `modifications: [{ action, file, oldCode, newCode, description }]` | | APPLY_FIX | applies it | `/api/chat/apply-fix`, OPUS: forced `replace_in_file` (or `modify_file`), then forced `compile_dsl`, then forced `validate_effect`; the tab runs each tool | | CONVERTING | ports GLSL to WGSL ("convert to WebGPU") | `/api/chat/convert` | | DONE, ERROR | the run ends | none | Creation loop: RESEARCH, PLAN, GENERATE, COMPILE, VALIDATE, ASK. Iteration loop: DIAGNOSE, RESEARCH_FIX, PLAN_FIX, APPLY_FIX, VALIDATE, ASK; a failed VALIDATE goes back to DIAGNOSE, up to ten times. During a run, a message is classified at `/api/chat/classify-intent` (HAIKU: JSON `{ intent, confidence, feedback, answer }`); an `ask` message goes to `/api/chat/answer-question`. ## Move work between apps Shade sessions use the same document dialect as Noisedeck, Polymorphic, Visualize and Foundry sessions, so `transfer` moves a program and its images between a Shade session and theirs, in either direction. The target app checks the program and refuses one that it cannot compile. `transfer` carries the custom effect too when the target's setProgram takes one, as Foundry and another Shade do (its result says `effect: "copied"`). Noisedeck, Polymorphic and Visualize take no custom effect through a session (`effect: "not taken by the target"`); the person can open the effect in Noisedeck or Polymorphic with effect > **edit in Noisedeck...** or **edit in Polymorphic...**. ## Control Shade in a browser you drive Use this route when you control a browser yourself and the person is signed in there with a Noisedeck membership: without it, the page and its files (`/js/agent/`, `/vendor/`) redirect to the sign-in page. Open https://shade.noisedeck.app and use the first route your browser tool supports: 1. WebMCP: discover the page tools named `shade_getState`, `shade_setProgram`, and so on. Each tool has the argument schema in the full contract and returns the envelope below as text. `getThumbnail`, `renderAt` and `getRequestImage` also return an image content block, without duplicating its bytes in text. 2. Page JavaScript: call `window.ShadeAgent` directly. Every command waits for startup automatically. Return the fields you need, not the whole API object. ```js const A = window.ShadeAgent await A.takeOver() await A.sendMessage({ text: 'a slow plasma in teal and gold' }) const { result } = await A.nextRequest({ waitSeconds: 25 }) return result.request && { id: result.request.id, endpoint: result.request.endpoint } ``` All routes use the same commands and validation. A browser with WebGL2 is required. --- ## Write a program and an effect yourself You do not need Shade's state machine to change the work: `setProgram` runs a program, with `effect` a custom effect too; `writeFile` changes one effect file as the code editor does; `getThumbnail` shows the result. Through a session, `listFiles` and `readFile` show only the effect's files and `dsl.txt`, so a file you write elsewhere answers `NOT_FOUND_FILE` when you read it back. Shade compiles as Run does and does not enforce Noisemaker's conventions; follow them anyway (https://foundry.noisedeck.app/llms.txt, "Noisemaker conventions"). ## Shader craft Discover this tab's available commands and argument schemas with `commands` or the browser's WebMCP catalog. `checkShader({ source, language })` checks GLSL or WGSL; `{ path: "glsl/.glsl" }` or `{ path: "wgsl/.wgsl" }` checks an existing visible shader. Supply exactly one source or path. Source text requires `language: "glsl" | "wgsl"`; a path supplies it from its extension. Findings are advisory `{ rule, severity, line, message }` entries with 1-based lines, not a proof of shader compilation or visual correctness. Retrieve only the references the effect needs. With shade-mcp, use `searchShaderKnowledge` with category `shader-craft` for the workflow, subject-routing, formulas, library references and examples; use `searchShaderLibrary` for exact GLSL/WGSL signatures. The same-origin module `/vendor/shade-mcp/knowledge/shader-craft.js` exports the pure checker, bundler, `searchShaderLibrary` and `getShaderCraftExample` for browser agents. Its paired effect examples include definitions, sources and credits. Read these on demand; do not paste the whole library into a prompt. The browser module comes from Shade's pinned shade-mcp release and runs locally; commands do not fetch the person's private files or reference video. Through a session, paths name only the shared effect, and offline tabs cannot answer session commands. (Source: the pinned shade-mcp knowledge module.) For the host-independent effect authoring workflow, follow https://noisemaker.app/llms-full.txt#portable-effect-authoring. `bundleShader` takes the same source/path/language inputs and returns self-contained source, added symbol IDs and technique credit keys. It adds referenced helpers and their dependency closure; caller definitions win. Use the library's exact signatures, including WGSL overload suffixes such as `fbm_f2i` and `sdBox_f3f3`. Keep the generated shader-skills MIT copyright and original technique-source comments. Missing caller-owned `map` or `ZERO` contracts are reported instead of invented: GLSL raymarch programs define `vec2 map(vec3 p)` and `ZERO` before the helpers; WGSL declares private `ZERO` and initializes it from its frame uniform in the entry point. Bundling writes only with an explicit shader `path` and `write: true`. The file remains written if compilation fails, and `compiled` reports the outcome, as with `writeFile`. (Source: shade-mcp shader-craft library conventions and bundler.) Build from the visual requirements, then verify silhouette, motion, material detail and lighting in renders. Use library PCG hashes instead of sine hashes. Keep lighting linear, then apply exposure, a chosen tonemapper, `linearToSrgb` and output dithering once. `time` is the normalized loop phase, not seconds; periodic terms must match across the seam. Each pass names its own program and inputs/outputs, and each program needs GLSL and WGSL sources. Use internal textures for intermediate or feedback passes. A bundled shader still needs compilation and equal-time rendered comparisons on both backends. (Source: shade-mcp `SHADER_CRAFT_WORKFLOW` and `shader-craft-rendering-pipeline`, adapted from shader-skills at `e09bc993bf04201f26c03c87c89210e9b472f526`.) Through a session, bundle writes, `renderAt`, `setLoopDuration`, `setBackend`, `play` and `pause` require the shared program and effect to be current and running in the tab. If unpublished work differs, `REMOTE_UNAVAILABLE` leaves it untouched. Explicitly apply the shared work with `setProgram` first. Source checks and non-writing bundles remain available. Loop duration and agent backend changes do not persist the person's preferences. Parameterize the primitives that make up the composition: expose relevant shape, position, scale, stretch, deformation, material and motion controls. Keep reference-matching defaults, with wide finite ranges that permit nonphysical combinations. Global brightness or speed controls do not replace primitive-level controls. Bind the same typed arguments in every shader implementation and inspect each control's intended effect independently. ## Recreate a reference video This workflow creates procedural interpretations of reference videos. It is not intended for photographic-quality reproductions. The person's external coding agent runs this workflow through the commands; Shade's own model does not run it. Inspect the supplied clip, measure its duration L, aspect ratio, cuts, objects and visible parts, colors, camera and motion. Sample its timeline, describe uncertain details and proposed omissions, and get approval for the breakdown in the conversation before building. Retrieve `shader-craft-video-to-effect` and the relevant craft references on demand. (Source: shade-mcp `SHADER_CRAFT_VIDEO_TO_EFFECT`.) Set `setLoopDuration({ seconds: L })` once. A frame at clip second s is `renderAt({ time: s / L, maxDimension: 1024, format: "png" })`. Finite `time` is between 0 and 1 inclusive. The command pauses, renders one fresh frame with zero elapsed simulation time, waits for GPU submission and returns its image. That frame stays paused; `play` resumes. Page JavaScript returns image bytes as base64; WebMCP returns an image content block; through Seance the Blob travels only as binary session image bytes. Use `setBackend` to repeat the same samples on WebGL2 and WebGPU. Develop composition and timeline, geometry and motion, materials and lighting, then detail. At each milestone compare rendered frames with the reference and correct the largest differences. Measure palette regions, subject size and beat timing. Inspect close-ups and frame sequences around transitions, contacts and the loop seam; stills do not verify motion. Keep pose, speed, camera and gait phase continuous. Analytic motion can be sampled at arbitrary times. Feedback textures depend on prior frames: `renderAt` does not reset or reconstruct their history, so verify them with sequences. Report measured performance; obtain approval before reducing the approved visual target. Keep the breakdown and evidence in the conversation. (Source: shade-mcp `SHADER_CRAFT_VIDEO_TO_EFFECT`, adapted from the same pinned shader-skills video workflow.) --- ## Keep results small - Every envelope includes `state`. Remove it when you do not need it; the agent tool removes it unless you add `--state`. - A model request is large: read `system` once per endpoint, then the messages. - In page JavaScript, image commands return base64 bytes; keep images small. ## The envelope ```js // success { ok: true, command: "setProgram", apiVersion: "1.0", result: { /* command-specific */ }, state: { /* snapshot */ }, warnings?: [ /* ... */ ] } // failure { ok: false, command: "setProgram", apiVersion: "1.0", error: { code: "INVALID_PROGRAM", message: "...", details: { diagnostics: [ /* ... */ ] } }, state: { /* snapshot */ } } ``` Every command rejects an argument that it does not declare, so a command with no arguments accepts only `{}`. Warnings do not stop a command: `IMAGE_MISSING` (the program names an `image:` that the tab does not have and the session does not hold) and `EFFECT_DEFINITION_INVALID` (definition.json is not valid JSON). ## State snapshot ``` state: { schemaVersion, program: { chars, running }, workspace: { name, files, effect, images }, // effect: the custom effect's func, or null compile: { ok, error? } | null, // the latest compile canvas: { width, height }, playback: { playing, loopDuration, time }, // time: rendered normalized phase, or null backend, // "webgl2" or "webgpu" agent: { state, running, asking }, // Shade's state machine; asking: "Does this look right?" is open delegate: { active, pending } // you have taken over; requests waiting for you } ``` ## Diagnostics `validateProgram` and a refused `setProgram` return Noisemaker compiler diagnostics, `{ code, severity, message, location? }`. A syntax error the parser throws has code `SYNTAX`. Diagnostics with severity `warning` do not stop a program. ## Error codes | Code | When | |---|---| | `INVALID_ARGS_TYPE` | wrong argument type | | `INVALID_ARGS_REQUIRED` | missing required argument | | `INVALID_ARGS_RANGE` | number, string length or list length out of range, or a path Shade cannot use | | `INVALID_ARGS_ENUM` | value not in the allowed list | | `INVALID_ARGS_UNKNOWN` | an argument that the command does not declare | | `INVALID_PROGRAM` | the program does not compile. `details.diagnostics` lists the errors when the compiler gave any. Nothing changed | | `INVALID_EFFECT` | `effect` is not a usable Portable effect (`details.field` names the field). Nothing changed | | `COMPILE_FAILED` | the renderer rejected a program that passed the compiler. The previous program and effect run again | | `INVALID_ANSWER` | an answer that a model provider's API would not return. The request still waits | | `NOT_FOUND_EFFECT` | unknown library effect, or no saved effect has that id | | `NOT_FOUND_FILE` | the workspace (or, through a session, the session) has no such file | | `NOT_FOUND_REQUEST` | no model request with that id waits for an answer | | `NOT_FOUND_IMAGE` | the request has no image with that index | | `NOT_FOUND_COMMAND` | the session asked for a command that Shade does not have | | `EFFECT_LOAD_FAILED` | an effect could not load from the shader CDN | | `BACKEND_UNAVAILABLE` | the browser cannot render with that backend | | `RENDER_FAILED` | the renderer did not produce the requested fresh frame | | `EXPORT_FAILED` | `exportZip`: the export request or the ZIP failed, and no ZIP was downloaded. `details.status` is the HTTP status when the request failed | | `CONFLICT_NOT_DELEGATED` | through a session, `sendMessage` or `answerAsk` before `takeOver`; or `sendMessage`, `answerAsk` or `stopGeneration` on a run you did not start under your current takeover | | `CONFLICT_BUSY` | Shade is still answering the last message | | `CONFLICT_NOT_ASKING` | `answerAsk` while Shade is not asking | | `CONFLICT_NOTHING_TO_EXPORT` | `exportZip` while the workspace has no files and no program | | `DELEGATE_CLOSED` | the takeover did not open, or ended (handed back, offline, or the connection to Shade closed) | | `REMOTE_UNAVAILABLE` | the command needs the person at the browser, or a session mutation would change unpublished local work | | `IMAGE_LIMIT` | the tab already took 16 images in ten minutes. `details.retryAfter` is in seconds | | `IMAGE_AS_TEXT` | a session request or answer would carry an image as base64 text. Add the image with `image-put` and use `image:` | | `OUTSIDE_LINK` | a session request names media by an outside link. Add the image with `image-put` and use `image:` | | `IMAGE_UPLOAD_FAILED` | the tab could not add an image to the session (the session holds up to 32 images) | | `INTERNAL_ERROR` | unexpected failure | --- ## Pointers - Full command reference: https://shade.noisedeck.app/llms-full.txt - DSL and effect contract: https://noisemaker.app/llms-full.txt - Noisemaker conventions: https://foundry.noisedeck.app/llms.txt - Agent tool: https://noisedeck.app/agent/seance-agent.mjs (`node seance-agent.mjs help`) - Platform guide: https://noisefactor.io/llms.txt - Source of truth in the page, behind sign-in: `/js/agent/index.js` (registration), `/js/agent/commands.js` (handlers), `/js/agent/delegate.js` (taking over), `/js/agent/schemas.js`, `/js/agent/descriptions.js`, `/js/agent/relay.js` (the session relay) --- ## Command reference Shade has 32 commands. Call a command as `await window.ShadeAgent.(args)`, or through a session as `node seance-agent.mjs call ''`. Every command rejects an argument that it does not declare, with `INVALID_ARGS_UNKNOWN`. ### Read state #### `getState` Returns the state snapshot. Every envelope already includes it in `state`. Returns: the snapshot. Arguments: none. #### `getProgram` Returns the program text (the workspace's dsl.txt), whether it is the program that runs, and the workspace's custom effect as a Portable effect, or null when the workspace has none. Through a Seance session both are what the session holds: its `main` and `effect` documents. Returns: `{ dsl, running, effect }`, where `effect` is `{ name, func, namespace, description, tags, globals, passes, ..., shaders: { : { glsl, wgsl } }, help }` or null. Arguments: none. ### Programs #### `validateProgram` Compiles `dsl` without applying it. With `effect`, the program is checked against that custom effect instead of the workspace's. Diagnostics come from the Noisemaker compiler; warnings do not stop a program. Returns: `{ valid, diagnostics }`. Arguments: - `dsl` (required): string, at least 1 character - `effect`: object #### `setProgram` Runs `dsl` in place of the current program and waits for its compile. With `effect` (a Portable effect, as getProgram returns it), that custom effect replaces the workspace's definition.json, shaders and help.md first, under the `user` namespace. A program with an error diagnostic changes nothing and fails with INVALID_PROGRAM; a program the renderer rejects restores the previous program and effect and fails with COMPILE_FAILED. The program compiles as Run compiles it. Returns: `{ applied: true, diagnostics }`; `warnings` lists any `image:` the tab does not have. Arguments: - `dsl` (required): string, at least 1 character - `effect`: object ### Workspace files #### `listFiles` Lists the workspace: its name, its files (definition.json, glsl/.glsl, wgsl/.wgsl, help.md, dsl.txt and any other file) and its images. Through a Seance session it lists only the files of the session's program and custom effect, and no images. Returns: `{ name, files: [{ path, chars }], images: [{ id, mimeType }] }`. Arguments: none. #### `readFile` Returns one workspace file. `dsl.txt` is the program. Through a Seance session only the files that getProgram returns can be read. Returns: `{ path, content }`. Arguments: - `path` (required): string, at least 1 character #### `writeFile` Writes one workspace file as the code editor does: the custom effect is registered again from definition.json and its shaders, and the program compiles. A file that does not compile stays written, as in the editor; `compiled` reports the error. Write the program itself with setProgram. The program compiles as Run compiles it. Returns: `{ path, chars, created, compiled: { success, error? } }`. Arguments: - `path` (required): string, at least 1 character - `content` (required): string #### `loadEffect` Copies a library effect into the workspace as a custom effect under the `user` namespace, like file > import effect from library...: its definition, GLSL and WGSL shaders and help become workspace files, and a program that uses it runs. `name` renames the copy. The workspace is replaced. Not through a session, where it would replace the person's whole workspace: its other files, its images and its undo history. Returns: `{ loaded: true, effectId, name, files, dsl, running }`. Not available through a session: it answers `REMOTE_UNAVAILABLE` there. Arguments: - `effectId` (required): string, at least 1 character - `name`: string, at least 1 character ### Saved effects #### `listSavedEffects` Lists the person's saved effect workspaces, newest first. Returns: `{ total, effects: [{ id, name, savedAt }] }`. Not available through a session: it answers `REMOTE_UNAVAILABLE` there. Arguments: none. #### `loadSavedEffect` Opens one of the person's saved effect workspaces in place of the current one, like the saved effects panel. Returns: `{ loaded: true, id, name, dsl, compiled }`. Not available through a session: it answers `REMOTE_UNAVAILABLE` there. Arguments: - `id` (required): string, at least 1 character #### `saveEffect` Saves the workspace and its images to the person's saved effects under `name`, like file > save effect workspace.... Every save is a new entry. Returns: `{ saved: true, id, name }`. Not available through a session: it answers `REMOTE_UNAVAILABLE` there. Arguments: - `name` (required): string, at least 1 character #### `deleteSavedEffect` Deletes one of the person's saved effect workspaces. Returns: `{ deleted: true, id, name }`. Not available through a session: it answers `REMOTE_UNAVAILABLE` there. Arguments: - `id` (required): string, at least 1 character ### Effects #### `searchEffects` Lists effects whose id, description or tags contain `query`: the library, and the workspace's custom effect as `user/`. `namespace` keeps one namespace. Returns: `{ total, effects: [{ effectId, namespace, name, description, tags }] }`. Arguments: - `query`: string - `namespace`: string - `limit`: integer, from 1 to 500, default `50` #### `getEffectDefinition` Returns the DSL function name and the parameters of one effect, including the workspace's `user/`. Returns: `{ effectId, func, namespace, description, params: [{ name, type, default, min?, max?, enum?, choices?, uniform?, label? }] }`. Arguments: - `effectId` (required): string, at least 1 character ### Playback #### `play` Starts the animation, like the play button. Through a session, requires the shared program and effect to be current in the tab. Returns: `{ playing }`. Arguments: none. #### `pause` Stops the animation. The current frame stays visible. Through a session, requires the shared program and effect to be current in the tab. Returns: `{ playing }`. Arguments: none. #### `renderAt` Pauses and renders one fresh frame at normalized time `time` (0..1 inclusive), with zero elapsed simulation time. Returns that frame as an image and leaves it paused. Does not reset feedback history. Through a session, requires the shared program and effect to be current in the tab; image bytes use the same binary path as getThumbnail. Returns: `{ time, playing: false, bytes, mimeType, width, height }` in the page; through a session, `image: { id, mimeType, bytes }` replaces base64 `bytes`, and `image.bytes` is the byte count. Arguments: - `time` (required): number, from 0 to 1 - `maxDimension`: integer, from 16 to 1024, default `256` - `format`: string, one of `png`, `jpg`, default `jpg` #### `setLoopDuration` Sets the loop length to finite positive `seconds` without changing the person's saved duration preference or the paused frame. Through a session, requires the shared program and effect to be current in the tab. Returns: `{ seconds }`. Arguments: - `seconds` (required): number, greater than 0 #### `setBackend` Renders with WebGL2 (GLSL) or WebGPU (WGSL), preserving playback and paused time without changing the person's saved preference. Through a session, requires the shared program and effect to be current in the tab. Fails with BACKEND_UNAVAILABLE when the browser cannot. Returns: `{ backend }`. Arguments: - `backend` (required): string, one of `webgl2`, `webgpu` ### Shader craft #### `checkShader` Checks GLSL or WGSL with the pinned local shader-craft checker. Supply exactly one `source` or existing shader `path`; source requires language, while a .glsl/.wgsl path supplies it. Findings are advisory and do not replace compilation. Through a session paths read only its shared effect. Returns: `{ language, advisory: true, findings: [{ rule, severity, line, message }] }`. Arguments: - `source`: string - `path`: string, at least 1 character - `language`: string, one of `glsl`, `wgsl` #### `bundleShader` Bundles referenced shader-craft helpers and their dependency closure, with credits. Uses the same source/path/language rules as checkShader. Changes no file unless `write: true` and a shader path are explicit. A write follows writeFile and reports compilation; through a session it requires the shared program and effect to be current in the tab. Missing caller-owned scene contracts are reported, not invented. Returns: `{ source, added, credits, language, written, compiled? }`. Arguments: - `source`: string - `path`: string, at least 1 character - `language`: string, one of `glsl`, `wgsl` - `write`: boolean, default `false` ### Images and files #### `getThumbnail` Returns an image of the canvas as the person sees it; it renders no extra frame. Through a Seance session the image is added to the session as its own bytes, and `image` replaces `bytes`. Returns: `{ bytes, mimeType, width, height }`, with `bytes` in base64. Through a session: `{ image: { id, mimeType, bytes }, mimeType, width, height }`, where `image.bytes` is the byte count. Arguments: - `maxDimension`: integer, from 16 to 1024, default `256` - `format`: string, one of `png`, `jpg`, default `jpg` #### `exportZip` Starts a browser download of the workspace as a ZIP, like file > download workspace files, and answers once Shade has built the ZIP and handed it to the browser. A workspace with no files and no program fails with CONFLICT_NOTHING_TO_EXPORT; an export request or ZIP that fails gives EXPORT_FAILED, and no ZIP is downloaded. Returns: `{ started: true, name }`. Not available through a session: it answers `REMOTE_UNAVAILABLE` there. Arguments: none. ### Shade's agent #### `sendMessage` Sends `text` from the chat box, as the person does: `create` makes or changes an effect (Shade's state machine starts, or the message joins the run as an interjection), `ask` asks a question. Returns as soon as the message is sent; follow the run with getState (`agent`). After takeOver, the run it starts answers to you to its end; without takeOver, Shade's own model answers, on the person's credits. Through a session it needs takeOver first, and answers CONFLICT_NOT_DELEGATED until then, and for a run the person started. Returns: `{ sent: true, intent, interjection }`, where `interjection` is true when a run was already going. Arguments: - `text` (required): string, at least 1 character - `intent`: string, one of `create`, `ask`, default `create` #### `answerAsk` Answers Shade's "Does this look right?" question, as its buttons do: `approved: true` finishes the run; false starts the fix loop with `feedback`, which answers to you after takeOver. Through a session it answers only the question of a run you started under your current takeover, and CONFLICT_NOT_DELEGATED otherwise: the person answers the others. Returns: `{ answered: true, approved }`. Arguments: - `approved` (required): boolean - `feedback`: string #### `stopGeneration` Stops the run in progress, like the Stop button. Through a session it stops only a run you started under your current takeover, and answers CONFLICT_NOT_DELEGATED for one the person started. Returns: `{ stopped }`, false when nothing was running. Arguments: none. #### `getChat` Returns the last messages of the person's chat with Shade. Returns: `{ total, messages: [{ role, content }] }`. Not available through a session: it answers `REMOTE_UNAVAILABLE` there. Arguments: - `limit`: integer, from 1 to 50, default `20` ### Take over from Shade's agent #### `takeOver` Lets you answer in place of Shade's model for the runs you start (sendMessage, answerAsk): every request such a run makes (each phase's system prompt, messages, tools and tool_choice) waits for your answer through nextRequest and respond, to the end of the run, and Shade applies your answers as it applies its own model's. Those requests do not call Shade's own model and spend no credits. Runs the person starts in their tab stay with Shade's own model. Returns: `{ active: true, pending }`. Arguments: none. #### `handBack` Ends the takeover. A run you started stops, as the Stop button stops it: a request that waits for you fails, and Shade's own model does not take the run over. Going offline, a dropped connection, or another tab taking over end the takeover the same way. Returns: `{ active: false, pending: 0 }`. Arguments: none. #### `nextRequest` Returns the oldest model request that waits for your answer, waiting up to `waitSeconds` for one. It returns the same request until you answer it. Runs at once, beside other commands. Returns: `{ active, pending, request }`, where `request` is `{ id, endpoint, call, state, tier, model, stream, system, messages, tools, tool_choice, max_tokens, thinking, effort, temperature, images: [{ index, mimeType, bytes }] }` or null. Arguments: - `waitSeconds`: integer, from 0 to 30, default `25` #### `getRequestImage` Returns an image a request's messages name as `{ type: "image", source: { type: "delegate", index } }`. Through a session it is added to the session as its own bytes. Runs at once. Returns: `{ id, index, mimeType, size, bytes }`, with `bytes` in base64. Through a session: `{ id, index, mimeType, size, image: { id, mimeType, bytes } }`. Arguments: - `id` (required): string, at least 1 character - `index` (required): integer, from 0 to 15 #### `respond` Answers a request with `content`, the content blocks a model would return: `{ type: "text", text }` and `{ type: "tool_use", name, input, id? }`. Shade checks them as a model provider's API guarantees them (only offered tools, the tool tool_choice forces, no provider-run tools) and fails with INVALID_ANSWER otherwise; the request then still waits. Runs at once. Returns: `{ accepted: true, id, active, pending }`. Arguments: - `id` (required): string, at least 1 character - `content` (required): array