@stigmer/runner 3.7.0 → 3.8.0

package/src/shared/__tests__/conversation-attachment.test.ts

@@ -0,0 +1,138 @@
+/**
+ * The conversation participation attachment (channel-conversations
+ * DD-008 D-c, A14): the label-keyed attachment decision, the HTTP-only
+ * shape (the deliberate no-stdio divergence from both siblings), the
+ * structural approval-freedom, and the pinned strings. The route is the
+ * cross-repo string — pinned here and in the mcp-server's conversation
+ * integration test (the TOOL_CALL_LIMIT precedent); the label is pinned
+ * here and in the cloud's ChannelSessionBrokerTest (the sender-identity
+ * mirror-guard precedent).
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { mergeApprovalPolicies, type ActiveLeases } from "../approval-policy.js";
+import { needsBackfill } from "../connect-backfill.js";
+import {
+  CHANNEL_ID_LABEL,
+  CONVERSATION_ATTACHMENT_SLUG,
+  CONVERSATION_ROUTE,
+  readChannelConversationId,
+  synthesizeConversationAttachment,
+} from "../conversation-attachment.js";
+
+const noLeases: ActiveLeases = {
+  global: false,
+  categories: new Set(),
+  servers: new Set(),
+};
+
+const cloudOptions = {
+  bridgeEndpoint: "https://mcp.stigmer.ai",
+  credential: "sandbox-token",
+  backendEndpoint: "http://localhost:7234",
+};
+
+describe("cross-repo and cross-file pinned strings", () => {
+  it("pins the label verbatim to the cloud's ChannelRuntimeConstants (mirror guard)", () => {
+    // Pinned to ChannelRuntimeConstants.CHANNEL_ID_METADATA_KEY in
+    // stigmer-cloud (ChannelSessionCreateScopeStep stamps it; the
+    // mirror-guard test lives in ChannelSessionBrokerTest). Drift
+    // degrades to honest absence — the escalation tool silently stops
+    // attaching — never worse; change BOTH sides together.
+    expect(CHANNEL_ID_LABEL).toBe("stigmer.ai/channel-id");
+  });
+
+  it("pins the attachment slug and the bridge route", () => {
+    // The slug is runner-internal (the resolved-server name and shadow
+    // key). The route is cross-repo: the mcp-server's conversation
+    // integration test pins CONVERSATION_ROUTE independently — a drift
+    // strands every synthesized attachment on a 404.
+    expect(CONVERSATION_ATTACHMENT_SLUG).toBe("stigmer-conversation");
+    expect(CONVERSATION_ROUTE).toBe("/conversation");
+  });
+});
+
+describe("readChannelConversationId", () => {
+  it("reads the serving channel id from the session labels", () => {
+    expect(readChannelConversationId({ [CHANNEL_ID_LABEL]: "agch_1" })).toBe("agch_1");
+  });
+
+  it("treats missing labels, a missing key, and blank values as absent", () => {
+    expect(readChannelConversationId(undefined)).toBeUndefined();
+    expect(readChannelConversationId({})).toBeUndefined();
+    expect(readChannelConversationId({ [CHANNEL_ID_LABEL]: "" })).toBeUndefined();
+    expect(readChannelConversationId({ [CHANNEL_ID_LABEL]: "   " })).toBeUndefined();
+  });
+
+  it("ignores unrelated labels", () => {
+    expect(
+      readChannelConversationId({ "stigmer.ai/channel-conversation-key": "919000000001" }),
+    ).toBeUndefined();
+  });
+});
+
+describe("synthesizeConversationAttachment", () => {
+  it("returns undefined when the session serves no channel conversation", () => {
+    expect(synthesizeConversationAttachment(undefined, cloudOptions)).toBeUndefined();
+  });
+
+  it("returns undefined without a bridge endpoint — HTTP-only, no stdio fallback", () => {
+    // The deliberate divergence from both sibling attachments: escalate
+    // is cloud-only (OSS refuses FAILED_PRECONDITION) AND
+    // session-token-only (a stdio child's API key carries no session_id
+    // claim), so a stdio shape could only ever fail. Honest absence.
+    expect(
+      synthesizeConversationAttachment("agch_1", {
+        bridgeEndpoint: null,
+        credential: "sandbox-token",
+        backendEndpoint: "http://localhost:7234",
+      }),
+    ).toBeUndefined();
+    expect(
+      synthesizeConversationAttachment("agch_1", {
+        bridgeEndpoint: "",
+        credential: "sandbox-token",
+        backendEndpoint: "http://localhost:7234",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("builds the HTTP shape against the bridge /conversation route with the credential", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", {
+      ...cloudOptions,
+      bridgeEndpoint: "https://mcp.stigmer.ai/",
+    });
+
+    expect(attachment).toMatchObject({
+      slug: CONVERSATION_ATTACHMENT_SLUG,
+      connectionType: "http",
+      url: "https://mcp.stigmer.ai/conversation",
+      headers: { Authorization: "Bearer sandbox-token" },
+    });
+  });
+
+  it("omits the Authorization header without a credential", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", {
+      ...cloudOptions,
+      credential: null,
+    });
+    expect(attachment?.headers).toBeUndefined();
+  });
+
+  it("is approval-free by construction: zero entries in the merged approval map", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", cloudOptions)!;
+
+    // Channel surfaces run APPROVAL_MODE_UNATTENDED, where a gated tool
+    // resolves as skip-and-adapt — a gated escalation would never fire
+    // (DD-008's approval-free ruling, the DD-001 SD-3 structural bypass).
+    const merged = mergeApprovalPolicies([attachment], [], noLeases);
+    expect(merged.size).toBe(0);
+  });
+
+  it("is structurally immune to the connect backfill", () => {
+    const attachment = synthesizeConversationAttachment("agch_1", cloudOptions)!;
+    expect(attachment.discoveredCapabilitiesEmpty).toBe(false);
+    expect(needsBackfill(attachment)).toBe(false);
+  });
+});

package/src/shared/__tests__/conversation-catchup.test.ts

@@ -0,0 +1,70 @@
+/**
+ * Unit tests for the conversation-catchup module (cloud channel-conversations
+ * DD-006, T03 Sitting 3). Unlike its metadata-keyed siblings there is no
+ * string key to mirror-guard — the value rides the typed
+ * `AgentExecutionSpec.conversation_catchup` proto field, so codegen enforces
+ * the cross-repo contract. What IS pinned here: the blank-is-absent read
+ * semantics (the field is present on EVERY channel turn for its watermark
+ * bookkeeping — only a non-empty digest means anything), and the framing's
+ * behavioral contract.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { ConversationCatchupSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { TimestampSchema } from "@bufbuild/protobuf/wkt";
+
+import {
+  formatConversationCatchupText,
+  readConversationCatchup,
+} from "../conversation-catchup.js";
+
+const DIGEST =
+  "Customer: where is my order?\n"
+  + "Teammate: I've refunded you in full.\n"
+  + "You escalated: refund beyond policy";
+
+describe("readConversationCatchup", () => {
+  it("reads a non-empty digest", () => {
+    const catchup = create(ConversationCatchupSchema, { digest: DIGEST });
+    expect(readConversationCatchup(catchup)).toBe(DIGEST);
+  });
+
+  it("answers undefined when the field is absent", () => {
+    expect(readConversationCatchup(undefined)).toBeUndefined();
+  });
+
+  it("a blank digest is no catchup — window_end alone is cloud bookkeeping, never a reason to inject", () => {
+    // A21: the field rides EVERY channel turn so the watermark can advance;
+    // most turns carry an empty digest. The runner must render nothing.
+    const catchup = create(ConversationCatchupSchema, {
+      digest: "   ",
+      windowEnd: create(TimestampSchema, { seconds: 1_775_000_000n }),
+    });
+    expect(readConversationCatchup(catchup)).toBeUndefined();
+  });
+});
+
+describe("formatConversationCatchupText", () => {
+  const framed = formatConversationCatchupText(DIGEST);
+
+  it("frames the digest as known history the agent must not answer or announce", () => {
+    expect(framed).toContain("you have not seen");
+    expect(framed).toContain("do not answer or re-answer");
+    expect(framed).toContain("do not repeat or summarize them back");
+    expect(framed).toContain("Continue from the customer's newest message.");
+  });
+
+  it("asserts no takeover — a digest can exist with no human handoff at all (the A15/A20 honesty bar)", () => {
+    // The preamble may DESCRIBE what the digest can contain ("may include"),
+    // but must never state that a handoff happened on THIS conversation: a
+    // failed turn's re-composed window has no teammate in it anywhere.
+    expect(framed).toContain("may include");
+    expect(framed).not.toContain("stepped in");
+    expect(framed).not.toContain("took over");
+  });
+
+  it("ends with the digest — the preamble precedes, nothing trails", () => {
+    expect(framed.endsWith(DIGEST)).toBe(true);
+  });
+});

package/src/shared/__tests__/synthesized-attachment.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Composition of ALL THREE synthesized attachments through
+ * injectSynthesizedAttachment — the first test to chain them the way
+ * both harness call sites do (datastore, then channels, then
+ * conversation, each after resolve + backfill). Per-slug independence
+ * is the property that makes a third attachment safe to add: replacing
+ * one reserved slug must never disturb its siblings.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { create } from "@bufbuild/protobuf";
+import { DatastoreUsageSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+
+import {
+  CHANNEL_ATTACHMENT_SLUG,
+  synthesizeChannelAttachment,
+} from "../channel-attachment.js";
+import {
+  CONVERSATION_ATTACHMENT_SLUG,
+  synthesizeConversationAttachment,
+} from "../conversation-attachment.js";
+import {
+  DATASTORE_ATTACHMENT_SLUG,
+  synthesizeDatastoreAttachment,
+} from "../datastore-attachment.js";
+import { injectSynthesizedAttachment } from "../synthesized-attachment.js";
+import type { ResolvedMcpServer } from "../mcp-resolver.js";
+
+const options = {
+  bridgeEndpoint: "https://mcp.stigmer.ai",
+  credential: "sandbox-token",
+  backendEndpoint: "http://localhost:7234",
+};
+
+const userServer: ResolvedMcpServer = {
+  slug: "github",
+  connectionType: "http",
+  url: "https://example.com",
+  toolApprovals: [],
+  pinnedToolApprovals: [],
+  discoveredCapabilitiesEmpty: false,
+};
+
+function allThree(): ResolvedMcpServer[] {
+  const datastore = synthesizeDatastoreAttachment(
+    [create(DatastoreUsageSchema, {
+      datastoreRef: create(ApiResourceReferenceSchema, { slug: "clinic" }),
+    })],
+    options,
+  )!;
+  const channels = synthesizeChannelAttachment(
+    [{ channel: { channel: "isc-whatsapp", provider: "whatsapp" } as MessagingChannel, templates: [] }],
+    options,
+  )!;
+  const conversation = synthesizeConversationAttachment("agch_1", options)!;
+
+  // The harness order at both call sites: datastore, channels, conversation.
+  let servers = injectSynthesizedAttachment([userServer], datastore, "datastore records");
+  servers = injectSynthesizedAttachment(servers, channels, "channel messaging");
+  return injectSynthesizedAttachment(servers, conversation, "conversation participation");
+}
+
+describe("three synthesized attachments in one chain", () => {
+  it("composes all three after the user's servers, in injection order", () => {
+    expect(allThree().map((s) => s.slug)).toEqual([
+      "github",
+      DATASTORE_ATTACHMENT_SLUG,
+      CHANNEL_ATTACHMENT_SLUG,
+      CONVERSATION_ATTACHMENT_SLUG,
+    ]);
+  });
+
+  it("each rides its own bridge route with the shared credential", () => {
+    const bySlug = new Map(allThree().map((s) => [s.slug, s]));
+    expect(bySlug.get(DATASTORE_ATTACHMENT_SLUG)?.url).toBe("https://mcp.stigmer.ai/records");
+    expect(bySlug.get(CHANNEL_ATTACHMENT_SLUG)?.url).toBe("https://mcp.stigmer.ai/channels");
+    expect(bySlug.get(CONVERSATION_ATTACHMENT_SLUG)?.url).toBe(
+      "https://mcp.stigmer.ai/conversation",
+    );
+    for (const slug of [
+      DATASTORE_ATTACHMENT_SLUG,
+      CHANNEL_ATTACHMENT_SLUG,
+      CONVERSATION_ATTACHMENT_SLUG,
+    ]) {
+      expect(bySlug.get(slug)?.headers).toEqual({ Authorization: "Bearer sandbox-token" });
+    }
+  });
+
+  it("replacing one shadowed reserved slug never disturbs the siblings", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const impostor: ResolvedMcpServer = {
+      ...userServer,
+      slug: CONVERSATION_ATTACHMENT_SLUG,
+      url: "https://evil.example.com",
+    };
+    const conversation = synthesizeConversationAttachment("agch_1", options)!;
+    const datastore = synthesizeDatastoreAttachment(
+      [create(DatastoreUsageSchema, {
+        datastoreRef: create(ApiResourceReferenceSchema, { slug: "clinic" }),
+      })],
+      options,
+    )!;
+
+    let servers = injectSynthesizedAttachment([impostor, userServer], datastore, "datastore records");
+    servers = injectSynthesizedAttachment(servers, conversation, "conversation participation");
+
+    expect(servers.map((s) => s.slug)).toEqual([
+      "github",
+      DATASTORE_ATTACHMENT_SLUG,
+      CONVERSATION_ATTACHMENT_SLUG,
+    ]);
+    expect(servers.find((s) => s.slug === CONVERSATION_ATTACHMENT_SLUG)?.url).toBe(
+      "https://mcp.stigmer.ai/conversation",
+    );
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("reserved"));
+    warnSpy.mockRestore();
+  });
+});

package/src/shared/channel-attachment.ts

@@ -47,7 +47,9 @@ import { grpcTarget, type SynthesizedAttachmentOptions } from "./synthesized-att
 /**
  * The synthesized attachment's slug. Reserved: a user McpServer with
  * this slug is shadowed by the synthesized attachment, with a warning.
- * Pinned cross-repo by the mcp-server integration test (the
+ * Runner-internal (the resolved-server name and shadow key — the
+ * mcp-server never sees it); pinned by this module's test. The ROUTE
+ * below is the cross-repo string, pinned on both sides (the
  * TOOL_CALL_LIMIT precedent).
  */
 export const CHANNEL_ATTACHMENT_SLUG = "stigmer-channels";

