viber-channel 0.8.16 → 0.8.17

package/lib/agent_tools.ts

@@ -17,7 +17,7 @@
  * MCP tool-result shape. It does NOT hold state.
  */
 import { postMessage, parseArtifact, type Artifact } from "./messages.js";
-import { listPeersAuto, openDm, type OpenDmResult } from "./peers.js";
+import { listPeersAuto, openDm, type OpenDmResult, type PeerFilters } from "./peers.js";
 import { ConversationTokenExpiredError } from "./messages.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
@@ -98,12 +98,27 @@ function errorText(s: string): AgentToolResult {
  * entry then carries a `project` field); a regular instance transparently
  * falls back to its own project (unchanged behaviour, no `project` field).
  */
-export async function listAgents(ctx: AgentToolsContext): Promise<AgentToolResult> {
+export async function listAgents(
+  ctx: AgentToolsContext,
+  args: Record<string, unknown> = {},
+): Promise<AgentToolResult> {
   if (!ctx.instanceToken()) {
     return errorText("Channel not ready: no instance identity yet.");
   }
+  // #501 step-05 — optional filters, applied SERVER-side. Without them a
+  // dev-lead looking for its two reviewers pulls every agent the project ever
+  // created (30 rows for 5 live ones, measured), in a loop.
+  const filters: PeerFilters = {};
+  if (args.online === true) filters.online = true;
+  if (typeof args.label_prefix === "string" && args.label_prefix !== "") {
+    filters.labelPrefix = args.label_prefix;
+  }
   try {
-    const { peers, scope } = await listPeersAuto(ctx.baseUrl(), ctx.instanceToken());
+    const { peers, scope, presenceStatus } = await listPeersAuto(
+      ctx.baseUrl(),
+      ctx.instanceToken(),
+      filters,
+    );
     // Project only what the model needs to pick a peer (drop last_seen /
     // active_conversation_id — available over the wire if a future tool needs them).
     const summary = peers.map((p) => ({
@@ -114,13 +129,22 @@ export async function listAgents(ctx: AgentToolsContext): Promise<AgentToolResul
       // Present only in the user-scoped (orchestrator) listing.
       ...(p.project_name !== undefined ? { project: p.project_name } : {}),
     }));
+    // An `online` filter under an unreadable presence source would come back
+    // empty and read as "nobody is alive" — the false green in listing form.
+    // The server drops the filter in that case; say so rather than let the
+    // caller believe it was applied.
+    const presenceWarning =
+      filters.online === true && presenceStatus === "unavailable"
+        ? "WARNING: the presence source is unavailable, so the `online` filter was NOT applied — " +
+          "`online` values below are unknown, not observed.\n\n"
+        : "";
     const body =
       summary.length === 0
         ? scope === "user"
           ? "No other agents are currently registered in any of your projects."
           : "No other agents are currently registered in this project."
         : JSON.stringify(summary, null, 2);
-    return text(body);
+    return text(`${presenceWarning}${body}`);
   } catch (err) {
     return errorText(`list_agents failed: ${String(err)}`);
   }

package/lib/bridge_tool_host.ts

@@ -92,8 +92,19 @@ export const TOOL_DEFS = [
       "List the OTHER agents (instances) you can DM. Returns each agent's id, " +
       "label, runtime kind, and whether it is online. Use it to find an id before message_agent. " +
       "Normally project-scoped; an ORCHESTRATOR instance (#307) sees all the owner's projects, " +
-      "each entry tagged with a `project` field.",
-    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      "each entry tagged with a `project` field. " +
+      "FILTER instead of listing everything (#501): `online: true` for live agents only, " +
+      "`label_prefix` for one team (e.g. \"501-\"). Both are applied server-side. " +
+      "If the presence source is unreachable the `online` filter is DROPPED and the answer " +
+      "says so — an empty list would wrongly read as \"no agent is alive\".",
+    inputSchema: {
+      type: "object",
+      properties: {
+        online: { type: "boolean", description: "Only agents currently seen online." },
+        label_prefix: { type: "string", description: 'Only labels starting with this, e.g. "501-".' },
+      },
+      additionalProperties: false,
+    },
   },
   {
     name: "message_agent",
@@ -146,7 +157,7 @@ export async function dispatchBridgeTool(
 ): Promise<AgentToolResult> {
   let result: AgentToolResult;
   if (name === "list_agents") {
-    result = await listAgents(opts.ctx);
+    result = await listAgents(opts.ctx, args);
   } else if (name === "message_agent") {
     result = await messageAgent(opts.ctx, args);
   } else if (name === "send_message") {

package/lib/claude_tool_defs.ts

@@ -71,10 +71,24 @@ export const CLAUDE_TOOL_DEFS = [
       "Use this to find the id of an agent (e.g. 'Codex Review') before calling message_agent. " +
       "Normally scoped to this project; if the owner designated this instance an ORCHESTRATOR " +
       "(#307), the list covers ALL the owner's projects and each entry carries a `project` field. " +
-      "You are never in the list.",
+      "You are never in the list. " +
+      "FILTER instead of listing everything (#501): `online: true` returns only agents the server " +
+      'currently sees online, `label_prefix` only those whose label starts with it (e.g. "501-" ' +
+      "for one team). Both are applied server-side, so an unfiltered call in a loop is the " +
+      "expensive path. If the presence source is unreachable the `online` filter is DROPPED and " +
+      'the answer says so — an empty list would wrongly read as "no agent is alive".',
     inputSchema: {
       type: "object" as const,
-      properties: {},
+      properties: {
+        online: {
+          type: "boolean",
+          description: "Only agents the server currently sees online.",
+        },
+        label_prefix: {
+          type: "string",
+          description: 'Only agents whose label starts with this prefix, e.g. "501-".',
+        },
+      },
       required: [],
       additionalProperties: false,
     },

package/lib/instance.ts

@@ -193,6 +193,16 @@ export interface AcquiredInstance {
  *   3. `auth.json` `instance_token` — reused (durable identity, D4 → same id).
  *   4. register a NEW instance with the stable project_token, persisted back to
  *      auth.json (self-healing migration — no forced manual reconnect).
+ *
+ * ⚠ #501 DEPENDS ON THE PRIORITY ORDER ABOVE. vibe-master's readiness gate proves
+ * an agent came up by watching for an instance id that did NOT exist before the
+ * launch. Only route 2 mints one: routes 1 and 3 REUSE an id, so a launch that
+ * took either would be reported as "never registered" while being perfectly
+ * healthy — a false red. vibe-master's spawns take route 2 because
+ * `vibe-master/lib/terminal.ts` scrubs `VIBER_INSTANCE_TOKEN`/`_ID` from the
+ * child environment; the guarantee lives there, and this comment exists so a
+ * change here is not made unaware of it. Locked by the route-precedence tests in
+ * `test/instance.test.ts`.
  */
 export async function acquireInstance(
   baseUrl: string,

package/lib/peers.ts

@@ -44,12 +44,41 @@ export class PeersHttpError extends Error {
  * Throws PeersHttpError on a non-2xx response so the caller can surface a
  * clear tool error — or fall back from user scope on a 403.
  */
+/** A listing plus whether the presence source could be read at all (#501). */
+export interface PeersListing {
+  peers: PeerView[];
+  presenceStatus: "available" | "unavailable";
+}
+
+export interface PeerFilters {
+  /** Only agents the server currently sees online. Dropped, server-side, when
+   *  presence is unavailable — an empty list would read as "nobody is alive". */
+  online?: boolean;
+  /** Team/label prefix, e.g. "501-". */
+  labelPrefix?: string;
+}
+
 export async function listPeers(
   baseUrl: string,
   instanceToken: string,
   scope?: "user",
-): Promise<PeerView[]> {
-  const qs = scope === "user" ? "?scope=user" : "";
+  filters: PeerFilters = {},
+): Promise<PeersListing> {
+  const params = new URLSearchParams();
+  if (scope === "user") params.set("scope", "user");
+  // #501 step-05: filtering happens SERVER-side. Doing it here would still pay
+  // the transfer that made this tool expensive to call in a loop.
+  if (filters.online === true) params.set("online", "true");
+  if (filters.labelPrefix !== undefined && filters.labelPrefix !== "") {
+    params.set("label_prefix", filters.labelPrefix);
+  }
+  const qs = params.size > 0 ? `?${params.toString()}` : "";
+  // ⚠ NEVER add `X-Client-Fingerprint` to these headers (#501). The server picks
+  // its auth path from that header's PRESENCE: with it, `/peers` validates the
+  // Bearer as a project_token instead of an instance_token — and there is no
+  // fallback between the two, by design. Adding it here (directly, via a fetch
+  // wrapper, or via a proxy) would 401 `list_agents` for the whole fleet, with a
+  // cause invisible from this file.
   const resp = await fetch(`${baseUrl}/api/instances/peers${qs}`, {
     method: "GET",
     headers: { Authorization: `Bearer ${instanceToken}`, ...cfAccessHeaders() },
@@ -64,8 +93,27 @@ export async function listPeers(
     }
     throw new PeersHttpError(`listPeers failed: ${detail}`, resp.status);
   }
-  const body = (await resp.json()) as { instances?: PeerView[] };
-  return Array.isArray(body.instances) ? body.instances : [];
+  const body = (await resp.json()) as {
+    instances?: PeerView[];
+    presence_status?: string;
+  };
+  // A body we cannot read is a READ FAILURE, not an empty project (#501). The
+  // old `?? []` turned `{"presence_status":"available"}` into "No other agents
+  // are registered" — the exact false conclusion this work exists to remove.
+  // The same rule already guards the readiness client and the server's presence
+  // snapshot; it applies here too.
+  if (!Array.isArray(body.instances)) {
+    throw new PeersHttpError(
+      `listPeers: unreadable body (no \`instances\` array) — refusing to report an empty project`,
+      resp.status,
+    );
+  }
+  return {
+    peers: body.instances,
+    // Only the literal "available" is trusted: an older backend that does not
+    // send the field must fall on the cautious side (#501).
+    presenceStatus: body.presence_status === "available" ? "available" : "unavailable",
+  };
 }
 
 /**
@@ -78,12 +126,19 @@ export async function listPeers(
 export async function listPeersAuto(
   baseUrl: string,
   instanceToken: string,
-): Promise<{ peers: PeerView[]; scope: "user" | "project" }> {
+  filters: PeerFilters = {},
+): Promise<PeersListing & { scope: "user" | "project" }> {
   try {
-    return { peers: await listPeers(baseUrl, instanceToken, "user"), scope: "user" };
+    return {
+      ...(await listPeers(baseUrl, instanceToken, "user", filters)),
+      scope: "user",
+    };
   } catch (err) {
     if (err instanceof PeersHttpError && err.status === 403) {
-      return { peers: await listPeers(baseUrl, instanceToken), scope: "project" };
+      return {
+        ...(await listPeers(baseUrl, instanceToken, undefined, filters)),
+        scope: "project",
+      };
     }
     throw err;
   }

package/lib/spawn_reason.ts

@@ -25,6 +25,9 @@ export const SPAWN_REASONS = [
   "roster_invalid",
   "codex_unavailable",
   "launch_failed",
+  "not_ready",
+  "readiness_unverified",
+  "launch_refused",
   // Emitted by the runner itself
   "policy_invalid",
   "policy_refused",
@@ -224,6 +227,26 @@ export function messageForReason(
       return "codex is not launchable on this machine, so no agent was started — install codex or set VIBER_CODEX_BIN";
     case "launch_failed":
       return `a member failed to start${names}; the rest of the roster was skipped — the team is incomplete`;
+    // #501 — these two used to borrow `launch_failed`, whose sentence says the
+    // agent never started AND that the roster was skipped. For an agent that is
+    // running, and a roster that Q1bis deliberately did NOT interrupt, that
+    // sentence is false twice — and an automated caller retrying on it would
+    // create the duplicate labels we just built a detector for.
+    case "not_ready":
+      // Deliberately NOT "not registered": this family also covers an agent that
+      // registered and never beat, one whose process died after registering, and
+      // one whose instance vanished. Naming only the first would deny a
+      // registration the server can prove (Codex review). The precise reason
+      // stays in the structured human recap.
+      return `these agents STARTED but did not become ready on the channel${names} — the rest of the roster was NOT interrupted; close their window (terminal agents are not stopped automatically) and spawn them again`;
+    case "launch_refused":
+      // Says neither "started" nor "skipped": both would be false here.
+      return `no process was started for these members${names} — another launch of the same label was already in flight on this machine, so the spawn was refused locally; the rest of the roster was NOT interrupted. Re-spawn them with a distinct prefix`;
+    case "readiness_unverified":
+      // Also covers post-launch correlation ambiguity, not just an unreadable
+      // presence source — so the sentence states the CONSEQUENCE (we could not
+      // establish it) rather than one of its causes.
+      return `these agents started, but their availability could NOT be established${names} — this says nothing against them. Nothing was stopped; check them with list_agents before relying on them`;
     case "policy_invalid":
       return "this machine's local runner policy is present but invalid, so the spawn was refused";
     case "policy_refused":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viber-channel",
-  "version": "0.8.16",
+  "version": "0.8.17",
   "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

@@ -475,7 +475,7 @@ async function handleCallTool(
   const args = (request.params.arguments ?? {}) as Record<string, unknown>;
 
   if (request.params.name === "list_agents") {
-    return libListAgents(channelToolsCtx);
+    return libListAgents(channelToolsCtx, args);
   }
 
   if (request.params.name === "message_agent") {