Skip to content
Sign in

iii-directory

v1.3.8

Engine introspection, workers registry proxy, filesystem-backed skills, system prompts, and agent profiles, kit install and update with reviewed plans, plus function search ranked by the judge worker (falling back to local hybrid/lexical) with a conditional pre-generate hint.

Install

bash
iii trigger compose::add worker=iii-directory

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

iii-directory

Workers registry HTTP proxy and filesystem-backed skills, system prompts, and agent profiles for the iii engine, plus kit install and update. Every public function sits under a single directory::* namespace, split into six surfaces (all MCP-agnostic):

Surface What clients see When to use it
Skills (directory::skills::*) Enriched listing via directory::skills::list ({ id, title, type, function_id, disable_model_invocation, description, bytes, modified_at } per row), a single-skill reader directory::skills::get { id } returning { id, title, type, function_id, disable_model_invocation, path, body, modified_at } (the full body instead of the list teaser), and directory::skills::index which renders a short per-worker overview document (one ## <title> + first paragraph + read more link per type: index skill). Authored by create, edited by update, removed by delete. title prefers the YAML frontmatter title: (then name:) over the body H1; type is lifted from frontmatter type: (e.g. index, how-to, reference) and serialised as null when absent. System-installed agent skills under the read-only agents_skills_folder are served too (see On-disk layout). Orientation: "when and why to use my worker's tools"
System prompts (directory::system-prompts::*) Identity prompts listed by list, read by get, authored by create, edited by update, and removed by delete. The list response keeps its prompts field name. Stored under any system-prompts/ path segment; create writes <skills_folder>/system-prompts/<name>.md. What the chat's system-prompt picker offers as an identity prompt (enrich or replace)
Agent Profiles (directory::agents::*) Reusable session identities whose file body is the system prompt, with display name, emoji logo, preloaded skills and functions (bodies and contracts the harness freezes into every session's prompt), and optional model + reasoning_effort in required frontmatter. list rows carry the display/configuration metadata and get adds system_prompt and unknown_skills. Stored as direct <agents_folder>/<id>.md files. See Agent profile storage. A named identity selected with harness::send { options: { agent } }
Search (directory::search_functions) One to six external capabilities → compact function-id candidates (installed, plus registry workers under installable), with a conditional pre-generate hint pointing agents at it. The response also carries skills (installed how-to documents) and observers (existing observers that already run a function on an event, schedule, or hook, minus ephemeral console listeners), ranked in the same mode as the functions; search_mode reports the mode that actually ranked. "Which functions do I call for this task?"
Kits (directory::download-kit, directory::kits::*) Install, update and remove kits — agent profiles, skills and registry workers published together as <author>/<kit> — through plans a human reviews (ADE → Directory → Kits) before anything is written. kits.lock records what is installed. See Kits. "Install the kanban team kit", "what does 1.1.0 change?"
Registry (directory::registry::*) HTTP proxy over api.workers.iii.dev with workers::{list,info}. Rows share the core name / description / version fields with the engine's engine::workers::list and add publication metadata (type, config, supported_targets, total_downloads, dependencies, optional image). workers::list is cursor-paginated with a server-authored page size. "What's published in the public registry?"

Engine introspection (functions / observers / workers) is served by the engine natively at engine::functions::*, engine::observers::* and engine::workers::*. Call the engine ids directly. One wrapper survives for callers that can only reach the directory:: namespace: directory::engine::functions::info proxies a single function's schema (see its row below).

This worker is where an agent's identity text LIVES. skills/system-prompts/iii-runtime.md ships here and is the one copy of "how to work against a live iii engine" — claude-code and pi fetch it with directory::system-prompts::get name=iii-runtime (plus directory::skills::index) for both their headless turns and their console terminals, rather than compiling a prompt of their own. Edit that file and every agent reads the edit; no worker release involved.

Skills and system prompts are sourced from skills_folder; agent profiles use the dedicated agents_folder. Writes are the directory::skills::download* functions, which pull markdown from either the workers registry or a GitHub repo and route each supported family to its configured root, plus the per-kind single-file editors — directory::skills::{create,update,delete}, directory::system-prompts::{create,update,delete} and directory::agents::{create,update,delete}. Once downloaded, files belong to the developer — edit them however you want, in the editor of your choice: a change made directly on disk calls the matching on-change with op: "external" (see Change functions).

directory::registry::workers::* and the engine's engine::workers::* share the core name / description / version fields so a parser that touches only those keys works against either surface; the registry view also surfaces publication metadata (type, config, supported_targets, total_downloads, dependencies, optional image) and the engine view adds runtime / connection state.

Table of contents

  1. Install
  2. Configuration
  3. Quickstart: download some skills
  4. On-disk layout
  5. Skill ids
  6. Kits
  7. Functions
  8. Function search & pre-generate hint
  9. Change functions
  10. Local development & testing

Install

iii call compose::add worker=iii-directory

iii call compose::add resolves the worker and its dependencies, writes exact declarations to worker-compose.yaml, and reconciles the Compose project.

For container settings, fetch compose::schema { function_id: "compose::add" } and use its workers list. For example, after arming the completion wake described below:

{
  "operation_id": "<operation-id>",
  "workers": [
    "state",
    {
      "worker": "iii-directory",
      "start_after": ["state"],
      "config_override": { "registry_search": true }
    }
  ]
}

The list can mix worker names and objects. Each object accepts scripts, config_name, config_override, working_dir, environment, env_file, startup_timeout, and package version as well as worker and start_after. scripts.run is for local workers only. Supplied maps replace the whole field; omitted settings are retained.

The returned install.payload from function search is a minimal shorthand. If the worker needs settings, replace its singular worker with an object in workers. Observe compose::on-operation-progress once, filtered on the operation_id, before calling compose::add; use the same operation_id in both calls, and wait for terminal success before using the new functions. An acceptance response does not mean the worker is ready. See the container settings example and completion flow for field behavior, path resolution, and recovery.


Skills

Install the iii-directory agent skill for Claude Code, Cursor, and 30+ other agents:

npx skills add iii-hq/workers --skill iii-directory

Browse or install every worker skill at once:

npx skills add iii-hq/workers --list
npx skills add iii-hq/workers --all

Configuration

Runtime settings live in the configuration worker under id iii-directory (the same pattern database and storage use). At boot the worker registers its JSON Schema, reads the live value via configuration::get (the configuration worker env-expands ${VAR}), and observes configuration::on-updated for its entry so it re-fetches on change.

Persisted values default to ./data/configuration/iii-directory.yaml (fs adapter). Edit that file directly, call configuration::set id=iii-directory, or use the Console's global Settings modal — all three propagate without a redeploy.

Fields

# TOPOLOGY — changing any of these requires a worker restart.
skills_folder: skills                  # under III_COMPOSE_DIR, or the process cwd standalone
local_skills_folder: skills/iii        # project-scoped overrides (whole-namespace local-wins)
agents_folder: agents                  # direct <id>.md agent profiles
agents_skills_folder: .agents/skills   # READ-ONLY agent skills, with the same relative-path base
auto_download: true                   # boot reconcile, rerun whenever a worker connects (observed)
# function_search_model_path: ~/.cache/iii/all-MiniLM-L6-v2-<revision> # pinned Hybrid bundle, also router::embed's local fallback (loads on first use in every mode); null disables both
function_search_model_download: true   # download the pinned bundle at boot in Hybrid mode

# TUNABLE — hot-reload live on `configuration:updated`.
registry_url: https://api.workers.iii.dev   # workers registry base URL (workers and kits)
# registry_web_url: https://workers.iii.dev  # registry web app for "open in registry" links; default: registry_url without its leading `api.`
download_timeout_ms: 60000                   # per git-clone / HTTP request timeout (ms)
registry_cache_ttl_ms: 60000                 # in-process TTL for registry::workers::* responses
filter_unregistered: true                    # hide skills whose namespace isn't an installed worker
inject_hint: false                           # observe harness::hook::on-pre-generate with the directory::pre-generate search hint (off: the harness identity prompt already teaches directory-first discovery)
hint_min_workers: 2                          # minimum surface width before the hint fires (0 = always)
registry_search: true                        # include installable registry workers in every search
function_search_mode: judge                  # lexical | hybrid | judge (default)
function_search_judge_timeout_ms: 3000        # integer 1..30000; shared judge deadline per public search
function_search_judge_min_relevance: 0.5      # finite 0..1 inclusive; noul floor (initial calibration value)
function_search_judge_side_lane_min_relevance: 0.3 # finite 0..1 inclusive; noul floor for the skills and observers sections
function_search_judge_question: choice       # choice (default: one question per capability) | noul (one yes/no per shortlisted document) | tournament (whole catalog: compact rounds, then a final choice; no Hybrid shortlist)
function_search_judge_choice_min_probability: 0.1 # finite 0..1 inclusive; with choice, the floor for all but the best document

The writable skills_folder and agents_folder roots are created when needed.

Zero-config default + seed

With no seed and no stored value the worker uses built-in defaults. Relative folder paths use III_COMPOSE_DIR when set and the process current directory otherwise (skills_folder: skills, agents_folder: agents, registry_url: https://api.workers.iii.dev). Pass --config <path> to supply a YAML seed: when present and no value is stored yet, its contents become initial_value on configuration::register (see config.yaml.example). Engine-managed deployments inline the config under the worker entry; the engine delivers it via --config.

Hot reload

On configuration::set (or an external edit to the persisted file), the worker re-fetches the authoritative value. Tunable changes apply in place and the registry caches are cleared so a repointed registry_url takes effect immediately. Topology changes (skills_folder / local_skills_folder / agents_folder / agents_skills_folder / auto_download / function_search_model_path / function_search_model_download) are refused with a "restart required" log; the previous configuration is kept until the worker restarts.

function_search_mode and all function_search_judge_* options hot-reload. Judge credentials and the model name are the judge-typesafe worker's settings, not this worker's.

The writable skills_folder, local_skills_folder, and agents_folder are watch roots, and the watcher creates each one at boot if it is missing. Direct <id>.md edits under agents_folder fire directory::agents::on-change with op: "external"; nested files are ignored. agents_skills_folder is a watch root too, but only when it already exists — the worker never creates (or writes) anything under it. Install your first agents skill while the worker is running and that root stays unwatched until the next restart: reads still serve it, since every read re-scans disk, but the live external doorbell is missing until then. local_skills_folder defaults to skills/iii under III_COMPOSE_DIR, or under the process current directory when the worker runs standalone. An empty local root shadows nothing. Because the roots are restart-required, the watch roots are fixed for the process lifetime.


Quickstart: download some skills

# Pull a specific worker's directory bundle at a fixed semver from
# the registry. Files land under `<skills_folder>/agent-memory/`.
iii call --function-id=directory::skills::download \
  --payload='{"worker": "agent-memory", "version": "1.2.3"}'

# Same, but always fetch whatever's tagged `latest` (also the default
# when neither version nor tag is given).
iii call --function-id=directory::skills::download \
  --payload='{"worker": "agent-memory"}'

# Pull a single subfolder out of a public GitHub repo via
# `git clone --depth 1 --branch main`. Files land under
# `<skills_folder>/frontend-design/`. The `branch` field defaults to
# `main`; pass `"master"` for older repos that haven't migrated.
iii call --function-id=directory::skills::download \
  --payload='{
    "repo": "https://github.com/anthropics/skills",
    "skill": "frontend-design"
  }'

The response is { namespace, skills_written, system_prompts_written, agents_written, agents_skipped?, source }. The three *_written fields list the files materialised in this run. Registry entries shaped exactly as agents/<id>.md land in <agents_folder>/<id>.md; repo downloads do not install agent profiles. A registry entry whose profile id an installed kit owns (kits.lock) is not written — kit profiles take precedence — and is reported in agents_skipped: [{ id, owned_by }].

A registry download (explicit or automatic) writes <skills_folder>/<worker>/.iii-skill-complete with the worker, the resolved version and, per agent profile it wrote, agents: { <id>: <sha256> }. That is how directory::agents::list attributes a profile to a worker.

After every successful download the worker calls directory::skills::on-change, directory::system-prompts::on-change, and/or directory::agents::on-change, so that their observers, like the mcp worker, can forward MCP notifications/list_changed to their clients.


On-disk layout

The worker uses separate roots for directory content and agent profiles:

skills_folder/
  <namespace>/                 # one folder per `directory::skills::download` namespace
    index.md                   # → iii://<namespace>/index
    contacts.md                # → iii://<namespace>/contacts
    emails/send-email.md       # → iii://<namespace>/emails/send-email
    system-prompts/            # ← magic marker for system prompts
      reviewer.md              # ← identity prompt (needs YAML frontmatter)
  system-prompts/              # ← where system-prompts::create writes
    pirate.md

agents_folder/                 # ← where agents::create writes
  release-captain.md           # ← agent profile (needs YAML frontmatter)
  frontend-design.md           # ← `extends: iii` builds on the bundled base

Three agent profiles ship inside the worker binary:

  • default — shown as Default in the chat's new-session gallery: the minimal directory-first identity (the same text as the bundled iii-minimal system prompt), with a composer example. New sessions in the ADE start on it.
  • iii — the harness default identity, verbatim. hidden: true keeps it out of the gallery; it stays a valid extends parent and runs by id.
  • iii-minimal — the previous id of default, kept as a hidden alias (extends: default, no body of its own) so existing extends: iii-minimal chains, saved sessions, and explicit invocations resolve to the same identity. New profiles should use extends: default.

Each is always listed (builtin: true), a local agents_folder/<id>.md shadows it, update on it copy-on-writes that local file, and deleting the file falls back to the bundled copy. No file is ever seeded on disk.

An optional composer_placeholder: frontmatter string is the example request the chat shows in an EMPTY composer while that profile is selected. It is presentation only — never sent, never added to the prompt — and profile-local: it does not inherit through extends, so a child without its own example gets the chat's generic hint. Whitespace collapses to single spaces, blank means absent, and more than 200 characters is rejected like any other invalid frontmatter.

An optional skills_index: boolean turns off the skills index for sessions running as that profile: with skills_index: false the harness starts them without the names-only <available_skills> block in the prompt (this is the prompt block, not the directory::skills::index function). It inherits through extends like model — the nearest profile that sets it wins, and true in a child turns the index back on. The profile's preloaded skills still render, and directory::skills::get stays callable when the session's policy allows it. A value that is not a YAML boolean makes the profile invalid, like hidden.

A second, READ-ONLY root — agents_skills_folder (default .agents/skills under the same Compose or standalone base) — serves agent skills. It is scanned shallowly: only <skill-dir>/SKILL.md becomes an entry (id <skill-dir>/index, displayed as <skill-dir>); a skill's reference/, scripts/, or other support payload is never listed. A missing directory is silently empty. These skills bypass filter_unregistered (their namespaces are skills, not workers), stay out of directory::skills::index (a per-WORKER surface), and are refused by update/delete — edit them with their owning tool, or copy one into skills_folder on disk to fork it. Precedence is local_skills_folder > skills_folder > agents_skills_folder, namespace-wise: a top-level namespace directory in a higher root shadows the same namespace below.

A few rules:

  • Skill ids are the relative path under skills_folder with .md stripped. Each segment must satisfy [a-z0-9_-]{1,64}.
  • Skill frontmatter is optional. When present, the reader recognises title: (preferred title), name: (title fallback), type: (free-form classifier), function_id: (canonical bus function id surfaced by list and get), description: (preferred list teaser), and disable-model-invocation: (boolean, default false, surfaced as disable_model_invocation by both responses). The body H1 and first paragraph are the title and list-description fallbacks, respectively. Disabled skills remain visible to ordinary directory clients; model index consumers decide whether to filter them. Any other YAML keys are ignored.
  • System prompts live under any */system-prompts/*.md path, with YAML frontmatter (description required, name optional). A path carrying both a prompts and a system-prompts segment is a system prompt because system-prompts is classified first. Other paths containing a prompts segment are ignored by scans and downloads.
  • What a system prompt can do, by design. The console's chat picker can send a selected system prompt with system_prompt_strategy: "override", which replaces the harness's built-in identity prompt with that file's body verbatim. Files reach system-prompts/ either by local authoring or via directory::skills::download from a git repo or the registry, so a downloaded bundle can supply one. This is an accepted property, not a hole: it takes a deliberate selection in the UI, the same UI already accepts arbitrary typed text, and the operator owns skills_folder. Worth knowing before you point skills_folder at a directory other people can write to.
  • Agent profiles are direct <agents_folder>/<id>.md files (unrelated to the read-only agents_skills_folder above, which holds external tools' skills). Nested profiles and the former <skills_folder>/**/agents/*.md layout are ignored. Frontmatter is required and must declare a non-empty name (the display name — the id is always the file stem); description may be empty, logo is emoji-only (≤16 bytes, no path characters), skills: filters the skill index (absent/empty = every skill), and model: names a model id for sessions using this profile (absent = the send decides), and optional reasoning_effort: names its provider-native effort. Both are stored verbatim and resolved against the live model catalog where they are used. The body is the system prompt, verbatim, and may be empty — a profile with no prompt of its own contributes only its parent chain (if any) and its non-prompt settings. Unknown skills ids are warnings surfaced by get, never load failures.
  • Agent profiles declare preloaded functions. functions: lists engine function ids (coder::tree, coder::search, …) the profile uses routinely. The harness resolves their contracts once, when a session starts as this profile, and freezes them into the system prompt as a <preloaded_functions> block (id, description, compacted request schema), so the model calls them on the first step instead of spending a directory::search_functions + engine::functions::info round-trip per session; everything else still goes through discovery. Ids are stored verbatim (non-empty, no whitespace; duplicates collapse, order kept); get reports ids the engine does not currently know in unknown_functions (a warning — the harness renders them as unavailable), list carries function_count. directory::agents::functions::add / ::remove { id, functions } edit only that frontmatter field — the rest of the file stays byte-identical — and fan out on-change as an update. The console's profile editor picks them from the live registry with the same keyboard-first search + Selected/Available lists as skills.
  • Agent profiles inherit. extends: <id> names one parent profile (chains allowed, at most 8 hops). The resolved system prompt served by get is the parent's resolved prompt followed by a blank line and this file's body — a blank body contributes nothing, so a profile with no prompt of its own serves its parent chain unchanged; model and reasoning_effort fall back to the nearest ancestor that sets them when omitted, while skills and functions inherit ADDITIVELY (the union of the chain's lists, root first, no duplicates — a child adds to what its parents allow / preload, it cannot remove); name, description, logo, icon and color are always the profile's own. A chain that does not resolve (unknown parent, loop, too deep) is reported by list/get as inheritance_error (D415 text) while the profile still serves its own file (so the editor can fix it); the harness refuses to run it.
  • Under a skills root, files outside prompts/, system-prompts/, and reserved agents/ segments are skills.

The download function namespaces by source:

Source Destination
repo=URL skill=NAME branch?=main <skills_folder>/<NAME>/...
worker=NAME version=… Skills/prompts under <skills_folder>/<NAME>/...; exact agents/<id>.md entries under <agents_folder>/<id>.md
worker=NAME tag=… (default tag=latest) Same routing as the version form

Re-pulling the same source overwrites files file-by-file — existing siblings outside the response set are preserved (so hand-edited additions survive a re-pull).


Skill ids

Skills are addressed by their relative path under skills_folder with .md stripped — e.g. <skills_folder>/agent-memory/observe.md → id "agent-memory/observe". The same string is what directory::skills::list returns and what directory::skills::get expects in { "id": ... }. The legacy iii://{id} link form is still accepted on get (the prefix is auto-stripped), but the worker no longer parses any other iii:// URI shape — bodies are read solely by id, and the auto-rendered tree-shaped index that previous releases served at iii://directory/skills is gone. Consumers that want a tree-shaped picker iterate list rows themselves and indent by id.matches('/').count().

Kits

A kit is a publishable bundle of agent profiles (agents/<id>.md), skills (skills/**.md) and registry workers declared by semver range, addressed as <author-handle>/<kit-name> and versioned in the registry (registry_url, endpoints under /k). Install one with

iii call directory::download-kit kit=acme/kanban-team          # latest
iii call directory::download-kit kit=acme/kanban-team@1.3.0    # or a tag, or a range (@^1.3)

Nothing is written by that call: it builds a plan and answers with it. Review the plan in the ADE (Directory → Kits) or apply it from a script with iii call directory::kits::apply plan_id=kp_…. apply=true on download-kit applies at once only when the plan has no warnings, nothing blocking it and no file that needs a decision.

What lands where

Kit file Installed at
agents/<id>.md <agents_folder>/<id>.md (flat ids, like every profile)
skills/<path>.md <skills_folder>/<handle>/<kit>/<path>.md — skill id <handle>/<kit>/<path> (SKILL.md / index.md → index)
workers: { kanban: ^1.4 } compose::add { workers: [{ worker: "kanban", version: "^1.4" }] } — the compose file declares the kit's range

Kit skill namespaces have two segments. They pass filter_unregistered (they are not workers), and a kit's local override is <local_skills_folder>/<handle>/<kit>/, which shadows that kit only — never the author's other kits. A kit installed inside local_skills_folder (the default skills/iii with an author handle iii) is the kit itself, not an override.

kits.lock

kits.lock sits next to the compose file and is meant to be committed. The compose file is III_COMPOSE_FILE when Compose started this worker; otherwise it is worker-compose.yaml in III_COMPOSE_DIR, or in the process working directory for a standalone worker.

version: 1
kits:
  acme/kanban-team:
    requested: ^1.3.0          # a tag, a range, or ^<version> for an exact install
    version: 1.3.0
    installed_at: 2026-10-08T14:02:11Z
    workers:
      kanban: ^1.4
    files:
      agents/product-manager.md:
        sha256: 4be1…          # the content the kit installed: the merge base
      agents/reviewer.md:
        sha256: 77c0…
        skipped: true          # you kept the file that was already there
      skills/acme/kanban-team/tickets/flow.md:
        sha256: 9a3e…
    ignored_versions: [1.4.0]

Paths are install paths: agents/… under agents_folder, skills/… under skills_folder. A file's state is computed on demand — intact (on-disk sha = base), edited, missing, or skipped. Bases are fetched back from the registry (GET /blobs/<sha256>); no copies are kept. An exact version request installs that version and records its caret range (1.3.0 → ^1.3.0, as npm saves an exact install) so compatible releases are offered as updates; tags and ranges are recorded as given.

Pending plans live in .iii/directory/kit-plans/<plan_id>.json next to the compose file (local state, not committed) and expire after 24 hours. The last update check is cached in .iii/directory/kit-updates.json.

Precedence and collisions

Kit profiles take precedence over profiles workers ship, but an install or update never replaces an existing file silently. Every agents/<id>.md has an owner: a kit (kits.lock), a worker (its completion marker records the profiles it wrote, with their sha256), or the project itself (local).

The kit writes a path that… Warning Default
a worker's bundle wrote agent_overwrite — "came from worker kanban 0.1.18 and will be replaced" replace
another kit owns agent_overwrite_kit; replacing moves the file to this kit and marks it skipped in the other kit's lock replace
was created in this project agent_overwrite_local (the strongest) replace
a user-global profile (~/.iii/agents) has agent_shadows_global replace
is default, iii or iii-minimal builtin_override — replaces a built-in profile project-wide replace
exists under the kit's skills folder but is not in the lock file_overwrite_local replace

Every collision can be answered keep: the kit's file is not written and the lock marks it skipped; later updates respect that until it is reverted. Identical content is no collision. Worker downloads skip profiles a kit owns and report them in agents_skipped. directory::agents::list / get carry source: { kind: kit | worker | local | global | builtin, kit?, worker?, version?, modified? }.

The plan

The plan JSON is the contract between the functions, the Kits page and the chat cards:

{
  "plan_id": "kp_…", "kind": "install | update | remove",
  "kit": "acme/kanban-team", "from": "1.3.0", "to": "1.4.0", "requested": "^1.3.0",
  "bump": "minor", "major": false,
  "author": { "handle": "acme", "name": "Acme", "verified": true },
  "registry_url": "<registry_web_url>/kits/acme/kanban-team", "notes": "…",
  "workers": [
    { "name": "github", "range": "^2.0", "installed": null, "action": "add", "to": "2.0.3", "type": "binary" },
    { "name": "kanban", "range": "^1.6", "range_from": "^1.4", "installed": "1.5.2", "action": "update", "to": "1.6.1" }
  ],
  "files": [
    { "path": "agents/reviewer.md", "source": "agents/reviewer.md", "kind": "agent", "id": "reviewer",
      "change": "added", "local": "occupied",
      "collision": { "owner": "worker", "worker": "kanban", "version": "1.6.1", "sha256": "…" },
      "default": "overwrite", "options": ["overwrite", "keep"], "agent": { …frontmatter… } },
    { "path": "skills/acme/kanban-team/tickets/flow.md", "kind": "skill", "change": "modified",
      "local": "edited", "base": "…", "theirs": "…", "ours": "…",
      "merge": "conflicts", "conflicts": 1, "default": null, "options": ["kit", "mine", "merged"] }
  ],
  "capabilities": { "workers_added": ["github"], "functions_added": [ … ], "models_changed": [ … ] },
  "functions": [ { "id": "kanban::ticket::create", "used_by": ["planner"], "worker": "kanban", "status": "ok" } ],
  "warnings": [ { "code": "agent_overwrite", "path": "agents/reviewer.md", "message": "…" } ],
  "blocking": [ { "code": "compose_not_running", "message": "… `iii compose --up` …" } ],
  "counts": { "agents": 3, "skills": 12, "workers": 2, "conflicts": 1, "decisions_required": 1, … },
  "created_at": "…", "expires_at": "…"
}
  • change: added, modified, removed, or kept (a skipped file whose kit version changed). local: absent, intact, edited, missing, or occupied (someone else's file). File bodies are not in the plan; directory::kits::plan { plan_id, contents: true } serves them.
  • An update merges a file you edited with the kit's change three ways (diffy): merge: clean defaults to merged; merge: conflicts has no default and needs kit, mine, or merged with the resolved text. Conflict markers read <<<<<<< yours / ||||||| installed / >>>>>>> kit. A file you edited that the kit did not change is not in the plan. A removed file you did not edit defaults to remove; one you edited defaults to keep (it becomes an ordinary local file).
  • Workers: add (not declared), update (installed version outside the range), redeclare (the compose file still declares the kit's previous range, which the installed version already satisfies), none, and remove for a worker the kit dropped — never removed unless named in remove_workers. path:// workers are never touched.
  • Warnings also cover local_edits_merged, merge_conflict, major_update and, on removal, edited_file_kept. Blocking: compose_not_running (the plan adds or moves workers and compose::status does not answer) and kit_deprecated.

Apply

directory::kits::apply { plan_id, decisions?, remove_workers? }, one apply at a time:

  1. Re-validate: the plan has not expired, kits.lock still holds the version it was made against, and every local file it looked at is unchanged. Otherwise nothing is applied and a fresh plan comes back with status: replanned.
  2. Download GET /k/<kit>/download?version=…&ci=… — counts the download (ci=true when CI is set) — and check every body against the sha the plan reviewed.
  3. Workers through Compose: one compose::add with { worker, version: <range> } objects for every added, moved or re-declared worker (an existing container's range is re-declared in place), then compose::remove for the ticked remove_workers, each followed through compose::operation. A failure stops here, before any file is written.
  4. Files, one atomic write or delete at a time, journaled in the plan so a retried apply recognises what it already wrote (the apply is idempotent).
  5. kits.lock, last; then the plan is deleted and on-change fires.

Workers added or moved get their own skills and profiles downloaded right after the apply (kit-owned profiles skipped), and the kit is checked for updates. Compose must be running (iii compose --up): the compose::* functions exist only while its daemon does.

Updates

directory::kits::check-updates asks POST /k/updates for every installed kit (or one): the newest version satisfying requested, unless it is in ignored_versions. It runs 15 seconds after boot, every 6 hours, after every install or update, and on demand. directory::kits::ignore { kit, version } adds a version to ignored_versions (and retires a pending update plan for it); ignore: false takes it back.

In the ADE

The Directory page has a Kits segment next to Skills and Agent Profiles; its badge counts plans waiting for review plus available updates.

  • Kits — pending reviews, an install box, and installed kits with their update state; "Check for updates".
  • An installed kit — Overview (README), Profiles and Skills (the files on disk, read-only, with "Edit in Directory"), Workers (as Compose has them), Files (intact / edited / missing / kept, with "View my changes" for edited ones), Remove, and a registry link.
  • Install review — the collisions on top (never collapsible) with replace / keep and a split diff for each, the permissions the kit asks for (workers and binaries it adds or moves, functions its profiles preload), the contents in three columns with a preview that shows frontmatter as fields and the prompt as markdown, and a button that says what will happen ("Install and replace 2 profiles"). A blocked plan shows the block instead. While it runs, the three steps (workers → files → kits.lock) report live; a failure offers "Try again".
  • Update review — release notes, then the changes as a pull request: new and changed profiles (a frontmatter summary, then the diff), workers and ranges, new / changed / removed skills, and the permissions the update grants. "Update" stays disabled while a conflict has no decision; "Ignore <version>" skips the version. A file you edited opens the conflict view: the kit's changes, yours, and an editable result that starts from the automatic merge.
  • Removal review — the files to delete (edited ones unticked) and the kit's workers (unticked, with a note when another kit uses one).

Chat cards render download-kit, plan-update and remove (the plan summary and "Review install", which opens this segment on the plan), apply (live steps, the result, and the plan summary while a harness approval is pending), check-updates and kits::list.


Functions

Functions sit under directory::*. All registrations are namespace-clean; this worker is intentionally agnostic to MCP and any other adapter.

directory::skills::* (filesystem reader + editor)

Function ID Description
directory::skills::download Download directory content. Flexible alias accepting either source set: {repo, skill, branch?} (defaults branch=main) or {worker, version?|tag?} (defaults tag=latest). Prefer the two explicit forms below so the source is unambiguous.
directory::skills::download_from_repo Repo-only form: {repo, skill, branch?}. Copies one skill folder out of a GitHub repo; paths under prompts/ and agents/ are ignored.
directory::skills::download_from_registry Registry-only form: {worker, version?|tag?}. Installs a published worker's bundle from api.workers.iii.dev, routing exact agents/<id>.md entries to agents_folder.
directory::skills::list Enriched listing of every fs-backed skill: { id, title, type, function_id, disable_model_invocation, description, bytes, modified_at } per row. title prefers the YAML frontmatter title: over the body H1, type is lifted from frontmatter type: (null when absent), function_id identifies the documented bus function when present, and description is the frontmatter description or first body paragraph — so consumers can render a picker without a follow-up get per row.
directory::skills::get Fetch one skill by id. Returns { id, title, type, function_id, disable_model_invocation, path, body, modified_at }. It shares the list row's identity, classification, function, and invocation metadata, but returns the raw markdown body and absolute on-disk path instead of the teaser and byte count; there is no description field. The path's parent directory is the skill's base directory, where payload like scripts/ and reference/ lives, and is meaningful only to callers on this worker's machine. Accepts a bare id or the same id prefixed with iii://. Pass raw: true to additionally get the FULL on-disk file (frontmatter included) as raw — the round-trip form update takes.
directory::skills::update Overwrite one EXISTING skill file with new full-file content: { id, content } where content is the edited raw from get { raw: true }. Validated against the read invariants (size cap, non-empty body after frontmatter); atomic write; fans out directory::skills::on-change with op: "update". Never creates files (use create). Refuses read-only system-installed skills under agents_skills_folder (D116).
directory::skills::create Create a NEW skill file at <skills_folder>/<id>.md from full-file content: { id, content }. Frontmatter is optional (same rules as update: size cap, non-empty body). Refuses an id that already resolves in the visible set — including the <id> → <id>/index overview alias and system-installed agents skills — or a target path that already exists on disk (D114); an id in a namespace reserved by a system-installed agents skill (D115); and, while filter_unregistered is on, an id the visibility filter would immediately hide (D115). Atomic write; fans out directory::skills::on-change with op: "create". Returns the same shape as update.
directory::skills::delete Permanently remove one EXISTING skill file by { id } (same id forms as get). Resolves against the same visible set as list/get, refuses read-only system-installed skills under agents_skills_folder (D116), removes the file plus any parent directories left empty (so a deleted namespace can't keep shadowing a lower-precedence root), and fans out directory::skills::on-change with op: "delete". Returns { id } (the resolved on-disk id).
directory::skills::index Render one short markdown entry per installed worker (skills with frontmatter type: index). Returns { body, workers_count } where body is a ready-to-paste page: # Skills index, then one ## <worker title> heading + the worker's first overview paragraph + a Read iii://<ns>/index pointer the agent can follow with directory::skills::get. Token-light by design; use directory::skills::list for per-skill rows.

directory::system-prompts::* (filesystem reader + editor)

Function ID Description
directory::system-prompts::list Metadata-only listing of every fs-backed system prompt.
directory::system-prompts::get Fetch one system prompt's body + {name, description, modified_at}. Plain shape, no envelope. Pass raw: true to additionally get the FULL on-disk file (frontmatter included) as raw.
directory::system-prompts::update Overwrite one EXISTING system prompt file with new full-file content: { name, content }. The frontmatter must keep a non-empty description (and a valid name when declared) — the same rules the scanner enforces. Atomic write; fans out directory::system-prompts::on-change with op: "update". Returns the system prompt's effective name after the write.
directory::system-prompts::create Create a NEW system prompt file at <skills_folder>/system-prompts/<name>.md from full-file content: { name, content }, where content is the FULL file including frontmatter. The frontmatter must carry a non-empty description (and a name matching the request, when declared) — the same rules update enforces. Refuses a name that already exists anywhere in the merged system-prompt scan, and a target path that already exists on disk even if the scanner would skip it. Atomic write; fans out directory::system-prompts::on-change with op: "create". Returns { name, description, bytes, modified_at }.
directory::system-prompts::delete Permanently remove one EXISTING system prompt file by { name }. Resolves against the same merged scan as list/get, fans out directory::system-prompts::on-change with op: "delete", and returns { name }.

Agent Profiles — directory::agents::* (filesystem reader + editor)

Function ID Description
directory::agents::list Metadata-only listing of every agent profile — fs-backed plus the bundled default / iii / iii-minimal profiles (builtin: true until a local file shadows one): { id, name, description, logo, skill_count, model, reasoning_effort, icon, color, extends, hidden, composer_placeholder, modified_at } per row (hidden and composer_placeholder omitted when unset; composer_placeholder never inherits), skill_count/model/reasoning_effort resolved through extends (skill_count: null = every skill; model: null = the send decides). A row whose chain does not resolve carries inheritance_error. Every row carries source: { kind: kit | worker | local | global | builtin, kit?, worker?, version?, modified? } — see Precedence and collisions.
directory::agents::get Fetch one agent profile by { id }: the RESOLVED system_prompt (each ancestor's body root-first, then this file's body), skills + unknown_skills (preloaded ids matching no visible skill — warnings), skills_index (resolved through extends; false = sessions start without the skills index, omitted when unset), model (null = the send decides), provider-native reasoning_effort, display icon/color, extends, hidden, the profile's own composer_placeholder (omitted when unset), builtin, modified_at, and inheritance_error when the chain does not resolve (own file served meanwhile), and the same source as list. Pass raw: true to additionally get this profile's FULL on-disk file as raw.
directory::agents::update Overwrite one EXISTING agent profile file with new full-file content: { id, content }. Same rules the scanner enforces (required frontmatter with non-empty name, emoji-only logo; the body — the system prompt — may be empty); the id stays the file stem. Updating a bundled profile creates the local file that shadows it. Atomic write; fans out directory::agents::on-change with op: "update".
directory::agents::create Create a NEW agent profile at <agents_folder>/<id>.md from full-file content: { id, content }. Refuses an id that already exists in the configured agent-profile root, and a target path that already exists on disk even if the scanner would skip it; creating a bundled id shadows the bundled copy. Atomic write; fans out directory::agents::on-change with op: "create". Returns { id, name, description, logo, bytes, modified_at }.
directory::agents::delete Permanently remove one EXISTING agent profile file by { id }. Resolves against the same configured root as list/get, fans out directory::agents::on-change with op: "delete", and returns { id }. Deleting the local shadow of a bundled profile falls back to the bundled copy; a bundled profile with no local file has nothing to delete (D414). Sessions already using the profile are unaffected; profiles extending it stop resolving until fixed.
directory::agents::functions::add { id, functions: ["coder::tree", …] } — append engine function ids to one EXISTING profile's OWN functions: list (its preloaded functions: the contracts the harness pre-loads into the system prompt of every new session running as the profile). Ids already present are kept once; only that frontmatter field is rewritten (block style), every other byte of the file is untouched; writes atomically, copy-on-writes a bundled profile's shadow, fans out on-change with op: "update". Returns { id, functions, added, unchanged?, bytes, modified_at } — unchanged: true means nothing was written. D416 for a request with no valid ids (entries must be non-empty and whitespace-free).
directory::agents::functions::remove { id, functions } — drop ids from one EXISTING profile's OWN functions: list (absent ids are ignored; the field disappears when the list empties). Same write semantics and D416; returns { id, functions, removed, unchanged?, bytes, modified_at }. Neither verb touches ids inherited through extends — those stay in the resolved union and are removed on the parent that declares them.

Kits — directory::download-kit, directory::kits::*

Function Description
directory::download-kit { kit: "<author>/<kit>[@version|tag|range]", apply? } → { status: planned | applied | up_to_date, kit, message, plan?, report? }. Builds an install plan (an update plan when the kit is installed; without @… an installed kit keeps its requested) and stores it; writes nothing unless apply: true and the plan has no warnings, blocks or pending decisions.
directory::kits::apply { plan_id, decisions?, remove_workers? } → { status: applied | replanned, report?, plan? }. decisions maps install paths to overwrite | keep | kit | mine | merged | remove or { choice: "merged", content }; files left out take the plan's default. The report lists files written / merged / removed / kept, workers added / updated / removed, the steps, and the agent ids the kit now provides.
directory::kits::plan-update { kit, version? } — plan an update (default target: the newest release matching requested). up_to_date when there is nothing newer.
directory::kits::remove { kit } — plan a removal; apply it with apply (remove_workers to remove the kit's workers too).
directory::kits::check-updates { kit? } → { checked_at, available, kits: [{ kit, current, available, latest, major, ignored?, deprecation? }], error? }.
directory::kits::list Installed kits (version, requested, file-state counts, workers, update, pending plan ids) and pending plan summaries; attention = pending plans + available updates.
directory::kits::get { kit, registry? } — one installed kit with every file's state and on-disk sha, its workers as Compose has them, and with registry: true the installed version's registry detail and README.
directory::kits::plan { plan_id, contents? } — a pending plan, its apply progress, and with contents: true the bodies it refers to (blobs by sha256, ours and merged by install path).
directory::kits::discard { plan_id } — drop a pending plan.
directory::kits::ignore { kit, version, ignore? } — add a version to (or with ignore: false remove it from) ignored_versions.
directory::kits::diff { kit, path } → { base, local, state } — what the kit installed and what is on disk, for "view my changes".

Errors: D510 unknown kit or version, D511 malformed kit ref, D512 expired or unknown plan, D513 missing or invalid decisions, D514 blocked plan (Compose not running, deprecated kit), D515 Compose operation failed, D516 the registry served different content than the plan reviewed, D520 registry unreachable, D521 the kit (the requested version, or every version a range matches) does not run on the iii that is running; the registry's message names the required range and says whether to run iii update or install another version of the kit.

Engine introspection (native, plus one wrapper)

Engine introspection is served natively; call these ids directly — every one takes the same filters (prefix, search, worker, include_internal where applicable). One wrapper is kept for callers whose policy only admits the directory:: namespace:

Function ID Description
directory::engine::functions::info Thin proxy to engine::functions::info for a single function_id: request/response schemas, metadata, args_format, observer_count, private and observable. The one directory::engine::* helper that still exists — reach for it only when you cannot call engine::* directly.

The native ids:

Function ID Description
engine::functions::list List functions registered with the engine.
engine::functions::info Single-function detail: schemas, owning worker, args_format, observer_count, private, observable.
engine::observers::list List observers: observed function, args, filters, target, observing worker, state.
engine::observers::get Single observer detail.
engine::workers::list List workers with an open engine WS connection. For the workers a compose project declares, connected or not, call compose::status.
engine::workers::info One worker's detail by name.

directory::registry::* (workers registry HTTP proxy)

Function ID Description
directory::registry::workers::list Browse / search published workers in api.workers.iii.dev. Optional free-text search (matched fuzzy by pg_trgm) and opaque cursor for pagination; page size is server-authored. Response is { workers: [...], pagination: { next_cursor, has_more, page_size } }. Shares the core name / description / version fields with the engine's engine::workers::list.
directory::registry::workers::info Pre-install card for one worker. Fans out two parallel registry calls — GET /w/{slug} for the worker envelope (publication metadata + readme + functions) and GET /w/{slug}/skills for the skills tree — and merges them into { worker, api_reference, skills_tree, readme? }. The card keeps public function names and descriptions only (the event sources the worker hosts included): request/response schemas, metadata, internal and search-excluded functions are dropped (browser's schemas alone ran 65 KB; the contract is engine::functions::info after installing), and readme (10–25 KB) is included only with readme: true. The full record stays cached in-process for directory::search_functions. Input still accepts version: (semver) or tag: (e.g. latest); both go on the wire as ?version=….

Both directory::registry::* responses are cached in-process for registry_cache_ttl_ms (default 60s).

There is no directory::skills::register — skills are the files described in On-disk layout.

Local embeddings — provider::minilm::embed

The MiniLM model that ranks directory::search_functions candidates also serves router::embed on a stack where no registered provider has an embed surface (Anthropic only, for example), with no key and no extra process. The memory worker's semantic recall is one caller.

  • Request and response. {model?, input[1..512]} → {model: "sentence-transformers/all-MiniLM-L6-v2@<revision>", embeddings}: 384 dimensions, L2-normalized, in input order.

  • Loading. The model loads on first use, in every function_search_mode. The boot-time bundle download still runs only in hybrid and judge mode.

  • Not configured. The surface answers provider/not_configured when:

    • the build has no MiniLM;
    • function_search_model_path is null;
    • the bundle is not provisioned;
    • the caller names another model.

    The router then moves on.

  • Not a declared provider. It never declares itself to the router, so it lists no models and no model picker shows it. router::embed tries it only when every registered provider either has no embed surface or is not configured for good (no API key). Configuring such a provider later moves callers to its vector space (memory re-embeds into the model the reply reports). An OpenAI or llama.cpp embeddings setup keeps its vectors, even while that provider restarts, once it has answered an embed: the router remembers that and waits for it while it was live in the last 15 minutes (one removed for longer no longer holds the fallback). A registered provider whose embeddings endpoint fails (llama-server started without --embeddings, say) returns its error instead of falling back here.

  • Access. Agents cannot call it directly: the root permissions deny provider::*.


Function search & pre-generate hint

One-shot function search over the live engine catalog. judge (the default) ranks through the optional judge worker when it is registered and answers, and otherwise behaves as hybrid (BM25 fused with the local MiniLM model, reranked); lexical is BM25 only. Absorbed from the former discovery worker, it returns only compact { function_id, description } candidates, grouped by worker in rank order. The model chooses the candidates it needs, then fetches their contracts in one engine::functions::info { function_ids: [...] } call instead of walking the catalog with engine::functions::list.

Function Kind What it does
directory::search_functions public { capabilities } → { guidance, workers[], installable[]?, skills[]?, observers[]?, search_mode, latency_ms }: rank with the configured mode over the live engine catalog in batches of six capabilities (12 candidates per batch across at most max(6, 2 × capabilities) workers, up to 3 batches) plus matching NOT-installed registry workers under installable. capabilities is a required list of non-empty unmet external capability searches (one to six is the norm); entries past the 18th are not searched and are named in guidance. Requests to summarize provided text/content are ignored.
directory::pre-generate internal hook Injects the conditional search hint into a harness generation (at most once per turn).
directory::on-functions-change internal Refreshes the search catalog; observes engine::on-functions-changed.
directory::hint-preview internal The exact hint text per exposure mode, for the configuration UI.

Lexical/Hybrid ranking pipeline:

  1. Corpus: the live engine catalog (boot snapshot + push refresh), slimmed to name + first description sentence + argument names. engine:: ids, functions published with metadata.internal, and the search itself never participate — the worker's own public directory::* functions are searchable like any other capability.
  2. Scoring: Okapi BM25 (k1 1.2, b 0.75) with the function name indexed at 3× weight, camelCase segmentation (presignUrl → presign + url), a 22-word grammatical stoplist, conservative plural folding, JSON-key stripping from capability text, and a two-distinct-terms minimum match.
  3. Capability queries: each capabilities entry is ranked independently against its own leader and is authoritative. Include every currently unmet external capability once in the same call. Write every capability in English, translating non-English requests while preserving proper names, URLs, and function ids. Requests to summarize provided text or content are ignored. Results merge round-robin so every capability gets a candidate before any gets a rider.
  4. Pruning: coverage-aware function floor (≥50% of the leader AND full term coverage or ≥85% score) drops same-worker family riders; a namespace-level floor (40% of the leader) drops trailing workers.
  5. Registry search (registry_search, default on): every call also consults the private workers registry in-process with the same capability queries plus informative-term retries (all concurrent; every listed worker is a candidate — the registry is team-authored). Candidates merge round-robin across search variants; their API references are pooled and ranked per capability with the configured mode. Hybrid fuses BM25 with the MiniLM dense lane (same 0.30 admission floor as the installed catalog), so a capability sharing no vocabulary with a contract ("retrieve web news articles" → web::fetch) still surfaces. Returns up to 2 workers / 6 candidates per batch of six capabilities (so up to 6 workers / 18 candidates across three batches; a worker two batches both surface keeps one entry with its functions merged) that WOULD match if installed, with compose::add guidance.
  6. Session memory (keyed by caller-supplied OTel baggage, fail-open): repeat queries omit candidates already delivered.

Judge mode

Function relevance is judged by the judge worker (judge::evaluate), which forwards to its configured provider (judge-typesafe by default). Both are optional: this worker does not declare them as dependencies, because Compose turns a dependency into a start_after edge and stops the directory whenever the judge exits. The Harness and dev-template stacks do not run them. Install the hub with iii call compose::add worker=judge (it brings judge-typesafe) and set the TypeSafe key and model in the judge-typesafe settings. This worker holds no credentials.

judge is the default mode for new installs. It ranks through the judge only while judge::evaluate is in the live function catalog and answers. Whenever the judge is unavailable the search uses Hybrid (then Lexical if the local model is not ready), for functions, installable workers, skills and observers alike:

  • judge::evaluate is not registered: no call is made at all.
  • the hub has no provider (provider_unavailable), or the provider has no API key (missing_key): logged once at info.
  • a provider error, transport failure or invalid reply: logged once as a warning.
  • the judge deadline runs out: that lane alone uses Hybrid.

After an unavailable or failing judge (the second and third cases), every search skips it for 30 seconds and uses Hybrid, so a missing key costs one fast round trip per 30 s rather than one per search. A key added to judge-typesafe, or a judge that comes back, is used within 30 seconds. A missed deadline does not pause the judge.

An install that already stored function_search_mode: hybrid keeps it: the stored configuration wins over the new default. Set judge with configuration::set (or the console form) to opt in.

function_search_mode: judge
function_search_judge_timeout_ms: 3000
function_search_judge_min_relevance: 0.5
function_search_judge_side_lane_min_relevance: 0.3
function_search_judge_question: choice
function_search_judge_choice_min_probability: 0.1

These fields apply without a restart. The timeout is an integer from 1 to 30000 ms and relevance a finite number from 0 to 1 inclusive. YAML seeds and JSON configuration updates use the same validation. The relevance floors were calibrated against jev-1.13.0; judge-typesafe defaults to the jev-latest alias, so pin its model if you rely on the floors.

The judge scores a shortlist per capability, not the whole catalog. A corpus of at most 16 documents goes whole, so the judge still finds functions whose wording shares nothing with the capability. A larger one is cut to the top 16 of raw BM25 fused with the raw MiniLM ranking (when the index is ready). Each capability is one evaluation, and all capabilities of a lane (functions, registry pool, skills or observers) travel in one judge::evaluate call, so the provider answers them together with one model, and cancels the rest when one fails. Requests carry normalized capabilities, function IDs, short descriptions and parameter names; no conversation history or argument values. Exact eligible IDs, internal-function exclusions, session deduplication and result limits stay local.

function_search_judge_question sets how each capability's shortlist is asked. choice (the default) asks one multiple-choice question per capability whose options are the shortlisted documents: 16× fewer questions, and the documents compete. The best document is always kept and every other needs function_search_judge_choice_min_probability (the relevance floors do not apply). noul asks one yes/no question per document and admits each by the relevance floors. Local judges need choice to fit the deadline: judge-semif answers a capability in about 0.3 s on a GPU, where the Noul shortlist of every lane takes it past 30 s. On 22 English capabilities over the 16-document shortlist, choice with 0.1 kept a correct function in every search for both jev-1.13.0 (precision 0.98, 1.2 functions per capability) and judge-semif (precision 0.87, 1.5 functions). Providers register their judge-<provider>::* functions as internal, so search results show only the hub's judge::*.

With choice, a judge whose models advertise a context window under 4096 tokens (context_window in judge::models::list, re-read when the judge hub's configuration changes and at least once a minute) gets compact options instead of the full description objects: each option is keyed by the function id and reads the first eight words of its description, and the state names the capability plainly ({"capability": …}). laya (512 tokens) shares about 190 of them among the sixteen options, so the objects cut the function ids themselves: live, it found the expected function in 13/22 searches with objects and 17/22 compact. SemIf (16384) and judges that advertise no window keep the objects.

tournament skips the Hybrid shortlist, following TypeSafe's skill-suggestion pattern (skim everything cheaply, then read the few in detail). The whole function catalog, sorted by id, is skimmed in rounds of compact Choices (the function id and the first eight words of its description) over groups of up to 128, or 16 for a judge that advertises a context window under 4096 tokens, and never more than the judge's advertised max_options (SemIf: 16); each group's three best go on (only the winner, for a small-window judge, whose final Choice degrades with more options) until 16 or fewer remain, and those get one final Choice with their full descriptions, admitted like choice. A 260-function catalog takes one round of three groups, then the final Choice over nine. It needs no local semantic model. Live through directory::search_functions over 22 English capabilities (RX 6900 XT), hit / top-1 / precision and median search time: JEV 22 / 22 / 1.00 at 2.2 s, SemIf 22 / 22 / 0.90 at 6.1 s, decider 22 / 21 / 0.88 at 3.7 s, laya 20 / 19 / 0.80 at 2.2 s; the former winner-only rounds of 16 gave JEV 22 / 22 / 0.98, decider 21 / 21 / 0.81 at 9.1 s, and timed SemIf out at 10 s. The installed functions and the registry pools play it; skills and observers keep their shortlists. With choice (the default), a judge that advertises a context window under 4096 tokens gets a tournament automatically; SemIf and hosted judges keep choice.

function_search_model_path: null is valid in judge mode and makes the Hybrid fallback BM25-only, without the local-model warning. With a configured path, the worker keeps an installed MiniLM bundle and its catalog index current, downloads a missing bundle at boot like Hybrid does, and uses the index both for the shortlist and for the fallback.

Registry discovery still starts with the registry API's lexical search. The judge evaluates a shortlist of the returned contract pool and cannot recover workers that upstream search did not return. Installable results remain suggestions until installation.

Every response carries search_mode — the mode that actually ranked the results (judge, hybrid or lexical), which can be lower than the configured mode when the judge was unavailable or paused, or the local model is not loaded yet. The console's search card shows it as the card's badge. A search whose lanes partly fell back reports the highest tier any lane reached.

Every mode also ranks the installed skill documents (the rows directory::skills::list serves, minus disable_model_invocation ones) against the same capabilities and lists the matches under skills as { id, title, description }, at most six per call round-robin across the capabilities, with a guidance note to read them through directory::skills::get { id }. Each skill's id and a trimmed title: description (300 bytes) form the document. The judge judges them with a how-to question under the same deadline as the functions; Lexical ranks them with BM25 and Hybrid fuses in the dense lane, the same ad-hoc document ranking the installable section uses, and that local ranking also serves whenever the judge fails. "Installed" is read off the live function catalog: a worker with no registered functions contributes no skills. The observers section (under observers) is ranked the same way in every mode.

A valid response with no functions at or above the relevance threshold stays empty. Judge failures instead fall back Judge → Hybrid → Lexical. Hybrid uses the existing local ranking policy; if the model is disabled, missing, not yet indexed for the current catalog, or fails, Lexical serves the results. A registry HTTP failure still omits the installable section.

The judge deadline is shared by every judge call of one public search. Capability batches run concurrently, and each batch's registry lookup runs in parallel with its installed-function judge call; the registry judge call then gets what is left of the deadline and, if nothing is, the pool is ranked locally. Local Hybrid fallback runs outside the budget. Evaluations are split at local byte limits (48 KiB per evaluation, 16 KiB for state plus the largest question); these guards are not token counts. Retries are the provider's policy (judge-typesafe retries 408/429/5xx within the deadline); the 30-second pause keeps a failing provider from being retried on every search. The hub's returned usage (stats) is logged per lane at debug level.

Switch to lexical at any time to use BM25 only. Switching from lexical to hybrid or judge prepares the local index from the current catalog. If the MiniLM bundle is missing, both use lexical fallback; the boot-time download and changes to the local model path require a worker restart.

Upgrading from the in-worker jev mode: the stored value function_search_mode: jev no longer parses, and the worker refuses to boot on it. While the old worker still runs, its schema only accepts lexical/hybrid/jev, so before upgrading set the mode to hybrid (or remove the key) with configuration::set, then set judge once the new worker is up. The removed keys function_search_jev_api_key and function_search_jev_model are ignored, and the console form drops every function_search_jev_* key on its next save; the remaining settings are read under their function_search_judge_* names only.

Pre-generate hint

The pre-generate hook appends one <discovery_assist> block pointing the model at search_functions, telling it to derive capabilities from the goal and current execution state and to batch selected ids through engine::functions::info — at most once per turn, and only when every gate clears: the function is callable in the surface, no search result is in the current task window yet, the surface spans at least hint_min_workers distinct workers, the current task (from the latest user message) has no real function results yet, and it does not already name a callable function id. Measured on 26 pre-existing e2e scenarios: an unconditional hint induces redundant discovery on guided tasks (up to +110% tokens). The hook ships OFF by default (inject_hint: false): the harness identity prompt already teaches directory::search_functions as the default discovery path, so the hint is for deployments running a custom identity prompt without that doctrine. The hook's transcript annotations (origin.directory) carry only coarse outcome/reason and counts.

With inject_hint: true the worker observes the harness's hook function with directory::pre-generate as the target, and disposes the observer when the knob turns off:

iii.observe(
  {
    function_id: 'harness::hook::on-pre-generate',
    args: { priority: 100, timeout_ms: 5000, on_error: 'fail_open' },
  },
  'directory::pre-generate',
)

fail_open keeps a slow or failing hint from blocking a turn. The observer stays pending until the harness registers the hook function.

Knobs (inject_hint, hint_min_workers, registry_search) live in the iii-directory configuration entry and hot-apply — see Configuration.

Change functions

The worker hosts four functions that it calls when a change happens. Each is private (only this worker calls it), takes no args, and returns the event it is called with, so its observers receive the event. Select changes with filters on the event's fields.

Function Called when Filter on Event
directory::skills::on-change After a directory::skills::download that wrote at least one skill markdown file, a directory::skills::update, create, or delete, a kit apply that wrote skills or downloaded the bundles of the workers it added or updated, or external (file pasted/edited/deleted directly on disk — including under agents_skills_folder) input.op, input.name, input.namespace download: { "op": "download", "namespace": "<ns>", "source": "repo" | "registry" } from directory::skills::download, { "op": "download", "source": "registry" } from a kit apply's worker bundles; update/create/delete: { "op": "<operation>", "namespace": "<ns>", "name": "<id>", "id": "<id>" }; kit: { "op": "kit", "kit", "plan_id" }; external: { "op": "external" }
directory::system-prompts::on-change After a directory::skills::download that wrote at least one system prompt markdown file, a directory::system-prompts::update, create, delete, or external file change input.op, input.name download: { "op": "download", "namespace": "<ns>", "source": "repo" | "registry" }; update/create/delete: { "op": "<operation>", "name": "<name>" }; external: { "op": "external" }
directory::agents::on-change After a directory::skills::download that wrote at least one agent profile, a directory::agents::update, create, delete, a kit apply that wrote profiles or downloaded the bundles of the workers it added or updated, or external file change input.op, input.name download: { "op": "download", "namespace": "<ns>", "source": "repo" | "registry" } from directory::skills::download, { "op": "download", "source": "registry" } from a kit apply's worker bundles; update/create/delete: { "op": "<operation>", "name": "<id>" }; kit: { "op": "kit", "kit", "plan_id" }; external: { "op": "external" }
directory::kits::on-change A kit plan is created or discarded, an apply makes progress or lands, or an update check changes the set of available updates input.op, input.plan_id, input.kit { "op": "plan", "kit", "plan_id", "kind" }, { "op": "discard", "kit", "plan_id" }, { "op": "progress", "plan_id", "kit", "steps": [{ id, label, state, detail? }], "error"? }, { "op": "apply", "kit", "plan_id", "kind" }, { "op": "updates", "kit"? }

Observe one with your own function as the target; it receives the Observed envelope, whose output is the event:

iii.observe(
  { function_id: 'directory::skills::on-change', capture: ['output'] },
  'mcp::__on_skills_changed',
)

// only the progress of one kit apply
iii.observe(
  {
    function_id: 'directory::kits::on-change',
    filters: { 'input.op': { $eq: 'progress' }, 'input.plan_id': { $eq: planId } },
    capture: ['output'],
  },
  'my-worker::on-kit-progress',
)

The worker calls them fire-and-forget (Void), and only when something observes them, so the write path doesn't block on downstream latency.

The external op comes from a filesystem watch over skills_folder, local_skills_folder, and (when it already exists) the read-only agents_skills_folder. It is a doorbell, not a ledger: every read re-scans disk, so a missed event costs a stale open view until the next call, never data. A burst coalesces into one event per kind, and this worker's own writes are suppressed — a create or update sends its precise op and never an extra external.

Loop hazard for observers. Suppression covers writes made through this worker. An observer that reacts to { "op": "external" } by writing .md files under skills_folder by some other route — a shell or coder worker, a script — is not suppressed and will run itself again. Either write through directory::*::update / create, or make the reaction idempotent and gated.


Local development & testing

Run from source

On targets with a pinned static ONNX Runtime (Linux glibc x86_64/aarch64, Apple Silicon macOS, Windows MSVC) every build links it and MiniLM retrieval and reranking are compiled in. With no ORT_LIB_PATH, ort-sys downloads the runtime for the build target at build time (SHA-256-verified). For offline or cached x86_64 Linux builds, provision it once and export the path it prints:

export ORT_LIB_PATH="$(scripts/provision-onnxruntime.sh)"   # idempotent, SHA-256 verified
export ORT_PREFER_DYNAMIC_LINK=0

Other targets (musl, armv7, Intel macOS) build the BM25-only worker and need nothing extra.

# --config is an optional YAML seed (see config.yaml.example); omit it to
# rely on the value stored in the `configuration` worker (or built-in defaults).
cargo run --release -- --url ws://127.0.0.1:49134 --config ./config.yaml.example

Tests

# Fast, offline — exercises the pure helpers (markdown / id validators
# / fs source) without needing an iii engine.
cargo test --lib

# Full BDD suite — requires an iii engine on ws://127.0.0.1:49134
# (or III_ENGINE_WS_URL). The git-backed download scenarios spin up
# a local fixture repo via `git init`; the registry-backed scenarios
# point a wiremock server at the worker's `registry_url` config.
cargo test

# One feature group at a time. Available tags:
#   @engine  @read  @download  @download_repo  @download_registry
#   @registry  @registry_worker_list  @registry_worker_info  @on_change
cargo test --test bdd -- --tags @download

The BDD harness lives under tests/. Feature files mirror the modules in src/functions/. Step definitions under tests/steps/ drive each feature through the same iii.call path the production binary uses.

Search the registry

Find workers, kits and executables, or jump to a page.