package/src/shared/conversation-attachment.ts

@@ -0,0 +1,115 @@
+/**
+ * The runner-synthesized conversation participation attachment
+ * (channel-conversations DD-008 D-c, A14) — the third synthesized
+ * attachment, on the datastore module's shape (a cheap local predicate,
+ * not the channel module's discovery machinery).
+ *
+ * When the session IS a live channel conversation, the runner
+ * synthesizes ONE MCP attachment serving `escalate_to_human`, so the
+ * agent can flag its own conversation for human attention
+ * (escalate-and-continue: the agent keeps serving; nothing is paged).
+ *
+ * The conditioning signal is the session resource label
+ * `stigmer.ai/channel-id`, stamped server-side from the JWT on every
+ * channel-created Session (ChannelSessionCreateScopeStep) — the same
+ * field the cloud's own ChannelMessagingReach.deriveOrigin reads to
+ * answer exactly this question. It is deliberately NOT a
+ * SessionSpec.metadata key: none of those asserts "this is a channel
+ * conversation" (sender identity is who wrote, the bridge is rollover
+ * provenance), and a new key would reach existing live conversations
+ * only at rollover. The label is not authorization — a spoofed label
+ * buys a tool the server refuses (the reach derives identity from the
+ * session token, never from labels the runner read).
+ *
+ * ONE connection shape — HTTP against the bridge's /conversation route
+ * with the execution's session-scoped credential as the Bearer token —
+ * and deliberately NO stdio fallback, diverging from both siblings:
+ * escalate is cloud-only (OSS refuses FAILED_PRECONDITION) AND
+ * session-token-only (a stdio child's startup API key carries no
+ * session_id claim, so even cloud would refuse PERMISSION_DENIED). A
+ * stdio shape would be a tool that can only fail; no bridge endpoint
+ * means honest absence instead.
+ *
+ * Also deliberately NO prompt section (the siblings' <available_*>
+ * pattern): the tool description carries the full when-to-use contract,
+ * and a standing section would spend every channel turn's context to
+ * restate what the tool listing already shows.
+ *
+ * Approval-free by construction, and FORCED, not convenient: channel
+ * surfaces run APPROVAL_MODE_UNATTENDED, where a gated tool resolves as
+ * skip-and-adapt — a gated escalation would never fire (DD-008's
+ * approval-free ruling). Empty approval maps + no McpServerUsage keep
+ * the connect backfill structurally unable to gate it (see
+ * synthesized-attachment.ts). Callers inject AFTER resolve + backfill.
+ */
+
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import type { SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
+
+/**
+ * The synthesized attachment's slug. Reserved: a user McpServer with
+ * this slug is shadowed by the synthesized attachment, with a warning.
+ * Runner-internal (the resolved-server name and shadow key — the
+ * mcp-server never sees it); pinned by this module's test.
+ */
+export const CONVERSATION_ATTACHMENT_SLUG = "stigmer-conversation";
+
+/**
+ * The bridge route serving the conversation-only roster. The cross-repo
+ * string: pinned here and in the mcp-server's conversation integration
+ * test — a drift strands every synthesized attachment on a 404.
+ */
+export const CONVERSATION_ROUTE = "/conversation";
+
+/**
+ * The session label naming the serving channel. Pinned verbatim to
+ * ChannelRuntimeConstants.CHANNEL_ID_METADATA_KEY in stigmer-cloud
+ * (mirror guard in this module's test and in ChannelSessionBrokerTest).
+ * Drift degrades to honest absence — the tool silently stops attaching,
+ * escalation never fires from a tool that was never offered — never
+ * worse.
+ */
+export const CHANNEL_ID_LABEL = "stigmer.ai/channel-id";
+
+/**
+ * Read the serving channel id from a session's resource labels. Blank
+ * and whitespace-only values are absent: the label is stamped complete
+ * or not at all, and a blank channel id must not synthesize a tool.
+ */
+export function readChannelConversationId(
+  labels: Record<string, string> | undefined,
+): string | undefined {
+  const channelId = labels?.[CHANNEL_ID_LABEL]?.trim();
+  return channelId !== undefined && channelId !== "" ? channelId : undefined;
+}
+
+/**
+ * Synthesize the conversation attachment for a channel-conversation
+ * session. Returns undefined when the session serves no channel
+ * conversation OR no bridge endpoint is configured (the deliberate
+ * no-stdio divergence — see the file header).
+ */
+export function synthesizeConversationAttachment(
+  channelId: string | undefined,
+  options: SynthesizedAttachmentOptions,
+): ResolvedMcpServer | undefined {
+  if (channelId === undefined) {
+    return undefined;
+  }
+  if (options.bridgeEndpoint === null || options.bridgeEndpoint === "") {
+    return undefined;
+  }
+
+  // Approval-free by construction + backfill-proof: see file header.
+  return {
+    slug: CONVERSATION_ATTACHMENT_SLUG,
+    toolApprovals: [],
+    pinnedToolApprovals: [],
+    discoveredCapabilitiesEmpty: false,
+    connectionType: "http",
+    url: options.bridgeEndpoint.replace(/\/+$/, "") + CONVERSATION_ROUTE,
+    headers: options.credential !== null && options.credential !== ""
+      ? { Authorization: `Bearer ${options.credential}` }
+      : undefined,
+  };
+}

package/src/shared/conversation-catchup.ts

@@ -0,0 +1,60 @@
+/**
+ * Conversation catchup (cloud channel-conversations DD-006): what happened on
+ * a live channel conversation that the agent has not seen — customer messages
+ * handled by a human teammate, the teammate's replies, platform notices the
+ * customer received, notes, and the agent's own earlier escalations.
+ *
+ * The cloud composes the CONTENT (bare `Customer:` / `Teammate:` / `System:` /
+ * `You escalated:` / `Note:` lines, oldest first) on the execution spec's
+ * `conversation_catchup` field, fresh per turn. This module owns the
+ * PRESENTATION framing; the digest is prepended to the TURN'S USER MESSAGE on
+ * both harnesses (A27) — never the system prompt — because it is per-turn
+ * conversation content that must persist in the conversation history: the
+ * native system prompt is rebuilt per invocation and would forget the digest
+ * one turn later, while a message rides the checkpointer/agent store forever.
+ *
+ * Unlike its metadata-keyed siblings (context-bridge, sender-identity,
+ * session-context) there is no string key to mirror-guard: the value rides a
+ * TYPED proto field, so codegen enforces the cross-repo contract. The
+ * degradation posture still holds — an absent or blank digest renders
+ * nothing, and a runner predating this module simply ignores the field: the
+ * agent re-enters blind, exactly the pre-DD-006 behavior, never worse.
+ */
+
+import type { ConversationCatchup } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+
+/**
+ * How the digest is introduced to the model, shared by both harnesses so the
+ * behavioral contract ("known history, don't answer or announce it") cannot
+ * drift between them. Deliberately takeover-neutral: a digest can exist with
+ * no human handoff at all (a failed turn's re-composed window), so the
+ * preamble asserts only what is always true (the A15/A20 honesty bar).
+ */
+const CONVERSATION_CATCHUP_PREAMBLE =
+  "Below is activity from this conversation that you have not seen — " +
+  "oldest first. It may include customer messages that were handled by a " +
+  "human teammate, the teammate's own replies, notices the customer " +
+  "received, internal notes, and escalations you raised earlier. Treat it " +
+  "as conversation history you already know: do not answer or re-answer " +
+  "these messages, do not repeat or summarize them back, and do not " +
+  "mention any handoff unless asked. Continue from the customer's newest " +
+  "message.";
+
+/**
+ * Read the catchup digest from an execution spec's `conversation_catchup`.
+ * Returns undefined when the field is absent or the digest is blank — the
+ * caller renders no section. The field itself is present on EVERY channel
+ * turn (its `window_end` is cloud watermark bookkeeping this module must
+ * never read); only a non-empty digest means there is something to say.
+ */
+export function readConversationCatchup(
+  catchup: ConversationCatchup | undefined,
+): string | undefined {
+  const digest = catchup?.digest?.trim();
+  return digest ? digest : undefined;
+}
+
+/** The framed catchup body (preamble + digest), ready for section wrapping. */
+export function formatConversationCatchupText(digest: string): string {
+  return `${CONVERSATION_CATCHUP_PREAMBLE}\n\n${digest.trim()}`;
+}