@stigmer/cli 3.1.7 → 3.1.9

package/src/resources/share.ts

@@ -0,0 +1,287 @@
+// `share agent` dispatch: enable or disable sharing for an agent and report
+// the hosted chat link + embed snippet.
+//
+// Sharing lives in its own AgentShare resource (decision 011) — the agent is
+// never modified. This module resolves the agent, reads its canonical share,
+// and commits changes via `agentShare.apply`, an idempotent upsert keyed on
+// the share's (org, slug) identity: the first enable creates the share, later
+// toggles update it, one code path.
+//
+// The one correctness invariant here: apply replaces the share's spec
+// WHOLESALE. A naive "set enabled" would silently wipe any allowed_origins,
+// visitor messages, audience, or credential bindings the owner configured in
+// the console. So this module always reads the current share first and sends
+// the complete spec back with only the requested fields flipped — the same
+// merge-preserve discipline as the web dialog. (The rotatable link token is
+// exempt: it is server-owned status, which survives every apply verbatim.)
+//
+// 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 type { AgentShare } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import {
+  GetAgentSharesByAgentRequestSchema,
+  RotateShareLinkInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/io_pb";
+import { AgentShareAudience } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/spec_pb";
+import {
+  buildChatUrl,
+  buildEmbedSnippet,
+  type AgentShareInput,
+  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 share'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
+   * spec 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 canonical share is already in the desired
+ * state, no write is issued (the link is still reported when sharing is
+ * on). When the agent has never been shared, enabling creates the share.
+ */
+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);
+  let share = await resolveCanonicalShare(client, agent);
+  const current = share?.spec;
+
+  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.",
+    );
+  }
+
+  // Never-shared + disable is a no-op, not a write: creating a share row
+  // just to mark it disabled would materialize a resource the owner never
+  // asked for. The one exception is an explicit --audience org, which is
+  // real configuration worth persisting as a paused share (mirroring the
+  // pre-promotion behavior of storing audience on a disabled block).
+  const alreadyInState =
+    share !== null
+      ? (current?.enabled ?? false) === options.enabled &&
+        currentAudience === targetAudience
+      : !options.enabled && targetAudience !== "org";
+
+  if (!alreadyInState) {
+    // Apply the COMPLETE spec with only the requested fields changed, so a
+    // CLI toggle can never wipe console-configured origins, visitor
+    // messages, credential bindings, or an org-members-only audience.
+    share = await client.agentShare.apply(
+      preservingShareInput(agent, share, options.enabled, targetAudience),
+    );
+  }
+
+  // The rotation is a separate targeted RPC (the token is server-owned
+  // status, not part of the spec apply merges). The returned share carries
+  // the fresh token, so the link printed below is the new one.
+  if (options.resetLink === true && share !== null) {
+    share = await client.agentShare.rotateShareLink(
+      create(RotateShareLinkInputSchema, {
+        resourceId: share.metadata?.id ?? "",
+      }),
+    );
+  }
+
+  return describeOutcome(
+    agent,
+    share,
+    options,
+    targetAudience,
+    alreadyInState && options.resetLink !== true,
+  );
+}
+
+/**
+ * The agent's canonical share: the one whose slug equals the agent's (the
+ * server's default on create), else the first entry, else null when the
+ * agent has never been shared. Mirrors the web dialog's selection so both
+ * surfaces manage the same row (decision 011 D3: one canonical share in
+ * Phase A).
+ */
+async function resolveCanonicalShare(
+  client: Stigmer,
+  agent: Agent,
+): Promise<AgentShare | null> {
+  const result = await client.agentShare.getByAgent(
+    create(GetAgentSharesByAgentRequestSchema, {
+      agentId: agent.metadata?.id ?? "",
+    }),
+  );
+  const agentSlug = agent.metadata?.slug ?? "";
+  return (
+    result.items.find((share) => share.metadata?.slug === agentSlug) ??
+    result.items[0] ??
+    null
+  );
+}
+
+// Unspecified means public by contract (a share created without an explicit
+// audience is an anyone-with-link share).
+function audienceFromProto(audience: AgentShareAudience | undefined): ShareAudience {
+  return audience === AgentShareAudience.org ? "org" : "public";
+}
+
+// The full share input with the desired `enabled` and audience, preserving
+// origins, messages, and credential bindings (empty defaults when the agent
+// was never shared before). Identity comes from the existing share when one
+// exists — a manifest-created share may carry a non-default slug, and
+// applying with the agent's slug would create a SECOND share — and from the
+// agent otherwise (the server's own D2 default, made explicit). The audience
+// is written explicitly — never left unspecified — so a console-managed org
+// share can't drift back to public.
+function preservingShareInput(
+  agent: Agent,
+  share: AgentShare | null,
+  enabled: boolean,
+  audience: ShareAudience,
+): AgentShareInput {
+  const agentOrg = agent.metadata?.org ?? "";
+  const agentSlug = agent.metadata?.slug ?? "";
+  const current = share?.spec;
+  return {
+    org: share?.metadata?.org || agentOrg,
+    slug: share?.metadata?.slug || agentSlug,
+    name: share?.metadata?.name || agent.metadata?.name || agentSlug,
+    agentRef: { org: agentOrg, slug: agentSlug },
+    enabled,
+    audience:
+      audience === "org"
+        ? AgentShareAudience.org
+        : AgentShareAudience.public,
+    allowedOrigins: [...(current?.allowedOrigins ?? [])],
+    messages: {
+      rateLimited: current?.messages?.rateLimited ?? "",
+      unavailable: current?.messages?.unavailable ?? "",
+      conversationEnded: current?.messages?.conversationEnded ?? "",
+    },
+    environmentRefs: (current?.environmentRefs ?? []).map((envRef) => ({
+      org: envRef.org,
+      slug: envRef.slug,
+    })),
+  };
+}
+
+// Build the user-facing result. Org/slug come from the SHARE's metadata —
+// the identity in the hosted chat URL (a share may carry a non-default
+// slug) — falling back to the resolved agent's on disable-when-never-shared.
+// The link token comes from the share'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,
+  share: AgentShare | null,
+  options: ShareAgentOptions,
+  audience: ShareAudience,
+  alreadyInState: boolean,
+): CommandResult {
+  const org = share?.metadata?.org || (agent.metadata?.org ?? "");
+  const slug = share?.metadata?.slug || (agent.metadata?.slug ?? "");
+  const name = agent.metadata?.name || slug;
+  const linkToken = share?.status?.shareLinkToken ?? "";
+
+  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;