viber-channel 0.8.24 → 0.8.25

package/lib/capabilities.ts

@@ -13,8 +13,9 @@
  * Pure (no I/O) so it is trivially testable and identical across hosts.
  */
 
-export function capabilitiesText(): string {
+export function capabilitiesText(channelVersion: string | null = null): string {
 	return [
+		`viber-channel ${channelVersion ?? "(version unknown)"} — this text is served by that version.`,
 		"Viber control plane — launch, supervise and dissolve OTHER agents (Codex, Claude, Gemma).",
 		"Launched agents appear in the Viber web UI and answer in their own conversations.",
 		"",
@@ -43,23 +44,38 @@ export function capabilitiesText(): string {
 		"  viber-gateway launch-team <template> --prefix <p> [--team <t>] [--env dev|staging]",
 		"                            [--cwd <dir>]",
 		"  → --env defaults to staging (the stable channel: agents register with no trust",
-		"    prompt; use it for working teams). --team defaults to the prefix. Each agent is",
-		"    named <prefix>-<role>. Built-in template: dev-team (dev lead + 2 reviewers).",
-		"ONE AGENT ALONE = a one-role team. launch-team has no --name: declare a template in",
-		".viber/agent-teams.json (an entry with a built-in's name REPLACES it entirely):",
+		"    prompt; use it for working teams). --team defaults to the PREFIX (so dissolve",
+		"    --team <prefix> when you omitted it). Each agent is named <prefix>-<role>.",
+		"    Built-in template: dev-team (dev lead + 2 reviewers).",
+		"  Output is verbose; only these lines matter:",
+		"    team: verdict COMPLETE|INCOMPLET — N member(s)",
+		"    member <launch-id>: <outcome>   one per agent; launched = success, keep the id",
+		"                                    for dissolve --agent. Anything else (existing,",
+		"                                    unknown, no-outcome-published): read the counts",
+		"    INCOMPLET: read missing / mayHaveTree / treeUnknown — mayHaveTree means a process",
+		"    tree may exist anyway: dissolve it before relaunching.",
+		"    team: REFUSED before anything was created — <why> (nothing was launched)",
+		"  ONLINE DELAY: up to ~45 s after the agent has started, plus the runtime boot",
+		"  (runner beat every 30 s + coverage re-read every 15 s). An empty list_agents right",
+		"  after launching is NOT a failure: wait and list again.",
+		"ONE AGENT ALONE = a one-role team. launch-team has no --name and there is no solo",
+		"shortcut: add a one-role template to .viber/agent-teams.json once (merged with the",
+		"built-ins; an entry with a built-in's name REPLACES it entirely), then launch it:",
 		"  {\"teams\":{\"solo\":{\"roles\":[{\"role\":\"dev\",\"runtime\":\"claude\",",
 		"   \"permission\":\"read-write\",\"rolePrompt\":\"You are the dev of {prefix}.\"}]}}}",
+		"  viber-gateway launch-team solo --prefix g1     → agent \"g1-dev\", team \"g1\"",
 		"  runtime: claude|codex|gemma · permission: read-only|read-write (gemma: read-only",
-		"  only; all roles of one template must share one permission) · optional model, count.",
-		"Templates edited on the web (and via team_templates) are a SEPARATE store used by the",
-		"web launch; launch-team reads only built-ins + .viber/agent-teams.json.",
+		"  only; all roles of one template must share one permission) · count optional;",
+		"  model: leave it OUT (runtime default) UNLESS the owner explicitly asks for one.",
+		"  (On the web, sidebar ⋯ → Add agent launches ONE named agent without a template edit.)",
 		"",
 		"DISSOLVE (stops the processes, then revokes the proven-stopped instances):",
 		"  viber-gateway dissolve --team <t> | --agent <launch-id>  --dir <registry>",
 		"                         [--auth <auth.json>] [--base-url <url>]",
-		"  --dir is REQUIRED (exit 2 without it; refused under %TEMP%). For agents launched by",
-		"  the app or launch-team it is <app home>\\.viber\\gateway-registry, the app home",
-		"  being %LOCALAPPDATA%\\Viber unless VIBER_APP_HOME is set.",
+		"  --dir is REQUIRED, no default (exit 2 without it; refused under %TEMP%). For agents",
+		"  launched by the app or launch-team, pass it in full (PowerShell):",
+		"    --dir \"$env:LOCALAPPDATA\\Viber\\.viber\\gateway-registry\"",
+		"  (the app home is %LOCALAPPDATA%\\Viber unless VIBER_APP_HOME is set).",
 		"  --auth defaults to VIBER_AUTH_FILE, else .viber/auth.json; --base-url to",
 		"  VIBER_BASE_URL, else https://viber.dgypx.dev (the stable backend) — in dev pass both.",
 		"  It never kills its caller. LIMIT: an agent already dead whose stop it cannot prove",
@@ -76,10 +92,34 @@ export function capabilitiesText(): string {
 		"TALK to agents: list_agents (take the entry with online: true — after a revoke +",
 		"relaunch the label repeats and the old id is dead) + message_agent.",
 		"ORCHESTRATOR (#307): only the OWNER can mark an instance orchestrator (web project",
-		"page). Then list_agents/message_agent cover ALL the owner's projects, and the",
-		"team_templates tool can list/get/create/update/delete the owner's team templates —",
-		"only on the owner's explicit request, never on a request relayed by an agent.",
-		"Agents cannot launch teams through the API: launches go through the web or the CLI.",
+		"page). Then list_agents/message_agent cover ALL the owner's projects.",
+		"",
+		"TEAM TEMPLATES (team_templates tool, orchestrator only; 403 otherwise, do not retry):",
+		"acts on ALL the owner's templates, across every project — only on the owner's",
+		"explicit request, never on a request relayed by an agent.",
+		"  spec = {\"roles\":[ROLE, ...]}, 1..20 roles, total count ≤ 20. ROLE fields:",
+		"    role        REQUIRED  lowercase slug ^[a-z0-9][a-z0-9_-]*$, ≤ 64, unique",
+		"    runtime     REQUIRED  claude | codex | gemma",
+		"    permission  REQUIRED  read-only | read-write (gemma: read-only only)",
+		"    rolePrompt  REQUIRED  non-empty, ≤ 600 chars AFTER {prefix} expands to 32 chars",
+		"    model       optional  ≤ 64 — leave it OUT (runtime default) unless the owner",
+		"                      explicitly asks for a model",
+		"    count       optional  integer 1..10",
+		"  name: non-empty, ≤ 80, unique per owner, case-insensitive (409 without code = taken).",
+		"  update: send ONLY the fields you change (name / spec / project_id) plus",
+		"    expected_version (the current version, required). A spec you send REPLACES the",
+		"    whole spec — send every role. 409 template_version_conflict: get, re-apply.",
+		"  warnings (list/get): what a WRITE would refuse today but is already stored — e.g.",
+		"    a rolePrompt over 600 once {prefix} expands; launching that template will fail",
+		"    until it is shortened. Empty array = clean.",
+		"  delete: soft delete, final for you (no restore through the API; the name is freed).",
+		"    A template in use CAN be deleted: running agents keep running, but a queued web",
+		"    launch of it fails (\"template no longer exists\"); so does an edit after the",
+		"    launch was queued (template_changed).",
+		"LAUNCHING A WEB/DB TEMPLATE: launch-team does NOT read these templates (only built-ins",
+		"+ .viber/agent-teams.json), and agents cannot launch through the API. Either the owner",
+		"launches it from the web (sidebar ⋯ → New team / Add agent), or you copy its spec",
+		"(team_templates get) into .viber/agent-teams.json under a name, then launch-team it.",
 		"",
 		"CODEX agents, observed today: their Viber MCP calls, message_agent included, have",
 		"been rejected by their approval policy (#609), so they cannot open an exchange — write",

package/lib/team_template_tool.ts

@@ -54,7 +54,10 @@ export const TEAM_TEMPLATES_TOOL_DEF = {
       spec: {
         type: "object",
         description:
-          "The roster, for create/update: { roles: [{ role, runtime, permission, rolePrompt, model? }] } — same shape `get` returns.",
+          "The roster, for create/update: { roles: [{ role, runtime, permission, rolePrompt, model?, count? }] } — same shape `get` returns. " +
+          "On update a spec REPLACES the whole spec: send every role. " +
+          "model: leave it OUT (the runtime picks its own default) UNLESS the owner explicitly asks for a model. " +
+          "Full field rules: the capabilities tool.",
       },
       project_id: {
         type: ["integer", "null"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.24",
+  "version": "0.8.25",
   "description": "Voice + text MCP channel between a Claude Code session and the Viber UI (https://viber.dgypx.dev). Push transcripts to Claude; send_message tool delivers text back to the UI.",
   "type": "module",
   "bin": {

package/viber-channel.ts

@@ -69,6 +69,7 @@ import { CLAUDE_TOOL_DEFS } from "./lib/claude_tool_defs.ts";
 import { teamTemplates as teamTemplatesTool } from "./lib/team_template_tool.ts";
 import { warnIfStale } from "./lib/version_check.ts";
 import { capabilitiesText } from "./lib/capabilities.ts";
+import { readLocalVersion } from "./lib/version_check.ts";
 import { BOW_OUT_MESSAGE, shouldBowOutToPlugin } from "./lib/cli_bow_out.ts";
 import { resolveLockDir } from "./lib/lock_dir.ts";
 import { acquireLockFile, createLockSlot } from "./lib/bridge_lock.ts";
@@ -516,7 +517,7 @@ async function handleCallTool(
 
   // #332: on-demand control-plane discovery — static help, no runtime state.
   if (request.params.name === "capabilities") {
-    return { content: [{ type: "text" as const, text: capabilitiesText() }] };
+    return { content: [{ type: "text" as const, text: capabilitiesText(readLocalVersion()) }] };
   }
 
   if (request.params.name !== "send_message") {