Two small media jobs come up again and again in workflows. One is a contact sheet: a handful of images laid out on one page, so a person can compare them at a glance. The other is a narration: a short text turned into an audio file.
Before v0.124.0, those two jobs took an outside program: the release notes name exec magick montage for the sheet and exec /usr/bin/say for a narration with no API key. An exec: task needs permits.exec, the grant that lets a workflow start a program on the machine. That is a broad permission for a narrow job, and a reviewer has to read the command line to know what it really does.
The 0.124.0 release notes close both cases: "A contact sheet no longer needs exec magick montage." and "A narration no longer needs exec /usr/bin/say." The same release also lets an agent application hand the images it generates to the next task.
Images on one sheet #
nika:image_compose is a new built-in tool. It takes an ordered list of 1 to 64 PNG images and lays them out as a grid, a row or a column. Each image keeps its own size (scale: none, the default), is scaled to fit its cell with its aspect kept (fit), or is scaled and center-cropped to fill it (fill). gap, padding and background finish the page.
The language spec ships an example, image-compose-sheet.nika. Here it is without its header comment. It makes a duotone of two sample photos with nika:image_fx, then builds a side-by-side strip and a two-by-two sheet:
nika: image-compose-sheet
permits:
exec: false
tools: ["nika:image_compose", "nika:image_fx"]
fs:
# Exact files, read and written: the photos ship with the repo, and the
# sheet also reads back the two duotones this file writes.
read:
- "examples/fixtures/photos/harbour-02.png"
- "examples/fixtures/photos/sunset-01.png"
- "out/contact/harbour-duotone.png"
- "out/contact/sunset-duotone.png"
write:
- "out/contact/harbour-duotone.png"
- "out/contact/sheet.png"
- "out/contact/strip.png"
- "out/contact/sunset-duotone.png"
tasks:
sunset_duotone:
invoke:
tool: "nika:image_fx"
args:
input: "examples/fixtures/photos/sunset-01.png"
out: "out/contact/sunset-duotone.png"
ops: [ { duotone: { dark: "#10141c", light: "#f2c14e" } } ]
harbour_duotone:
invoke:
tool: "nika:image_fx"
args:
input: "examples/fixtures/photos/harbour-02.png"
out: "out/contact/harbour-duotone.png"
ops: [ { duotone: { dark: "#10141c", light: "#7fd1ff" } } ]
# Two photos side by side, each at its own size.
strip:
invoke:
tool: "nika:image_compose"
args:
inputs:
- "examples/fixtures/photos/sunset-01.png"
- "examples/fixtures/photos/harbour-02.png"
out: "out/contact/strip.png"
layout: row
gap: 4
background: "#10141c"
# The sheet reads the duotones, so it runs after both land.
sheet:
after: { sunset_duotone: success, harbour_duotone: success }
invoke:
tool: "nika:image_compose"
args:
inputs:
- "examples/fixtures/photos/sunset-01.png"
- "out/contact/sunset-duotone.png"
- "examples/fixtures/photos/harbour-02.png"
- "out/contact/harbour-duotone.png"
out: "out/contact/sheet.png"
scale: fit
cell: { width: 96, height: 64 }
gap: 4
padding: 8
background: "#10141c"
outputs:
strip:
value: ${{ tasks.strip.output }}
description: "The side-by-side receipt · path, sha256, width and height"
sheet:
value: ${{ tasks.sheet.output }}
description: "The contact-sheet receipt · path, sha256, width and height"Three properties matter here.
The work is pure. The standard library contract says the tool uses "NO provider, NO network, NO clock, NO keys". The changelog states the consequence: "the same input bytes and args give the same PNG bytes". The recipe that made the file (the contract tag image_compose/v1, each input's digest and size, the resolved layout) rides inside the PNG as a text chunk. The task's output carries the path, sha256, width and height, never the image bytes. In the contract's words, "re-render IS the tamper check".
Every input is a read and the sheet is a write. In the example, permits.fs.read names each photo and each duotone, permits.fs.write names each file the workflow writes, and exec is false. The contract says a static checker judges "each literal input path" as a read before anything runs; a templated list waits for the run's boundary.
The limits are checked before the pixels. Caps on each input's side, on the summed input pixels, on each scaled box and on the final canvas are judged from the PNG headers before any decompression, and fail NIKA-BUILTIN-IMAGE_COMPOSE-005.
A voice with no key #
nika:tts_generate already turned text into audio through a provider. v0.124.0 adds provider: system: the machine's own synthesizer, offline and with no key. On macOS that is /usr/bin/say. On Linux it is espeak-ng, found in an absolute directory of the engine's PATH.
The engine starts the program itself, as part of the built-in tool, with the text on standard input. So the workflow needs no permits.exec. The spec's conformance suite holds a valid fixture for exactly that point, 079-valid-tts-system-no-exec-grant: its permits: name the tool and a write grant for the audio folder, and nothing else.
The text is spoken as text. Both programs read [[ as the start of their own markup, and the changelog gives the example of [[volm 0]], which "would mute the file". The engine breaks every [[ with a space before the text reaches them. The audio is capped at 64 MiB and still lands under output_dir: through permits.fs.write. Every start is journaled as a permit_checked frame on the builtin plane.
The cost line stays honest. The output reports cost_usd: null with cost_unpriced: local_model, which the standard library describes as "local compute is unpriced, never free". The same release changed how a run under a spending cap treats paid images and speech: it bills them at dated public prices, and refuses a paid call the catalog cannot price. The keyless voice, the notes say, "bills no provider and runs under any cap as unpriced local work".
Images from an agent become values #
The third change concerns an agent: task that runs on an agent application such as Codex instead of an API model, the harness seat of The agent app asks before it acts. Such an application can generate images during its turn. Before, a workflow that wanted them asked the application to copy them into the project. The notes say Codex keeps its copies in ~/.codex/generated_images, "which every session shares".
Now the task can declare images:. Its .output becomes { message, images }, and each image carries index, path, sha256, size_bytes, mime_type, width and height. With images: { save: <path> }, Nika writes the received bytes itself through nika:write, inside permits.fs.write. The harness guide shows the shape as a fragment of a tasks: map:
banner:
agent:
prompt: "Draw a 16:9 release banner, no text"
images:
save: ./out/release/banner.png # optional
halftone:
with:
banner: ${{ tasks.banner.output.images[0].path }}
invoke:
tool: nika:image_fx
args: { input: "${{ with.banner }}", out: ./out/release/banner-halftone.png, ops: [{ halftone: {} }] }Only the bytes the application sent on this task's own session count. The path the application reports is never opened, so a task cannot pick up another session's image. A save with no image received fails NIKA-AGENT-007, instead of succeeding with no file.
Why it matters #
The first two remove an exec: from two everyday jobs. No exec: means no permits.exec, and a boundary that names files, tools and nothing else is easier to review. The contact sheet can be rebuilt from its inputs and compared byte for byte. The narration's cost is labelled for what it is. An agent's images enter the workflow with a digest, not as a path in a folder every session on the machine shares.
What it does not do #
nika:image_compose"reads PNG only" (0.124.0 notes): 8-bit gray, gray with alpha, RGB or RGBA, with no interlacing. A palette PNG or another format is refused (-003). Labels and JPEG input are not part of the first version of the contract.- The system voice needs macOS
sayor Linuxespeak-ng. On another operating system, or when the program is absent, the call failsNIKA-BUILTIN-TTS_GENERATE-002, with no fallback to another provider. A named voice must be installed on the host. - "only a Codex seat delivers images to
images:" (0.124.0 notes). On another application,images: { save: }receives nothing and failsNIKA-AGENT-007. On an API or local model,nika checkand the run refuseimages:. - A save writes at most four images, at
banner.png, thenbanner-2.pngup tobanner-4.png. - The notes also say it plainly: 0.124.0 makes no video.
Read the v0.124.0 release, the standard library page, or continue with Media are workflow citizens.