viber-channel 0.6.0 → 0.7.0

package/lib/agent_tools.ts

@@ -0,0 +1,201 @@
+/**
+ * agent_tools.ts — shared logic for the three channel tools (#317).
+ *
+ * The Claude MCP server (viber-channel.ts) and the Codex bridge
+ * (viber-codex-bridge.ts) must expose the SAME tools with the SAME behaviour —
+ * one source, no double maintenance. This module holds that behaviour as pure,
+ * context-injected functions; each host wraps them in a thin adapter (an MCP
+ * CallTool handler for Claude, an in-process MCP server for Codex).
+ *
+ * The context is read through LIVE getters, never a snapshot: the host's
+ * conversation token rotates (token refresh / re-mint) and these functions must
+ * always read the current value at call time. That is why the context exposes
+ * functions, not fields.
+ *
+ * messages.ts (postMessage/parseArtifact) and peers.ts (listPeers/openDm) stay
+ * pure HTTP clients — this module orchestrates them and maps results to the
+ * MCP tool-result shape. It does NOT hold state.
+ */
+import { postMessage, parseArtifact, type Artifact } from "./messages.js";
+import { listPeers, openDm, type OpenDmResult } from "./peers.js";
+import { ConversationTokenExpiredError } from "./messages.js";
+
+/** MCP tool-result shape (text content + optional error flag). */
+export interface AgentToolResult {
+  isError?: boolean;
+  content: { type: "text"; text: string }[];
+}
+
+/**
+ * Live, by-reference access to the host channel's runtime state. Implemented by
+ * both hosts so the shared tool logic never reads a stale snapshot. Every getter
+ * is called at tool-invocation time.
+ */
+export interface AgentToolsContext {
+  /** API base URL (e.g. https://viber-dev.dgypx.dev). */
+  baseUrl(): string;
+  /** This instance's durable instance_token (Bearer) for the agent endpoints. */
+  instanceToken(): string;
+  /** WebSocket base URL used to stream an opened DM (empty until ready). */
+  voiceBaseUrl(): string;
+  /** Conversation id send_message posts into (main conv, or the active DM). */
+  sendConversationId(): string;
+  /** Conversation token paired with sendConversationId(). */
+  sendConversationToken(): string;
+  /**
+   * Start streaming a freshly opened DM so the peer's reply surfaces back on the
+   * host channel. The host supplies its own ws base URL; the lib only forwards
+   * the DM coordinates. Fire-and-forget (parity with the Claude channel).
+   */
+  startDmStream(dm: OpenDmResult): void;
+  /**
+   * Optional: the current stream's AbortSignal, passed to postMessage so a post
+   * in flight is cancelled atomically if the stream is torn down (re-join /
+   * revoke / shutdown). The Claude channel returns undefined (it never passed a
+   * signal); the Codex bridge returns its per-turn stream signal (#303 parity).
+   */
+  abortSignal?(): AbortSignal | undefined;
+}
+
+function text(s: string): AgentToolResult {
+  return { content: [{ type: "text" as const, text: s }] };
+}
+
+function errorText(s: string): AgentToolResult {
+  return { isError: true, content: [{ type: "text" as const, text: s }] };
+}
+
+/**
+ * list_agents — return this project's other agents so the model can pick one to
+ * message. Guards the startup window: an empty instance token means "channel not
+ * ready" rather than hitting the peers endpoint with no credential.
+ */
+export async function listAgents(ctx: AgentToolsContext): Promise<AgentToolResult> {
+  if (!ctx.instanceToken()) {
+    return errorText("Channel not ready: no instance identity yet.");
+  }
+  try {
+    const peers = await listPeers(ctx.baseUrl(), ctx.instanceToken());
+    // 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) => ({ id: p.id, label: p.label, kind: p.kind, online: p.online }));
+    const body =
+      summary.length === 0
+        ? "No other agents are currently registered in this project."
+        : JSON.stringify(summary, null, 2);
+    return text(body);
+  } catch (err) {
+    return errorText(`list_agents failed: ${String(err)}`);
+  }
+}
+
+/**
+ * message_agent — open/reuse a DM with a peer and post a message, then start
+ * streaming that DM so the peer's reply arrives back on this channel. Mirrors
+ * the Claude MCP behaviour exactly: structured outcomes for offline / transient
+ * conflict, a clean retry hint on an expired DM token, and the DM stream started
+ * BEFORE the post so we are subscribed before the peer can reply.
+ */
+export async function messageAgent(
+  ctx: AgentToolsContext,
+  args: Record<string, unknown>,
+): Promise<AgentToolResult> {
+  if (!ctx.instanceToken() || !ctx.voiceBaseUrl()) {
+    return errorText("Channel not ready: no instance identity yet.");
+  }
+  const peerId = args.instance_id;
+  const body = args.text;
+  if (typeof peerId !== "string" || peerId.trim().length === 0) {
+    return errorText("Invalid input: instance_id must be a non-empty string");
+  }
+  if (typeof body !== "string" || body.trim().length === 0) {
+    return errorText("Invalid input: text must be a non-empty string");
+  }
+  const trimmedPeerId = peerId.trim();
+
+  let outcome;
+  try {
+    outcome = await openDm(ctx.baseUrl(), ctx.instanceToken(), trimmedPeerId);
+  } catch (err) {
+    return errorText(`message_agent failed: ${String(err)}`);
+  }
+  if (!outcome.ok) {
+    let friendly: string;
+    if (outcome.detail === "target_offline") {
+      friendly = "That agent is offline right now — it must be running to receive a DM.";
+    } else if (outcome.detail === "dm_unavailable_retry") {
+      friendly = "Could not open the DM due to a transient conflict — try message_agent again.";
+    } else {
+      friendly = `Could not open a DM: ${outcome.detail}`;
+    }
+    return errorText(friendly);
+  }
+
+  // Subscribe before posting so the peer's reply (which requires the peer agent
+  // to process the message, i.e. seconds) always loses the race to our subscribe.
+  ctx.startDmStream(outcome.dm);
+
+  let result;
+  try {
+    result = await postMessage(
+      ctx.baseUrl(),
+      outcome.dm.conversation_id,
+      outcome.dm.conversation_token,
+      body,
+      undefined,
+      ctx.abortSignal?.(),
+    );
+  } catch (err) {
+    // A DM membership token expired — unlike send_message we do NOT tear down the
+    // host here (the main conversation is unaffected). Tell the model to retry;
+    // a retry re-opens the DM with a fresh token.
+    if (err instanceof ConversationTokenExpiredError) {
+      return errorText("The DM session token expired — call message_agent again to re-open and resend.");
+    }
+    return errorText(`message_agent post failed: ${String(err)}`);
+  }
+  if (!result.ok) {
+    return errorText(result.detail);
+  }
+  return text(`Message sent to agent (DM ${outcome.dm.conversation_id}).`);
+}
+
+/**
+ * send_message — post text (+ optional artifact) into the conversation this turn
+ * belongs to. Guards the startup window (empty conversation token/id) and
+ * validates input identically to the Claude MCP.
+ *
+ * NB: a ConversationTokenExpiredError from postMessage is NOT caught here — the
+ * host adapter handles it (Claude tears down the channel; the bridge surfaces a
+ * controlled shutdown), because that policy differs per host.
+ */
+export async function sendMessage(
+  ctx: AgentToolsContext,
+  args: Record<string, unknown>,
+): Promise<AgentToolResult> {
+  if (!ctx.sendConversationToken() || !ctx.sendConversationId()) {
+    return errorText("Channel not ready: no conversation yet.");
+  }
+  const body = args.text;
+  if (typeof body !== "string" || body.trim().length === 0) {
+    return errorText("Invalid input: text must be a non-empty string");
+  }
+  const parsed = parseArtifact(args.artifact);
+  if (!parsed.ok) {
+    return errorText(`Invalid input: ${parsed.error}`);
+  }
+  const artifact: Artifact | undefined = parsed.artifact;
+
+  const result = await postMessage(
+    ctx.baseUrl(),
+    ctx.sendConversationId(),
+    ctx.sendConversationToken(),
+    body,
+    artifact,
+    ctx.abortSignal?.(),
+  );
+  if (!result.ok) {
+    return errorText(result.detail);
+  }
+  return text(`Message sent: ${result.message_id}`);
+}