Changelog

​

Register triggers from anywhere: engine::register_trigger + invocation metadata

​

Triggers survive reconnects and provider reloads

​

engine::functions::list results are relevance-ranked

​

engine::functions::info accepts batches

​

Live pending spans: traces show work in flight

​

Distributed traces: inbound tracestate honored, remote-parent traces visible

​

RabbitMQ priority queues

​

iii t — a shorthand for trigger

​

One iii.worker.yaml for the registry and the engine

​

Bundle workers: pick any rootfs, install dependencies at first boot

​

Compound scripts.start commands run correctly

​

Configuration: env placeholders in numeric fields, and a friendlier config directory

​

Docker projects start cleanly on Linux

​

exporter: both no longer strips the service name from OTLP spans

​

Node SDK: ChannelWriter reconnects after a dropped WebSocket

​

Worker configuration moves to ./config and edits apply in real time

workers:
  - name: configuration
    config:
      adapter:
        name: fs
        config:
          directory: ./config

​

SDK: a major, breaking reorganization of the public surface

​

Shared types extracted into @iii-dev/helpers

​

Cross-language parity: renames and removals

• Main client handle aligned to IIIClient (Node was ISdk, Rust was III).
• Telemetry config aligned to TelemetryOptions (Rust was WorkerTelemetryMeta).
• Buffered HTTP request and response renamed ApiRequest and ApiResponse to HttpRequest and HttpResponse; streaming keeps StreamRequest and StreamResponse. Rust StreamCallRequest and StreamJoinLeaveCallRequest become StreamChangeEvent and StreamJoinLeaveEvent.
• Stream helper type names aligned across the three SDKs: the change-event detail is StreamChangeEventDetail everywhere (Rust was StreamEventDetail, Node was an inline object), the result types are StreamSetResult / StreamUpdateResult / StreamDeleteResult (Rust had bare SetResult / UpdateResult, Node and Rust had a bare DeleteResult), and MergePath is now a named export in all three.
• Removed: UpdateBuilder, the Rust Value re-export, IIIForbiddenError and IIITimeoutError (Python), the TriggerActionType alias, the Rust FieldPath path helper, and the root Logger and OpenTelemetry re-exports (use @iii-dev/observability).

​

Submodule grouping

• errors (InvocationError, Error), channel, trigger, runtime: the first slice. The III prefix is dropped from the invocation error types. These keep their old root paths working as deprecated aliases. See the first slice.
• engine (EngineFunctions, EngineTriggers, RemoteFunctionHandler), protocol (the message and register-input types), internal (InternalHttpRequest), and Python utils (the format helpers): these move out of the root with the root export removed. IIIConnectionState (runtime) and TriggerActionVoid (Python trigger) likewise leave the root. See the submodule entry.

​

Compatibility

​

Observability moved into @iii-dev/helpers

​

Saving a file in a local overlay worker restarts cleanly the first time

​

config.yaml worker blocks are stripped once their value is persisted

​

Overlay workers boot on every architecture

​

Workers share one read-only rootfs instead of cloning it per worker

​

Local workers no longer leave empty dependency folders in your project

​

Overlay local workers boot reliably and pack large base images

• The host source share mounts reliably. In copy-in mode the host project is shared into the VM as a virtio-fs device that iii-init mounts right after the root pivot. virtio-fs device registration is asynchronous, so a mount issued too early could transiently fail — and because that share is boot-critical (the worker aborts when it isn’t mounted), it surfaced as an intermittent boot failure (/mnt/host-src … is not a virtiofs mountpoint). iii-init now retries each share mount for ~2s to ride out the device-probe race; a genuinely failed mount logs the cause instead of being silently swallowed.
• Large base images pack within bounded memory and file descriptors. Building the shared read-only base streams each file’s bytes through a single on-disk spool instead of holding the whole image in memory or keeping one open descriptor per file, so even a large base (the node image carries ~15k files) packs cleanly.

​

iii-pubsub runtime settings live in the configuration worker

​

iii-stream runtime settings live in the configuration worker

​

iii-cron runtime settings live in the configuration worker

​

iii-observability is fully configurable through the configuration worker

​

iii-queue runtime settings live in the configuration worker

​

iii.worker.yaml is validated before anything is installed

• Unknown keys are rejected — collected and sorted, so a manifest with several typos surfaces them all in one run:
  unknown key(s) in ./my-worker/iii.worker.yaml: [runtimee, scrpits].
  Supported fields are: name, description, runtime.base_image,
  scripts.(setup|install|start), env, dependencies, resources.(cpus|memory).
  
