sailfork / t3code-github / packages/ client-runtime/ src/ state/ subagentRuntime.ts

import { groupBy } from "effect/Array";
import * as DateTime from "effect/DateTime";
import type {
  ModelSelection,
  OrchestrationV2AppThread,
  OrchestrationV2Subagent,
  OrchestrationV2SubagentWorkflow,
  OrchestrationV2TurnItem,
} from "@t3tools/contracts";
import { isOrchestrationV2WorkActive, isProviderNativeSubagentThread } from "@t3tools/contracts";

export type RuntimeSubagentStatus =
  | "pending"
  | "running"
  | "waiting"
  | "idle"
  | "completed"
  | "failed"
  | "cancelled"
  | "interrupted";

export interface SubagentUsage {
  readonly totalTokens: number;
  readonly inputTokens?: number;
  readonly cachedInputTokens?: number;
  readonly outputTokens?: number;
  readonly reasoningOutputTokens?: number;
  readonly toolUses?: number;
  readonly durationMs?: number;
}

export interface SubagentActivityEntry {
  readonly at: string;
  readonly summary: string;
}

export interface SubagentWorkflowPhase {
  readonly index: number;
  readonly title: string;
}

export interface SubagentRunHandles {
  readonly runId?: string | undefined;
  readonly scriptPath?: string | undefined;
  readonly transcriptDir?: string | undefined;
  readonly sessionUrl?: string | undefined;
}

export interface RuntimeSubagent {
  readonly id: string;
  readonly kind: "subagent" | "subagent_batch" | "workflow" | "workflow_agent";
  readonly title: string;
  readonly role: string | null;
  readonly model: string | null;
  readonly effort: string | null;
  readonly speed?: string | undefined;
  readonly status: RuntimeSubagentStatus;
  readonly activationCount: number;
  readonly usage: SubagentUsage | null;
  readonly progress: string | null;
  readonly lastToolName: string | null;
  readonly result: string | null;
  readonly error: string | null;
  readonly outputFile: string | null;
  readonly parentAgentId: string | null;
  readonly agentIndex: number | null;
  readonly phaseIndex: number | null;
  readonly phaseTitle: string | null;
  readonly attempt: number | null;
  readonly workflowName: string | null;
  readonly phases: ReadonlyArray<SubagentWorkflowPhase>;
  readonly runHandles: SubagentRunHandles | null;
  readonly childThreadId: string | null;
  readonly recentActivity: ReadonlyArray<SubagentActivityEntry>;
  readonly firstSeenAt: string;
  readonly startedAt: string | null;
  readonly completedAt: string | null;
  readonly updatedAt: string;
}

const TERMINAL_STATUSES: ReadonlySet<RuntimeSubagentStatus> = new Set([
  "completed",
  "failed",
  "cancelled",
  "interrupted",
]);

export function isTerminalSubagentStatus(status: RuntimeSubagentStatus): boolean {
  return TERMINAL_STATUSES.has(status);
}

export function isActiveSubagentStatus(status: RuntimeSubagentStatus): boolean {
  return isOrchestrationV2WorkActive(status);
}

export function isLiveSubagentTurnItem(item: OrchestrationV2TurnItem): boolean {
  return item.type === "subagent" && isOrchestrationV2WorkActive(item.status);
}

export interface SubagentWorkflowGroup {
  readonly workflow: RuntimeSubagent;
  readonly phases: ReadonlyArray<{
    readonly index: number;
    readonly title: string;
    readonly members: ReadonlyArray<RuntimeSubagent>;
    readonly state: "pending" | "running" | "done";
    readonly settledCount: number;
  }>;
  readonly unphasedMembers: ReadonlyArray<RuntimeSubagent>;
}

function workflowUsage(source: {
  readonly totalTokens?: number | undefined;
  readonly toolCalls?: number | undefined;
  readonly durationMs?: number | undefined;
}): SubagentUsage | null {
  if (source.totalTokens === undefined) return null;
  return {
    totalTokens: source.totalTokens,
    ...(source.toolCalls === undefined ? {} : { toolUses: source.toolCalls }),
    ...(source.durationMs === undefined ? {} : { durationMs: source.durationMs }),
  };
}

