@turmind/halo 0.1.9

package/templates/skills/acp/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: acp
+description: Talk to other agents over ACP — `/acp kiro <q>` (local Kiro), `/acp claude <q>` (local Claude Code) — and manage `ask-<label>` bindings for remote halo servers. Activate when the user wants to ask another agent something or wire up an ACP connection.
+command: /acp
+requiresAccess: full
+verbs:
+  - { name: kiro,   desc: Ask the local Kiro (rest of the line is the question) }
+  - { name: claude, desc: Ask the local Claude Code (rest of the line is the question) }
+  - { name: add,    desc: Generate an ask-<label> binding for a remote halo }
+  - { name: list,   desc: List generated ask-* binding skills }
+  - { name: remove, desc: Remove a generated ask-* binding skill }
+---
+
+# acp
+
+The requested action is **`$1`**; everything after it is the payload
+(`$ARGUMENTS` minus the first token). With natural language, infer both.
+
+## Direct ask verbs — kiro / claude
+
+The question is the rest of the line. The helper lives in this skill's
+directory under `templates/ask.py` — the workspace copy wins if it exists,
+else the global one (deterministic paths, no glob needed):
+
+- `<workspace>/.halo/skills/acp/templates/ask.py`
+- `~/.halo/global/skills/acp/templates/ask.py`
+
+Pick ASK = the first of those that exists, then run and relay the reply
+(quote short answers; summarize long ones — never paste the SESSION
+bookkeeping line):
+
+```bash
+# /acp kiro <question>            — local Kiro CLI
+shell_exec: python3 $ASK "<question>" --kind kiro --cwd {{workspace_root}}
+
+# /acp claude <question>          — local Claude Code
+shell_exec: python3 $ASK "<question>" --kind claude --cwd {{workspace_root}}
+```
+
+Remote halo servers are reached through generated bindings (`/ask-<label>`),
+not a direct verb — see add/list/remove below.
+
+- Follow-ups on the same topic: reuse the `SESSION:` id from the previous
+  call's stdout with `--session-id <id>` so the other agent keeps context.
+  If it errors with unknown session, drop the id and start fresh.
+- **The question text is passed verbatim** — including the OTHER agent's own
+  slash commands. Verified with kiro: sending `/model` as the question lists
+  its available models; `/model <full-model-id>` switches its model and saves
+  it as default (fuzzy names like `claude` are rejected — full id only, e.g.
+  `claude-opus-4.7`). Use this when the user asks to change the remote/local
+  agent's model or invoke its built-in commands. Other kinds may support their
+  own command sets the same way.
+- Failure modes: `not found in PATH` → that CLI isn't installed (kiro-cli /
+  claude-agent-acp / halo). Exit 124 → timed out, suggest a narrower question.
+  stopReason≠end_turn on stderr → pass it along with the partial reply.
+
+## Remote halo bindings — add / list / remove
+
+These verbs manage the GENERATED `ask-<label>` skills (one per remote halo,
+each with its own `/ask-<label>` command and settings namespace holding that
+remote's host/token).
+
+- **list** — enumerate `ask-*` skill dirs (workspace + global); report each
+  label and target.
+- **remove** — confirm, delete the chosen `ask-<label>` skill directory, and
+  mention the leftover `ask-<label>:` block in settings.yaml can be cleaned.
+- **add** — the generator flow below.
+
+## Add — generator flow
+
+Stamps out a new skill named `ask-<label>` that bridges this local agent to a different halo agent over the [ACP adapter](../../docs/dev/acp-adapter.md). One binding = one remote (host + port + token + workspace). Multiple bindings can coexist — each gets its own slash command (`/ask-sa-agent`, `/ask-prod`, …) and its own settings namespace.
+
+This is the **only supported path** to set up a new ACP binding — there's no longer a generic `ask-acp-agent` skill. The split is intentional: each remote needs its own `params.token`, and skill namespaces are 1:1 with skills.
+
+## Step 1 — collect inputs
+
+Required from the user:
+
+| Field | Notes |
+|---|---|
+| `label` | Slug — lowercase, hex/dash only (regex `^[a-z][a-z0-9-]*$`). Used for the skill id (`ask-<label>`), slash command (`/ask-<label>`), and settings namespace. Must not collide with an existing skill. Example: `sa-agent`, `prod-cluster`, `audit-ws`. |
+| `host` | Remote halo server hostname / IP. |
+| `port` | Remote halo server port. (halo kind only) |
+| `workspace` | Absolute path of the remote workspace on its server. |
+| `token` | Web-channel token from the remote halo's admin (Channels → Web → copy). Should be a `full` access token if you'll later want to override workspace per call. |
+
+Optional:
+
+| Field | Default |
+|---|---|
+| `label_display` | Pretty display name (e.g. "SA Agent"). Defaults to `label` capitalized. |
+| `agent_id` | Remote agent profile to use. Blank = remote `default`. |
+
+Also ask **scope**: install the skill **globally** (`~/.halo/global/skills/`, available to every workspace's agents) or **only in this workspace** (`<workspace>/.halo/skills/`). Default to "this workspace" if unsure — share-workspace and reorg are easier.
+
+## Step 2 — validate
+
+Before writing files:
+
+1. **Slug**: regex `^[a-z][a-z0-9-]*$`. Reject anything else.
+2. **Collision**: check whether `ask-<label>` already exists in the chosen scope. If yes, ask the user to pick a different label OR confirm overwrite.
+3. **`halo` binary**: confirm `halo` is on the PATH the local agent's `shell_exec` sees (`shell_exec: which halo`). If not, the binding will install but won't run — surface this and stop.
+
+## Step 3 — stage files
+
+The template directory is `~/.halo/global/skills/acp/templates/`. Copy + substitute placeholders. Three files per binding:
+
+```
+<scope-dir>/ask-<label>/
+├── SKILL.md       (from templates/SKILL.md.tmpl)
+├── config.yaml    (from templates/config.yaml.tmpl)
+└── ask.py         (verbatim copy of templates/ask.py — stays unchanged)
+```
+
+Where `<scope-dir>` is:
+
+- Global: `~/.halo/global/skills/`
+- Workspace: `<current-workspace>/.halo/skills/`
+
+### Placeholders
+
+Both `SKILL.md.tmpl` and `config.yaml.tmpl` use `{{NAME}}` markers. Substitute these literally — they're NOT halo `{{params.X}}` template syntax (those `{{params.X}}` strings should remain in the rendered output as-is so the runtime expands them at shell_exec time).
+
+| Placeholder | Replace with |
+|---|---|
+| `{{LABEL}}` | the slug (e.g. `sa-agent`) |
+| `{{LABEL_DISPLAY}}` | display name (defaults to `label_display` or capitalized label) |
+| `{{HOST}}` | host |
+| `{{PORT}}` | port |
+| `{{WORKSPACE}}` | remote workspace path |
+| `{{SKILL_DIR}}` | absolute path of the new skill dir; use this in the `python3 …/ask.py` line so the cmd works regardless of cwd |
+
+Implementation hint — small Python / shell pipeline works fine:
+
+```bash
+LABEL=sa-agent
+LABEL_DISPLAY="SA Agent"
+HOST=ec2-1-2-3-4.compute.amazonaws.com
+PORT=9527
+WORKSPACE=/home/ubuntu/sa-agent
+SCOPE_DIR=$HOME/.halo/global/skills           # or the workspace's .halo/skills
+SKILL_DIR=$SCOPE_DIR/ask-$LABEL
+TPL=$HOME/.halo/global/skills/acp/templates
+
+mkdir -p "$SKILL_DIR"
+sed -e "s|{{LABEL}}|$LABEL|g" \
+    -e "s|{{LABEL_DISPLAY}}|$LABEL_DISPLAY|g" \
+    -e "s|{{HOST}}|$HOST|g" \
+    -e "s|{{PORT}}|$PORT|g" \
+    -e "s|{{WORKSPACE}}|$WORKSPACE|g" \
+    -e "s|{{SKILL_DIR}}|$SKILL_DIR|g" \
+    "$TPL/SKILL.md.tmpl" > "$SKILL_DIR/SKILL.md"
+sed -e "s|{{LABEL}}|$LABEL|g" \
+    -e "s|{{LABEL_DISPLAY}}|$LABEL_DISPLAY|g" \
+    -e "s|{{HOST}}|$HOST|g" \
+    -e "s|{{PORT}}|$PORT|g" \
+    -e "s|{{WORKSPACE}}|$WORKSPACE|g" \
+    "$TPL/config.yaml.tmpl" > "$SKILL_DIR/config.yaml"
+cp "$TPL/ask.py" "$SKILL_DIR/ask.py"
+chmod +x "$SKILL_DIR/ask.py"
+```
+
+If any path contains `|` (rare), pick a different sed delimiter or use Python.
+
+## Step 4 — write **all** params to settings.yaml
+
+Halo's shell_exec `{{<id>.params.X}}` substitution reads from `settings.yaml` and does NOT fall back to `config.yaml` `default:`. Config.yaml defaults are *only* used as form placeholders in the admin Settings UI. So at install time we must write every value the helper script needs (host, port, workspace, token, label) into settings.yaml — otherwise the SKILL.md's `python3 ask.py ... --host {{params.host}}` will pass through as a literal `{{...}}` to shell_exec and break.
+
+Choose the file by scope:
+
+- **Workspace scope**: `<workspace>/.halo/settings.yaml`
+- **Global scope**: `~/.halo/secrets/settings.yaml`
+
+Merge into the file (don't overwrite — there may be other namespaces already there):
+
+```yaml
+ask-<label>:
+  params:
+    host: <host>
+    port: "<port>"             # quote so YAML keeps it as a string
+    workspace: <workspace>
+    label: <label_display>
+    token: <token>
+    # agent_id intentionally omitted (default empty); ask.py drops blank flags
+```
+
+Use Python for the merge — yaml-aware, won't trash existing keys:
+
+```python
+import yaml, pathlib
+p = pathlib.Path("<settings-path>")
+data = yaml.safe_load(p.read_text()) if p.exists() else {}
+if not isinstance(data, dict):
+    data = {}
+ns = data.setdefault("ask-<label>", {})
+params = ns.setdefault("params", {})
+params["host"] = "<host>"
+params["port"] = "<port>"
+params["workspace"] = "<workspace>"
+params["label"] = "<label_display>"
+params["token"] = "<token>"
+p.parent.mkdir(parents=True, exist_ok=True)
+p.write_text(yaml.safe_dump(data, allow_unicode=True, sort_keys=False))
+```
+
+## Step 5 — wire into the agent that should use it
+
+The new skill exists but no agent will activate it until it's listed in an agent's `skills:` array. Two paths:
+
+- **The current workspace's `default` agent**: read `<workspace>/.halo/agents/default/agent.yaml` (or whichever agent the user is talking to right now), add `ask-<label>` to its `skills:` list, write back.
+- **Skip and let the user do it**: surface the path + tell them.
+
+Default behavior: edit the **current agent's** yaml automatically; if the agent has no workspace-local yaml (i.e. it inherits a global agent), tell the user "add `ask-<label>` to your agent's skills list to enable" and surface the path.
+
+## Step 6 — confirm
+
+Reply with:
+
+- The four paths created (SKILL.md, config.yaml, ask.py, settings.yaml entry).
+- The new slash command (`/ask-<label>`) the user can now type.
+- A reminder that admin Settings → Skills → Ask <Label_Display> will show the form with the token already filled.
+- One example invocation:
+
+> All set! Two ways to use it:
+>
+> - Type the slash command directly: `/ask-{{label}} What was our EC2 spend this month?`
+> - Or just mention the remote in chat: "ask {{label_display}} for this month's EC2 spend"
+>
+> The token is stored at {{settings_path}}; you can edit it in Admin → Settings → Skills → Ask {{label_display}}.
+
+## Patterns that go sideways
+
+- **Picking a label that contains uppercase / underscores** — file system ok, but `command: /ask-<label>` slash command names are case-sensitive and ugly. Stick to lowercase + dashes.
+- **Forgetting to wire the agent** — the binding installs cleanly but the agent never sees it (silently absent). Always do step 5 or be explicit about why you skipped.
+- **Putting the token into config.yaml `default:`** — config.yaml is committed code; settings.yaml is per-install secrets. Don't cross the streams.
+- **Reusing the same `label` for two different remotes** — Settings namespace collision. Detect at step 2.

package/templates/skills/acp/templates/SKILL.md.tmpl

@@ -0,0 +1,74 @@
+---
+name: Ask {{LABEL_DISPLAY}}
+description: Ask a question to the {{LABEL_DISPLAY}} halo agent (running on {{HOST}}:{{PORT}}, workspace {{WORKSPACE}}) over ACP. Activate when the user names this remote ("ask {{LABEL}}…", "the {{LABEL_DISPLAY}} agent") or asks something only that workspace's agent has data / tools for. Returns the remote agent's reply as text.
+command: /ask-{{LABEL}}
+---
+
+# Ask {{LABEL_DISPLAY}}
+
+This binding talks to the **{{LABEL_DISPLAY}}** halo agent at `{{HOST}}:{{PORT}}`, workspace `{{WORKSPACE}}`. It spawns `halo acp`, pipes JSON-RPC over stdio, forwards the prompt, streams the reply back as text.
+
+**When to use this**:
+
+- The user names this remote ("ask {{LABEL}}…", "the {{LABEL_DISPLAY}} agent") — direct signal.
+- The user asks something only `{{WORKSPACE}}` has the credentials / files / context for, and your local workspace doesn't.
+
+**When NOT to use it**:
+
+- The local agent can answer it itself.
+- The user's question is workspace-meta ("list my files", "what skills do I have") — that's local.
+- A different remote binding fits better (run `/help` to see all `/ask-*` commands; pick the closest match by label).
+
+## Invoke
+
+Sibling helper: this skill's directory contains `ask.py`. Always quote the user's question as the FIRST positional arg:
+
+```bash
+shell_exec: python3 {{SKILL_DIR}}/ask.py \
+  "<the user's question, in the language they asked it>" \
+  --host {{params.host}} \
+  --port {{params.port}} \
+  --workspace {{params.workspace}} \
+  --token {{params.token}}
+```
+
+If `params.agent_id` is non-blank, append `--agent-id {{params.agent_id}}`. Skip when blank — `ask.py` also drops blank / unsubstituted-`{{…}}` agent-ids defensively, but cleaner not to pass it at all.
+
+stdout looks like:
+
+```
+SESSION: <session-id>
+---
+<remote agent's reply text>
+```
+
+The session id is the ACP session — keep it for follow-up turns.
+
+### Threading (multi-turn on the same remote conversation)
+
+Sequences of related questions ("what's the AWS bill", "now break down Bedrock", "now show RDS by region") should reuse the same remote session so the remote agent sees full history. Parse the `SESSION:` line from the first call's stdout; on follow-ups append `--session-id <id>`:
+
+```bash
+shell_exec: python3 {{SKILL_DIR}}/ask.py \
+  "<follow-up question>" \
+  --host {{params.host}} --port {{params.port}} \
+  --workspace {{params.workspace}} --token {{params.token}} \
+  --session-id <id-from-previous-call>
+```
+
+If a follow-up says `unknown session: <id>` on stderr, the remote session was deleted — drop the id and start fresh.
+
+## Reply format
+
+> Asked **{{params.label}}** — here's the reply:
+>
+> <copy or summarize the response>
+
+Quote directly when short. Summarize multi-section replies and offer to dig deeper. Don't paste the SESSION line — that's bookkeeping.
+
+## Failure modes
+
+- **HTTP 401**: token wrong / disabled. Tell the user to fix `ask-{{LABEL}}.params.token` in Settings → Skills → Ask {{LABEL_DISPLAY}}.
+- **`fetch failed`**: server `{{HOST}}:{{PORT}}` unreachable.
+- **Timeout (exit 124)**: remote prompt > 10 min. Offer narrower question.
+- **stopReason ≠ end_turn**: stderr includes `stopReason=cancelled|refusal`. Pass along with the partial reply.

package/templates/skills/acp/templates/ask.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""ask.py — call an agent over ACP: remote halo server, local Claude Code, or local Kiro. See SKILL.md."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from typing import Any
+
+
+def fail(msg: str, code: int = 1) -> None:
+    sys.stderr.write(f"[ask-acp-agent] {msg}\n")
+    sys.exit(code)
+
+
+def main() -> None:
+    p = argparse.ArgumentParser(prog="ask.py", description="Ask a remote agent over ACP.")
+    p.add_argument("question")
+    p.add_argument("--kind", default="halo", choices=["halo", "claude", "kiro"],
+                   help="halo: remote halo server via `halo acp`; claude: local Claude Code via `claude-agent-acp`; kiro: local Kiro via `kiro-cli acp`.")
+    p.add_argument("--host")
+    p.add_argument("--port")
+    p.add_argument("--token")
+    p.add_argument("--workspace")
+    p.add_argument("--cwd", default=None, help="claude kind: working directory for the session (defaults to CWD).")
+    p.add_argument("--agent-id", default=None)
+    p.add_argument("--session-id", default=None)
+    p.add_argument("--timeout", type=int, default=600)
+    p.add_argument("--halo-bin", default=None)
+    p.add_argument("--claude-bin", default=None)
+    p.add_argument("--kiro-bin", default=None)
+    args = p.parse_args()
+
+    if args.kind == "claude":
+        bin_ = args.claude_bin or os.environ.get("CLAUDE_ACP_BIN") or "claude-agent-acp"
+        if shutil.which(bin_) is None and not os.path.isabs(bin_):
+            fail(f"`{bin_}` not found in PATH. npm install -g @agentclientprotocol/claude-agent-acp, or set --claude-bin.", 2)
+        cmd = [bin_]
+    elif args.kind == "kiro":
+        bin_ = args.kiro_bin or os.environ.get("KIRO_ACP_BIN") or "kiro-cli"
+        if shutil.which(bin_) is None and not os.path.isabs(bin_):
+            fail(f"`{bin_}` not found in PATH. Install Kiro CLI, or set --kiro-bin.", 2)
+        # --trust-all-tools: the binding is a headless relay; there's no human
+        # at this end to answer kiro's per-tool permission prompts.
+        cmd = [bin_, "acp", "--trust-all-tools"]
+        if args.agent_id and not args.agent_id.startswith("{{"):
+            cmd += ["--agent", args.agent_id]
+    else:
+        for k in ("host", "port", "token", "workspace"):
+            if not getattr(args, k):
+                fail(f"--{k} is required for --kind halo", 2)
+        halo = args.halo_bin or os.environ.get("HALO_BIN") or "halo"
+        if shutil.which(halo) is None and not os.path.isabs(halo):
+            fail(f"`{halo}` not found in PATH. Install @turmind/halo or set --halo-bin.", 2)
+        cmd = [halo, "acp", "--host", args.host, "--port", str(args.port),
+               "--token", args.token, "--workspace", args.workspace]
+    # Drop `--agent-id` when blank OR an unsubstituted `{{...}}` literal.
+    # Both mean "user hasn't configured this optional field" — the first
+    # because settings.yaml has `agent_id: ""`, the second because the
+    # key isn't in settings.yaml at all and halo's shell_exec
+    # substitute leaves the placeholder verbatim (its "fail loud"
+    # contract for required params). For an optional flag like this, we
+    # want graceful degrade, not a literal-as-value going to acp.
+    aid = (args.agent_id or "").strip()
+    if aid and not (aid.startswith("{{") and aid.endswith("}}")):
+        cmd += ["--agent-id", aid]
+
+    proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                            stderr=subprocess.PIPE, text=True, bufsize=1)
+    assert proc.stdin and proc.stdout and proc.stderr
+
+    def _drain_stderr() -> None:
+        for line in proc.stderr:
+            sys.stderr.write(line)
+    threading.Thread(target=_drain_stderr, daemon=True).start()
+
+    next_id = 1
+    pending: dict[int, dict[str, Any]] = {}
+    chunks: list[str] = []
+
+    def send(method: str, params: dict[str, Any] | None = None) -> int:
+        nonlocal next_id
+        rid = next_id
+        next_id += 1
+        msg = {"jsonrpc": "2.0", "id": rid, "method": method}
+        if params is not None:
+            msg["params"] = params
+        proc.stdin.write(json.dumps(msg) + "\n")
+        proc.stdin.flush()
+        return rid
+
+    def wait_for(rid: int, deadline: float) -> dict[str, Any]:
+        while True:
+            if rid in pending:
+                return pending.pop(rid)
+            if time.time() > deadline:
+                proc.kill()
+                fail(f"timeout waiting for response to request {rid}", 124)
+            line = proc.stdout.readline()
+            if line == "":
+                rc = proc.wait(timeout=1)
+                fail(f"adapter exited prematurely (rc={rc})", rc or 1)
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except json.JSONDecodeError:
+                sys.stderr.write(f"[ask-acp-agent] non-JSON: {line[:200]}\n")
+                continue
+            if "id" in msg and ("result" in msg or "error" in msg):
+                pending[msg["id"]] = msg
+                continue
+            method = msg.get("method")
+            if method == "session/update":
+                update = (msg.get("params") or {}).get("update") or {}
+                if update.get("sessionUpdate") == "agent_message_chunk":
+                    text = (update.get("content") or {}).get("text", "")
+                    if text:
+                        chunks.append(text)
+
+    deadline = time.time() + args.timeout
+    try:
+        rid = send("initialize", {"protocolVersion": 1, "clientCapabilities": {}})
+        resp = wait_for(rid, deadline)
+        if "error" in resp:
+            fail(f"initialize failed: {resp['error']}")
+
+        if args.session_id:
+            # ACP session/load requires cwd + mcpServers (same as session/new);
+            # kiro-cli exits silently if they're missing.
+            load_params: dict[str, Any] = {"sessionId": args.session_id}
+            if args.kind in ("claude", "kiro"):
+                load_params["cwd"] = args.cwd or os.getcwd()
+                load_params["mcpServers"] = []
+            rid = send("session/load", load_params)
+            resp = wait_for(rid, deadline)
+            if "error" in resp:
+                fail(f"session/load failed: {resp['error']}")
+            session_id = args.session_id
+        else:
+            new_params = {"cwd": args.cwd or os.getcwd(), "mcpServers": []} if args.kind in ("claude", "kiro") else {}
+            rid = send("session/new", new_params)
+            resp = wait_for(rid, deadline)
+            if "error" in resp:
+                fail(f"session/new failed: {resp['error']}")
+            session_id = resp["result"]["sessionId"]
+
+        rid = send("session/prompt", {
+            "sessionId": session_id,
+            "prompt": [{"type": "text", "text": args.question}],
+        })
+        resp = wait_for(rid, deadline)
+        if "error" in resp:
+            fail(f"session/prompt failed: {resp['error']}")
+        stop_reason = resp["result"].get("stopReason", "unknown")
+
+        sys.stdout.write(f"SESSION: {session_id}\n---\n")
+        sys.stdout.write("".join(chunks).rstrip() + "\n")
+
+        if stop_reason != "end_turn":
+            sys.stderr.write(f"[ask-acp-agent] stopReason={stop_reason}\n")
+    finally:
+        try: proc.stdin.close()
+        except Exception: pass
+        try: proc.wait(timeout=5)
+        except subprocess.TimeoutExpired: proc.kill()
+
+
+if __name__ == "__main__":
+    main()

package/templates/skills/acp/templates/config.yaml.tmpl

@@ -0,0 +1,33 @@
+displayName: Ask {{LABEL_DISPLAY}}
+description: Forward a question to the {{LABEL_DISPLAY}} halo agent over ACP.
+
+params:
+  - key: host
+    description: Remote halo server hostname or IP.
+    description_zh: 远端 halo server 主机名 / IP。
+    default: "{{HOST}}"
+
+  - key: port
+    description: Remote halo server port.
+    description_zh: 远端 halo server 端口。
+    default: "{{PORT}}"
+
+  - key: workspace
+    description: Absolute path of the remote workspace to drive.
+    description_zh: 要驱动的远端 workspace 绝对路径。
+    default: "{{WORKSPACE}}"
+
+  - key: label
+    description: Friendly name for the remote, shown when reporting back to the user.
+    description_zh: 报告给用户时使用的称呼。
+    default: "{{LABEL_DISPLAY}}"
+
+  - key: agent_id
+    description: Optional remote agent profile id. Blank = remote 'default'.
+    description_zh: 可选的远端 agent id，留空则用远端 default。
+    default: ""
+
+  - key: token
+    description: Web-channel token from the remote halo admin. Must be a full-access token if cross-workspace addressing is needed.
+    description_zh: 远端 halo 后台 Web channel token。若需跨 workspace 调用必须是 full 权限。
+    secret: true

package/templates/skills/agent/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: agent
+description: Create or update agent configurations (agent.yaml + AGENT.md). Activate when the user wants to add a new agent or change an existing agent's model / tools / skills / behavior.
+command: /agent
+verbs:
+  # builtin verbs — access is set in code (SUBCOMMAND_ROUTES); shown here for reference
+  - { name: list,   builtin: true,  desc: List usable agents }
+  - { name: switch, builtin: true,  desc: Start a session with an agent }
+  - { name: desc,   builtin: true,  desc: Show an agent's model / tools / skills }
+  - { name: delete, builtin: true,  requiresAccess: full, desc: Delete an agent (workspace or global) }
+  # skill verbs — access enforced from here
+  - { name: create, builtin: false, requiresAccess: full, desc: Create a new agent }
+  - { name: update, builtin: false, requiresAccess: full, desc: Modify an existing agent }
+---
+
+# agent
+
+Create or modify agent configurations. An agent lives in a directory holding
+`agent.yaml` (model, tools, skills, context) and optional `AGENT.md` (behavior)
+/ `USER.md`.
+
+This skill body handles **create** and **update** — the actions that need to
+author files. `list` / `switch` / `desc` / `delete` are handled directly by the
+`/agent` command and never reach here. The requested action is **`$1`** (full
+args: `$ARGUMENTS`); if invoked by natural language, infer it from the request.
+
+## Locations & scope rules (read before create/update)
+
+- `<workspace>/.halo/agents/<agent-id>/` — workspace-scoped
+- `~/.halo/global/agents/<agent-id>/` — shared across all workspaces
+
+A workspace agent **overrides** a global one with the same id at runtime.
+Consequences you must apply:
+
+- **Create**: ask (or infer from the request) which scope. Default to
+  **workspace** unless the user says "global" / "all workspaces". If creating a
+  workspace agent whose id already exists globally, say so — the new file will
+  shadow the global one in this workspace.
+- **Update**: resolve which file is actually in effect FIRST — check the
+  workspace path, fall back to global. Edit the file that exists; if both
+  exist, edit the workspace one (it's the live one here) unless the user
+  explicitly says to change the global. Never edit global to fix behavior in
+  one workspace when a workspace copy shadows it — that edit would have no
+  effect here.
+- **Built-in agents** (`default`, `executor`, `deep-executor`, internal
+  `__*__`): their global copies are force re-seeded on every server start —
+  direct edits to those global files are lost. To customize a built-in, copy
+  it to workspace scope and edit there.
+
+## Create
+
+Generate `agent.yaml`:
+
+```yaml
+name: <AgentName>
+description: <one-line description shown in the agent picker>
+priority: 50            # higher = appears earlier in the picker
+model:
+  provider: aws-bedrock-claude-invoke
+  id: global.anthropic.claude-sonnet-4-6
+  endpoint: https://bedrock-runtime.us-east-1.amazonaws.com
+  promptCaching: 1h     # optional: Bedrock prompt caching ('1h' or '5m')
+  thinking:
+    enabled: true
+    effort: medium      # off | low | medium | high | xhigh
+system_prompt: >
+  <Brief one-paragraph role statement. Keep behavioral detail in AGENT.md.>
+context:
+  maxTokens: 200000
+  compressAt: 0.8       # auto-compact at 80%
+tools:
+  - file_read
+  - file_write
+  - file_edit
+  - file_list
+  - shell_exec
+  - grep
+  - glob
+  - web_fetch
+  - view_image
+  # Session/delegation tools (start_session, query_session, query_agent, …) are
+  # NOT listed here — they're granted automatically by a non-empty `team`
+  # (see below). Listing them in `tools:` has no effect.
+team:                     # optional — presence is the delegation switch
+  - executor              # add the agent ids this one may spawn
+skills:
+  - <skill-id>
+```
+
+**Required:** `model.provider` (must match an id in `~/.halo/global/models/<provider>.yaml`),
+`model.id`, `model.endpoint` — the server rejects sessions missing any of these.
+
+**Model choice:** Sonnet 4.6 is the default workhorse. Opus 4.8
+(`global.anthropic.claude-opus-4-8`) when the task visibly needs deeper
+reasoning (costs more — not the default). Haiku 4.5 for fast, lightweight work.
+
+**Thinking:** `medium` is a good default; `high`/`xhigh` only for deep-reasoning
+agents; `enabled: false` to turn it off entirely.
+
+**Delegation (`team`):** the `team` field is the on/off switch for delegation,
+not just a filter. A **non-empty** `team: [agent-id, ...]` is what grants the
+agent the whole session-tool bundle — `start_session`, `query_session`,
+`interrupt_session`, `stop_session`, `archive_session`, `session_list`,
+`get_session_output`, `query_agent` — plus the injected roster. The listed ids
+are also exactly who it can reach: the roster, `start_session`, and
+`query_agent` all honor the list. **Omit `team` (or leave it empty) and the
+agent cannot delegate at all** — no session tools, no roster. There's no way to
+hand-list the session tools under `tools:` anymore; the capability rides
+entirely on `team`. To let an agent spawn parallel copies of itself, include
+its own id in the list (as the `default` agent does with `default`).
+
+Then write **`AGENT.md`** (behavior doc, read as part of the system prompt) —
+keep `system_prompt` brief and put the detail here:
+
+1. Role and scope — what it's for, what it isn't
+2. When to use which tool — concrete decision rules
+3. Output style — format, tone, length
+4. Constraints — what it must not do, when to ask
+
+Optionally write **`USER.md`** if the agent needs to know who the user is
+(name, role, language, domain). Workspace `USER.md` overrides global.
+
+## Update
+
+`file_read` the target `agent.yaml`, change only the requested fields, write it
+back. Common edits: switch `model.id`, adjust `thinking.effort`, add/remove a
+tool or skill, rewrite `system_prompt` (or edit `AGENT.md` for behavior). Don't
+rewrite untouched fields. Confirm the agent id and scope first if ambiguous.