• Deprecated keys warn but still work (runtime.kind / package_manager / entry / language, top-level config / language / entry) — honored for now, scheduled for removal in a future version, with migration hints per key. Silence with III_NO_DEPRECATION_WARN=1.
• Shape errors read in plain English — runtime: node reports “runtime must be a mapping”, not serde’s “expected struct RuntimeSection”. A manifest missing name says so precisely instead of the false “No project manifest detected”.
• The same strict validation re-runs at start, with a 64 KiB size cap that defuses hostile (billion-laughs) or accidental multi-GB manifests before they are slurped into host memory.

​

Author → check → add: worker::validate and the manifest contract

• worker::validate dry-runs a manifest — inline string or host path — and returns { valid, name, errors, unknown_keys, deprecated_keys, warnings } without touching anything. valid: true means worker::add would accept it.
• worker::schema { function_id: "iii.worker.yaml" } serves the manifest’s JSON Schema (closed-world: every field described, unknown keys rejected) plus a ready-to-write hello-world bundle using the correct iii-sdk package — self-tested against our own validator so the example can never drift from the rules.

​

worker::status: one worker, full picture

​

Local-path workers: stop re-adding after code edits

​

worker add --force reruns install when dependencies change

​

W120 tells you when the lock holder is the daemon itself

​

worker::logs output is terminal-sanitized

​

iii-state runtime settings live in the configuration worker

​

OTLP observability exports work with TLS collectors

​

Hardening

• The VM UDP relay now writes a real pseudo-header checksum on response packets (strict guest stacks drop zero-checksum UDP), bounds payloads to the 16-bit IP length limit instead of silently truncating, and no longer injects empty frames into the guest’s rx ring.
• Shell frame readers (proto, client, relay) zero-initialize their buffers instead of using uninitialized memory before the socket read.

​

iii-http runtime settings live in the configuration worker

​

Nothing the engine started survives it — zombie-worker leak fixed

​

Daemon no longer panics when the engine dies with broken stdio

​

Live trace feed is tree-correct and lower-latency

​

Go SDK: connection-scoped replies no longer leak across reconnects

​

Conflicting HTTP routes are rejected instead of crashing the worker

Route 'GET users/:userId' conflicts with already-registered route 'GET users/:id':
routes with identical structure but different path-parameter names are not supported

​

HTTP trigger unregister is owner-aware

​

Install script retries transient download failures

​

worker::* management API is self-describing — and kind: "local" now works over the trigger

• Malformed worker::* payloads now return W105 (BadRequest) instead of W101 (InvalidSource). The envelope’s details.hint names the worker::schema call that returns the request schema. W101 and W102 are now reserved (documented but never emitted) — consumers matching W101 for malformed payloads should match W105.
• worker::* op failures now surface the W-code as the transport ErrorBody.code (previously the generic "invocation_failed", with the W-code only inside the message envelope). Consumers that matched code == "invocation_failed" to detect worker-op failures should match the W-code instead.

​

engine::triggers::info now exposes response_schema

{
  "id": "http",
  "configuration_schema": { "…": "route fields — path, method, middleware" },
  "request_schema": { "…": "envelope your handler receives" },
  "response_schema": {
    "properties": {
      "status_code": { "…": "HTTP status to send; defaults to 200 when omitted" },
      "headers": { "…": "{ \"Header-Name\": \"value\" } map or [\"Header-Name: value\"] strings" },
      "body": { "…": "serialized as JSON, text, or bytes per your Content-Type" }
    }
  },
  "instance_count": 1
}

​

SDK: inbound unregistertrigger for custom trigger types

​

What this fixes

• Unregistering a trigger bound to a custom trigger type now invokes the provider’s unregisterTrigger callback instead of leaving stale bindings server-side.
• When the provider worker reconnects, the engine re-sends registertrigger for existing bindings (unchanged); cleanup on consumer disconnect now correctly pairs with unregisterTrigger on the provider.

​

SDK surface trimming — deprecated and unused exports removed

​

Observability re-exports dropped (Node + Python)

// Node — before
import { Logger } from 'iii-sdk'
// after
import { Logger } from '@iii-dev/observability'

# Python — before
from iii import Logger, init_otel, with_span, OtelConfig
# after
from iii_observability import Logger, init_otel, with_span, OtelConfig

​

Rust SDK: crate-root re-exports and dead types removed

​

Node SDK: TriggerActionType alias removed

​

Python SDK: IIIForbiddenError / IIITimeoutError removed

# before
try:
    result = iii.trigger(...)
except IIITimeoutError:
    ...