function isoFromEpochMillis(value: number | undefined): string | null {
  return value === undefined ? null : DateTime.formatIso(DateTime.makeUnsafe(value));
}

function workflowMembersToRuntime(
  coordinator: RuntimeSubagent,
  workflow: OrchestrationV2SubagentWorkflow,
): ReadonlyArray<RuntimeSubagent> {
  return workflow.agents.map((agent) => {
    const status =
      (agent.state === "queued" || agent.state === "running") &&
      isTerminalSubagentStatus(coordinator.status)
        ? coordinator.status
        : agent.state === "queued"
          ? "pending"
          : agent.state;
    const failed = status === "failed";
    const startedAt = isoFromEpochMillis(agent.startedAt);
    const completedAt = isTerminalSubagentStatus(status)
      ? (isoFromEpochMillis(agent.completedAt) ??
        (agent.startedAt !== undefined && agent.durationMs !== undefined
          ? isoFromEpochMillis(agent.startedAt + agent.durationMs)
          : coordinator.completedAt))
      : null;
    return {
      ...coordinator,
      id: `${coordinator.id}:agent:${agent.index}`,
      kind: "workflow_agent" as const,
      title: agent.label,
      model: agent.model ?? null,
      effort: agent.effort ?? null,
      ...(agent.speed === undefined ? {} : { speed: agent.speed }),
      status,
      activationCount: agent.attempt ?? 1,
      usage: workflowUsage(agent),
      progress: agent.prompt ?? null,
      result: failed ? null : (agent.result ?? null),
      error: failed ? (agent.result ?? null) : null,
      parentAgentId: coordinator.id,
      agentIndex: agent.index,
      phaseIndex: agent.phaseIndex ?? null,
      phaseTitle: agent.phaseTitle ?? null,
      attempt: agent.attempt ?? null,
      phases: [],
      childThreadId: agent.childThreadId ?? null,
      recentActivity: [],
      firstSeenAt: isoFromEpochMillis(agent.queuedAt) ?? startedAt ?? coordinator.firstSeenAt,
      startedAt,
      completedAt,
      updatedAt: completedAt ?? startedAt ?? coordinator.firstSeenAt,
    } satisfies RuntimeSubagent;
  });
}

function promptTitle(prompt: string): string {
  if (prompt.length <= 80) return prompt;
  let end = 77;
  const previous = prompt.charCodeAt(end - 1);
  const next = prompt.charCodeAt(end);
  if (previous >= 0xd800 && previous <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) {
    end -= 1;
  }
  return `${prompt.slice(0, end)}...`;
}

export function workflowMemberModelSelection(
  member: Pick<RuntimeSubagent, "model" | "effort" | "speed">,
  instanceId: ModelSelection["instanceId"],
): ModelSelection | undefined {
  if (!member.model) return undefined;
  return {
    instanceId,
    model: member.model,
    options: [
      ...(member.effort ? [{ id: "effort", value: member.effort }] : []),
      ...(member.speed ? [{ id: "fastMode", value: member.speed === "fast" }] : []),
    ],
  };
}

export function projectedSubagentsToRuntime(
  subagents: ReadonlyArray<{
    readonly id: string;
    readonly title: string | null;
    readonly prompt: string;
    readonly model: string | null;
    readonly status: OrchestrationV2Subagent["status"];
    readonly progress?: string | undefined;
    readonly childThreadId?: string | null | undefined;
    readonly workflow?: OrchestrationV2SubagentWorkflow | undefined;
    readonly result: string | null;
    readonly startedAt: DateTime.Utc | null;
    readonly completedAt: DateTime.Utc | null;
    readonly updatedAt: DateTime.Utc;
  }>,
): ReadonlyArray<RuntimeSubagent> {
  return subagents.flatMap((subagent) => {
    const updatedAt = DateTime.formatIso(subagent.updatedAt);
    const startedAt = subagent.startedAt === null ? null : DateTime.formatIso(subagent.startedAt);
    const firstSeenAt = startedAt ?? updatedAt;
    const { workflow } = subagent;
    const runHandles = workflow?.runHandles ?? null;
    const coordinator = {
      id: subagent.id,
      kind: workflow === undefined ? "subagent" : "workflow",
      title: subagent.title ?? promptTitle(subagent.prompt),
      role: null,
      model: subagent.model,
      effort: null,
      status: subagent.status,
      activationCount: 1,
      usage: workflow === undefined ? null : workflowUsage(workflow),
      progress: subagent.progress ?? null,
      lastToolName: null,
      result: subagent.result,
      error: subagent.status === "failed" ? (subagent.result ?? null) : null,
      outputFile: null,
      parentAgentId: null,
      agentIndex: null,
      phaseIndex: null,
      phaseTitle: null,
      attempt: null,
      workflowName: workflow?.name ?? null,
      phases: workflow?.phases ?? [],
      runHandles,
      childThreadId: subagent.childThreadId ?? null,
      recentActivity: [],
      firstSeenAt,
      startedAt,
      completedAt: subagent.completedAt === null ? null : DateTime.formatIso(subagent.completedAt),
      updatedAt,
    } satisfies RuntimeSubagent;
    return workflow === undefined
      ? [coordinator]
      : [coordinator, ...workflowMembersToRuntime(coordinator, workflow)];
  });
}

