@cryptolibertus/pi-peer 0.3.2

package/src/peers/inbound-bridge.mjs

@@ -0,0 +1,240 @@
+import { appendPeerGoalEvent } from "./goal-board.mjs";
+import { normalizePeerMessageResponseBody, redactPeerAuditValue } from "./protocol.mjs";
+import { renderPeerCommunicationGuidance } from "./guidance.mjs";
+
+export const PI_PEER_INBOUND_CUSTOM_TYPE = "pi-peer-inbound";
+
+export function createInboundPromptBridge(options = {}) {
+  const pi = options.pi;
+  const responseTimeoutMs = Number.isInteger(options.responseTimeoutMs) ? options.responseTimeoutMs : 30 * 60 * 1000;
+  const queue = [];
+  let activeEntry;
+
+  function activateNext() {
+    if (activeEntry || !queue.length) return;
+
+    const entry = queue.shift();
+    activeEntry = entry;
+    entry.context?.markActive?.();
+    startActiveTimer(entry);
+
+    try {
+      pi.sendMessage({
+        customType: PI_PEER_INBOUND_CUSTOM_TYPE,
+        content: renderInboundPeerPrompt(entry.envelope, { responderProfile: options.responderProfile, homeDir: options.homeDir }),
+        display: true,
+        envelope: summarizeEnvelope(entry.envelope),
+      }, { deliverAs: "followUp", triggerTurn: true });
+    } catch (error) {
+      activeEntry = undefined;
+      settleEntry(entry, { status: "ERROR", summary: error?.message || String(error) });
+      activateNext();
+    }
+  }
+
+  function startActiveTimer(entry) {
+    entry.timer = setTimeout(() => {
+      if (activeEntry !== entry || entry.settled) return;
+      activeEntry = undefined;
+      settleEntry(entry, { status: "ERROR", summary: `Timed out waiting for agent_end response for peer message '${entry.envelope.id}'` }, { clearTimer: false });
+      activateNext();
+    }, responseTimeoutMs);
+  }
+
+  return {
+    async handleEnvelope(envelope, context = {}) {
+      if (!pi || typeof pi.sendMessage !== "function") {
+        return { status: "ERROR", summary: "Inbound peer prompt bridge is not connected to pi.sendMessage" };
+      }
+
+      return new Promise((resolve) => {
+        if (activeEntry) context.markQueued?.();
+        const entry = {
+          envelope,
+          messageId: envelope.id,
+          conversationId: envelope.conversationId,
+          context,
+          resolve,
+          timer: undefined,
+          settled: false,
+        };
+        queue.push(entry);
+        activateNext();
+      });
+    },
+
+    handleAgentEnd(event) {
+      const entry = activeEntry;
+      if (!entry) return false;
+      activeEntry = undefined;
+
+      if (!entry.settled) {
+        const finalAssistantMessage = extractFinalAssistantText(event);
+        settleEntry(entry, normalizePeerMessageResponseBody({
+          status: finalAssistantMessage ? "OK" : "ERROR",
+          finalAssistantMessage,
+          summary: finalAssistantMessage ? "Peer turn completed" : "agent_end did not include final assistant text",
+        }));
+      }
+      activateNext();
+      return true;
+    },
+
+    recordProgress(input = {}) {
+      const entry = activeEntry;
+      if (!entry || entry.settled) return { ok: false, reason: "no active inbound peer task" };
+      const progress = normalizeProgress(input);
+      entry.context?.progress?.(progress);
+      void recordGoalProgress(entry, progress, options).catch(() => {});
+      return { ok: true, messageId: entry.messageId, conversationId: entry.conversationId, progress };
+    },
+
+    pendingCount() {
+      return queue.length + (activeEntry && !activeEntry.settled ? 1 : 0);
+    },
+
+    dispose(reason = "Inbound peer bridge disposed") {
+      const entry = activeEntry;
+      activeEntry = undefined;
+      if (entry && !entry.settled) settleEntry(entry, { status: "CANCELLED", summary: reason });
+      while (queue.length) {
+        const queued = queue.shift();
+        settleEntry(queued, { status: "CANCELLED", summary: reason });
+      }
+    },
+  };
+}
+
+export function renderInboundPeerPrompt(envelope, options = {}) {
+  const source = envelope?.source?.peerId || "unknown-peer";
+  const intent = envelope?.body?.intent || "ask";
+  const prompt = redactForPrompt(envelope?.body?.prompt || "", options);
+  const refs = Array.isArray(envelope?.body?.contextRefs) && envelope.body.contextRefs.length
+    ? `\n\nContext refs:\n${envelope.body.contextRefs.map((ref) => `- ${ref.type || "ref"}: ${redactForPrompt(ref.value || "", options)}`).join("\n")}`
+    : "";
+  const responderInstructions = renderResponderInstructions(envelope, options.responderProfile, options);
+  const claimedPaths = renderClaimedPaths(envelope, options);
+  const handoff = renderTaskHandoffGuidance(envelope);
+  return `[Pi peer inbound]\n${responderInstructions}\n\nFrom: ${source}\nConversation: ${envelope.conversationId}\nMessage: ${envelope.id}\nIntent: ${intent}${claimedPaths}\n\n${prompt}${refs}${handoff}`;
+}
+
+function renderResponderInstructions(envelope, profile = {}, options = {}) {
+  const peerId = profile.peerId || envelope?.target?.peerId || "this-peer";
+  const lines = [
+    "Responder instructions:",
+    `- You are local Pi peer '${redactForPrompt(peerId, options)}'.`,
+  ];
+  if (profile.role) lines.push(`- Role: ${redactForPrompt(profile.role, options)}`);
+  if (profile.persona) lines.push(`- Persona: ${redactForPrompt(profile.persona, options)}`);
+  lines.push("", "Peer communication guidance:", renderPeerCommunicationGuidance());
+
+  const guidance = [profile.agentInstructions, profile.agentMdContent].filter(Boolean).map((item) => redactForPrompt(item, options)).join("\n\n").trim();
+  if (guidance) lines.push("", "Configured AGENT.md-style guidance:", truncatePromptSection(guidance));
+  return lines.join("\n");
+}
+
+function renderClaimedPaths(envelope, options = {}) {
+  const paths = envelope?.body?.metadata?.claimedPaths;
+  if (!Array.isArray(paths) || paths.length === 0) return "";
+  const clean = paths.filter((item) => typeof item === "string" && item.trim()).map((item) => redactForPrompt(item, options));
+  return clean.length ? `\nClaimed paths: ${clean.join(", ")}` : "";
+}
+
+function renderTaskHandoffGuidance(envelope) {
+  const intent = envelope?.body?.intent || "ask";
+  const claimedPaths = envelope?.body?.metadata?.claimedPaths;
+  const taskLike = intent === "task" || (Array.isArray(claimedPaths) && claimedPaths.length > 0);
+  if (!taskLike) return "";
+  return `\n\nLong-running peer task guidance:\n- Use peer_progress to report meaningful checkpoints before final response when available.\n- Required final handoff for this peer task:\n  - Status: done | blocked | partial\n  - Files changed: path list or none\n  - Verification: command + exit status, or not run with reason\n  - Blockers/risks: concise bullets or none\n  - Safe for review: yes | no`;
+}
+
+function normalizeProgress(input = {}) {
+  const summary = typeof input.summary === "string" && input.summary.trim() ? input.summary.trim() : "Peer task progress";
+  return {
+    summary,
+    ...(typeof input.status === "string" && input.status.trim() ? { status: input.status.trim() } : {}),
+    ...(typeof input.phase === "string" && input.phase.trim() ? { phase: input.phase.trim() } : {}),
+    ...(input.detail !== undefined ? { detail: input.detail } : {}),
+  };
+}
+
+async function recordGoalProgress(entry, progress, options = {}) {
+  const metadata = entry.envelope?.body?.metadata || {};
+  if (!options.cwd || !metadata.goalId || !metadata.goalClaimId) return;
+  await appendPeerGoalEvent(options.cwd, metadata.goalId, {
+    type: "heartbeat",
+    peerId: entry.envelope?.target?.peerId || "unknown",
+    resolves: metadata.goalClaimId,
+    summary: progress.phase ? `${progress.phase}: ${progress.summary}` : progress.summary,
+    metadata: {
+      messageId: entry.messageId,
+      conversationId: entry.conversationId,
+      progress: true,
+      ...(progress.status ? { status: progress.status } : {}),
+    },
+  });
+}
+
+function redactForPrompt(value, options = {}) {
+  if (value === undefined || value === null) return "";
+  const redacted = redactPeerAuditValue(value, { homeDir: options.homeDir || process.env.HOME || "" });
+  if (typeof redacted === "string") return redacted;
+  return JSON.stringify(redacted);
+}
+
+function truncatePromptSection(value, maxLength = 12_000) {
+  return value.length > maxLength ? `${value.slice(0, maxLength)}\n[truncated]` : value;
+}
+
+export function extractFinalAssistantText(event) {
+  if (typeof event === "string") return event.trim();
+  if (!event || typeof event !== "object") return "";
+  for (const key of ["finalAssistantText", "finalText", "text", "content"]) {
+    const value = event[key];
+    const text = contentToText(value);
+    if (text) return text;
+  }
+  if (event.message?.role === "assistant") return contentToText(event.message.content);
+  if (event.finalMessage?.role === "assistant") return contentToText(event.finalMessage.content);
+  if (Array.isArray(event.messages)) {
+    for (let index = event.messages.length - 1; index >= 0; index -= 1) {
+      const message = event.messages[index];
+      if (message?.role === "assistant") {
+        const text = contentToText(message.content);
+        if (text) return text;
+      }
+    }
+  }
+  return "";
+}
+
+function contentToText(value) {
+  if (typeof value === "string") return value.trim();
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      if (typeof item === "string") return item;
+      if (typeof item?.text === "string") return item.text;
+      if (typeof item?.content === "string") return item.content;
+      return "";
+    }).filter(Boolean).join("\n").trim();
+  }
+  if (typeof value?.text === "string") return value.text.trim();
+  return "";
+}
+
+function summarizeEnvelope(envelope) {
+  return {
+    messageId: envelope.id,
+    conversationId: envelope.conversationId,
+    source: envelope.source,
+    target: envelope.target,
+    intent: envelope.body?.intent || "ask",
+  };
+}
+
+function settleEntry(entry, response, options = {}) {
+  if (entry.settled) return;
+  entry.settled = true;
+  if (options.clearTimer !== false) clearTimeout(entry.timer);
+  entry.resolve(response);
+}