@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/src/pi-intercom/inspection.ts

@@ -0,0 +1,82 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { IntercomTransport } from "./transport.ts";
+import type { InboundJournal } from "./inbound-journal.ts";
+import type { ReplyTracker } from "./reply-tracker.ts";
+import type { IntercomSessionScope, ToolResultLike } from "./runtime-types.ts";
+import { formatSessionListSections, sessionsForScope } from "./ui/session-format.ts";
+import { formatSessionTarget } from "./session-targets.ts";
+import { pendingAskPreview } from "./message-format.ts";
+import { toolError, toolText } from "./tool-arguments.ts";
+import { errorMessage } from "./validation.ts";
+type Journal = Readonly<Pick<InboundJournal, "entries" | "reconcileConsumed">>;
+type Replies = Readonly<Pick<ReplyTracker, "listPending">>;
+
+export class IntercomInspection {
+  private readonly journal: Journal;
+  private readonly replies: Replies;
+  constructor(journal: Journal, replies: Replies) {
+    this.journal = journal;
+    this.replies = replies;
+  }
+  pending(): ToolResultLike {
+    const asks = this.replies.listPending();
+    if (asks.length === 0) {
+      return toolText("No unresolved inbound asks.");
+    }
+    const now = Date.now();
+    const lines = asks.map(({ from, message, receivedAt }) => {
+      const sender =
+        from.name !== undefined && from.name !== ""
+          ? `${from.name} (${formatSessionTarget(
+              from,
+              asks.map((ask) => ask.from),
+            )})`
+          : from.id;
+      const replyTo = JSON.stringify(message.id);
+      return `- ${sender} · replyTo: ${replyTo} · ${Math.max(0, Math.floor((now - receivedAt) / 1000))}s ago · ${pendingAskPreview(message)}\n  Reply: intercom({ action: "reply", replyTo: ${replyTo}, message: "..." })`;
+    });
+    return toolText(`**Pending asks:**\n${lines.join("\n")}`);
+  }
+  async list(active: IntercomTransport, scope: IntercomSessionScope): Promise<ToolResultLike> {
+    try {
+      const id = active.sessionId;
+      if (id === null || id === "") {
+        throw new Error("Current intercom session id is unavailable.");
+      }
+      const all = await active.listSessions();
+      return toolText(formatSessionListSections(all, id, scope), {
+        sessionCount: sessionsForScope(all, id, scope).length,
+      });
+    } catch (error) {
+      return toolError(`Failed to list sessions: ${errorMessage(error)}`);
+    }
+  }
+  async status(
+    active: IntercomTransport,
+    scope: IntercomSessionScope,
+    ctx: ExtensionContext,
+  ): Promise<ToolResultLike> {
+    try {
+      const id = active.sessionId;
+      if (id === null || id === "") {
+        throw new Error("Current intercom session id is unavailable.");
+      }
+      const all = await active.listSessions();
+      this.journal.reconcileConsumed(ctx);
+      const pending = this.journal.entries();
+      const lines = pending.map(
+        (entry) =>
+          `- ${entry.from.name === undefined || entry.from.name === "" ? entry.from.id : entry.from.name} [${entry.message.id}] (${entry.stage === "queued" ? "queued; not yet delivered to model" : "delivered to model queue; not yet consumed"})\n${entry.bodyText}`,
+      );
+      const text =
+        pending.length > 0
+          ? `\n\nPending inbound messages: ${pending.length}\n${lines.join("\n\n")}`
+          : "\n\nPending inbound messages: 0";
+      return toolText(
+        `**Intercom Status:**\nConnected: Yes\nSession ID: ${id}\nConnected sessions in scope: ${sessionsForScope(all, id, scope).length}\n\n${formatSessionListSections(all, id, scope)}${text}`,
+      );
+    } catch (error) {
+      return toolError(`Failed to get status: ${errorMessage(error)}`);
+    }
+  }
+}

package/src/pi-intercom/interview.ts