export function deriveWorkflowGroups(
  agents: ReadonlyArray<RuntimeSubagent>,
): ReadonlyArray<SubagentWorkflowGroup> {
  const workflows = agents
    .filter((agent) => agent.kind === "workflow")
    .sort((a, b) => a.firstSeenAt.localeCompare(b.firstSeenAt) || a.id.localeCompare(b.id));
  const members = groupBy(
    agents.filter((agent) => agent.kind !== "workflow" && agent.parentAgentId !== null),
    (agent) => agent.parentAgentId!,
  );

  return workflows.map((workflow) => {
    const workflowMembers = Object.hasOwn(members, workflow.id) ? members[workflow.id]! : [];
    // Union, not either/or: the declared plan lags the members, because the
    // provider only admits a phase once something in it starts. Members seed
    // the map; the declared titles then overwrite whatever they guessed.
    const phaseTitles = new Map<number, string>();
    for (const member of workflowMembers) {
      if (member.phaseIndex === null) continue;
      phaseTitles.set(
        member.phaseIndex,
        member.phaseTitle ?? phaseTitles.get(member.phaseIndex) ?? `Phase ${member.phaseIndex + 1}`,
      );
    }
    for (const phase of workflow.phases) phaseTitles.set(phase.index, phase.title);
    const knownPhases = Array.from(phaseTitles.entries())
      .map(([index, title]) => ({ index, title }))
      .sort((a, b) => a.index - b.index);

    const phases = knownPhases.map((phase) => {
      const phaseMembers = workflowMembers
        .filter((member) => member.phaseIndex === phase.index)
        .sort((a, b) => (a.agentIndex ?? 0) - (b.agentIndex ?? 0));
      const hasActiveMember = phaseMembers.some(
        // Idle members count as active for phase-liveness: a resumable Codex
        // member has not finished the phase.
        (member) => isActiveSubagentStatus(member.status) || member.status === "idle",
      );
      const settledCount = phaseMembers.filter((member) =>
        isTerminalSubagentStatus(member.status),
      ).length;
      const state: "pending" | "running" | "done" =
        phaseMembers.length === 0 ? "pending" : hasActiveMember ? "running" : "done";
      return {
        index: phase.index,
        title: phase.title,
        members: phaseMembers,
        state,
        settledCount,
      };
    });

    const unphasedMembers = workflowMembers
      .filter((member) => member.phaseIndex === null)
      .sort((a, b) => (a.agentIndex ?? 0) - (b.agentIndex ?? 0));

    return { workflow, phases, unphasedMembers };
  });
}

// Workflow scripts open with their `meta` export, after any leading comments.
const WORKFLOW_SCRIPT_START = /^\s*(?:(?:\/\/[^\n]*|\/\*[\s\S]*?\*\/)\s*)*export\s+const\s+meta\b/;

/**
 * Whether a user message is the script a provider-native workflow runs. Servers mark every
 * subagent prompt either way; only threads recorded before the mark fall back to the text.
 */
export function isWorkflowScriptMessage(message: {
  readonly role: string;
  readonly text: string;
  readonly workflowScript?: boolean | undefined;
}): boolean {
  return (
    message.role === "user" && (message.workflowScript ?? WORKFLOW_SCRIPT_START.test(message.text))
  );
}

