Ikenga iyke (control bridge)

Register this agent so locks and timers can attribute work to it. Returns an opaque id. Pass the id as holder to iyke_lock_acquire. Repeated calls with the same {id} bump last_seen_at; omit id to mint a new one.

Cancel a running chi agent run by run_id.

List chi agent runs. Optionally filter by engine_id. Returns rows newest-first with runId, engineId, status, and brief.

Continue an existing chi agent run with a new prompt. Requires run_id from a previous iyke_chi_run or iyke_chi_list.

Start a new chi agent run against an engine. Returns { runId, status, output?, error? }. Use iyke_chi_status to poll for output. engine_id examples: claude-code, gemini, codex. mode controls permissions: plan, default, auto, bypassPermissions.

Get the current status and output of a chi run. Returns { runId, engineId, status, output?, error?, brief? }. Poll periodically after iyke_chi_run.

List Claude-config asset pins for a scope. Scope is "workspace" (cross-project) or "project:<id>" (this project only). Returns one entry per pin with preferred_tier + preferred_source.

Pin a preferred provider for a Claude-config asset name in a scope. When discovery finds the same asset name in multiple tiers (e.g. a `code-reviewer` agent in both ~/.claude/ and a project pkg), the lowest tier wins by default; a pin overrides that. Scope is "workspace" (cross-project) or "project:<id>" (this project only). preferred_tier is one of personal | workspace_pkg | project | project_pkg. preferred_source is the pkg id (or "personal" for ~/.claude/) — omit to match any source in the tier.

Remove a pinned resolution. Falls back to the default lowest-tier-wins rule.

List Claude-config assets (skills, agents, commands, hooks, mcps) discovered for a project, grouped by provider tier. Returns a tree where each asset name maps to one or more AssetSource entries; multiple entries on the same name indicate a conflict between tiers. Defaults to the active project; pass project_id to query a specific one. Use this to see what an agent will actually load in a project context.

Click an element. Specify exactly one of `ref` (from iyke_dom), `selector` (CSS), or `text` (innerText match). Refs are most reliable.

Close a pane (or the focused pane if pane_id omitted). Closes the entire pane and all its tabs — to close a single tab from the in-app keyboard, use ⌘⇧W (⌘W closes the whole pane). Refuses to close the last remaining pane.

Open Chrome DevTools for the main webview (debug builds only). Returns 503 in production builds.

Take an accessibility-tree snapshot of the focused pane. Returns Playwright-style text plus structured JSON. Each interactive element gets a stable ref like e1, e2; pass that ref to iyke_click / iyke_type / iyke_key. Refs invalidate on the next snapshot or page navigation. Use `query` for substring filter, `all=true` to include hidden elements.

Focus a specific pane. Provide either pane_id (leaf id from iyke_state response — shell.panes.leaves[].id) or index (1-based DFS leaf index, matching the in-app ⌃1..⌃6 keyboard shortcuts).

Navigate the focused pane to a route path inside the Ikenga desktop app (e.g. "/notes/today"). Path must start with "/". This replaces the focused pane's active tab content; use iyke_open with kind=route to add a new tab instead.

Send a fire-and-forget postMessage to an iframe pane. The iframe bridge listens for known kinds (e.g. "story-select") and acts on the payload. Use to drive mini-app actions from outside the running app.

Read the latest published state object for an iframe pane (storyboard cursor, comp current frame, etc.). Iframes call publishState(key, value) from their iyke-bridge to expose runtime state for inspection.

Dispatch a keyboard combo. Use names like "Enter", "Escape", "Tab", "ArrowDown", and modifiers Ctrl/Alt/Shift/Meta separated by + or , (e.g. "Ctrl+S", "Meta+K"). Optional `ref`/`selector` targets a specific element; otherwise the active element receives.

Delete a KV entry. Idempotent.

Read a JSON value at scope+key. Returns { key, value: null } if absent (200, not 404).

List KV entries in a scope. `prefix` filter narrows by key prefix.

Store a small JSON value at scope+key. Cap 64 KB per value; cap 1 MB total per scope. For larger durable text, use scratchpads. Scope defaults to active project.

Get the saved layout (pane tree, files-explorer state, panel sizes) for a project. Returns the raw layout_state row contents — each field is the JSON the shell wrote, or null when nothing has been saved for that key. Defaults to the active project; pass project_id to query a specific one. Useful for the conductor pattern (an agent inspecting "what does this project look like to the user").

Reset a project's saved layout — deletes the pane tree, files-explorer state, and panel sizes rows. Next time the user (or anyone) switches to this project, the layout-swap orchestrator finds no saved state and leaves the current view in place. Use this to recover from a wedged layout or as part of a clean-slate workflow.

Acquire a project-scoped lease lock on a named resource. Use for short-lived coordination around shared files, plans, migrations. holder is the agent id from iyke_agent_register. ttl_ms defaults to 60000 (clamped to [1000, 600000]). If wait_ms is set, blocks up to that long for an existing lock to expire.

Release a lock you hold. No-op if held by someone else or already expired.

Extend a lock you hold by ttl_ms. Useful for long-running work that needs more time than the original lease.

Check whether a resource is currently locked (active leases only). Returns held=false if the lease has expired.

Read recent console + error logs (last 500) from the running webview. Includes window error and unhandledrejection captures.

List MCP servers visible from a project. Returns each (server name × source) pair so conflicts across tiers are surfaced separately. Each entry reports: source tier (personal | workspace_pkg | project | project_pkg), provider (pkg id or "personal"), lifecycle (long-lived | per-call | on-demand), live state (running / parked / crashed / blocked / not-started / on-demand), and the source file path. Defaults to the active project; pass project_id to query a specific one.

