iii-hq/iii

iii-core-primitives

Use when registering iii functions, calling them (call with sync, void, or enqueue), observing functions and event sources, creating workers, inspecting the live worker registry, installing registry workers, or moving channel data across TypeScript, Python,…

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/iii-hq/iii --skill iii-core-primitives

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

Core Primitive: the Function

iii has one primitive, the Function: a named unit of work such as orders::validate. There are two operators:

  • call: any worker runs a function now with call
  • observe: iii.observe(a, b): when a runs, b runs

Workers host functions. A worker is a process that connects to the engine, registers functions, and calls and observes them.

Everything is reactive. An HTTP request, a database write, a queue message, and a state change are each a call of a source function (http::on-request, database::on-row-changed, queue::on-message, state::on-changed), so observing that function is how work starts on the event. See iii-observe.

Use :: in function IDs, leading slashes in HTTP path args, and expression for cron args.

Function Registration

Register local handlers when you control the implementation. To call an existing external endpoint, register a handler that makes the HTTP call.

ShapeUse for
registerFunction(id, handler, options?)Local worker code
observe(source, target, options?)Running target when source runs: another function, an HTTP route, a database change, a queue topic, an engine event (iii-observe)
call({ function_id, payload, action?, timeoutMs? })Calling any function by ID

Functions and observers 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. There are two common paths:

TaskUse
Create your own workerWrite SDK code that calls registerWorker, registerFunction, call, and observe
Add an existing capabilityBrowse https://workers.iii.dev/, then call compose::add worker=<name>
Pin a worker versioncompose::add worker=<name>@<version>
Declare a local workerAdd worker: path://./workers/my-worker under containers:
Reproduce a projectCommit 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; the sandbox-libkrun adapter behind iii-sandbox is a registry worker that Compose installs.) 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, and observers. Read it through the built-in discovery functions:

FunctionReturns
engine::workers::listConnected workers and metrics
engine::functions::listRegistered functions, with args_format, private, observable, and observer_count
engine::observers::listObservers you may see (function_id, namespace, worker filters)

For topology changes, observe the engine-hosted sources engine::on-workers-changed, engine::on-functions-changed, or engine::on-observers-changed with capture: ['input']: the event is the payload's input (see iii-observe).

Built-In Sources

Capability workers host these source functions, and the engine hosts observability::on-log. Add the worker, then observe the function with the args it takes; iii-observe has the full table and the other engine-hosted sources.

Source functionargsWhat the target receives
http::on-request{ method: "POST", path: "/orders/:id", middleware_function_ids? }{ method, path, path_params, query_params, headers, body }; its result is the response { status_code, headers?, body? }
cron::on-tick{ expression: "0 0 9 * * * *" }The payload; input is { expression, scheduled_time, actual_time }
queue::on-message{ topic: "payments", max_retries?, backoff_ms?, group? }The published data; returning acks the message
state::on-changednone; filter on input.scope, input.keyThe payload; input is { event_type, scope, key, old_value, new_value }
database::on-row-changed{ db, table?, ops? }The payload; input is the row change
observability::on-lognone; filter on input.severity_text; from a namespaced worker, observe with namespace: "default"The payload; input is one log record

A condition you can state over the call (its input, output, error, caller, or metadata) is a filter on the observer. A condition that needs code goes in the target.

Invocation Modes

ModeShapeUse when
Synccall({ function_id, payload })The caller needs the result
VoidCallAction.Void()Optional side effect, no result needed
EnqueueCallAction.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::*, observability::*) live in default; engine::* and configuration::* resolve there implicitly, and observability::* needs namespace: "default" on the call or observer from a namespaced worker. Routing is strict and ids are never prefixed with a namespace. From the CLI, iii call -n <namespace> <function> selects it. Details and per-language examples are in iii-sdk-reference.

Code Examples

TypeScript

typescript
import { registerWorker, CallAction } 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 (req) => {
  const validated = await iii.call({ function_id: "orders::validate", payload: req.body });
  await iii.call({
    function_id: "orders::charge",
    payload: validated,
    action: CallAction.Enqueue({ queue: "payments" }),
  });
  return { status_code: 202, body: { accepted: true, orderId: validated.id } };
});

// POST /orders runs orders::process; its result is the HTTP response
iii.observe(
  { function_id: "http::on-request", args: { method: "POST", path: "/orders" } },
  "orders::process",
);

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(req):
    validated = iii.call({"function_id": "orders::validate", "payload": req["body"]})
    iii.call({
        "function_id": "orders::charge",
        "payload": validated,
        "action": {"type": "enqueue", "queue": "payments"},
    })
    return {"status_code": 202, "body": {"accepted": True, "orderId": validated["id"]}}

iii.register_function("orders::validate", validate)
iii.register_function("orders::process", process)
iii.observe(
    {"function_id": "http::on-request", "args": {"method": "POST", "path": "/orders"}},
    "orders::process",
)

Rust

rust
use iii_sdk::{register_worker, CallAction, Error, InitOptions, RegisterFunction, Source};
use iii_sdk::protocol::CallRequest;
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 |req: Value| {
    let iii = process_client.clone();
    async move {
        let validated = iii.call(CallRequest::new("orders::validate", req["body"].clone())).await?;
        iii.call(CallRequest {
            function_id: "orders::charge".into(),
            payload: validated.clone(),
            action: Some(CallAction::Enqueue { queue: "payments".into() }),
            timeout_ms: None,
        }).await?;
        Ok::<_, Error>(json!({ "status_code": 202, "body": { "accepted": true, "order": validated } }))
    }
}));

// POST /orders runs orders::process; its result is the HTTP response
iii.observe(
    Source::function("http::on-request").args(json!({ "method": "POST", "path": "/orders" })),
    "orders::process",
);

Advanced Primitive Patterns

  • Event sources: a worker turns events from outside iii into calls of a function it hosts,

registered with a handler that returns the event and { args_format, private: true }. It overrides iii's defaults with onObserverAdded (set up from obs.args), onObserverRemoved (tear down), onObservationMatch (which observers want each call), and onObservationDeliver (deliver each call itself and return what the caller gets). See iii-observe.

  • Channels: use createChannel() for binary or streaming data that should not be serialized into

JSON payloads. Pass readerRef or writerRef through a function payload.

  • External HTTP services: for third-party endpoints or services you cannot change, register a

handler that makes the HTTP call and keeps its secrets in the worker's environment.

  • 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, calling functions, invocation mode decisions, worker

creation, worker registry access, the built-in source functions and their args, and channels.

  • Use this when a task spans TypeScript, Python, or Rust examples for the same iii primitive.

Boundaries

  • For iii.observe options, filters, engine-hosted sources, observer hooks, event sources, and

local dispatch, 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.
같은 저장소의 Skills

더 많은 Skills

모든 Skills