@@ -0,0 +1,295 @@
+import { errorMessage, isRecord, isUnknownArray } from "./validation.ts";
+
+export type InterviewType = "single" | "multi" | "text" | "image" | "info";
+export type InterviewOption =
+  | string
+  | (Readonly<Record<string, unknown>> & { readonly label: string });
+export interface SupervisorInterviewQuestion extends Readonly<Record<string, unknown>> {
+  readonly id: string;
+  readonly type: InterviewType;
+  readonly question: string;
+  readonly options?: readonly InterviewOption[];
+}
+export interface SupervisorInterviewRequest extends Readonly<Record<string, unknown>> {
+  readonly title?: string;
+  readonly description?: string;
+  readonly questions: readonly SupervisorInterviewQuestion[];
+}
+export interface SupervisorInterviewReply {
+  readonly responses: readonly { readonly id: string; readonly value: unknown }[];
+}
+function interviewType(value: unknown): value is InterviewType {
+  return (
+    value === "single" ||
+    value === "multi" ||
+    value === "text" ||
+    value === "image" ||
+    value === "info"
+  );
+}
+function nonempty(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} must be a non-empty string`);
+  }
+  return value.trim();
+}
+function optionValue(value: unknown, field: string): InterviewOption {
+  if (typeof value === "string") {
+    const label = value.trim();
+    if (label === "") {
+      throw new Error(`${field} must not be empty`);
+    }
+    return label;
+  }
+  if (!isRecord(value) || typeof value.label !== "string" || value.label.trim() === "") {
+    throw new Error(`${field} must be a non-empty string or an object with a non-empty label`);
+  }
+  return { ...value, label: value.label.trim() };
+}
+function parseOptions(
+  raw: Readonly<Record<string, unknown>>,
+  field: string,
+  type: InterviewType,
+): readonly InterviewOption[] | undefined {
+  if (raw.options === undefined) {
+    if (type === "single" || type === "multi") {
+      throw new Error(`${field}.options must be a non-empty array for ${type} questions`);
+    }
+    return;
+  }
+  if (!isUnknownArray(raw.options)) {
+    throw new Error(`${field}.options must be an array when provided`);
+  }
+  const options = raw.options.map((option, index) =>
+    optionValue(option, `${field}.options[${index}]`),
+  );
+  if (type !== "single" && type !== "multi") {
+    throw new Error(`${field}.options is only valid for single and multi questions`);
+  }
+  if (options.length === 0) {
+    throw new Error(`${field}.options must be a non-empty array for ${type} questions`);
+  }
+  return options;
+}
+function parseQuestion(value: unknown, index: number): SupervisorInterviewQuestion {
+  const field = `interview.questions[${index}]`;
+  if (!isRecord(value)) {
+    throw new Error(`${field} must be an object`);
+  }
+  const id = nonempty(value.id, `${field}.id`);
+  if (!interviewType(value.type)) {
+    throw new Error(`${field}.type must be one of: single, multi, text, image, info`);
+  }
+  const question = nonempty(value.question, `${field}.question`);
+  if (value.context !== undefined && typeof value.context !== "string") {
+    throw new Error(`${field}.context must be a string when provided`);
+  }
+  const options = parseOptions(value, field, value.type);
+  return { ...value, id, type: value.type, question, ...(options ? { options } : {}) };
+}
+function optionalText(value: unknown, field: string): string | undefined {
+  if (value === undefined) {
+    return;
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string when provided`);
+  }
+  return value.trim();
+}
+function parseInterview(input: unknown): SupervisorInterviewRequest {
+  if (!isRecord(input)) {
+    throw new Error("interview must be an object with a questions array");
+  }
+  const title = optionalText(input.title, "interview.title");
+  const description = optionalText(input.description, "interview.description");
+  if (!isUnknownArray(input.questions) || input.questions.length === 0) {
+    throw new Error("interview.questions must be a non-empty array");
+  }
+  const ids = new Set<string>();
+  const questions = input.questions.map((value, index) => {
+    const question = parseQuestion(value, index);
+    if (ids.has(question.id)) {
+      throw new Error(`interview question id must be unique: ${question.id}`);
+    }
+    ids.add(question.id);
+    return question;
+  });
+  return {
+    ...input,
+    ...(title !== undefined ? { title } : {}),
+    ...(description !== undefined ? { description } : {}),
+    questions,
+  };
+}
+export function validateSupervisorInterviewRequest(
+  input: unknown,
+):
+  | { readonly ok: true; readonly interview: SupervisorInterviewRequest }
+  | { readonly ok: false; readonly error: string } {
+  try {
+    return { ok: true, interview: parseInterview(input) };
+  } catch (error) {
+    return { ok: false, error: errorMessage(error) };
+  }
+}
+function optionLabel(option: InterviewOption): string {
+  return typeof option === "string" ? option : option.label;
+}
+function exampleValue(question: SupervisorInterviewQuestion): unknown {
+  switch (question.type) {
+    case "multi":
+      return question.options?.slice(0, 2).map(optionLabel) ?? [];
+    case "single": {
+      const first = question.options?.[0];
+      return first === undefined ? "option label" : optionLabel(first);
+    }
+    case "image":
+      return "image/file reference or description";
+    case "info":
+    case "text":
+      return "answer text";
+  }
+}
+function interviewPreamble(
+  interview: SupervisorInterviewRequest,
+  message: string | undefined,
+): string[] {
+  const lines = [
+    ["Interview", interview.title],
+    ["", interview.description],
+    ["Child note", message],
+  ].flatMap(([label, value]) => {
+    const text = value?.trim() ?? "";
+    if (text === "") {
+      return [];
+    }
+    return [label === "" ? text : `${label ?? ""}: ${text}`];
+  });
+  if (lines.length > 0) {
+    lines.push("");
+  }
+  return lines;
+}
+export function formatSupervisorInterviewRequest(
+  interview: SupervisorInterviewRequest,
+  message?: string,
+): string {
+  const lines = interviewPreamble(interview, message);
+  lines.push("Questions:");
+  interview.questions.forEach((question, index) => {
+    lines.push(`${index + 1}. [${question.id}] (${question.type}) ${question.question}`);
+    if (typeof question.context === "string" && question.context.trim() !== "") {
+      lines.push(`   Context: ${question.context.trim()}`);
+    }
+    if (question.options !== undefined && question.options.length > 0) {
+      lines.push("   Options:");
+      for (const option of question.options) {
+        lines.push(`   - ${optionLabel(option)}`);
+      }
+    }
+  });
+  const responseExample = {
+    responses: interview.questions
+      .filter((question) => question.type !== "info")
+      .map((question) => ({ id: question.id, value: exampleValue(question) })),
+  };
+  lines.push(
+    "",
+    "Supervisor reply instructions:",
+    "Reply with plain JSON or a fenced ```json block using this stable shape. Use the question ids exactly. Info questions are context-only and do not need responses. For single questions, value is one option label. For multi questions, value is an array of option labels. For text/image questions, value is a string unless the question asks otherwise.",
+    "",
+    "```json",
+    JSON.stringify(responseExample, null, 2),
+    "```",
+  );
+  return lines.join("\n");
+}
+function multiResponse(
+  value: unknown,
+  question: SupervisorInterviewQuestion,
+  field: string,
+): readonly string[] {
+  if (!isUnknownArray(value) || !value.every((item): item is string => typeof item === "string")) {
+    throw new Error(`${field} must be an array of strings for multi questions`);
+  }
+  const labels = new Set(question.options?.map(optionLabel));
+  const selected = value.map((item) => item.trim());
+  const invalid = selected.find((item) => !labels.has(item));
+  if (invalid !== undefined && invalid !== "") {
+    throw new Error(`${field} contains an option that is not in the question options: ${invalid}`);
+  }
+  return selected;
+}
+function responseValue(
+  value: unknown,
+  question: SupervisorInterviewQuestion,
+  index: number,
+): unknown {
+  const field = `responses[${index}].value`;
+  if (question.type === "multi") {
+    return multiResponse(value, question, field);
+  }
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string for ${question.type} questions`);
+  }
+  if (question.type !== "single") {
+    return value;
+  }
+  const labels = new Set(question.options?.map(optionLabel));
+  if (!labels.has(value.trim())) {
+    throw new Error(`${field} must match one of the question options`);
+  }
+  return value.trim();
+}
+function validateReply(
+  value: unknown,
+  interview: SupervisorInterviewRequest,
+): SupervisorInterviewReply {
+  if (!isRecord(value)) {
+    throw new Error("reply JSON must be an object with a responses array");
+  }
+  if (!isUnknownArray(value.responses)) {
+    throw new Error("reply JSON must include a responses array");
+  }
+  const byId = new Map(
+    interview.questions
+      .filter((question) => question.type !== "info")
+      .map((question) => [question.id, question]),
+  );
+  const seen = new Set<string>();
+  const responses = value.responses.map((response, index) => {
+    if (!isRecord(response)) {
+      throw new Error(`responses[${index}] must be an object`);
+    }
+    const id = nonempty(response.id, `responses[${index}].id`);
+    const question = byId.get(id);
+    if (!question) {
+      throw new Error(`responses[${index}].id must match a non-info interview question id`);
+    }
+    if (seen.has(id)) {
+      throw new Error(`responses[${index}].id is duplicated: ${id}`);
+    }
+    seen.add(id);
+    if (!Object.hasOwn(response, "value")) {
+      throw new Error(`responses[${index}].value is required`);
+    }
+    return { id, value: responseValue(response.value, question, index) };
+  });
+  return { responses };
+}
+export function parseStructuredSupervisorReply(
+  text: string,
+  interview: SupervisorInterviewRequest,
+): { readonly value?: SupervisorInterviewReply; readonly error?: string } | undefined {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = (fenced?.[1] ?? text).trim();
+  if (!candidate.startsWith("{") && !candidate.startsWith("[")) {
+    return;
+  }
+  try {
+    const value: unknown = JSON.parse(candidate);
+    return { value: validateReply(value, interview) };
+  } catch (error) {
+    return { error: errorMessage(error) };
+  }
+}

package/src/pi-intercom/lifecycle.ts

@@ -0,0 +1,183 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { IntercomConfig } from "./config.ts";
+import { buildPresenceIdentity } from "./identity.ts";
+import { resolveSessionProjectId } from "./session-targets.ts";
+import type { SessionInfo } from "./types.ts";
+
+/** Owns native context validity and occupancy, never journal or socket state. */
+export class IntercomLifecycle {
+  private context: ExtensionContext | null = null;
+  private sessionId: string | null = null;
+  private model = "unknown";
+  private disposed = true;
+  private started = false;
+  private epoch = 0;
+  private running = false;
+  private activity = 0;
+  private readonly tools = new Map<string, string>();
+  private readonly pi: ExtensionAPI;
+  private readonly config: IntercomConfig;
+  constructor(pi: ExtensionAPI, config: IntercomConfig) {
+    this.pi = pi;
+    this.config = config;
+  }
+  get generation(): number {
+    return this.epoch;
+  }
+  get currentSessionId(): string | null {
+    return this.sessionId;
+  }
+  get runtimeStarted(): boolean {
+    return this.started;
+  }
+  get toolCount(): number {
+    return this.tools.size;
+  }
+  start(ctx: ExtensionContext): number {
+    this.disposed = false;
+    this.started = true;
+    this.epoch += 1;
+    this.context = ctx;
+    this.sessionId = ctx.sessionManager.getSessionId();
+    this.model = ctx.model?.id ?? "unknown";
+    this.running = false;
+    this.activity = 0;
+    this.tools.clear();
+    return this.epoch;
+  }
+  invalidate(): void {
+    this.disposed = true;
+    this.epoch += 1;
+    this.running = false;
+    this.tools.clear();
+  }
+  clear(): void {
+    this.context = null;
+    this.sessionId = null;
+  }
+  live(
+    ctx: ExtensionContext | null = this.context,
+    generation = this.epoch,
+  ): ExtensionContext | null {
+    if (this.disposed || generation !== this.epoch || !ctx) {
+      return null;
+    }
+    try {
+      if (this.sessionId !== null && ctx.sessionManager.getSessionId() !== this.sessionId) {
+        return null;
+      }
+      // Reading a native property detects invalidated contexts without modifying them.
+      const hasUI = ctx.hasUI;
+      if (typeof hasUI !== "boolean") {
+        return null;
+      }
+      return ctx;
+    } catch {
+      return null;
+    }
+  }
+  notify(
+    ctx: ExtensionContext,
+    message: string,
+    level: "info" | "warning" | "error",
+    generation = this.epoch,
+  ): void {
+    const live = this.live(ctx, generation);
+    if (live?.hasUI !== true) {
+      return;
+    }
+    try {
+      live.ui.notify(message, level);
+    } catch {
+      // The UI may disappear while an asynchronous overlay settles during shutdown.
+    }
+  }
+  isIdle(ctx: ExtensionContext): boolean {
+    // ponytail: Pi 1.0 has no busy signal during foreign prompt preparation.
+    if (this.running || this.tools.size > 0) {
+      return false;
+    }
+    try {
+      return ctx.isIdle();
+    } catch {
+      return false;
+    }
+  }
+  agentStart(): void {
+    this.running = true;
+    this.tools.clear();
+  }
+  agentSettled(): void {
+    this.running = false;
+    this.tools.clear();
+  }
+  toolStart(id: string, name: string): void {
+    this.tools.set(id, name);
+  }
+  toolEnd(id: string): void {
+    this.tools.delete(id);
+  }
+  selectModel(id: string): void {
+    this.model = id;
+  }
+  markActivity(): void {
+    this.activity = Date.now();
+  }
+  identity(sessionId: string): { readonly name: string } {
+    return buildPresenceIdentity(this.pi, sessionId);
+  }
+  status(): string {
+    const tool = this.tools.values().next().value;
+    let status = this.running ? "thinking" : "idle";
+    if (tool !== undefined && tool !== "") {
+      status = `tool:${tool}`;
+    }
+    return this.config.status !== undefined && this.config.status !== ""
+      ? `${status} · ${this.config.status}`
+      : status;
+  }
+  health(pendingAsks: number): {
+    readonly pendingAsks: number;
+    readonly acceptsAsks: boolean;
+    readonly lastIntercomActivity: number;
+  } {
+    const live = this.live();
+    return {
+      pendingAsks,
+      acceptsAsks: live ? this.isIdle(live) : false,
+      lastIntercomActivity: this.activity,
+    };
+  }
+  async registration(pendingAsks: number): Promise<Omit<SessionInfo, "id">> {
+    const live = this.live();
+    if (!live || this.sessionId === null) {
+      throw new Error("Intercom runtime not initialized");
+    }
+    const cwd = live.cwd;
+    return {
+      ...this.identity(this.sessionId),
+      cwd,
+      model: this.model,
+      projectId: await resolveSessionProjectId(cwd),
+      lastSeen: Date.now(),
+      status: this.status(),
+      ...this.health(pendingAsks),
+    };
+  }
+  targetMatches(to: string, resolvedTo?: string | null, brokerId?: string | null): boolean {
+    const targets = [
+      this.sessionId,
+      brokerId,
+      this.pi.getSessionName(),
+      this.sessionId === null ? undefined : this.identity(this.sessionId).name,
+    ];
+    return (
+      (resolvedTo !== undefined &&
+        resolvedTo !== null &&
+        brokerId !== undefined &&
+        brokerId !== null &&
+        resolvedTo === brokerId) ||
+      targets.some((target) => target?.trim().toLowerCase() === to.trim().toLowerCase())
+    );
+  }
+}

package/src/pi-intercom/message-format.ts

@@ -0,0 +1,77 @@
+import type { Attachment, Message } from "./types.ts";
+import { isRecord } from "./validation.ts";
+
+export function formatAttachments(attachments: readonly Attachment[]): string {
+  return attachments
+    .map((att) =>
+      att.language !== undefined && att.language !== ""
+        ? `\n\n---\n📎 ${att.name}\n~~~${att.language}\n${att.content}\n~~~`
+        : `\n\n---\n📎 ${att.name}\n${att.content}`,
+    )
+    .join("");
+}
+export function inboundIdFromCustomMessage(message: unknown): string | undefined {
+  if (
+    !isRecord(message) ||
+    (message.customType !== "intercom_message" && message.customType !== "subagent-human-message")
+  ) {
+    return;
+  }
+  if (!isRecord(message.details) || !isRecord(message.details.message)) {
+    return;
+  }
+  return typeof message.details.message.id === "string" ? message.details.message.id : undefined;
+}
+export function getAssistantErrorMessage(message: unknown): string | null {
+  if (!isRecord(message) || message.role !== "assistant" || message.stopReason !== "error") {
+    return null;
+  }
+  const error = typeof message.errorMessage === "string" ? message.errorMessage.trim() : "";
+  return error === "" ? "assistant turn failed" : error;
+}
+export function previewText(value: unknown, maxLength = 72): string | undefined {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized === "") {
+    return;
+  }
+  return normalized.length > maxLength ? `${normalized.slice(0, maxLength - 1)}…` : normalized;
+}
+function metadataField(text: string, pattern: Readonly<RegExp>): string | undefined {
+  return text.match(pattern)?.[1]?.trim();
+}
+function namedPreview(label: string, value: string | undefined): string | undefined {
+  return value === undefined || value === "" ? undefined : `${label}=${value}`;
+}
+export function pendingAskPreview(message: Message): string {
+  const text = message.content.text;
+  const normalized = text.replace(/\s+/g, " ").trim();
+  if (
+    !text.startsWith("Subagent needs a supervisor decision.") &&
+    !text.startsWith("Subagent requests a structured supervisor interview.")
+  ) {
+    return previewText(normalized, 180) ?? normalized;
+  }
+  const run = metadataField(text, /^Run:\s*(.+)$/m);
+  const agent = metadataField(text, /^Agent:\s*(.+)$/m);
+  const target = metadataField(text, /^Child intercom target:\s*(.+)$/m);
+  const body = text
+    .split(/\n\s*\n/)
+    .slice(1)
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return [
+    text.startsWith("Subagent requests")
+      ? "structured supervisor interview"
+      : "supervisor decision",
+    namedPreview("run", run),
+    namedPreview("agent", agent),
+    namedPreview("target", target),
+    namedPreview("question", previewText(body, 180)),
+  ]
+    .filter((part) => part !== undefined)
+    .join(" · ");
+}