# zilX **Repository Path**: MacRsh/zilX ## Basic Information - **Project Name**: zilX - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-07-14 - **Last Updated**: 2026-07-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # zilX zilX is a zero-configuration role router for OpenCode. Lead decides what kind of work a task requires; zilX selects the highest-ranked connected model for that role and runs the work in an isolated child Session. Users do not assign models to agents and do not maintain a zilX configuration file. They only connect Providers in OpenCode. ## Roles zilX adds one primary coordinator and five namespaced execution agents. Routing keeps the short role names, while OpenCode registers execution agents as `zilx-quick`, `zilx-build`, `zilx-explore`, `zilx-analyze`, and `zilx-research` so built-in agents such as Plan and Build remain unchanged. | Agent | Responsibility | Tools | | --- | --- | --- | | `lead` | Classify work, route it, and synthesize results | `read`, `glob`, `grep`, `task` | | `quick` (`zilx-quick`) | Small, bounded implementation and command tasks | local read/write tools and `bash` | | `build` (`zilx-build`) | Complex or cross-cutting implementation | local read/write tools, `bash`, and restricted `task` | | `explore` (`zilx-explore`) | Read-only local code and context discovery | `read`, `glob`, `grep` | | `analyze` (`zilx-analyze`) | Read-only architecture, review, and debugging | `read`, `glob`, `grep` | | `research` (`zilx-research`) | External documentation and primary-source research | `read`, `webfetch` | Lead cannot edit files or execute shell commands. Build may delegate read-only support work to `zilx-explore`, `zilx-analyze`, and `zilx-research`; all other execution agents remain leaf agents and cannot create subagents. zilX is isolated from OpenCode's built-in `build` and `plan` agents. The plugin does not replace their model, prompt, mode, or ordinary permissions; it adds final deny rules and per-message tool visibility guards that hide `zilx-*` delegation targets and zilX-only tools from those two agents. Runtime routing, prompt authorization, and assurance observation run only for sessions bound to `lead` or a registered `zilx-*` agent. Conversely, Lead can delegate only to the five namespaced zilX execution agents and cannot delegate to the built-in agents. The complete `zilx-*` namespace is reserved, and unknown IDs or cross-boundary agent attachments are rejected. A session cannot switch across the built-in/zilX boundary; start a new session when changing between those agent families. ## Routing Lead delegates through OpenCode's built-in tool: ```text task(subagent_type="zilx-build", description, prompt) ``` For the selected role, zilX: 1. intercepts namespaced zilX task calls before execution; 2. reads the current OpenCode Provider catalog; 3. keeps models from connected Providers; 4. intersects them with the role leaderboard and selects the lowest rank number; 5. keeps the stable public agent ID and binds the selected model with a one-use route ticket; 6. lets OpenCode's native `task` implementation run the child Session and return its result. There is no cross-role fallback. If a role has no connected ranked model, zilX reports the currently available roles. ## `/loop` zilX also ships a Lead command for repeated execution in one persistent isolated child session: ```text /loop [--agent ] --max <1..100> [--compact-at <0.50..0.95>] -- ``` Defaults: `--agent build`, `--compact-at 0.80`. `--max` and the `--` delimiter are required. Each activation prompts the same stable public agent with the loop's fixed explicit model, and `max` includes the first activation. The target agent must call `zilx_loop_report` with `status: "satisfied"`, `"continue"`, or `"blocked"`; zilX never infers completion from prose. Terminal results are `satisfied`, `blocked`, `limit_reached`, `protocol_error`, `cancelled`, or `failed` and include loop/session/model IDs plus activation and compaction counts. `--agent` accepts logical role names only. Runtime aliases such as `zilx-build` are intentionally rejected. Before each activation after the first, zilX reads OpenCode v2 context telemetry for the selected model's fixed context limit. Occupancy is `input + output + reasoning` from the latest assistant telemetry; cache read/write fields are accounting subdivisions and are not added again. If occupancy is at or above `compact-at`, it compacts the child session and continues with a structured checkpoint containing the immutable goal, activation/max, and complete last report including evidence. V1 allows one active loop per parent session. Cancellation or plugin disposal aborts the active child session and rejects new loop starts while disposal is in progress. If v2 context or compaction APIs are unavailable, `/loop` fails clearly; ordinary native task routing is unaffected. ### Native task experience zilX no longer implements child Session execution itself. The parent displays OpenCode's native task UI, including child-session navigation, live activity, cancellation, result rendering, and supported foreground/background behavior. zilX's hook runs only before the native task starts. ## Architecture baseline zilX is organized as portable core plus an explicit OpenCode adapter. OpenCode-specific imports live under `src/adapters/opencode`; core routing, catalog, agent, loop, and port code is host-neutral. OpenCode loads the dedicated package server entry (`@macrsh/zilx/server` via package resolution), while the root package entry preserves the public API and the adapter can also be imported from `@macrsh/zilx/adapters/opencode`. ### Shadow Observation + Verification Receipt v1 The portable core now exports a shadow assurance layer. The OpenCode adapter observes supported tool lifecycle events and produces `VerificationReceiptV1` records with `scope: "observed_execution"` and `appliedMode: "unchanged"`: receipts describe one observed execution (currently one host tool invocation, including a `task`/`loop` delegation invocation) and may recommend `fast`, `guarded`, or `assured`, but do not change model choice, model turns, tool calls, task depth, or UI. Full cross-tool user-task aggregation is deferred. Receipts separate task outcome from verification status. Evidence has explicit source provenance (`host-observed`, `tool-reported`, `model-claimed`), purpose qualification (`lifecycle_observation` vs `verifier_result`), and result. Host observation alone is not verification: only host-observed verifier evidence with a passing result can make a receipt `verified`; failed/unknown verifier results do not. The receipt includes `authorizationRequired` from policy. Telemetry is bounded, in-memory, and non-persistent by default (closed receipts 200, open executions 64, evidence per execution 64, anomalies per execution 32, global/health anomalies 128, sink pending 16, external text/IDs 256 chars) and excludes prompts, tool args/output, tokens, and credentials. Read APIs perform TTL cleanup. Deferred items include automatic mode upgrades, Assured retry/review, persistent checkpoints, semantic classification, and user authorization enforcement. Breaking baseline changes: catalog data is bundled or explicitly injected only; removed catalog prose fields (`routerHint`, `agentInstruction`) are rejected; native `task_id` resume and old native-task compaction support were removed; zilX agent definitions are regenerated deterministically without merging unknown prior zilX fields; the OpenCode adapter fails fast if provider/session capabilities are unavailable. ## Installation Install the prebuilt package from npm: ```powershell npm install "@macrsh/zilx" ``` Installing from the npm registry requires Node 22 or newer and does not require Bun. To install directly from Git instead: ```powershell npm install "@macrsh/zilx@git+https://gitee.com/MacRsh/zilX.git#" ``` Git installation uses `prepare` to build `dist/` from the checkout, so that installation path also requires Bun 1.3.12 or newer. For local development: ```powershell npm install npm run build opencode plugin "file:///absolute/path/to/zilx" ``` For an installed package, configure the scoped plugin name; OpenCode resolves zilX's dedicated server entry, so no external bridge file is required. For local development, point at the package root that contains `package.json`; do not pass `dist/index.js`. Then select Lead as the default agent: ```json { "$schema": "https://opencode.ai/config.json", "plugin": ["@macrsh/zilx"], "default_agent": "lead" } ``` Local clone example: `"plugin": ["file:///absolute/path/to/zilx"]`. Restart OpenCode after changing its configuration. ## Prompt Templates The executable prompt source is [`src/prompts/prompt-templates.json`](src/prompts/prompt-templates.json). It contains role instructions, native-task wrapping text, and the conditional review template. Human-readable migration notes may explain policy changes, but the validated JSON template is canonical for runtime behavior. The plugin reads and validates this file once during startup; `npm run build` copies it to `dist/prompt-templates.json`. Restart OpenCode after editing or rebuilding it. Programmatic integrations may pass `promptTemplatesPath` to `createZilXPlugin()` to load another schema-compatible file. Tool permissions, delegation targets, role IDs, and model selection remain enforced by code rather than by the template. Lead owns orchestration, synthesis, judgment, and final acceptance. It may answer directly for no-tool work and may use its read-only tools directly for small, low-risk, clearly bounded checks such as reading one known file or running one precise search. It delegates when repository exploration, external sources, file changes, commands, review, difficult debugging, or specialist analysis is independently valuable. Delegation and concurrency are conditional: Lead does not split simple tasks for process, uses the minimum necessary parallelism, and only runs non-overlapping workstreams concurrently when the benefit is clear. For multi-stage Lead orchestration, analysis, planning, implementation, review, and fix are reportable phases only when they are genuinely lengthy, risky, multi-stage, or progress-relevant. Simple tasks do not require mechanical updates; when updates are warranted, Lead continues automatically after each update, and a parallel cohort produces one update after the cohort settles. Independent stages use fresh task sessions. Non-empty native `task_id` values are rejected by zilX's strict baseline instead of being resumed. The route boundary is pinned to the current OpenCode hook contract. `tool.execute.before` keeps `subagent_type` on its stable public ID and prepends a random, bounded, TTL-limited, one-use ticket to the child prompt. Before OpenCode saves or executes the child message, `chat.message` consumes that exact ticket, removes its marker, and changes only `message.model`; message agent, tools, permissions, and existing system text are unchanged. Missing, expired, repeated, ambiguous, or cross-role tickets throw from the non-isolated hook and cannot silently inherit the parent model. Provider routes are refreshed after the 15-second TTL without restarting OpenCode. The after hook only releases route-ticket bookkeeping for matching pending calls. It does not authenticate result envelopes for future resume. For technical reviews, Lead marks the Analyze task with `[zilx-review]`. zilX removes the marker and injects the full canonical `Review Record` only into that task, so ordinary Lead and Analyze prompts do not carry the large template. After a review, Lead gives every finding a disposition with rationale and evidence (`accept-now`, `reject-out-of-scope`, `defer`, or `needs-user-decision`) rather than accepting all by default. Fix tasks receive a self-contained Decision Brief with the original objective, constraints, acceptance criteria, and complete per-finding instructions. Quick may implement only a small, explicit, low-risk accept-now finding under a complete Decision Brief; broader or riskier fixes go to Build. User input is reserved for non-inferable product tradeoffs, irreversible or significantly risky actions, and mutually exclusive scope choices; independent accepted work continues while only dependent work pauses. The Review Record is evidence, not Build/Quick authorization, and Build does not assume access to the Analyze session or record. Fresh Analyze re-review is risk-driven; low-risk directly observable fixes may be accepted by Lead, but unverified accept-now work is not complete. ## Model Leaderboard The source of truth is [`src/catalog/models.json`](src/catalog/models.json). A model may be ranked in multiple roles and may declare multiple OpenCode Provider routes. ```json { "name": "example-model", "routes": ["provider/example-model", "other-provider/example-model"], "roles": { "build": { "rank": 1 } }, "capabilities": { "contextLength": 200000, "toolCall": true, "reasoning": "high", "vision": true, "cost": "medium", "latency": "medium" } } ``` Leaderboard rules: - `routes` use complete `provider/model` IDs and are checked in listed order. - Rank numbers are unique within each role; lower is preferred. - A model needs at least one role. - Removed prose fields such as `routerHint` and `agentInstruction` are rejected by the schema. - Capability fields are reserved for future routing policy and do not affect V1 selection. - Increase the top-level `revision` whenever publishing a new leaderboard. ## Catalog source The bundled leaderboard is immediately available and is the default source. Programmatic callers may explicitly inject a catalog through `createModelCatalogStore({ catalog })`. There is no automatic remote update, cache read, or source fallback chain. ## Verification Every test command has explicit short timeouts: ```powershell npm run typecheck npm run test:unit npm run test:integration ``` Unit and integration tests use a 5-second per-test timeout. Integration coverage composes the real plugin hooks, Provider catalog, native task argument rewriting, and model-bound agent registration in-process.