@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.4

package/dist/builtin/intercom/result-renderers.ts

@@ -1,77 +0,0 @@
-import type { ToolDefinition } from "@bastani/atomic";
-import { Text } from "@earendil-works/pi-tui";
-
-type ToolResultRenderer = NonNullable<ToolDefinition["renderResult"]>;
-type ToolRenderResultArgs = Parameters<ToolResultRenderer>;
-type ToolRenderResult = ReturnType<ToolResultRenderer>;
-type RenderedResult = ToolRenderResultArgs[0];
-type TextContentBlock = Extract<RenderedResult["content"][number], { type: "text" }>;
-
-type IntercomResultDetails = {
-	delivered?: boolean;
-	error?: boolean;
-	messageId?: string;
-	reason?: string;
-};
-
-type ContactSupervisorResultDetails = IntercomResultDetails & {
-	structuredReplyParseError?: string;
-};
-
-function isTextContentBlock(block: RenderedResult["content"][number]): block is TextContentBlock {
-	return block.type === "text";
-}
-
-function firstTextContent(result: RenderedResult): string {
-	return result.content.find(isTextContentBlock)?.text.replace(/\*\*/g, "") ?? "";
-}
-
-export const renderContactSupervisorResult: ToolResultRenderer = (result, { isPartial }, theme, context) => {
-	if (isPartial) {
-		return new Text(theme.fg("warning", "Waiting for supervisor..."), 0, 0);
-	}
-	const details = result.details as ContactSupervisorResultDetails | undefined;
-	const textContent = firstTextContent(result);
-	const failed = Boolean(context.isError || details?.error === true || details?.delivered === false);
-	const parseWarning = typeof details?.structuredReplyParseError === "string";
-	let text = failed
-		? theme.fg("error", "✗ ")
-		: parseWarning
-			? theme.fg("warning", "⚠ ")
-			: theme.fg("success", "✓ ");
-	text += theme.fg(failed ? "error" : "text", textContent);
-	if (parseWarning) {
-		text += "\n" + theme.fg("warning", `Structured reply parse issue: ${details.structuredReplyParseError}`);
-	}
-	return new Text(text, 0, 0);
-};
-
-export const renderIntercomResult: ToolResultRenderer = (result, { isPartial }, theme, context) => {
-	if (isPartial) {
-		return new Text(theme.fg("warning", "Intercom working..."), 0, 0);
-	}
-	const details = result.details as IntercomResultDetails | undefined;
-	const failed = Boolean(context.isError || details?.error === true || details?.delivered === false);
-	let text = failed ? theme.fg("error", "✗ ") : theme.fg("success", "✓ ");
-	text += theme.fg(failed ? "error" : "text", firstTextContent(result));
-	if (details?.messageId && !context.expanded) {
-		text += theme.fg("dim", ` (${details.messageId})`);
-	}
-	if (details?.reason && context.expanded) {
-		text += "\n" + theme.fg("dim", `Reason: ${details.reason}`);
-	}
-	return new Text(text, 0, 0);
-};
-
-export function renderIntercomToolResult(name: string, args: ToolRenderResultArgs): ToolRenderResult {
-	switch (name) {
-		case "intercom":
-			return renderIntercomResult(...args);
-		case "contact_supervisor":
-			return renderContactSupervisorResult(...args);
-		default: {
-			const theme = args[2];
-			return new Text(theme.fg("error", `Result renderer not found: ${name}`), 0, 0);
-		}
-	}
-}

package/dist/builtin/intercom/runtime-group.ts

@@ -1,13 +0,0 @@
-import { runtimeIntercomGroupEnvKey } from "@bastani/atomic";
-
-export { runtimeIntercomGroupEnvKey } from "@bastani/atomic";
-
-/** Register one extension instance's current runtime group for child inheritance. */
-export function setRuntimeIntercomGroup(sessionId: string, group: string): void {
-	process.env[runtimeIntercomGroupEnvKey(sessionId)] = group;
-}
-
-/** Remove one extension instance's runtime group without clobbering another session. */
-export function clearRuntimeIntercomGroup(sessionId: string): void {
-	delete process.env[runtimeIntercomGroupEnvKey(sessionId)];
-}

