iii / worker
$worker

iii-directory

v0.5.2

Engine introspection (functions / triggers / workers), workers registry proxy, and filesystem-backed skill + prompt reader.

  • macOS: arm64 · x64
  • Linux: arm64 · armv7 · x64
  • Windows: arm64 · x64 · x86

functions

16

directory::prompts::list

function

List filesystem-backed prompts (name, description, modified_at) from skills_folder.

request
empty object
response
  • promptsobject[]required
    • descriptionstringrequired
    • modified_atstringrequired

      File mtime as RFC 3339.

    • namestringrequired

directory::skills::download

function

Download skills + prompts into skills_folder. Pass {repo, skill, branch?} to clone a single skill folder from a GitHub repo (git clone --depth 1 --branch <branch>; branch defaults to "main"), or {worker, version?|tag?} to pull from the workers registry (defaults to tag="latest" when neither version nor tag is given). Files in the destination namespace are overwritten file-by-file.

request
  • branchstring

    Source A: branch to clone. Defaults to `"main"`. Pass `"master"` (or any other branch name) for repos whose default branch is not `main`.

  • repostring

    Source A: GitHub repo URL. Pair with `skill`.

  • skillstring

    Source A: subfolder under `skills/` inside the repo. Doubles as the destination namespace inside `skills_folder`.

  • tagstring

    Source B: registry tag to pull (e.g. `latest`). Mutually exclusive with `version`. Defaults to `"latest"` when neither `version` nor `tag` is provided.

  • versionstring

    Source B: explicit semver to pull. Mutually exclusive with `tag`.

  • workerstring

    Source B: workers registry name. Pair with exactly one of `version` / `tag`.

response
  • namespacestringrequired
  • prompts_writtenstring[]required
  • skills_writtenstring[]required
  • sourceunknownrequired

directory::prompts::get

function

Fetch one filesystem-backed prompt by name. Returns the raw markdown body plus name, description, and modified_at — no envelope, no templating.

request
  • namestringrequired
response
  • bodystringrequired

    Raw markdown body (post-frontmatter) from disk.

  • descriptionstringrequired
  • modified_atstringrequired

    File mtime as RFC 3339.

  • namestringrequired

directory::registry::workers::list

function

List workers from the public registry (api.workers.iii.dev). Optional free-text `search` is matched fuzzily by the registry; omit it to browse by `total_downloads DESC`. Pagination is cursor-based with a server-authored page size — pass back `pagination.next_cursor` as `cursor` to fetch the next page. Shares the core `name` / `description` / `version` fields with directory::engine::workers::list. Results are cached for `registry_cache_ttl_ms` (default 60s).

request
  • cursorstring

    Opaque cursor returned by a previous call's `pagination.next_cursor`. Pass back verbatim to fetch the next page; omit (or pass `null`) to fetch the first page.

  • searchstring

    Optional free-text query. Forwarded to the registry as `?search=…`; the registry ranks results by `pg_trgm` similarity against `lower(name)` and `lower(description)`. When omitted, results are ordered by `total_downloads DESC`.

response
  • paginationobjectrequired

    Pagination envelope returned alongside a worker-list page. Mirrors the OpenAPI `Pagination` schema.

    • has_moreboolean
    • next_cursorstring

      Opaque cursor for the next page. `null` on the last page.

    • page_sizeinteger· uint32min 0

      Server-authored page size. The client cannot override this.

  • workersobject[]required
    • authorany of
      any of (2)
      variant 1
      • namestring
      • pfpstring

        Profile picture URL. `null` when the author hasn't uploaded one.

      • verifiedboolean
      variant 2
      valuenull
    • configunknown

      Free-form runtime configuration block from the publish payload.

    • dependenciesobject[]
      • namestringrequired
      • versionstringrequired
    • descriptionstring
    • imagestring

      Container image tag, populated only for `type=image` workers.

    • namestringrequired
    • repostring
    • supported_targetsstring[]
    • total_downloadsinteger· uint64min 0
    • typestring

      Worker kind — `binary`, `image`, or `engine`.

    • versionstring

      Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).

directory::engine::workers::list