Restart a supervised MCP server by pkg id. Restarts every long-lived MCP entry the pkg declares (the supervisor keys per pkg, not per server name). Useful when a child has wedged. Fails with 404 if the pkg is not supervised — per-call MCPs spawn fresh on every tool invocation and have nothing persistent to restart.

Switch the activity-bar sidebar mode. Valid modes: app, files, agents, sessions, settings, storyboard, video-engine, canvas-design, image-generator. The first five are core; the rest are mini-apps.

Read recent fetch + XHR network activity (last 100). Each entry has method, url, status, duration_ms, and error if it failed.

Open a new tab in the focused pane. `kind` selects the view type. For "route" pass `path`; "terminal" optionally `cmd` (a shell command string); "chat" requires `session_id`; "artifact" requires `path` (a single .html file); "artifact-studio" requires `path` plus optional `density` (grid for a folder, loupe for a single artifact, compare for two — with a `vs` sibling path); "artifact-grid" is a back-compat alias for `artifact-studio` at grid density; "mini-app" requires `name`.

Pause a batch of drafted actions into the Ikenga approve gate for operator sign-off (ux_mode: approve). Call this INSTEAD of performing the side effect (sending an email, posting, etc.) once you have drafted the outgoing items: it writes them to the gate at /outbox/approvals where the operator edits + approves, then STOP — the operator's approval drives the real send, not you. Each draft's `payload` must be `{ item: DraftItem, meta: ApproveGateMeta }` (the draft content + batch metadata).

Transition a pin from `open` to `in_progress`. Call this once you've read the pin and started working — the grid cell's pin dot flips to kola-amber so the user sees you're on it. Idempotent: later calls leave the existing `acknowledged_at` timestamp intact.

Fetch the full payload for an artifact-grid pin by id. The routing dispatcher pastes a short prompt referencing the pin id; call this tool to retrieve the structured context — artifact_path (the .html file on disk), selector (CSS selector inside the artifact iframe), text (the user's comment body), screenshot_path (local PNG of the targeted element, may be null), plus lifecycle stamps. Use the path + selector + text to reason about and execute the requested change. 404 if the pin no longer exists.

Transition a pin to `resolved`. Call this after committing the change you set out to make — the grid cell's pin dot flips to verdigris (resolved). Users can also resolve manually from the grid right-click menu; this is the agent-initiated path for closing the loop without bouncing back to the human. Stamps `resolved_at` on first transition; idempotent on re-calls.

Change the scope of an installed pkg. scope="workspace" (always loaded) or "project:<id>" (loaded only when that project is active). Triggers a kernel reconcile so sidecars start/stop accordingly.

List installed pkgs visible from the active project. Workspace-scoped pkgs are always included; project-scoped pkgs are included only when their project is active unless include_other_projects=true. Each entry: id, version, install_path, enabled, source, scope ("workspace" | "project:<id>"), active_now.

List trust state for every installed pkg. Returns one entry per pkg with state (auto_trusted / auto_granted / granted / needs_approval), declared sensitive permissions summary, and last grant timestamp when applicable. Use when surveying which third-party pkgs need user approval before their MCP tools can be invoked.

Get the trust state for a single installed pkg. Returns one of: auto_trusted (built-in com.ikenga.* shipped with the shell), auto_granted (no sensitive permissions declared), granted (user approved a specific manifest version), or needs_approval (sensitive perms declared but no current grant; either never approved, perms changed since last grant, or explicitly revoked). When state is needs_approval, MCP tools/call against this pkg returns the structured `trust_required` error until the user grants approval via Settings → Pkgs.

Uninstall a pkg. Stops its sidecars, removes its registry entries, deletes its files. Project-scoped state in iyke_kv / iyke_scratchpads / iyke_todos survives. Builtins (com.ikenga.*) cannot be uninstalled.

List kernel-level permission-violation audit rows newest-first. Today only `shell.execute` denials write here (a pkg attempted to spawn a binary outside its manifest's declared allowlist). Returns one entry per attempt with attempted (the resolved command), declared (the manifest allowlist at attempt time, comma-joined), scope_kind ('shell.execute'), pkg_id, and occurred_at (unix millis). Pass pkg_id to filter to one pkg; omit for a cross-pkg view. limit defaults to 100 and is hard-capped at 1000.

Archive a project (soft-delete — sets archived_at, no data removed). The project disappears from the default switcher list but its sessions/pkgs/todos remain on disk and can be restored by a later iyke_project_update if needed. Refuses to archive the built-in "Default" project. If the archived project was active, the shell falls back to Default automatically.

Create a new project in the Ikenga shell. Projects scope chats, installed pkgs, pane layouts, todos, scratchpads and cron jobs — switching project rebinds those surfaces. Slug `id` must match ^[a-z0-9][a-z0-9_-]{0,63}$ and be unique; `default` is reserved. `display_name` is freely Unicode, capped at 120 chars. `root_path` is optional but recommended — it becomes the cwd for new chats spawned inside the project. `color` is a hex string used for the activity-bar dot. Use when the user asks to set up a new working context (a codebase, a label, an experiment).

Return the currently active project (id, display_name, root_path, icon, color, description, position, is_default, created_at). Call this before iyke_project_set_active or any project-scoped mutation so an agent knows which project the user is in.

List projects in switcher order (position ASC, then created_at). Each entry has id, display_name, root_path, icon, color, description, position, is_default, created_at, archived_at. Archived projects are hidden by default — pass include_archived=true to surface them (e.g. when an agent is restoring an old project).

Switch the shell's active project. Subsequent new chats, scratchpads, todos and pkg installs default to this project; existing project-scoped TanStack queries (sessions, pkgs, todos, scratchpads, cron) refetch automatically. Does NOT navigate panes — pane contents stay put until a phase-2/6-aware surface reads the new active id. Fails if the id is unknown or archived.