@stigmer/cli 3.1.6 → 3.1.8

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({

package/src/resources/stream/events.ts

@@ -15,7 +15,7 @@ import type { JsonObject } from "@bufbuild/protobuf";
 export interface ToolCallInfo {
   readonly id: string;
   readonly name: string;
-  /** Mapped status: pending|running|completed|failed|waiting_approval|skipped|unknown. */
+  /** Mapped status: pending|running|completed|failed|waiting_approval|skipped|interrupted|unknown. */
   readonly status: string;
   readonly args?: JsonObject;
   readonly result: string;
@@ -85,6 +85,19 @@ export interface ToolCompletedEvent {
   readonly subAgentId: string;
 }
 
+/**
+ * A tool call the platform settled to INTERRUPTED because its execution
+ * terminalized mid-call (issue #207). A distinct terminal event — routing it
+ * through toolCompleted would print a dishonest checkmark for a tool that
+ * never finished.
+ */
+export interface ToolInterruptedEvent {
+  readonly kind: "toolInterrupted";
+  readonly toolCallId: string;
+  readonly toolCall: ToolCallInfo;
+  readonly subAgentId: string;
+}
+
 export interface ToolWaitingApprovalEvent {
   readonly kind: "toolWaitingApproval";
   readonly toolCallId: string;
@@ -175,6 +188,7 @@ export type StreamEvent =
   | ToolResultEvent
   | ToolRunningEvent
   | ToolCompletedEvent
+  | ToolInterruptedEvent
   | ToolWaitingApprovalEvent
   | ToolStreamDeltaEvent
   | SystemMessageEvent

package/src/resources/stream/render-ndjson.test.ts

@@ -62,6 +62,16 @@ describe("envelope", () => {
 });
 
 describe("tool events", () => {
+  it("emits tool_interrupted as its own wire type (issue #207)", () => {
+    const { data } = render([
+      { kind: "toolInterrupted", toolCallId: "t1", subAgentId: "", toolCall: toolInfo({ id: "t1", name: "shell", status: "interrupted" }) },
+    ]);
+    expect(data.lines()[0]).toMatchObject({
+      type: "tool_interrupted",
+      payload: { tool_call_id: "t1", tool_name: "shell", status: "interrupted" },
+    });
+  });
+
   it("emits tool_running with only the meaningful fields", () => {
     const { data } = render([
       { kind: "toolRunning", toolCallId: "t1", subAgentId: "", toolCall: toolInfo({ id: "t1", result: "out", durationMs: 42 }) },

package/src/resources/stream/render-ndjson.ts

@@ -77,6 +77,8 @@ function mapToNdjson(event: StreamEvent): MappedEvent | undefined {
       return { type: "tool_running", payload: toolEventPayload(event.toolCallId, event.toolCall, event.subAgentId) };
     case "toolCompleted":
       return { type: "tool_completed", payload: toolEventPayload(event.toolCallId, event.toolCall, event.subAgentId) };
+    case "toolInterrupted":
+      return { type: "tool_interrupted", payload: toolEventPayload(event.toolCallId, event.toolCall, event.subAgentId) };
     case "toolWaitingApproval":
       return {
         type: "tool_waiting_approval",

package/src/resources/stream/render-plaintext.test.ts

@@ -39,6 +39,14 @@ describe("PlaintextRenderer", () => {
     expect(status).toContain("✗ shell: exploded");
   });
 
+  it("renders an interrupted tool with the neutral glyph, not a checkmark (issue #207)", () => {
+    const { status } = render([
+      { kind: "toolInterrupted", toolCallId: "t1", subAgentId: "", toolCall: toolInfo({ name: "shell", status: "interrupted" }) },
+    ]);
+    expect(status).toContain("⊘ shell (interrupted)");
+    expect(status).not.toContain("✓");
+  });
+
   it("notes the auto-skip for approvals and resolves to SKIP", () => {
     const r = new PlaintextRenderer({ data: { write: () => {} }, status: { write: () => {} } });
     const action = r.resolveApproval({

package/src/resources/stream/render-plaintext.ts

@@ -49,6 +49,9 @@ export class PlaintextRenderer implements HeadlessRenderer {
             : `  ✓ ${event.toolCall.name}\n`,
         );
         return;
+      case "toolInterrupted":
+        status.write(`  ⊘ ${event.toolCall.name} (interrupted)\n`);
+        return;
       case "approvalNeeded":
         status.write(`  ⚠ Approval needed: ${event.toolName} (auto-skipped in non-TTY mode)\n`);
         return;

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

@@ -79,6 +79,20 @@ describe("snapshotToEvents", () => {
     expect(events[0]).toMatchObject({ kind: "toolCompleted", toolCallId: "tc1" });
   });
 
+  it("replays a platform-interrupted call as toolInterrupted — never a live running block", () => {
+    // Issue #207: before the fix an INTERRUPTED status fell through to
+    // "unknown" (non-terminal) and replayed as toolRunning, a block that never
+    // closes. It must replay as its own settled event.
+    const events = snapshotToEvents([
+      exec({
+        phase: ExecutionPhase.EXECUTION_CANCELLED,
+        messages: [toolMsg(tool("tc1", ToolCallStatus.TOOL_CALL_INTERRUPTED))],
+      }),
+    ]);
+    expect(kinds(events)).toEqual(["toolInterrupted", "done"]);
+    expect(events[0]).toMatchObject({ kind: "toolInterrupted", toolCallId: "tc1" });
+  });
+
   it("only the final execution emits done", () => {
     const events = snapshotToEvents([
       exec({ message: "first", messages: [aiMsg("a")] }),

package/src/resources/stream/snapshot.ts

@@ -159,7 +159,11 @@ function emitOtherMessage(out: StreamEvent[], msg: AgentMessage): void {
 function emitToolByStatus(out: StreamEvent[], tc: ToolCall): void {
   const status = mapToolCallStatus(tc.status);
   const toolCall = convertToolCall(tc);
-  if (isTerminalToolStatus(status)) {
+  if (status === "interrupted") {
+    // Terminal but never "completed": replaying a platform-interrupted call as
+    // either a checkmark or a live running block would lie (issue #207).
+    out.push({ kind: "toolInterrupted", toolCallId: tc.id, toolCall, subAgentId: "" });
+  } else if (isTerminalToolStatus(status)) {
     out.push({ kind: "toolCompleted", toolCallId: tc.id, toolCall, subAgentId: "" });
   } else if (status === "waiting_approval") {
     out.push({ kind: "toolWaitingApproval", toolCallId: tc.id, toolCall, subAgentId: "" });

package/src/resources/stream/tool-state.ts

@@ -55,14 +55,14 @@ export class ToolStateTracker {
       // First sight, already terminal (e.g. re-attach): synthesize completion so
       // the block exists — otherwise its MESSAGE_TOOL is suppressed and it vanishes.
       if (!seen && isTerminalToolStatus(current)) {
-        pending.push(this.completed(tc, subAgentId));
+        pending.push(this.terminal(tc, current, subAgentId));
         this.states.set(tc.id, current);
         continue;
       }
 
       // running/waiting -> terminal: close the block.
       if (seen && (prev === "running" || prev === "waiting_approval") && isTerminalToolStatus(current)) {
-        pending.push(this.completed(tc, subAgentId));
+        pending.push(this.terminal(tc, current, subAgentId));
         this.states.set(tc.id, current);
         this.results.delete(tc.id);
         continue;
@@ -113,8 +113,16 @@ export class ToolStateTracker {
     return { kind: "toolWaitingApproval", toolCallId: tc.id, toolCall: convertToolCall(tc), subAgentId };
   }
 
-  private completed(tc: ToolCall, subAgentId: string): StreamEvent {
-    return { kind: "toolCompleted", toolCallId: tc.id, toolCall: convertToolCall(tc), subAgentId };
+  // The terminal-close event for a settled status: interrupted gets its own
+  // kind (issue #207) so renderers never print a checkmark for a tool the
+  // platform cut short; every other terminal status closes as completed.
+  private terminal(tc: ToolCall, status: string, subAgentId: string): StreamEvent {
+    return {
+      kind: status === "interrupted" ? "toolInterrupted" : "toolCompleted",
+      toolCallId: tc.id,
+      toolCall: convertToolCall(tc),
+      subAgentId,
+    };
   }
 }
 
@@ -123,6 +131,7 @@ export function toolEventId(event: StreamEvent): string {
   switch (event.kind) {
     case "toolRunning":
     case "toolCompleted":
+    case "toolInterrupted":
     case "toolWaitingApproval":
     case "toolStreamDelta":
       return event.toolCallId;