function

List every worker currently connected to the engine. Filter by name substring, runtime, or status. Same row shape as directory::registry::workers::list so callers learn one envelope.

request
  • runtimestring

    Exact runtime match (e.g. `"rust"`, `"node"`).

  • searchstring

    Case-insensitive substring match against `name`.

  • statusstring

    Exact status match (e.g. `"connected"`).

response
  • workersobject[]required
    • active_invocationsinteger· uintrequiredmin 0
    • connected_at_msinteger· uint64requiredmin 0
    • descriptionstring

      Engine-side workers carry no description; field present for shape parity with `registry::Worker.description`. Always `None`.

    • function_countinteger· uintrequiredmin 0
    • idstringrequired

      Engine-assigned connection id (directory-specific).

    • ip_addressstring
    • isolationstring
    • namestring

      Worker name as registered with the engine.

    • osstring
    • runtimestring
    • statusstringrequired

      Connection state (e.g. `"connected"`, `"disconnected"`).

    • versionstring

      Worker version string from the worker's published manifest.

directory::registry::workers::info

function

Fetch full registry metadata for one worker: worker envelope (same core fields as directory::engine::workers::info plus registry-only `type` / `config` / `supported_targets` / `total_downloads` / `dependencies` / `image`), readme, full API reference (functions + triggers schemas), and the tree of skill / prompt file paths fetched from the registry's /w/{slug}/skills endpoint. Pass either `version` or `tag` (defaults to tag="latest"). Results are cached for `registry_cache_ttl_ms`.

request
  • namestringrequired

    Worker name in the registry (e.g. `"resend"`).

  • tagstring
  • versionstring

    Mutually exclusive with `tag`. If neither is provided we fall back to `tag: "latest"`.

response
  • api_referenceobjectrequired
    • functionsobject[]
      • descriptionstring
      • metadataunknown
      • namestringrequired
      • request_schemaunknown
      • response_schemaunknown
    • triggersobject[]
      • descriptionstring
      • invocation_schemaunknown
      • metadataunknown
      • namestringrequired
      • return_schemaunknown
  • readmestring
  • skills_treeobjectrequired
    • promptsobject[]
      • descriptionstring
      • namestringrequired
    • skillsobject[]
      • pathstringrequired
  • workerall ofrequired

    Same shape as `directory::registry::workers::list` rows (and `directory::engine::workers::info.worker`).

    all of (1)
    variant 1
    • authorany of
      … expand 2 nested
      any of (2)
      variant 1
      • namestring
      • pfpstring

        Profile picture URL. `null` when the author hasn't uploaded one.

      • verifiedboolean
      variant 2
      valuenull
    • configunknown

      Free-form runtime configuration block from the publish payload.

    • dependenciesobject[]
      … expand 2 nested
      • namestringrequired
      • versionstringrequired
    • descriptionstring
    • imagestring

      Container image tag, populated only for `type=image` workers.

    • namestringrequired
    • repostring
    • supported_targetsstring[]
    • total_downloadsinteger· uint64min 0
    • typestring

      Worker kind — `binary`, `image`, or `engine`.

    • versionstring

      Latest published version (worker-list) or the resolved version (worker-info, when called with `version` / `tag`).

directory::engine::registered-triggers::info

function

Full denormalized detail for one registered trigger: instance config + trigger-type detail + function detail.

request
  • idstringrequired
