Log in

iii-core-primitives

All-time installs
4,869

Use when registering iii functions, binding triggers, observing functions, selecting sync/void/enqueue invocation, creating workers, inspecting the live worker registry, installing registry workers, authoring event sources, moving channel data, or adapting external HTTP functions across TypeScript, Python, and Rust.

Other options

Summary

Use when registering iii functions, binding triggers, observing functions, selecting sync/void/enqueue invocation, creating workers, inspecting the live worker registry, installing registry workers, authoring event sources, moving channel data, or adapting external HTTP functions across TypeScript, Python, and Rust.

Raw SKILL.md

12.1K bytes
---
name: iii-core-primitives
description: >-
  Use when registering iii functions, binding triggers, observing functions, selecting
  sync/void/enqueue invocation, creating workers, inspecting the live worker registry, installing
  registry workers, authoring event sources, moving channel data, or adapting external HTTP
  functions across TypeScript, Python, and Rust.
---

# Core Primitives

iii has three top-level primitives:

- **Function**: a named unit of work such as `orders::validate`
- **Trigger**: an event source bound to a function
- **Worker**: a process that connects to the engine and executes functions

Since 0.25 every function is also **observable**: `iii.observe(source, target)` invokes `target`
on each invocation of `source` that passes its filters. Observers replace trigger bindings over
time; the built-in providers (`http`, `cron`, queue, `state`, `stream`, pub/sub, database) still
use trigger types in 0.25, so keep `registerTrigger` for them. See `iii-observe`.

Use `::` in function IDs, leading slashes in HTTP `api_path`, and `expression` for cron config.

## Function Registration

Register local handlers when you control the implementation. Register HTTP-invoked functions when
iii should call an existing external endpoint.

| Shape | Use for |
| --- | --- |
| `registerFunction(id, handler, options?)` | Local worker code |
| `registerFunction(id, HttpInvocationConfig, options?)` | Existing HTTP services |
| `registerTrigger({ type, function_id, config, metadata? })` | Binding a built-in event source (deprecated in 0.25, still required for providers that have not migrated) |
| `observe({ function_id, args?, filters? }, target, options?)` | Running `target` after another function's invocations, or on an engine event (`iii-observe`) |
| `trigger({ function_id, payload, action?, timeout? })` | Calling any function by ID |

Functions and triggers can carry metadata for ownership, discovery, and generated skills. Do not put
secrets in metadata.

## Workers and Registry

A worker is any process that connects to the engine and registers functions or trigger types. There
are two common paths:

| Task | Use |
| --- | --- |
| Create your own worker | Write SDK code that calls `registerWorker`, `registerFunction`, and `registerTrigger` or `observe` |
| Add an existing capability | Browse `https://workers.iii.dev/`, then call `compose::add worker=<name>` |
| Pin a worker version | `compose::add worker=<name>@<version>` |
| Declare a local worker | Add `worker: path://./workers/my-worker` under `containers:` |
| Reproduce a project | Commit the exact versions in `worker-compose.yaml` |

The public worker registry at `workers.iii.dev` is for installable workers such as HTTP, state,
queue, pub/sub, cron, database, shell, console, rbac-proxy, and other capability workers.
(`iii-sandbox` and `iii-observability` are engine-owned and are not added through the registry.) Those workers may ship their own function-level skills; do not duplicate every capability
as a top-level iii skill.

### Worker Manifest

Use `iii.worker.yaml` when iii should start a local worker project:

```yaml
name: math-worker
runtime:
  kind: python
  package_manager: pip
  entry: math_worker.py
scripts:
  install: "pip install -r requirements.txt"
  start: "python math_worker.py"
```

The manifest describes how to start the process. Once running, the WebSocket connection and function
registrations are what make the worker part of iii.

### Live Engine Registry

The engine keeps a live registry of connected workers, registered functions, triggers, and trigger
types. Read it through the built-in discovery functions:

| Function | Returns |
| --- | --- |
| `engine::workers::list` | Connected workers and metrics |
| `engine::functions::list` | Registered functions |
| `engine::triggers::list` | Registered triggers |
| `engine::trigger-types::list` | Advertised trigger types and schemas |
| `engine::observers::list` | Observers you may see (`function_id`, `namespace`, `worker` filters) |

For topology changes, observe the engine-hosted sources `engine::on-workers-changed` or
`engine::on-functions-changed` with `deliver: 'input'` (see `iii-observe`). The older
`engine::workers-available` and `engine::functions-available` trigger types still fire.

## Built-In Trigger Shapes

The workers behind these types have not moved to source functions in 0.25, so bind them with
`registerTrigger`. Each call logs a one-time deprecation warning per process; it is informational
and the binding works as before. For `log`, the engine also hosts the `observability::on-log`
source (`iii-observe`).

| Trigger type | Registration config | Handler payload |
| --- | --- | --- |
| `http` | `{ api_path: "/orders/:id", http_method: "POST" }` | `{ query_params, path_params, headers, path, method, body }` |
| `cron` | `{ expression: "0 0 9 * * * *" }` | `{ trigger, job_id, scheduled_time, actual_time }` |
| `durable:subscriber` | `{ topic: "payments" }` | The queued message payload |
| `subscribe` | `{ topic: "orders.created" }` | The published event payload |
| `state` | `{ scope: "orders", key?: "order-123" }` | `{ event_type, scope, key, old_value, new_value }` |
| `stream` | `{ stream_name, group_id, item_id? }` | Stream event details |
| `log` | `{ level: "warn" }` | OpenTelemetry-style log data |

Add `condition_function_id` to built-in trigger config when the handler should only run if a boolean
condition function returns `true`. With `observe`, a condition you can state over the event becomes a
declarative filter; a condition that needs code stays on `registerTrigger` or moves into the target.

## Invocation Modes

| Mode | Shape | Use when |
| --- | --- | --- |
| Sync | `trigger({ function_id, payload })` | The caller needs the result |
| Void | `TriggerAction.Void()` | Optional side effect, no result needed |
| Enqueue | `TriggerAction.Enqueue({ queue })` | Reliable async work with queue policy |

Use enqueue for work that must complete with retries. Use void for analytics, notifications, and
other non-critical side effects.

## Namespaces

Every worker registers in a namespace: the `namespace` init option, else `III_NAMESPACE`, else the
engine's `default`. Compose sets `III_NAMESPACE` to its daemon's namespace for every worker it
starts, so all workers in one `worker-compose.yaml` share a namespace and call each other by bare
function id. Engine-owned functions (`engine::*`, `configuration::*`, `stream::*`) live in `default`;
`engine::*` resolves there implicitly, the others need `namespace: "default"` on the call from a
namespaced worker. Routing is strict and ids are never prefixed with a namespace. From the CLI,
`iii trigger -n <namespace> <function>` selects it. Details and per-language examples are in
`iii-sdk-reference`.

## Code Examples

### TypeScript

```typescript
import { registerWorker, TriggerAction } from "iii-sdk";

const iii = registerWorker("ws://localhost:49134", { workerName: "orders-worker" });

iii.registerFunction("orders::validate", async (order) => {
  if (!order.id) throw new Error("missing order id");
  return { ...order, valid: true };
});

iii.registerFunction("orders::process", async (order) => {
  const validated = await iii.trigger({ function_id: "orders::validate", payload: order });
  await iii.trigger({
    function_id: "orders::charge",
    payload: validated,
    action: TriggerAction.Enqueue({ queue: "payments" }),
  });
  return { accepted: true, orderId: validated.id };
});

iii.registerTrigger({
  type: "http",
  function_id: "orders::process",
  config: { api_path: "/orders", http_method: "POST" },
});
```

### Python

