@stigmer/cli 3.1.7 → 3.1.8

package/src/resources/share.test.ts

@@ -0,0 +1,389 @@
+// Unit tests for the share-agent resource layer. The critical contract is
+// merge-preservation: `updateSharing` replaces `spec.sharing` wholesale, so a
+// CLI toggle must never wipe console-configured origins or visitor messages.
+
+import { clone, create } from "@bufbuild/protobuf";
+import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/status_pb";
+import type { UpdateAgentSharingInput } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import { AgentSharingAudience } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { buildEmbedSnippet, type Stigmer } from "@stigmer/sdk";
+import { describe, expect, it } from "vitest";
+import { classify, ExitCode, UsageError } from "../errors/index.js";
+import { shareAgent } from "./share.js";
+
+const CLOUD = { appOrigin: "https://app.stigmer.ai", isLocal: false };
+const LOCAL = { appOrigin: "http://localhost:8234", isLocal: true };
+
+function makeAgent(
+  sharing?: {
+    enabled?: boolean;
+    audience?: AgentSharingAudience;
+    allowedOrigins?: string[];
+    messages?: { rateLimited?: string; unavailable?: string; conversationEnded?: string };
+  },
+  shareLinkToken?: string,
+): Agent {
+  return create(AgentSchema, {
+    metadata: { id: "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", org: "acme", slug: "support-agent", name: "Support Agent" },
+    spec: sharing !== undefined ? { sharing } : {},
+    ...(shareLinkToken !== undefined ? { status: { shareLinkToken } } : {}),
+  });
+}
+
+// A minimal fake of the SDK surface shareAgent touches: agent.getByReference /
+// agent.get + call-recording agent.updateSharing / agent.rotateShareLink
+// (skill.test.ts convention). Rotation answers with the agent re-stamped
+// with `rotatedToken`, mirroring the server's fresh-entropy response.
+function fakeClient(
+  agent: Agent,
+  opts: { failWith?: Error; rotatedToken?: string } = {},
+) {
+  const calls: UpdateAgentSharingInput[] = [];
+  let rotations = 0;
+  const client = {
+    agent: {
+      async get() {
+        return agent;
+      },
+      async getByReference() {
+        return agent;
+      },
+      async updateSharing(input: UpdateAgentSharingInput) {
+        if (opts.failWith) throw opts.failWith;
+        calls.push(input);
+        return agent;
+      },
+      async rotateShareLink() {
+        rotations += 1;
+        const rotated = clone(AgentSchema, agent);
+        rotated.status = create(AgentStatusSchema, {
+          shareLinkToken: opts.rotatedToken ?? "fresh-token",
+        });
+        return rotated;
+      },
+    },
+  } as unknown as Stigmer;
+  return { client, calls, rotationCount: () => rotations };
+}
+
+describe("shareAgent merge-preservation (fails closed)", () => {
+  it("enabling preserves console-configured origins and messages verbatim", async () => {
+    const agent = makeAgent({
+      enabled: false,
+      allowedOrigins: ["https://example.com", "https://docs.example.com"],
+      messages: { rateLimited: "Slow down!", unavailable: "Back soon.", conversationEnded: "Bye!" },
+    });
+    const { client, calls } = fakeClient(agent);
+
+    await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].resourceId).toBe("agt_01ARZ3NDEKTSV4RRFFQ69G5FAV");
+    expect(calls[0].sharing?.enabled).toBe(true);
+    expect(calls[0].sharing?.allowedOrigins).toEqual(["https://example.com", "https://docs.example.com"]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("Slow down!");
+    expect(calls[0].sharing?.messages?.unavailable).toBe("Back soon.");
+    expect(calls[0].sharing?.messages?.conversationEnded).toBe("Bye!");
+  });
+
+  it("disabling preserves origins and messages, flipping only enabled", async () => {
+    const agent = makeAgent({
+      enabled: true,
+      allowedOrigins: ["https://example.com"],
+      messages: { rateLimited: "Slow down!" },
+    });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: false, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].sharing?.enabled).toBe(false);
+    expect(calls[0].sharing?.allowedOrigins).toEqual(["https://example.com"]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("Slow down!");
+    expect(result.message).toContain("Sharing disabled");
+    // No link/snippet on disable — the URL no longer works.
+    expect(result.sections).toHaveLength(0);
+  });
+
+  it("enables cleanly for an agent that has never been shared (no spec.sharing)", async () => {
+    const { client, calls } = fakeClient(makeAgent(undefined));
+
+    await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].sharing?.enabled).toBe(true);
+    expect(calls[0].sharing?.allowedOrigins).toEqual([]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("");
+  });
+
+  it("a plain toggle preserves an org-members-only audience (never reverts to public)", async () => {
+    const agent = makeAgent({
+      enabled: false,
+      audience: AgentSharingAudience.org,
+      allowedOrigins: [],
+    });
+    const { client, calls } = fakeClient(agent);
+
+    await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+    // A re-enable without --audience must keep the org restriction: writing
+    // public here would silently expose an internal agent to the internet.
+    expect(calls[0].sharing?.audience).toBe(AgentSharingAudience.org);
+  });
+});
+
+describe("shareAgent audience", () => {
+  it("--audience org sets the audience and writes the full block", async () => {
+    const agent = makeAgent({
+      enabled: true,
+      allowedOrigins: ["https://example.com"],
+      messages: { rateLimited: "Slow down!" },
+    });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "org",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].sharing?.audience).toBe(AgentSharingAudience.org);
+    expect(calls[0].sharing?.enabled).toBe(true);
+    expect(calls[0].sharing?.allowedOrigins).toEqual(["https://example.com"]);
+    expect(calls[0].sharing?.messages?.rateLimited).toBe("Slow down!");
+
+    // Org shares print the member link and NO embed snippet (embeds serve
+    // anonymous guests, which org shares refuse).
+    const link = result.sections.find((s) => s.title === "Member chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+    expect(result.sections.find((s) => s.title === "Embed on your site")).toBeUndefined();
+    expect(result.hints.some((h) => h.includes("signed-in members"))).toBe(true);
+    expect(result.hints.some((h) => h.includes("search engines"))).toBe(false);
+  });
+
+  it("--audience public converts an org share back to an explicit public one", async () => {
+    const agent = makeAgent({ enabled: true, audience: AgentSharingAudience.org });
+    const { client, calls } = fakeClient(agent);
+
+    await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "public",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(1);
+    // Written as the explicit enum value, never left unspecified.
+    expect(calls[0].sharing?.audience).toBe(AgentSharingAudience.public);
+  });
+
+  it("an audience change alone triggers a write even when enabled matches", async () => {
+    const agent = makeAgent({ enabled: true });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "org",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(result.message).toContain("Sharing enabled");
+  });
+
+  it("matching enabled AND audience stays idempotent (no write)", async () => {
+    const agent = makeAgent({ enabled: true, audience: AgentSharingAudience.org });
+    const { client, calls } = fakeClient(agent);
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      audience: "org",
+      ...CLOUD,
+    });
+
+    expect(calls).toHaveLength(0);
+    expect(result.message).toContain("already on");
+  });
+});
+
+describe("shareAgent idempotency", () => {
+  it("skips the write when sharing is already enabled, still reporting the link", async () => {
+    const { client, calls } = fakeClient(makeAgent({ enabled: true }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(0);
+    expect(result.message).toContain("already on");
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+  });
+
+  it("skips the write when sharing is already disabled", async () => {
+    const { client, calls } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: false, ...CLOUD });
+
+    expect(calls).toHaveLength(0);
+    expect(result.message).toContain("already off");
+  });
+});
+
+describe("shareAgent output", () => {
+  it("builds the link and snippet from the RESOLVED agent's org/slug (ID refs included)", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "", { enabled: true, ...CLOUD });
+
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+  });
+
+  it("emits the exact embed snippet the web share dialog emits", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    const embed = result.sections.find((s) => s.title === "Embed on your site");
+    expect(embed?.items.join("\n")).toBe(buildEmbedSnippet("https://app.stigmer.ai", "acme", "support-agent"));
+  });
+
+  it("includes the who-pays and indexability hints", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(result.hints.some((h) => h.includes("acme's credits"))).toBe(true);
+    expect(result.hints.some((h) => h.includes("search engines"))).toBe(true);
+  });
+
+  it("warns that a local link won't serve visitors (guest chat is Cloud-only)", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...LOCAL });
+
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual(["http://localhost:8234/chat/acme/support-agent"]);
+    expect(result.hints.some((h) => h.includes("Stigmer Cloud"))).toBe(true);
+  });
+
+  it("omits the local warning on a cloud backend", async () => {
+    const { client } = fakeClient(makeAgent({ enabled: false }));
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD });
+
+    expect(result.hints.some((h) => h.includes("Stigmer Cloud"))).toBe(false);
+  });
+});
+
+describe("shareAgent --reset-link (rotatable share token)", () => {
+  it("rotates and prints the fresh tokened link and snippet", async () => {
+    const { client, calls, rotationCount } = fakeClient(
+      makeAgent({ enabled: true }),
+      { rotatedToken: "fresh-token" },
+    );
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      resetLink: true,
+      ...CLOUD,
+    });
+
+    // Already enabled: no sharing write, exactly one rotation.
+    expect(calls).toHaveLength(0);
+    expect(rotationCount()).toBe(1);
+    expect(result.message).toContain("Share link reset");
+
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual([
+      "https://app.stigmer.ai/chat/acme/support-agent?k=fresh-token",
+    ]);
+    const embed = result.sections.find((s) => s.title === "Embed on your site");
+    expect(embed?.items.join("\n")).toBe(
+      buildEmbedSnippet("https://app.stigmer.ai", "acme", "support-agent", "fresh-token"),
+    );
+    expect(result.hints.some((h) => h.includes("Re-share the new link"))).toBe(true);
+  });
+
+  it("a plain toggle on a locked link keeps printing the existing tokened URL", async () => {
+    const { client, rotationCount } = fakeClient(
+      makeAgent({ enabled: true }, "existing-token"),
+    );
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      ...CLOUD,
+    });
+
+    // No rotation was requested: the current token must ride the link
+    // verbatim, or the printed URL would be dead.
+    expect(rotationCount()).toBe(0);
+    const link = result.sections.find((s) => s.title === "Public chat link");
+    expect(link?.items).toEqual([
+      "https://app.stigmer.ai/chat/acme/support-agent?k=existing-token",
+    ]);
+  });
+
+  it("refuses --reset-link for an org-members-only share with actionable guidance", async () => {
+    const { client, rotationCount } = fakeClient(
+      makeAgent({ enabled: true, audience: AgentSharingAudience.org }),
+    );
+
+    const err = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      resetLink: true,
+      ...CLOUD,
+    }).catch((e: unknown) => e);
+
+    // Org access is gated by live membership — the token is never consulted,
+    // so rotating it would be a silent no-op the user did not get.
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as Error).message).toContain("public links");
+    expect(rotationCount()).toBe(0);
+  });
+
+  it("the member link never carries a token, even when one exists in status", async () => {
+    const { client } = fakeClient(
+      makeAgent({ enabled: true, audience: AgentSharingAudience.org }, "existing-token"),
+    );
+
+    const result = await shareAgent(client, "acme/support-agent", "acme", {
+      enabled: true,
+      ...CLOUD,
+    });
+
+    const link = result.sections.find((s) => s.title === "Member chat link");
+    expect(link?.items).toEqual(["https://app.stigmer.ai/chat/acme/support-agent"]);
+  });
+});
+
+describe("shareAgent errors", () => {
+  it("fails fast with org guidance for a bare slug and no org", async () => {
+    const { client, calls } = fakeClient(makeAgent());
+
+    const err = await shareAgent(client, "support-agent", "", { enabled: true, ...CLOUD }).catch((e: unknown) => e);
+
+    expect(err).toBeInstanceOf(UsageError);
+    expect((err as Error).message).toContain("organization not set");
+    expect(classify(err)?.exitCode).toBe(ExitCode.Usage);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("does not apply the org guard to an ID reference", async () => {
+    const { client, calls } = fakeClient(makeAgent({ enabled: false }));
+
+    await shareAgent(client, "agt_01ARZ3NDEKTSV4RRFFQ69G5FAV", "", { enabled: true, ...CLOUD });
+
+    expect(calls).toHaveLength(1);
+  });
+
+  it("propagates server rejections (permission denied) unchanged", async () => {
+    const denied = new Error("permission denied: can_edit required");
+    const { client } = fakeClient(makeAgent({ enabled: false }), { failWith: denied });
+
+    await expect(shareAgent(client, "acme/support-agent", "acme", { enabled: true, ...CLOUD })).rejects.toThrow(
+      /permission denied/,
+    );
+  });
+});

package/src/resources/share.ts

@@ -0,0 +1,227 @@
+// `share agent` dispatch: enable or disable public sharing for an agent and
+// report the hosted chat link + embed snippet.
+//
+// The one correctness invariant here: the `updateSharing` RPC replaces
+// `spec.sharing` WHOLESALE. A naive "set enabled" would silently wipe any
+// `allowed_origins` or visitor messages the owner configured in the console.
+// So this module always reads the current state first and sends the complete
+// block back with only `enabled` flipped — the same merge-preserve discipline
+// as the web dialog's draftFromAgent (sdk/react ShareAgentDialog.tsx).
+//
+// URL and snippet shapes come from @stigmer/sdk's sharing helpers — the single
+// source of truth shared with the web console — so every surface emits
+// byte-identical output. The caller supplies the app origin (resolved from the
+// backend type by the command layer) to keep this module pure and env-free.
+
+import { create } from "@bufbuild/protobuf";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import {
+  RotateShareLinkInputSchema,
+  UpdateAgentSharingInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agent/v1/io_pb";
+import {
+  AgentSharingAudience,
+  AgentSharingMessagesSchema,
+  AgentSharingSchema,
+  type AgentSharing,
+} from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import { buildChatUrl, buildEmbedSnippet, type Stigmer } from "@stigmer/sdk";
+import { UsageError } from "../errors/index.js";
+import { CommandResult } from "../output/index.js";
+import { isAgentId } from "./reference.js";
+import { resolveAgentRef } from "./run/resolve.js";
+
+/** Who can chat over the shared link. Mirrors the SDK's SharingAudience. */
+export type ShareAudience = "public" | "org";
+
+/** Inputs for {@link shareAgent} beyond the reference itself. */
+export interface ShareAgentOptions {
+  /** Desired sharing state: `true` to enable, `false` to disable. */
+  readonly enabled: boolean;
+  /**
+   * Desired audience. Omitted means "keep the agent's current audience" —
+   * a plain toggle must never flip an org-members-only share back to
+   * public (or vice versa).
+   */
+  readonly audience?: ShareAudience;
+  /**
+   * Rotate the share-link token: the server generates a fresh `?k=`
+   * secret and the current link (tokened or plain) stops working
+   * immediately. The token is server-owned status — never part of the
+   * sharing block this module merges.
+   */
+  readonly resetLink?: boolean;
+  /** The app origin serving the hosted chat page and `embed.js`. */
+  readonly appOrigin: string;
+  /**
+   * Whether the CLI points at a local backend. Guest chat (the token mint
+   * behind the hosted page) is a Stigmer Cloud capability, so a local link
+   * gets a "won't serve visitors" warning alongside the result.
+   */
+  readonly isLocal: boolean;
+}
+
+/**
+ * Enable or disable sharing for the referenced agent and describe the
+ * outcome. Idempotent: when the agent is already in the desired state, no
+ * write is issued (the link is still reported when sharing is on).
+ */
+export async function shareAgent(
+  client: Stigmer,
+  ref: string,
+  org: string,
+  options: ShareAgentOptions,
+): Promise<CommandResult> {
+  // Fail fast with actionable guidance instead of the backend's cryptic
+  // "org value length must be at least 1" — mirrors the connect org guard.
+  if (org === "" && !isAgentId(ref) && !ref.includes("/")) {
+    throw new UsageError(
+      "organization not set\n\n" +
+        "Set it with:\n" +
+        "  stigmer config context set --org <org>\n" +
+        `  stigmer share agent ${ref} --org <org>`,
+    );
+  }
+
+  const agent = await resolveAgentRef(client, ref, org);
+  const current = agent.spec?.sharing;
+
+  const currentAudience = audienceFromProto(current?.audience);
+  const targetAudience = options.audience ?? currentAudience;
+
+  // Resetting the link is meaningless for org-members-only shares: their
+  // access is gated by live membership, and the member link never carries
+  // the token. Refuse rather than silently rotating an unused secret —
+  // the share dialog hides its Reset control for org audience for the
+  // same reason.
+  if (options.resetLink === true && targetAudience === "org") {
+    throw new UsageError(
+      "--reset-link only applies to public links\n\n" +
+        "This share is restricted to organization members, whose access is\n" +
+        "checked on every message. To cut someone off, remove them from the\n" +
+        "organization.",
+    );
+  }
+
+  const alreadyInState =
+    (current?.enabled ?? false) === options.enabled &&
+    currentAudience === targetAudience;
+
+  if (!alreadyInState) {
+    // Send the COMPLETE sharing block with only the requested fields changed,
+    // so a CLI toggle can never wipe console-configured origins, visitor
+    // messages, or an org-members-only audience.
+    await client.agent.updateSharing(
+      create(UpdateAgentSharingInputSchema, {
+        resourceId: agent.metadata?.id ?? "",
+        sharing: preservingSharing(current, options.enabled, targetAudience),
+      }),
+    );
+  }
+
+  // The rotation is a separate targeted RPC (the token is server-owned
+  // status, not part of the sharing block). The returned agent carries the
+  // fresh token, so the link printed below is the new one.
+  let linkToken = agent.status?.shareLinkToken ?? "";
+  if (options.resetLink === true) {
+    const rotated = await client.agent.rotateShareLink(
+      create(RotateShareLinkInputSchema, {
+        resourceId: agent.metadata?.id ?? "",
+      }),
+    );
+    linkToken = rotated.status?.shareLinkToken ?? "";
+  }
+
+  return describeOutcome(agent, options, targetAudience, linkToken, alreadyInState && options.resetLink !== true);
+}
+
+// Unspecified means public by contract (pre-audience shares keep their
+// anyone-with-link behavior).
+function audienceFromProto(audience: AgentSharingAudience | undefined): ShareAudience {
+  return audience === AgentSharingAudience.org ? "org" : "public";
+}
+
+// The full sharing config with the desired `enabled` and audience,
+// preserving origins and messages (empty defaults when the agent was never
+// shared before). The audience is written explicitly — never left
+// unspecified — so a console-managed org share can't drift back to public.
+function preservingSharing(
+  current: AgentSharing | undefined,
+  enabled: boolean,
+  audience: ShareAudience,
+): AgentSharing {
+  return create(AgentSharingSchema, {
+    enabled,
+    audience:
+      audience === "org"
+        ? AgentSharingAudience.org
+        : AgentSharingAudience.public,
+    allowedOrigins: [...(current?.allowedOrigins ?? [])],
+    messages: create(AgentSharingMessagesSchema, {
+      rateLimited: current?.messages?.rateLimited ?? "",
+      unavailable: current?.messages?.unavailable ?? "",
+      conversationEnded: current?.messages?.conversationEnded ?? "",
+    }),
+  });
+}
+
+// Build the user-facing result. Org/slug come from the RESOLVED agent's
+// metadata (authoritative even when the user passed an ID), matching how the
+// web share dialog derives them. The link token comes from the agent's
+// status (post-rotation when --reset-link ran) and rides the printed URL
+// and snippet — public audience only (org access is gated by membership).
+function describeOutcome(
+  agent: Agent,
+  options: ShareAgentOptions,
+  audience: ShareAudience,
+  linkToken: string,
+  alreadyInState: boolean,
+): CommandResult {
+  const org = agent.metadata?.org ?? "";
+  const slug = agent.metadata?.slug ?? "";
+  const name = agent.metadata?.name || slug;
+
+  if (!options.enabled) {
+    const result = CommandResult.success(
+      alreadyInState ? `Sharing is already off for '${name}'` : `Sharing disabled for '${name}'`,
+    );
+    result.hint("The share link no longer works. Re-enable with:");
+    result.hint(`  stigmer share agent ${org}/${slug}`);
+    return result;
+  }
+
+  const result = CommandResult.success(
+    options.resetLink === true
+      ? `Share link reset for '${name}' — the old link no longer works`
+      : alreadyInState
+        ? `Sharing is already on for '${name}'`
+        : `Sharing enabled for '${name}'`,
+  );
+
+  const publicLinkToken = audience === "org" ? undefined : linkToken || undefined;
+  result
+    .addSection(audience === "org" ? "Member chat link" : "Public chat link")
+    .item(buildChatUrl(options.appOrigin, org, slug, publicLinkToken));
+
+  if (audience === "org") {
+    // Embeds serve anonymous guests, which org-members-only shares refuse
+    // by design — no snippet to print.
+    result.hint(`Only signed-in members of ${org} can chat. Access ends when they leave the organization.`);
+    result.hint(`Members chat on ${org}'s credits.`);
+  } else {
+    const snippetSection = result.addSection("Embed on your site");
+    for (const line of buildEmbedSnippet(options.appOrigin, org, slug, publicLinkToken).split("\n")) {
+      snippetSection.item(line);
+    }
+
+    result.hint(`Visitors chat on ${org}'s credits.`);
+    result.hint("Public links can be forwarded and indexed by search engines.");
+    if (options.resetLink === true) {
+      result.hint("Re-share the new link with the people who should keep access.");
+    }
+  }
+  if (options.isLocal) {
+    result.hint("Guest chat is a Stigmer Cloud capability — this local link won't serve visitors.");
+  }
+  return result;
+}

package/src/resources/stream/convert.ts

@@ -18,7 +18,15 @@ import {
 import type { ToolCallInfo, TodoItemView } from "./events.js";
 
 /** Mapped tool-call status strings. */
-export type ToolStatus = "pending" | "running" | "completed" | "failed" | "waiting_approval" | "skipped" | "unknown";
+export type ToolStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "waiting_approval"
+  | "skipped"
+  | "interrupted"
+  | "unknown";
 
 /** Convert a proto ToolCall to render info. Mirrors Go's convertToolCall. */
 export function convertToolCall(tc: ToolCall): ToolCallInfo {
@@ -110,6 +118,8 @@ export function mapToolCallStatus(status: ToolCallStatus): ToolStatus {
       return "waiting_approval";
     case ToolCallStatus.TOOL_CALL_SKIPPED:
       return "skipped";
+    case ToolCallStatus.TOOL_CALL_INTERRUPTED:
+      return "interrupted";
     default:
       return "unknown";
   }
@@ -148,9 +158,13 @@ export function subAgentStatusName(status: SubAgentStatus): string {
   return SubAgentStatus[status] ?? "SUB_AGENT_STATUS_UNSPECIFIED";
 }
 
-/** True for tool statuses that mean the tool is no longer executing. Mirrors Go's isTerminalToolStatus. */
+/**
+ * True for tool statuses that mean the tool is no longer executing.
+ * "interrupted" (platform-settled at terminalization, issue #207) is terminal:
+ * without it, a settled call replays as a live running block forever.
+ */
 export function isTerminalToolStatus(status: string): boolean {
-  return status === "completed" || status === "failed" || status === "skipped";
+  return status === "completed" || status === "failed" || status === "skipped" || status === "interrupted";
 }
 
 /** True for terminal agent phases. Mirrors Go's isTerminalAgentPhase. */

package/src/resources/stream/diff.test.ts

@@ -190,6 +190,28 @@ describe("tool call interleaving", () => {
     expect(kindsFor(seq)).toContain("toolCompleted");
   });
 
+  it("running → interrupted closes the block with toolInterrupted, not toolCompleted", () => {
+    // Issue #207: the platform settles an in-flight call to INTERRUPTED when
+    // the execution terminalizes; the live differ must close its running block
+    // with the honest event (a checkmark would claim the tool finished).
+    const seq = [
+      snapshot({ messages: [aiMsg("calling", { toolCalls: [tool("t1", "shell", ToolCallStatus.TOOL_CALL_RUNNING)] })] }),
+      snapshot({ messages: [aiMsg("calling", { toolCalls: [tool("t1", "shell", ToolCallStatus.TOOL_CALL_INTERRUPTED)] })] }),
+    ];
+    const kinds = kindsFor(seq);
+    expect(kinds).toContain("toolInterrupted");
+    expect(kinds).not.toContain("toolCompleted");
+  });
+
+  it("first-sight interrupted tool (re-attach) synthesizes toolInterrupted", () => {
+    const seq = [
+      snapshot({
+        messages: [toolMsg("", [tool("t1", "read", ToolCallStatus.TOOL_CALL_INTERRUPTED)])],
+      }),
+    ];
+    expect(kindsFor(seq)).toContain("toolInterrupted");
+  });
+
   it("emits a streaming delta when a running tool's result grows", () => {
     const seq = [
       snapshot({