package/dist/builtin/intercom/session-target.ts

@@ -1,54 +0,0 @@
-import type { SessionInfo } from "./types.js";
-
-export type SessionTargetResolution =
-  | { kind: "resolved"; session: SessionInfo }
-  | { kind: "ambiguous_name"; matches: readonly SessionInfo[] }
-  | { kind: "not_found" };
-
-/** Resolve an Intercom session by exact ID or exact case-insensitive name. */
-export function resolveSessionTarget(
-  sessions: readonly SessionInfo[],
-  nameOrId: string,
-): SessionTargetResolution {
-  const target = nameOrId.trim();
-  const exactId = sessions.find((session) => session.id === target);
-  if (exactId !== undefined) return { kind: "resolved", session: exactId };
-
-  const lowerTarget = target.toLowerCase();
-  const exactNames = sessions.filter(
-    (session) => session.name?.toLowerCase() === lowerTarget,
-  );
-  if (exactNames.length === 1) {
-    return { kind: "resolved", session: exactNames[0]! };
-  }
-  if (exactNames.length > 1) {
-    return { kind: "ambiguous_name", matches: exactNames };
-  }
-
-  return { kind: "not_found" };
-}
-
-export function sessionTargetFailureReason(
-  target: string,
-  resolution: Exclude<SessionTargetResolution, { kind: "resolved" }>,
-): string {
-  if (resolution.kind === "ambiguous_name") {
-    return `Multiple sessions named "${target}" are connected. Use the session ID instead.`;
-  }
-  return "Session not found";
-}
-
-export interface SessionListingClient {
-  listSessions(): Promise<SessionInfo[]>;
-}
-
-/** Resolve a target through the broker's current session list. */
-export async function resolveSessionTargetId(
-  client: SessionListingClient,
-  nameOrId: string,
-): Promise<string | null> {
-  const resolution = resolveSessionTarget(await client.listSessions(), nameOrId);
-  if (resolution.kind === "resolved") return resolution.session.id;
-  if (resolution.kind === "not_found") return null;
-  throw new Error(sessionTargetFailureReason(nameOrId, resolution));
-}

package/dist/builtin/intercom/source-ownership.ts

@@ -1,31 +0,0 @@
-import { type SubagentChildPolicy } from "@bastani/atomic";
-import type { Message } from "./types.js";
-
-export function buildSubagentMessageSource(
-  runIdValue: string | undefined,
-  agentValue: string | undefined,
-  indexValue: string | undefined,
-): Message["source"] | undefined {
-  const subagentRunId = runIdValue?.trim();
-  if (!subagentRunId) return undefined;
-  const subagentAgent = agentValue?.trim();
-  const rawIndex = indexValue?.trim();
-  const parsedIndex = rawIndex === undefined ? undefined : Number(rawIndex);
-  const subagentIndex = parsedIndex !== undefined && Number.isInteger(parsedIndex) && parsedIndex >= 0
-    ? parsedIndex : undefined;
-  return {
-    subagentRunId,
-    ...(subagentAgent ? { subagentAgent } : {}),
-    ...(subagentIndex !== undefined ? { subagentIndex } : {}),
-  };
-}
-
-export function readSubagentMessageSource(policy?: SubagentChildPolicy): Message["source"] | undefined {
-	const identity = policy?.intercom;
-	if (!identity) return undefined;
-	return {
-		subagentRunId: identity.runId,
-		subagentAgent: identity.agent,
-		subagentIndex: identity.index,
-	};
-}

package/dist/builtin/intercom/stable-delivery-retry.ts