# after
try:
    result = iii.trigger(...)
except IIIInvocationError as e:
    if e.code == "TIMEOUT":
        ...

​

Channel and stream helpers moved to a helpers submodule

// Node — before
const ch = iii.createChannel(bufferSize)
iii.createStream(name, stream)
// after
import { createChannel, createStream } from 'iii-sdk/helpers'
const ch = createChannel(iii, bufferSize)
createStream(iii, name, stream)

# Python — before
ch = iii.create_channel()
# after
from iii.helpers import create_channel, create_channel_async, create_stream
ch = create_channel(iii)

// Rust — before
let ch = iii.create_channel(buffer_size);
// after
let ch = iii_sdk::helpers::create_channel(&iii, buffer_size);

​

iii-worker warns when scripts.install is omitted

​

Observability: getTracer / getMeter / SpanKind dropped from the public Node API

• instrument with withSpan / initOtel, and
• import SpanKind from @opentelemetry/api directly.

// before
import { getTracer, SpanKind } from '@iii-dev/observability'
// after
import { SpanKind } from '@opentelemetry/api'
// (getTracer is internal — instrument via withSpan)

​

Stored logs are stripped of ANSI escape codes

​

Single register_function entry point in the Rust SDK

iii.register_function("greet", RegisterFunction::new(greet));
iii.register_function(
    "http::fetch",
    RegisterFunction::new_async(fetch).description("Fetches a URL"),
);
iii.register_function(
    "ext::lambda",
    RegisterFunction::http(http_config),
);

​

Logger and OpenTelemetry primitives moved to iii-observability

• flush_otel / flushOtel — force-flushes every provider without tearing OTel down. Use it before short-lived process exits where you still need pending spans, metrics, and logs delivered.
• execute_traced_request / executeTracedRequest — wraps an outgoing HTTP call (httpx in Python, fetch in Node) in an OTel CLIENT span. Injects W3C traceparent, records HTTP semantic-convention attributes, sets ERROR status on >= 400 responses, and records exceptions on network errors.

​

Migration

// Before (Node)
import { Logger, initOtel, withSpan } from 'iii-sdk'

// After (Node)
import { Logger, initOtel, withSpan } from '@iii-dev/observability'

# Before (Python)
from iii import Logger
from iii.telemetry import init_otel, with_span

# After (Python)
from iii_observability import Logger, init_otel, with_span

// Before (Rust)
use iii_sdk::{Logger, OtelConfig, init_otel, with_span, execute_traced_request};

// After (Rust)
use iii_observability::{Logger, OtelConfig, init_otel, with_span, execute_traced_request};

​

register_service removed from all SDKs

​

Unused telemetry accessors removed

• Node (iii-sdk): getTracer, getMeter, SpanStatusCode — import SpanStatusCode from @opentelemetry/api; tracer and meter are internal.
• Python (iii): get_tracer, get_meter, is_initialized are now private (_get_tracer, _get_meter, _is_initialized) — use the opentelemetry API directly.
• Rust (iii_sdk): the get_tracer, get_meter, is_initialized, SpanKind, and SpanStatus re-exports — obtain meters via opentelemetry::global::meter(...) and import SpanKind from opentelemetry::trace.

​

sandbox::run — one call from zero to result

# before (4 calls)
SB=$(iii trigger sandbox::create image=python | jq -r .sandbox_id)
iii trigger sandbox::fs::write sandbox_id="$SB" path=/workspace/run.py content='print(2+2)'
iii trigger sandbox::exec sandbox_id="$SB" cmd=python3 args='["/workspace/run.py"]'
iii trigger sandbox::stop sandbox_id="$SB"

# after (1 call)
iii trigger sandbox::run --json '{"image":"python","code":"print(2+2)"}'

​

sandbox::catalog::list

​

sandbox::exec and sandbox::create accept more input shapes

• cmd + args (classic POSIX)
• argv array
• shell-line cmd (shlex-split when args / argv are empty)

​

sandbox::fs::read returns inline bodies for small text

const { content, body } = await trigger({ function_id: 'sandbox::fs::read', payload: { sandbox_id, path } })
const text = body ?? await readChannel(content) // prefer inline body, fall back to stream

​

Structured sandbox::* errors with resubmittable fix payloads

{
  "code": "S211",
  "type": "FsParentNotFound",
  "message": "parent directory /workspace/a/b does not exist",
  "docs_url": "https://github.com/iii-hq/iii/.../README.md#S211",
  "retryable": false,
  "fix": { "parents": true },
  "fix_note": "merge `fix` into the original request and resubmit: `parents: true` auto-creates missing intermediate directories"
}

