@stigmer/runner 3.6.0 → 3.8.0

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/artifact-storage.ts

@@ -89,11 +89,23 @@ export class LocalArtifactStorage implements ArtifactStorage {
 
 export class ProxyArtifactStorage implements ArtifactStorage {
   private readonly baseUrl: string;
-  private readonly authToken: string;
+  private readonly authTokenSource: ProxyAuthTokenSource;
 
-  constructor(proxyEndpoint: string, authToken: string) {
+  constructor(proxyEndpoint: string, authToken: ProxyAuthTokenSource) {
     this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/artifacts`;
-    this.authToken = authToken;
+    this.authTokenSource = authToken;
+  }
+
+  /**
+   * Resolve the credential per call rather than pinning the boot token: a
+   * cloud sandbox's control-plane token rotates in place (see
+   * sandbox-token-renewal.ts), and this storage lives for the pod's whole
+   * life — a captured string would silently 401 after the first rotation.
+   */
+  private get authToken(): string {
+    return typeof this.authTokenSource === "string"
+      ? this.authTokenSource
+      : (this.authTokenSource.current ?? "");
   }
 
   async upload(key: string, content: Buffer, contentType?: string): Promise<string> {
@@ -214,12 +226,18 @@ export class ProxyArtifactStorage implements ArtifactStorage {
 
 // ── Factory ──────────────────────────────────────────────────────────
 
+/**
+ * The proxy credential, either fixed (a caller-supplied string) or live (a
+ * shared mutable ref, read per call — the sandbox token-renewal posture).
+ */
+export type ProxyAuthTokenSource = string | { readonly current: string | null };
+
 export interface ArtifactStorageConfig {
   readonly type: ArtifactStorageType;
   readonly localPath: string;
   readonly localServeUrl: string;
   readonly proxyEndpoint: string | null;
-  readonly proxyAuthToken: string | null;
+  readonly proxyAuthToken: ProxyAuthTokenSource | null;
 }
 
 export function loadArtifactStorageConfig(config: Config): ArtifactStorageConfig {
@@ -239,7 +257,11 @@ export function loadArtifactStorageConfig(config: Config): ArtifactStorageConfig
     localPath: process.env.LOCAL_ARTIFACT_PATH ?? "/var/stigmer/artifacts",
     localServeUrl: process.env.LOCAL_ARTIFACT_SERVE_URL ?? "http://localhost:7235",
     proxyEndpoint: type === "proxy" ? (config.proxyEndpoint ?? null) : null,
-    proxyAuthToken: type === "proxy" ? (config.stigmerToken ?? null) : null,
+    // Prefer the live ref: renewal rotates the token in place and uploads
+    // must present the current credential, not the boot one.
+    proxyAuthToken: type === "proxy"
+      ? (config.stigmerTokenRef ?? config.stigmerToken ?? null)
+      : null,
   };
 }
 
@@ -248,10 +270,13 @@ export function createArtifactStorage(cfg: ArtifactStorageConfig): ArtifactStora
     if (!cfg.proxyEndpoint) {
       throw new Error("Proxy artifact storage requires STIGMER_PROXY_ENDPOINT");
     }
-    if (!cfg.proxyAuthToken) {
+    const tokenAtBoot = typeof cfg.proxyAuthToken === "string"
+      ? cfg.proxyAuthToken
+      : cfg.proxyAuthToken?.current;
+    if (!tokenAtBoot) {
       throw new Error("Proxy artifact storage requires STIGMER_TOKEN");
     }
-    return new ProxyArtifactStorage(cfg.proxyEndpoint, cfg.proxyAuthToken);
+    return new ProxyArtifactStorage(cfg.proxyEndpoint, cfg.proxyAuthToken!);
   }
 
   return new LocalArtifactStorage(cfg.localPath, cfg.localServeUrl);

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()}`;
+}

package/src/workflow-engine/__tests__/golden-execution.test.ts

@@ -404,9 +404,9 @@ describe("Golden Execution — Tier 1d: Advanced Tasks", () => {
     expect(config.message).not.toContain("${ $context");
     expect(config.message).not.toContain("${ $input");
     expect(config.env).toEqual({ GITHUB_TOKEN: "${.secrets.GITHUB_TOKEN}" });
-    expect(config.config?.model).toBe("claude-3-5-sonnet");
-    expect(config.config?.timeout).toBe(300);
-    expect(config.config?.temperature).toBe(0.2);
+    expect(config.run_config?.model_name).toBe("claude-3-5-sonnet");
+    expect(config.run_config?.max_cost_usd).toBe(0.75);
+    expect(config.run_config?.service_tier).toBe("SERVICE_TIER_STANDARD");
     expect(config.harness).toBe("HARNESS_NATIVE");
     expect(config.output?.schema).toBeDefined();
     expect(config.output?.schema.required).toContain("severity");
@@ -428,7 +428,6 @@ describe("Golden Execution — Tier 1d: Advanced Tasks", () => {
       "      with:",
       '        agent: "stigmer/code-reviewer"',
       '        message: "Review this"',
-      '        org: "stigmer"',
     ].join("\n");
 
     const model = loadWorkflowFromYaml(crossOrgYaml);
@@ -444,7 +443,6 @@ describe("Golden Execution — Tier 1d: Advanced Tasks", () => {
     expect(mockCallAgent).toHaveBeenCalledOnce();
     const [config] = mockCallAgent.mock.calls[0];
     expect(config.agent).toBe("stigmer/code-reviewer");
-    expect(config.org).toBe("stigmer");
     expect(config.message).toBe("Review this");
   });
 
@@ -1048,9 +1046,11 @@ describe("Golden Execution — Structured Output Pipeline", () => {
     expect(config.message).toContain("Date: 2026-05-26");
     expect(config.message).not.toContain("${ $env");
 
-    // Config and harness preserved
-    expect(config.config?.model).toBe("claude-sonnet-4");
-    expect(config.config?.timeout).toBe(300);
+    // Run config and harness preserved. The tier arrives canonical from the
+    // golden's "fast" shorthand — the loader mapping riding a full workflow
+    // load (#357).
+    expect(config.run_config?.model_name).toBe("claude-sonnet-4");
+    expect(config.run_config?.service_tier).toBe("SERVICE_TIER_FAST");
     expect(config.harness).toBe("HARNESS_CURSOR");
     expect(metadata.taskName).toBe("analyze_player_data");