type ProjectedSubagent = Parameters<typeof projectedSubagentsToRuntime>[0][number] &
  Pick<OrchestrationV2Subagent, "driver" | "providerInstanceId">;

export interface WorkflowOpening {
  readonly messageId: string;
  readonly script: string;
  readonly name: string | null;
  readonly description: string | null;
  readonly driver: OrchestrationV2Subagent["driver"] | null;
  readonly providerInstanceId: OrchestrationV2Subagent["providerInstanceId"] | null;
  /** Null until the parent thread's coordinator row is loaded. */
  readonly group: SubagentWorkflowGroup | null;
}

/**
 * The opening of a workflow coordinator's thread: its first user message is the workflow script,
 * shown as the workflow's plan. The coordinator row lives on the parent thread, so
 * `parentSubagents` is the parent projection's subagents, or null when it is not loaded.
 */
export function resolveWorkflowOpening(input: {
  readonly thread: Pick<OrchestrationV2AppThread, "id" | "lineage" | "creationSource">;
  readonly messages: ReadonlyArray<{
    readonly id: string;
    readonly role: string;
    readonly text: string;
    readonly workflowScript?: boolean | undefined;
  }>;
  readonly parentSubagents: ReadonlyArray<ProjectedSubagent> | null;
}): WorkflowOpening | null {
  if (!isProviderNativeSubagentThread(input.thread)) return null;
  const first = input.messages.find((message) => message.role === "user");
  if (first === undefined) return null;
  const coordinator = input.parentSubagents?.find(
    (subagent) => subagent.childThreadId === input.thread.id,
  );
  if (first.workflowScript === false) return null;
  if (coordinator?.workflow === undefined && !isWorkflowScriptMessage(first)) return null;
  return {
    messageId: first.id,
    script: first.text,
    name: coordinator?.workflow?.name ?? null,
    description: coordinator?.title ?? null,
    driver: coordinator?.driver ?? null,
    providerInstanceId: coordinator?.providerInstanceId ?? null,
    group:
      coordinator?.workflow === undefined
        ? null
        : (deriveWorkflowGroups(projectedSubagentsToRuntime([coordinator]))[0] ?? null),
  };
}

/**
 * The parent thread whose subagent rows describe this thread's workflow, or null when the thread
 * does not open with a workflow script. Gates loading the parent so ordinary subagent threads
 * never subscribe to their parent's detail.
 */
export function workflowOpeningParentThreadId(input: {
  readonly thread: Pick<OrchestrationV2AppThread, "lineage" | "creationSource">;
  readonly messages: ReadonlyArray<Parameters<typeof isWorkflowScriptMessage>[0]>;
}): OrchestrationV2AppThread["id"] | null {
  if (!isProviderNativeSubagentThread(input.thread)) return null;
  const first = input.messages.find((message) => message.role === "user");
  return first !== undefined && isWorkflowScriptMessage(first)
    ? input.thread.lineage.parentThreadId
    : null;
}

/** The opening block's heading: the workflow, what it does, and how its agents stand. */
export function workflowOpeningHeadline(opening: WorkflowOpening): {
  readonly title: string;
  readonly description: string | null;
  readonly agents: string | null;
} {
  const title = opening.name ?? opening.description ?? "Workflow";
  const members =
    opening.group === null
      ? []
      : [
          ...opening.group.phases.flatMap((phase) => phase.members),
          ...opening.group.unphasedMembers,
        ];
  const counts = new Map<string, number>();
  for (const member of members) {
    const key = isTerminalSubagentStatus(member.status)
      ? member.status === "completed"
        ? "done"
        : member.status === "failed"
          ? "failed"
          : "stopped"
      : "working";
    counts.set(key, (counts.get(key) ?? 0) + 1);
  }
  const agents =
    members.length === 0
      ? null
      : `${members.length} ${members.length === 1 ? "agent" : "agents"} · ${[
          "working",
          "done",
          "failed",
          "stopped",
        ]
          .filter((key) => counts.has(key))
          .map((key) => `${counts.get(key)} ${key}`)
          .join(" · ")}`;
  return {
    title,
    description:
      opening.description !== null && opening.description !== title ? opening.description : null,
    agents,
  };
}