risorseartificiali/lince-add-supported-agent

lince-add-supported-agent

You are an AI assistant guiding the user through registering a new agent with the LINCE ecosystem (agent-sandbox + lince-dashboard). The output of this skill is user-side TOML config (plus an optional hook script), written to the user's $HOME. Nothing goes into the repo — shipped agents (claude, codex, gemini, opencode, pi, bash/zsh/fish) live in lince-dashboard/agents-defaults.toml and are out of scope.

References (consult as needed):

• references/config-schema.md — Field reference (sandbox + dashboard)
• references/examples.md — Shipped-agent configurations to model from
• references/hook-templates.md — Hook script skeletons (bash / TS / JS)
• scripts/validate-agent.sh — Post-registration validation, run as last step

---

1. Overview & Tier Model

Pick the tier first, before writing anything. Ask the user explicitly.

Tier A — Native hooks (rich status)

The agent runs an external program on lifecycle events (e.g. Claude Code's PreToolUse / Stop, Codex's notify, OpenCode events). Output:

• [agents.<key>] in ~/.agent-sandbox/config.toml
• [agents.<key>] in ~/.config/lince-dashboard/agents-defaults.toml with has_native_hooks = true and a populated [agents.<key>.event_map]
• Hook script in ~/.local/share/lince/hooks/<key>-status-hook.<ext>

Dashboard shows Running / INPUT / PERMISSION / Stopped for the agent's whole lifetime.

Tier B — Wrapper-only (Unknown)