response
  • configunknownrequired
  • functionany of

    Full function detail for `function_id`. `None` if the function has been unregistered between calls.

    any of (2)
    variant 1
    • descriptionstring
    • function_idstringrequired
    • how_guideany of
      … expand 2 nested
      any of (2)
      variant 1
      • bodystringrequired
      • skill_idstringrequired
      • titlestringrequired
      variant 2
      valuenull
    • metadataunknown
    • registered_triggersobject[]required
      … expand 3 nested
      • configunknownrequired
      • idstringrequired
      • trigger_typestringrequired
    • related_skillsobject[]required

      Other skills (any `type`) that mention this function via either the literal `function_id` or the `iii://fn/<dotted/path>` URI. Body content is omitted; fetch on demand via `directory::skills::get`.

      … expand 2 nested
      • skill_idstringrequired
      • titlestringrequired
    • request_schemaunknown
    • response_schemaunknown
    • worker_namestring
    variant 2
    valuenull
  • function_idstringrequired
  • idstringrequired
  • metadataunknown
  • triggerany of

    Full trigger-type detail for `trigger_type`. `None` if the type has been unregistered between calls.

    any of (2)
    variant 1
    • configuration_schemaunknown

      SDK 0.11.3 surfaces a single `trigger_request_format` that doubles as the per-instance configuration shape; expose it explicitly so callers don't have to know the alias.

    • descriptionstringrequired
    • idstringrequired
    • instance_countinteger· uintrequiredmin 0
    • return_schemaunknown
    • worker_namestring
    variant 2
    valuenull
  • trigger_typestringrequired
  • worker_namestring

directory::skills::list

function

List filesystem-backed skills (id, title, type, description, bytes, modified_at) from skills_folder. `title` prefers the YAML frontmatter `title:` over the body H1, `type` is lifted from frontmatter `type:`, and `description` is the first paragraph of the body — so consumers can render a picker or indented index without one get per row.

request
empty object
response
  • skillsobject[]required
    • bytesinteger· uintrequiredmin 0
    • descriptionstringrequired

      First paragraph of the body, empty when the file has only headings.

    • idstringrequired
    • modified_atstringrequired

      File mtime as RFC 3339 (best effort; empty if unavailable).

    • titlestringrequired

      Frontmatter `title:` when present and non-empty, otherwise the first `# H1` line in the body, otherwise the bare `id`.

    • typestring

      Frontmatter `type:` (e.g. `index`, `how-to`, `reference`). `null` when the file has no frontmatter or omits the key.

directory::engine::functions::list

function

List every function registered with the engine. Filter by free-text search, namespace prefix, and/or worker name.

request
  • prefixstring

    Exact prefix match on `function_id` (e.g. `"mem::"`).

  • searchstring

    Case-insensitive substring match against `function_id` and `description`.

  • workerstring

    Exact worker-name match (the worker that registered the function).

response
  • functionsobject[]required
    • descriptionstring
    • function_idstringrequired
    • worker_namestring

      Worker that registered it (resolved via `WorkerInfo.functions[]`), or the first `::` segment of `function_id` as fallback.

directory::engine::workers::info

function

Worker envelope plus the lists of functions, trigger types, and registered triggers it owns. The `worker` field has the same shape as directory::registry::workers::info so callers can switch between local + registry surfaces with the same parser.

request
  • namestringrequired
response
  • functionsobject[]required
    • descriptionstring
    • function_idstringrequired
  • registered_triggersobject[]required
    • function_idstringrequired
    • idstringrequired
    • trigger_typestringrequired
  • trigger_typesobject[]required
    • descriptionstringrequired
    • idstringrequired
  • workerall ofrequired

    Same shape as `worker-list` rows (and `registry::worker-info.worker`).

    all of (1)
    variant 1
    • active_invocationsinteger· uintrequiredmin 0
    • connected_at_msinteger· uint64requiredmin 0
    • descriptionstring

      Engine-side workers carry no description; field present for shape parity with `registry::Worker.description`. Always `None`.

    • function_countinteger· uintrequiredmin 0
    • idstringrequired

      Engine-assigned connection id (directory-specific).

    • ip_addressstring
    • isolationstring
    • namestring

      Worker name as registered with the engine.

    • osstring
    • runtimestring
    • statusstringrequired

      Connection state (e.g. `"connected"`, `"disconnected"`).

    • versionstring

      Worker version string from the worker's published manifest.

directory::skills::index

function

Render one short markdown entry per installed worker (skills with frontmatter `type: index`). Each entry is a `## <worker title>` heading, the first paragraph of the worker's overview, and a `Read iii://<ns>/index` line the agent can follow via `directory::skills::get` for the full reference. Token-light by design; for per-skill rows use `directory::skills::list`.