• docs_url anchors directly at the in-repo S-code subsection. Breaking: the base URL flipped from https://iii.dev/docs/errors/sandbox/Sxxx to https://github.com/iii-hq/iii/blob/main/crates/iii-worker/src/sandbox_daemon/README.md#Sxxx while the canonical iii.dev error pages are still pending. Bookmarks and scrapers built on the old URL need to follow the new anchors.
• fix is a non-null JSON payload the agent can merge into the original request and resubmit verbatim when recovery is unambiguous (parent-missing writes, sandbox::run sub-step failures, etc.).
• fix_note describes how to use the fix or — when fix is null — explains why no auto-recovery exists.
• sandbox::run sub-step failures surface the inner S-code transparently and name the failing step in fix.context, plus fix.sandbox_id when keep_sandbox: true.
• FS error message strings now carry a kind prefix (e.g. "file not found: {path}" instead of bare {path}). The authoritative code / type fields are unchanged; only callers that grep the message text are affected.

​

sandbox::exec default timeout raised to 5 minutes

​

Handler-boundary tracing on every sandbox::* handler

​

Telemetry re-exports removed from public SDK surface

​

Migration

• For custom spans, prefer withSpan / with_span / run_in_span. These preserve trace context.
• To obtain a tracer or meter directly, depend on @opentelemetry/api (Node) or the opentelemetry crate / Python package and call its accessors. Rust users can also keep using iii::telemetry::get_tracer / iii::telemetry::get_meter.

// Before (Node)
import { getTracer, getMeter, SpanStatusCode } from 'iii-sdk/telemetry'

// After (Node)
import { trace, metrics, SpanStatusCode } from '@opentelemetry/api'
const tracer = trace.getTracer('my-service')
const meter = metrics.getMeter('my-service')

// Before (Rust)
use iii::{get_tracer, get_meter, SpanKind, SpanStatus};

// After (Rust)
use opentelemetry::global;
use opentelemetry::trace::{SpanKind, Status};
let meter = global::meter("my-service");

# Before (Python)
from iii.telemetry import get_tracer, get_meter, is_initialized

# After (Python)
from opentelemetry import trace, metrics
tracer = trace.get_tracer("my-service")
meter = metrics.get_meter("my-service")

​

iii sandbox subcommand removed

# before
iii sandbox create python --idle-timeout 300
iii sandbox exec "$SB" -- python3 -c 'print(2+2)'
iii sandbox stop "$SB"

# after
SB=$(iii trigger sandbox::create image=python idle_timeout_secs=300 | jq -r .sandbox_id)
iii trigger sandbox::exec sandbox_id="$SB" cmd=python3 args='["-c","print(2+2)"]'
iii trigger sandbox::stop sandbox_id="$SB"

​

iii trigger reshape

# kv form
iii trigger orders::process amount=149.99 currency=USD

# JSON form
iii trigger orders::process --json '{"amount": 149.99, "currency": "USD"}'

# Combined: --json is the base, kv overrides individual keys
iii trigger orders::process --json '{"amount": 100}' amount=149.99

​

iii update --list-targets

​

Migrating from Motia

​

SDK discovery wrappers removed

• listFunctions / list_functions / list_functions_async
• listWorkers / list_workers / list_workers_async
• listTriggers / list_triggers / list_triggers_async
• listTriggerTypes / list_trigger_types / list_trigger_types_async
• onFunctionsAvailable / on_functions_available

​

Worker RBAC

​

Trigger format, validation, and metadata

​

Browser SDK

​

Sandbox and Container Workers

​

iii worker exec

​

Reproducible worker installs

​

Topic-based fan-out queues

// Before
registerTrigger({ type: 'queue', function_id: 'my::handler', config: { topic: 'order.created' } })
trigger({ function_id: 'enqueue', payload: { topic: 'order.created', data } })

// After
registerTrigger({ type: 'durable:subscriber', function_id: 'my::handler', config: { topic: 'order.created' } })
trigger({ function_id: 'iii::durable::publish', payload: { topic: 'order.created', data } })

​

Node SDK: registerFunction signature change

// Before
registerFunction({ id: 'function-id' }, handler)

// After
registerFunction('function-id', handler, {})

​

Everything is a worker

• Config YAML — modules: top-level key renamed to workers:, class: field renamed to name: with short identifiers.
• Rust API — Module trait → Worker, register_module! → register_worker!, EngineBuilder::add_module() → add_worker().
• Adapter IDs — changed from long Rust-style paths to short names: kv, redis, builtin, rabbitmq, local, bridge.