```python
from iii import register_worker

iii = register_worker("ws://localhost:49134")

def validate(order):
    if not order.get("id"):
        raise ValueError("missing order id")
    return {**order, "valid": True}

def process(order):
    validated = iii.trigger({"function_id": "orders::validate", "payload": order})
    iii.trigger({
        "function_id": "orders::charge",
        "payload": validated,
        "action": {"type": "enqueue", "queue": "payments"},
    })
    return {"accepted": True, "orderId": validated["id"]}

iii.register_function("orders::validate", validate)
iii.register_function("orders::process", process)
iii.register_trigger({
    "type": "http",
    "function_id": "orders::process",
    "config": {"api_path": "/orders", "http_method": "POST"},
})
```

### Rust

```rust
use iii_sdk::{register_worker, Error, InitOptions, RegisterFunction, TriggerAction};
use iii_sdk::protocol::{RegisterTriggerInput, TriggerRequest};
use serde_json::{json, Value};

let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());

iii.register_function("orders::validate", RegisterFunction::new(|order: Value| -> Result<Value, Error> {
    if order["id"].is_null() {
        return Err("missing order id".into());
    }
    Ok(json!({ "valid": true, "order": order }))
}));

let process_client = iii.clone();
iii.register_function("orders::process", RegisterFunction::new_async(move |order: Value| {
    let iii = process_client.clone();
    async move {
        let validated = iii.trigger(TriggerRequest::new("orders::validate", order)).await?;
        iii.trigger(TriggerRequest {
            function_id: "orders::charge".into(),
            payload: validated.clone(),
            action: Some(TriggerAction::Enqueue { queue: "payments".into() }),
            timeout_ms: None,
        }).await?;
        Ok::<_, Error>(json!({ "accepted": true, "order": validated }))
    }
}));

// Deprecated since 0.25 (the http worker still provides a trigger type): compiles with a warning.
#[allow(deprecated)]
iii.register_trigger(RegisterTriggerInput::new(
    "http",
    "orders::process",
    json!({ "api_path": "/orders", "http_method": "POST" }),
))?;
```

## Advanced Primitive Patterns

- **Custom event sources**: since 0.25, register a function with an `observe` descriptor
  (`delivery: 'owner'`, `args_format`, `onObserverAdded` / `onObserverRemoved`) and hand events to
  observers with `obs.emit` or `obs.call` (see `iii-observe`). `registerTriggerType({ id,
  description }, handler)` is deprecated: it still works and logs one warning per process. Keep
  listener setup in `registerTrigger` and cleanup in `unregisterTrigger` if you maintain one.
- **Channels**: use `createChannel()` for binary or streaming data that should not be serialized into
  JSON payloads. Pass `readerRef` or `writerRef` through a function payload.
- **HTTP-invoked functions**: use `HttpInvocationConfig` for legacy APIs, third-party endpoints, or
  immutable services. Use environment variable names for auth fields, not raw secrets.
- **Schemas**: Rust can derive request/response schemas with `schemars::JsonSchema`; Python can use
  type hints or Pydantic; Node can pass JSON Schema manually.

## When to Use

- Use this skill for function registration, trigger binding, trigger payload shapes, invocation mode
  decisions, worker creation, worker registry access, trigger conditions, custom trigger types,
  channels, and HTTP-invoked functions.
- Use it to decide between `registerTrigger` (built-in providers in 0.25) and `observe` (any
  function, engine events, migrated providers).
- Use this when a task spans TypeScript, Python, or Rust examples for the same iii primitive.

## Boundaries

- For `iii.observe`, filters, observable functions, local dispatch, and migrating off
  `registerTrigger` / `registerTriggerType`, use `iii-observe`.
- For engine ports, adapters, engine-owned workers, RBAC (`rbac-proxy`), and deployment config,
  use `iii-engine-config`.
- For SDK-specific package exports and language caveats, use `iii-sdk-reference`.
- For complete backend designs such as workflows, CQRS, agentic systems, and reactive apps, use
  `iii-architecture-patterns`.
- For failed invocations, timeouts, RBAC denials, and retryability, use `iii-error-handling`.
- Worker-backed capability details live with the worker docs, not as top-level iii skills.

Security audits

SnykPASS
SocketPASS
Gen Agent Trust HubPASS