request
empty object
response
  • bodystringrequired

    Rendered markdown document — one short `## <title>` block per installed worker (skills with frontmatter `type: index`), carrying the worker's first-paragraph overview and a read-more link pointing at `iii://<ns>/index`. Sorted lex by id.

  • workers_countinteger· uintrequiredmin 0

    Number of worker entries rendered (i.e. the count of `type: index` skills that survived the filter). Cheap sanity check that doesn't require re-parsing the body.

directory::skills::get

function

Fetch one filesystem-backed skill by id. Returns the raw markdown body plus id, title, type, description, and modified_at — same flat shape as directory::prompts::get with `type` lifted from the YAML frontmatter and `title` preferring frontmatter over the body H1. Accepts a bare id (e.g. "directory/skills/list") or the same id prefixed with iii://.

request
  • idstringrequired

    Skill id (the same string returned by `directory::skills::list`, e.g. `"directory/skills/list"`). The legacy `iii://{id}` form is also accepted for ergonomics; the prefix is stripped before validation. Other URI schemes are rejected.

response
  • bodystringrequired

    Raw markdown body (post-frontmatter) from disk.

  • descriptionstringrequired
  • idstringrequired
  • modified_atstringrequired

    File mtime as RFC 3339.

  • titlestringrequired

    Frontmatter `title:` when present and non-empty, otherwise the first `# H1` line in the body, otherwise the bare `id`.

  • typestring

    Frontmatter `type:` (e.g. `index`, `how-to`, `reference`). `null` when the file has no frontmatter or omits the key.

directory::engine::triggers::info

function

Full detail for one trigger type: configuration schema, return schema, owning worker, and current instance count.

request
  • idstringrequired
response
  • configuration_schemaunknown

    SDK 0.11.3 surfaces a single `trigger_request_format` that doubles as the per-instance configuration shape; expose it explicitly so callers don't have to know the alias.

  • descriptionstringrequired
  • idstringrequired
  • instance_countinteger· uintrequiredmin 0
  • return_schemaunknown
  • worker_namestring

directory::engine::triggers::list

function

List every trigger TYPE registered with the engine. Filter by search, prefix, worker. (For registered trigger instances, use directory::engine::registered-triggers::list.)

request
  • prefixstring
  • searchstring
  • workerstring
response
  • triggersobject[]required
    • descriptionstringrequired
    • idstringrequired
    • worker_namestring

directory::engine::registered-triggers::list

function

List registered trigger instances (the link rows between trigger types and target functions). Filter by trigger_type, function_id, worker, or free-text search.

request
  • function_idstring
  • searchstring
  • trigger_typestring
  • workerstring
response
  • registered_triggersobject[]required
    • config_summarystringrequired

      Truncated (~80 chars) JSON preview of `config` so listings stay scannable. Use `directory::registered-trigger-info` for the full payload.

    • function_idstringrequired
    • idstringrequired
    • trigger_typestringrequired
    • worker_namestring

directory::engine::functions::info

function

Full detail for one function: schemas, owning worker, registered triggers that target it, and any matching how-to skill from skills_folder.

request
  • function_idstringrequired
response
  • descriptionstring
  • function_idstringrequired
  • how_guideany of
    any of (2)
    variant 1
    • bodystringrequired
    • skill_idstringrequired
    • titlestringrequired
    variant 2
    valuenull
  • metadataunknown
  • registered_triggersobject[]required
    • configunknownrequired
    • idstringrequired
    • trigger_typestringrequired
  • related_skillsobject[]required

    Other skills (any `type`) that mention this function via either the literal `function_id` or the `iii://fn/<dotted/path>` URI. Body content is omitted; fetch on demand via `directory::skills::get`.

    • skill_idstringrequired
    • titlestringrequired
  • request_schemaunknown
  • response_schemaunknown
  • worker_namestring

triggers

2

directory::prompts::on-change

trigger

Fires after every successful directory::skills::download that wrote at least one prompt markdown file.

invocation
valueunknown
return
valueunknown

directory::skills::on-change

trigger

Fires after every successful directory::skills::download that wrote at least one skill markdown file.

invocation
valueunknown
return
valueunknown