@@ -1,32 +0,0 @@
-export interface StableDeliveryRetryOptions {
-  deliver: () => Promise<void>;
-  isCurrent: () => boolean;
-  schedule?: (retry: () => void) => void;
-}
-
-/** Retries one stable-key delivery until it succeeds or its session generation retires. */
-export function retryStableDelivery(options: StableDeliveryRetryOptions): Promise<void> {
-  const schedule = options.schedule ?? ((retry) => { setTimeout(retry, 100); });
-  return new Promise((resolve, reject) => {
-    let retirementRetryUsed = false;
-    let attempted = false;
-    const attempt = (): void => {
-      if (!options.isCurrent() && (!attempted || retirementRetryUsed)) {
-        reject(new Error("Stable delivery owner retired before delivery succeeded"));
-        return;
-      }
-      if (!options.isCurrent()) retirementRetryUsed = true;
-      attempted = true;
-      const failed = (error: unknown): void => {
-        if (options.isCurrent() || !retirementRetryUsed) schedule(attempt);
-        else reject(error);
-      };
-      try {
-        void Promise.resolve(options.deliver()).then(resolve, failed);
-      } catch (error) {
-        failed(error);
-      }
-    };
-    attempt();
-  });
-}

package/dist/builtin/intercom/subagent-relay.ts