The agent has no native hook system (raw shells, simple CLIs, or any binary you don't yet know how to instrument). Output: only the two TOML sections, has_native_hooks = false, no hook script, no event_map. The dashboard displays - (Unknown) for the agent's lifetime. This is honest, not broken.

Tier C — User contribution

Everything this skill produces is Tier C: it lives in the user's $HOME, never in the repo. Repo defaults are managed by update.sh.

State explicitly to the user: "If you are uncertain whether the agent has native hooks, pick Tier B. You can promote to Tier A later by writing a hook script and adding an event_map."

---

2. Hook Contract (Tier A only)

The dashboard accepts a single minimal JSON message per Zellij pipe write:

{"agent_id": "<id>", "event": "<native_event_name>"}

• agent_id — value of $LINCE_AGENT_ID, set by the dashboard when spawning the agent. The hook MUST exit 0 silently if this is empty.
• event — the native event name from the agent (e.g. PreToolUse, idle_prompt, agent-turn-complete). Do NOT translate inside the hook.

The dashboard resolves it in this order:

1. Look up event in [agents.<key>.event_map] → map to canonical
2. If unmapped, check whether event is itself a canonical name
3. Otherwise → Unknown + warning log line (no silent fallback)

Canonical events (the 5 m-15 states)

| Canonical | Meaning | |--------------|----------------------------------------------------| | running | Agent is actively working | | input | Agent is waiting on the user (user's turn) | | permission | Agent is asking approval for a tool / action | | stopped | Agent process ended (voluntary or error) | | unknown | Internal fallback only — do NOT emit from hooks |

Pipe name defaults to lince-status; override per-agent with status_pipe_name = "..." (e.g. Claude uses "claude-status").

After generation, verify wiring with:

echo '{"agent_id":"test","event":"running"}' | zellij pipe --name lince-status

---

3. Decision Tree (walk the user through in order)

1. Binary — Command name and install path (e.g. cursor-agent at ~/.local/bin/cursor-agent). Verify with command -v <binary>.
2. Config directory — Does the agent persist config / credentials on disk? (e.g. ~/.cursor/). This becomes home_ro_dirs. Empty list if none.
3. API key environment variables — Which env vars must reach the agent? (e.g. CURSOR_API_KEY). These populate [agents.<key>.env_vars].
4. Internal sandbox conflict — Does the agent itself use bwrap, Docker, or seccomp internally? If yes, find the CLI flag that disables it and set bwrap_conflict = true plus disable_inner_sandbox_args.
5. Has native lifecycle hooks? This is the Tier A vs B decision.
   • "Does the agent run an external program on tool use, idle, permission prompts, or exit?" → Tier A.
   • "No, it just runs and prints to stdout / takes stdin." → Tier B.
6. Hook language (Tier A only) — bash / TypeScript / JavaScript. Default to bash unless the agent's docs explicitly require a different runtime.

Confirm all answers back to the user before writing anything.

Derive the config key

Lowercase the binary name; replace spaces / underscores with hyphens; strip special characters (cursor-agent → cursor-agent, Bob_CLI → bob-cli). Show the derived key and ask for confirmation; allow override.

---

4. Generation Steps

Pre-flight: check the target files for an existing [agents.<key>] section and ask replace / keep / abort before overwriting. The skill is idempotent — re-running must update in place, never duplicate.

4.1 Sandbox TOML (always, both tiers)

Target file: ~/.agent-sandbox/config.toml.

[agents.<key>]
command = "<binary>"
default_args = [<headless args>]
env = { <API_KEY> = "$<API_KEY>" }
home_ro_dirs = ["<dir relative to ~>"]  # e.g. ".cursor" — no leading ~ or /
home_rw_dirs = []
bwrap_conflict = <true|false>
disable_inner_sandbox_args = [<args>]   # only when bwrap_conflict = true

4.2 Dashboard TOML (always, both tiers)

Target file: ~/.config/lince-dashboard/agents-defaults.toml (user overrides — merged on top of the repo defaults at load time).

[agents.<key>]
command = ["agent-sandbox", "run", "-p", "{project_dir}", "--id", "{agent_id}", "--agent", "<key>"]
display_name = "<Human Name>"
short_label = "<3 chars uppercase>"
color = "<color>"
sandboxed = true
has_native_hooks = <true|false>
pane_title_pattern = "agent-sandbox"
status_pipe_name = "lince-status"
providers = ["__discover__"]
sandbox_level = "normal"
home_ro_dirs = ["~/<dir>/"]   # with ~/ prefix here, unlike sandbox config

[agents.<key>.env_vars]
<API_KEY> = "$<API_KEY>"

LINCE defaults to apply without asking the user:

| Field | Default | Notes | |-------|---------|-------| | has_native_hooks | from Tier A/B | true only for Tier A | | status_pipe_name | "lince-status" | Reserved: "claude-status" for Claude | | sandboxed | true | Add <key>-unsandboxed variant only if asked | | pane_title_pattern | "agent-sandbox" (sandboxed) or <binary> (unsandboxed) | | | color | propose by name | red, green, yellow, blue, magenta, cyan, white | | short_label | first 3 chars uppercase | Pad with space if needed | | sandbox_level | "normal" | Omit for shells / no-provider agents |

4.3 Tier A only: event_map + hook script

Append an event_map sub-table mapping the agent's native event names to canonical events. Propose entries from the agent's docs; prompt the user if unknown. Example:

[agents.<key>.event_map]
"PreToolUse"     = "running"
"idle_prompt"    = "input"
"permission_prompt" = "permission"
"Stop"           = "stopped"

For Tier B: omit event_map entirely.

Write the hook script to ~/.local/share/lince/hooks/<key>-status-hook.<ext> using a template from references/hook-templates.md. The bash skeleton:

#!/usr/bin/env bash
set -uo pipefail
AGENT_ID="${1:-unknown}"
PIPE_NAME="${LINCE_PIPE:-lince-status}"

send() {
    local event="$1"
    local payload
    payload=$(printf '{"agent_id":"%s","event":"%s"}' "$AGENT_ID" "$event")
    if command -v zellij >/dev/null 2>&1 && [[ -n "${ZELLIJ:-}" ]]; then
        echo "$payload" | zellij pipe --name "$PIPE_NAME" 2>/dev/null || true
    fi
    mkdir -p /tmp/lince-dashboard
    echo "$payload" > "/tmp/lince-dashboard/${AGENT_ID}.state"
}

# TODO: customise the trigger logic for your agent.
# Example: parse stdin JSON, watch a file, etc., then call:
#   send "running"   |   send "input"   |   send "permission"   |   send "stopped"

Then chmod +x the file. Show the user the pipe test command from §2 and tell them what they still need to fill in (the event-detection logic).

4.4 Tier B only

Skip hooks. State explicitly to the user: "The dashboard will show - for this agent. That is expected — there is no signal to read."

---

5. Examples (reference implementations)

Point the user at these in-repo examples (read-only, ship with LINCE):

| Tier | Agent | Reference files | |------|-------|-----------------| | A (rich) | Claude Code | lince-dashboard/hooks/claude-status-hook.sh, [agents.claude] + [agents.claude.event_map] in lince-dashboard/agents-defaults.toml | | A (lean) | Codex | lince-dashboard/hooks/codex-status-hook.sh, [agents.codex] + [agents.codex.event_map] in lince-dashboard/agents-defaults.toml | | B | Gemini | [agents.gemini] with has_native_hooks = false (no event_map, no hook script) in lince-dashboard/agents-defaults.toml | | B | Bash / Zsh / Fish | [agents.bash] etc. — has_native_hooks = false, no providers, no event_map | | C | User-side | Anything generated by this skill, in ~/.config/lince-dashboard/agents-defaults.toml (same schema, $HOME instead of repo) |

See references/examples.md for full TOML snippets.

---

6. Validate

After writing, run:

bash <skill_dir>/scripts/validate-agent.sh <key>

The script:

• Parses both TOML files with python3 -c "import tomllib; ..." (FAIL on syntax error)
• Confirms [agents.<key>] exists in both files
• Verifies the binary is in PATH
• Tier A: syntax-checks the hook script (bash -n) and verifies every event_map value is a canonical event (running|input|permission|stopped)
• Tier B: confirms has_native_hooks = false and that no hook script and no event_map were written
• Prints PASS / FAIL summary

Report the output verbatim to the user. On failure, surface the message and offer to re-edit.

---

Important Notes

• The skill is idempotent — re-running for the same key updates in place.
• Never write into the repo's lince-dashboard/agents-defaults.toml. That file ships with LINCE and is managed by update.sh.
• All file writes go through this skill — never by hand instructions (project CLAUDE.md, no-manual-edits rule).
• The dashboard config file uses the same [agents.<key>] nested table form as the sandbox config. Field semantics differ (see references/config-schema.md) but the section header pattern is identical.
• event_map values are validated against the closed set {running, input, permission, stopped}. Typos cause silent dev-only warnings to stderr — the validate script catches them.
• Unknown / unmapped events resolve to Unknown with a warning, not a fallback.