@@ -1,290 +0,0 @@
-import { isStaleExtensionContextError, type ExtensionAPI, type ExtensionContext } from "@bastani/atomic";
-import { randomUUID } from "crypto";
-import type { IntercomClient } from "./broker/client.js";
-import type { SessionInfo, Message } from "./types.js";
-import {
-  SUBAGENT_CONTROL_INTERCOM_EVENT,
-  SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT,
-  SUBAGENT_RESULT_INTERCOM_EVENT,
-  SUBAGENT_TERMINAL_ORDERING_BARRIER_EVENT,
-  SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT,
-  getErrorMessage,
-  parseSubagentIntercomPayload,
-  parseSubagentResultBarrier,
-} from "./intercom-utils.js";
-import { DeliveredMessageCache } from "./broker/delivered-message-cache.js";
-import { buildSendSignature } from "./broker/send-signature.js";
-import { emitGlobalTerminalOrderingBarrier } from "./terminal-ordering-barrier.js";
-
-interface SubagentRelayDeps {
-  runtimeGeneration(): number;
-  runtimeStarted(): boolean;
-  runtimeContext(): ExtensionContext | null;
-  getLiveContext(ctx?: ExtensionContext | null, generation?: number): ExtensionContext | null;
-  currentSessionTargetMatches(to: string, resolvedTo?: string | null, activeClient?: IntercomClient): boolean;
-  sendIncomingMessage(entry: { from: SessionInfo; message: Message; bodyText: string }, delivery: "trigger" | "followUp", generation?: number): unknown;
-  ensureConnected(reason: "background"): Promise<IntercomClient>;
-  authorizeSupervisorChild?(childName: string): Promise<import("./broker/client.js").SupervisorAuthorization>;
-  resolveSessionTarget(activeClient: IntercomClient, nameOrId: string): Promise<string | null>;
-  homeGroup?(): string;
-}
-
-async function dispatchRelayFallback(
-  pi: ExtensionAPI,
-  prefix: Array<{ customType: string; content: string; display: boolean; details?: unknown }>,
-  terminalMessage: { customType: string; content: string; display: boolean; details?: unknown },
-  stageAdmissionKey: string,
-): Promise<void> {
-  let delivered = 0;
-  try {
-    for (const message of prefix) {
-      await pi.sendMessage(message, { deliverAs: "steer" });
-      delivered += 1;
-    }
-    await pi.sendMessage(terminalMessage, { triggerTurn: true, stageAdmissionKey });
-  } catch (error) {
-    const failure = new Error(error instanceof Error ? error.message : String(error), { cause: error });
-    Object.assign(failure, { terminalPreludeDelivered: delivered });
-    throw failure;
-  }
-}
-
-export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps): void {
-  const { getLiveContext, currentSessionTargetMatches, sendIncomingMessage, ensureConnected, resolveSessionTarget } = deps;
-  const localDeliveries = new DeliveredMessageCache();
-  const localDeliveriesInFlight = new Map<string, { signature: string; completion: Promise<void> }>();
-  function deliverLocalSubagentRelayMessage(
-    sender: "subagent-control" | "subagent-result",
-    status: string,
-    messageText: string,
-    terminalBarrier?: { runId: string; terminalId?: string; sourceSessionTargets: string[] },
-    requestId?: string,
-  ): Promise<void> {
-    const now = Date.now();
-    const entry = {
-      from: {
-        id: sender, name: sender, cwd: deps.runtimeContext()?.cwd ?? process.cwd(),
-        model: sender, pid: process.pid, startedAt: now, lastActivity: now, status, group: deps.homeGroup?.(),
-      },
-      message: { id: randomUUID(), timestamp: now, content: { text: messageText } },
-      bodyText: messageText,
-    };
-    let dispatched = false;
-    let completion: Promise<void> | undefined;
-    if (terminalBarrier) {
-      const payload = {
-        ...terminalBarrier,
-        terminalAt: now,
-        source: "result-relay" as const,
-        dispatch: (prefix: Array<{ customType: string; content: string; display: boolean; details?: unknown }>) => {
-          dispatched = true;
-          const terminalMessage = {
-            customType: "intercom_message",
-            content: `**📨 From ${sender}** (${entry.from.cwd})\n\n${messageText}`,
-            display: true,
-            details: entry,
-          };
-          const stageAdmissionKey = `intercom:${requestId ?? entry.message.id}`;
-          if (typeof pi.sendMessages === "function") {
-            return pi.sendMessages([...prefix, terminalMessage], { triggerTurn: true, stageAdmissionKey });
-          }
-          return dispatchRelayFallback(pi, prefix, terminalMessage, stageAdmissionKey);
-        },
-      };
-      Object.defineProperty(payload, "terminalOwner", { value: pi });
-      try {
-        pi.events.emit(SUBAGENT_TERMINAL_ORDERING_BARRIER_EVENT, payload);
-      } catch (error) {
-        if (!isStaleExtensionContextError(error) || dispatched) throw error;
-      }
-      emitGlobalTerminalOrderingBarrier(payload);
-      completion = (payload as typeof payload & { completion?: Promise<void> }).completion;
-    }
-    if (completion) return completion;
-    if (!dispatched) return Promise.resolve(sendIncomingMessage(entry, "trigger")).then(() => {});
-    return Promise.resolve();
-  }
-  function recordSubagentDeliveryError(entryType: string, to: string, message: string, error: unknown): void {
-    pi.appendEntry(entryType, {
-      to,
-      message,
-      error: getErrorMessage(error),
-      timestamp: Date.now(),
-    });
-  }
-  function recordSubagentDeliveryErrorSafely(entryType: string, to: string, message: string, error: unknown): void {
-    try {
-      recordSubagentDeliveryError(entryType, to, message, error);
-    } catch (recordError) {
-      console.error("Failed to record local subagent relay error:", recordError);
-    }
-  }
-  function emitResultDelivery(requestId: string | undefined, delivered: boolean, error?: unknown): void {
-    if (!requestId) return;
-    try {
-      pi.events.emit(SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT, {
-        requestId,
-        delivered,
-        ...(error ? { error: getErrorMessage(error) } : {}),
-      });
-    } catch (emitError) {
-      if (!isStaleExtensionContextError(emitError)) throw emitError;
-      // Delivery acknowledgements are best effort after a runtime replacement.
-    }
-  }
-  function acknowledgeResult(options: { acknowledge?: boolean }, requestId: string | undefined, delivered: boolean, error?: unknown): void {
-    if (options.acknowledge) emitResultDelivery(requestId, delivered, error);
-  }
-  async function deliverLocal(
-    parsed: ReturnType<typeof parseSubagentIntercomPayload> & {},
-    options: { sender: "subagent-control" | "subagent-result"; status: string; errorEntryType: string; acknowledge?: boolean; terminalBarrier?: { runId: string; terminalId?: string; sourceSessionTargets: string[] } },
-  ): Promise<void> {
-    try {
-      const signature = buildSendSignature(parsed.to, { text: parsed.message });
-      const match = parsed.requestId ? localDeliveries.lookup(parsed.requestId, signature) : "miss";
-      if (match === "conflict") {
-        throw new Error(`Intercom message ID '${parsed.requestId}' was already delivered with a different target or payload`);
-      }
-      if (match === "miss") {
-        const pending = parsed.requestId ? localDeliveriesInFlight.get(parsed.requestId) : undefined;
-        if (pending && pending.signature !== signature) {
-          await pending.completion;
-          throw new Error(`Intercom message ID '${parsed.requestId}' was already delivered with a different target or payload`);
-        }
-        let delivery = pending?.completion;
-        if (!delivery && parsed.requestId) {
-          const deferred = Promise.withResolvers<void>();
-          delivery = deferred.promise;
-          void delivery.catch(() => {});
-          localDeliveriesInFlight.set(parsed.requestId, { signature, completion: delivery });
-          try {
-            void deliverLocalSubagentRelayMessage(options.sender, options.status, parsed.message, options.terminalBarrier, parsed.requestId).then(deferred.resolve, deferred.reject);
-          } catch (error) {
-            deferred.reject(error);
-          }
-          void delivery.finally(() => { localDeliveriesInFlight.delete(parsed.requestId!); }).catch(() => {});
-        } else if (!delivery) {
-          delivery = deliverLocalSubagentRelayMessage(options.sender, options.status, parsed.message, options.terminalBarrier, parsed.requestId);
-        }
-        await delivery;
-        if (parsed.requestId) localDeliveries.record(parsed.requestId, signature);
-      }
-      acknowledgeResult(options, parsed.requestId, true);
-    } catch (error) {
-      recordSubagentDeliveryErrorSafely(options.errorEntryType, parsed.to, parsed.message, error);
-      try {
-        acknowledgeResult(options, parsed.requestId, false, error);
-      } catch (ackError) {
-        console.error("Failed to acknowledge local subagent relay error:", ackError);
-      }
-    }
-  }
-  function relaySubagentIntercomPayload(payload: unknown, options: {
-    sender: "subagent-control" | "subagent-result";
-    status: string;
-    errorEntryType: string;
-    acknowledge?: boolean;
-  }): void {
-    const parsed = parseSubagentIntercomPayload(payload);
-    if (!parsed) return;
-    const terminalBarrier = options.sender === "subagent-result" ? parseSubagentResultBarrier(payload) ?? undefined : undefined;
-
-    const relayGeneration = deps.runtimeGeneration();
-    void (async () => {
-      const runtimeLive = () => Boolean(getLiveContext(deps.runtimeContext(), relayGeneration));
-      const relayStillLive = () => !deps.runtimeStarted() || runtimeLive();
-      if (!relayStillLive()) {
-        acknowledgeResult(options, parsed.requestId, false);
-        return;
-      }
-      if (currentSessionTargetMatches(parsed.to)) {
-        await deliverLocal(parsed, { ...options, terminalBarrier });
-        return;
-      }
-      if (!deps.runtimeStarted()) {
-        // The runtime never initialized for this session (no session_start
-        // reached the extension and no lifecycle context was available), so a
-        // broker connection attempt can only fail. Acknowledge the message as
-        // undelivered without recording a misleading connection error entry;
-        // callers treat an undelivered ack as their inline-result fallback.
-        acknowledgeResult(options, parsed.requestId, false, new Error("Intercom runtime not initialized"));
-        return;
-      }
-
-      let activeClient: IntercomClient;
-      let target: string;
-      try {
-        activeClient = await ensureConnected("background");
-        target = await resolveSessionTarget(activeClient, parsed.to) ?? parsed.to;
-      } catch (error) {
-        if (!relayStillLive()) {
-          acknowledgeResult(options, parsed.requestId, false, error);
-          return;
-        }
-        recordSubagentDeliveryErrorSafely(options.errorEntryType, parsed.to, parsed.message, error);
-        acknowledgeResult(options, parsed.requestId, false, error);
-        return;
-      }
-
-      if (!relayStillLive()) {
-        acknowledgeResult(options, parsed.requestId, false);
-        return;
-      }
-      if (currentSessionTargetMatches(parsed.to, target, activeClient)) {
-        await deliverLocal(parsed, { ...options, terminalBarrier });
-        return;
-      }
-
-      try {
-        const result = await activeClient.send(target, {
-          text: parsed.message,
-          ...(parsed.requestId ? { messageId: parsed.requestId } : {}),
-        });
-        if (!relayStillLive()) {
-          acknowledgeResult(options, parsed.requestId, result.delivered);
-          return;
-        }
-        if (!result.delivered) {
-          const error = new Error(result.reason ?? "Session may not exist or has disconnected.");
-          recordSubagentDeliveryErrorSafely(options.errorEntryType, parsed.to, parsed.message, error);
-          acknowledgeResult(options, parsed.requestId, false, error);
-          return;
-        }
-        acknowledgeResult(options, parsed.requestId, true);
-      } catch (error) {
-        if (!relayStillLive()) {
-          acknowledgeResult(options, parsed.requestId, false, error);
-          return;
-        }
-        recordSubagentDeliveryErrorSafely(options.errorEntryType, parsed.to, parsed.message, error);
-        acknowledgeResult(options, parsed.requestId, false, error);
-      }
-    })().catch((error) => {
-      if (!isStaleExtensionContextError(error)) {
-        console.error("Subagent intercom relay failed:", error);
-      }
-    });
-  }
-  pi.events.on(SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT, (payload) => {
-    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
-    const request = payload as { childName?: unknown; completion?: Promise<unknown> };
-    const childName = typeof request.childName === "string" ? request.childName.trim() : "";
-    if (!childName || request.completion || !deps.authorizeSupervisorChild) return;
-    request.completion = deps.authorizeSupervisorChild(childName);
-  });
-  pi.events.on(SUBAGENT_CONTROL_INTERCOM_EVENT, (payload) => {
-    relaySubagentIntercomPayload(payload, {
-      sender: "subagent-control",
-      status: "needs_attention",
-      errorEntryType: "intercom_control_error",
-    });
-  });
-  pi.events.on(SUBAGENT_RESULT_INTERCOM_EVENT, (payload) => {
-    relaySubagentIntercomPayload(payload, {
-      sender: "subagent-result",
-      status: "result",
-      errorEntryType: "intercom_result_error",
-      acknowledge: true,
-    });
-  });
-}

package/dist/builtin/intercom/supervisor-authorization-registry.ts

@@ -1,22 +0,0 @@
-import { randomUUID } from "node:crypto";
-import type { IntercomClient, SupervisorAuthorization } from "./broker/client.js";
-
-/** Parent-runtime cache used to restore broker capabilities after reconnects. */
-export class SupervisorAuthorizationRegistry {
-  private readonly byCapability = new Map<string, SupervisorAuthorization>();
-  readonly ownerToken = randomUUID();
-
-  async authorize(childName: string, connect: () => Promise<IntercomClient>): Promise<SupervisorAuthorization> {
-    const client = await connect();
-    const authorization = await client.authorizeSupervisorChild(childName.trim());
-    this.byCapability.set(authorization.capability, authorization);
-    return authorization;
-  }
-
-  async restore(client: IntercomClient): Promise<void> {
-    for (const [capability, existing] of this.byCapability) {
-      const authorization = await client.authorizeSupervisorChild(existing.childName, capability);
-      this.byCapability.set(capability, authorization);
-    }
-  }
-}