import { backgroundWorkHoldsCompletion } from "@t3tools/shared/orchestrationV2PendingBackgroundWork";
import { threadPullRequestsOf } from "../threadPullRequests.ts";
import type {
ThreadLinkedPullRequest,
EnvironmentId,
MessageId,
OrchestrationProjectShell,
OrchestrationV2ProviderGoal,
OrchestrationV2RunStatus,
OrchestrationV2ProviderFailureClass,
OrchestrationV2ThreadProjection,
OrchestrationV2ThreadShell,
PlanId,
ProjectId,
ProviderInstanceId,
RunId,
ThreadId,
} from "@t3tools/contracts";
import * as DateTime from "effect/DateTime";
import { formatSubagentDisplayTitle } from "./subagentDisplay.ts";
export interface EnvironmentProject extends OrchestrationProjectShell {
readonly environmentId: EnvironmentId;
readonly isScratch?: true;
}
/**
* The projection stays nested so the server projection and all structurally
* shared collections retain their identities.
*/
export interface EnvironmentThread {
readonly environmentId: EnvironmentId;
readonly projection: OrchestrationV2ThreadProjection;
}
type ProjectionTurnItem = OrchestrationV2ThreadProjection["turnItems"][number];
type StreamedProjectionTurnItem = Extract<
ProjectionTurnItem,
{ readonly type: "assistant_message" | "reasoning" }
>;
/** A turn item without the fields that move while it streams. */
export type ThreadStructureTurnItem =
| Exclude<ProjectionTurnItem, StreamedProjectionTurnItem>
| Omit<Extract<ProjectionTurnItem, { readonly type: "assistant_message" }>, "text" | "updatedAt">
| Omit<Extract<ProjectionTurnItem, { readonly type: "reasoning" }>, "text" | "updatedAt">;
export type ThreadStructureVisibleTurnItem = Omit<
OrchestrationV2ThreadProjection["visibleTurnItems"][number],
"item"
> & {
readonly item: ThreadStructureTurnItem;
};
/**
* A thread projection without the fields that move while a reply streams, so a
* reader of the quiet thread cannot depend on them and go stale. A full
* projection is assignable to it.
*/
export type ThreadStructureThread = Omit<
OrchestrationV2ThreadProjection["thread"],
"updatedAt" | "lastVisitedAt"
>;
export type ThreadStructure = Omit<
OrchestrationV2ThreadProjection,
"thread" | "turnItems" | "visibleTurnItems" | "updatedAt"
> & {
readonly thread: ThreadStructureThread;
readonly turnItems: ReadonlyArray<ThreadStructureTurnItem>;
readonly visibleTurnItems: ReadonlyArray<ThreadStructureVisibleTurnItem>;
};
export interface EnvironmentThreadStructure {
readonly environmentId: EnvironmentId;
readonly projection: ThreadStructure;
}
export interface ThreadRunSummary {
readonly runId: RunId;
readonly status: OrchestrationV2RunStatus;
readonly requestedAt: string | null;
readonly startedAt: string | null;
readonly completedAt: string | null;
readonly assistantMessageId: MessageId | null;
/**
* The run is still open, but its provider turn already ended, so nothing is
* generating while the server settles it.
*/
readonly turnEnded?: boolean;
readonly sourcePlanRef?: {
readonly threadId: ThreadId;
readonly planId: PlanId;
};
}
export interface ThreadRuntimeSummary {
readonly status: OrchestrationV2RunStatus | "idle";
readonly activeRunId: RunId | null;
readonly activityStartedAt?: string | null | undefined;
readonly providerInstanceId: ProviderInstanceId;
readonly providerName: string | null;
readonly lastError: string | null;
readonly lastErrorClass?: OrchestrationV2ProviderFailureClass | null;
readonly lastErrorCode?: string | null;
readonly usageLimitResetAt?: string | null;
readonly updatedAt: string;
}
/** The runtime summary a thread's structure determines; see ThreadStructure. */
export type ThreadStructureRuntime = Omit<ThreadRuntimeSummary, "updatedAt">;
export function threadRuntimeIsActive(runtime: ThreadStructureRuntime | null | undefined): boolean {
return runtime !== null && runtime !== undefined && threadRunStatusIsActive(runtime.status);
}
export function threadRuntimeCanArchive(runtime: ThreadRuntimeSummary | null | undefined): boolean {
if (runtime?.status === "queued") return runtime.activeRunId === null;
return (
runtime?.status !== "preparing" &&
runtime?.status !== "starting" &&
runtime?.status !== "running"
);
}
function threadRunStatusIsActive(status: ThreadRuntimeSummary["status"]): boolean {
return (
status === "preparing" ||
status === "queued" ||
status === "starting" ||
status === "running" ||
status === "waiting"
);
}
export interface EnvironmentThreadShell {
readonly environmentId: EnvironmentId;
readonly id: ThreadId;
readonly projectId: ProjectId;
readonly title: string;
readonly providerInstanceId: ProviderInstanceId;
readonly modelSelection: OrchestrationV2ThreadShell["modelSelection"];
readonly runtimeMode: OrchestrationV2ThreadShell["runtimeMode"];
readonly interactionMode: OrchestrationV2ThreadShell["interactionMode"];
readonly branch: string | null;
readonly worktreePath: string | null;
readonly lineage: OrchestrationV2ThreadShell["lineage"];
readonly forkedFrom: OrchestrationV2ThreadShell["forkedFrom"];
readonly linkOrigin: OrchestrationV2ThreadShell["linkOrigin"] | null;
/** The thread in a linked environment that delegated this one, if one did. */
readonly delegatedFrom: OrchestrationV2ThreadShell["delegatedFrom"] | null;
readonly activeProviderThreadId: OrchestrationV2ThreadShell["activeProviderThreadId"];
readonly latestRun: ThreadRunSummary | null;
readonly runtime: ThreadRuntimeSummary | null;
readonly blockedOnThreadWait?: boolean;
readonly latestUserMessageAt: string | null;
readonly latestUserAuthoredMessageAt?: string | null;
readonly hasPendingApprovals: boolean;
readonly hasPendingUserInput: boolean;
readonly pendingUserInputAt?: string | null;
readonly pendingSubagentRequest?: PendingSubagentRequest | null;
/** Guest messages waiting for the owner to send or dismiss. */
readonly pendingGuestMessageCount?: number;
readonly hasActionableProposedPlan: boolean;
readonly pendingBackgroundTasks: ReadonlyArray<
NonNullable<OrchestrationV2ThreadShell["pendingBackgroundTasks"]>[number]
>;
readonly providerInstanceHistory: ReadonlyArray<ProviderInstanceId>;
readonly goal: OrchestrationV2ProviderGoal | null;
readonly itemCount: number;
readonly visibleItemCount: number;
readonly createdAt: string;
readonly updatedAt: string;
readonly archivedAt: string | null;
readonly settledOverride: "settled" | "active" | null;
readonly settledAt: string | null;
readonly unsettledAt: string | null;
readonly snoozedUntil: string | null;
readonly snoozedAt: string | null;
readonly limitRecovery?: import("@t3tools/contracts").OrchestrationV2LimitRecovery | null;
readonly pinnedAt: string | null;
readonly autoSettleDisabledAt?: string | null;
readonly pinOrderKey: string | null;
readonly activeOrderKey: string | null;
readonly pullRequests: ReadonlyArray<import("@t3tools/contracts").ThreadPullRequestLink>;
readonly linkedPullRequest?: ThreadLinkedPullRequest | null;
readonly branchPullRequest?: ThreadLinkedPullRequest | null;
/**
* Server-tracked visited watermark. `undefined` means the environment's
* server predates visited tracking and clients should fall back to any
* local visited state they keep.
*/
readonly lastVisitedAt?: string | null;
/** Server-tracked open history for search ranking. */
readonly opens?: import("@t3tools/contracts").OrchestrationV2ThreadOpens | null;
readonly titleRegeneration?: { readonly requestId: string; readonly startedAt: string } | null;
readonly deletedAt: string | null;
readonly source: OrchestrationV2ThreadShell;
}
function iso(value: DateTime.Utc): string {
return DateTime.formatIso(value);
}
function nullableIso(value: DateTime.Utc | null): string | null {
return value === null ? null : iso(value);
}
function terminalRunStatus(status: OrchestrationV2RunStatus): boolean {
return (
status === "completed" ||
status === "interrupted" ||
status === "failed" ||
status === "cancelled" ||
status === "rolled_back"
);
}
// Only work the agent waits on holds it: commands and monitors it left running
// unmarked, such as a dev server, present the run's own status. The
// server suppresses the roster while an interruptible activity run exists, so a
// remaining roster is stronger than checkpoint-oriented waiting.
function shellRuntime(thread: OrchestrationV2ThreadShell): ThreadRuntimeSummary | null {
const parkAtIdle =
backgroundWorkHoldsCompletion(thread.pendingBackgroundTasks ?? []) &&
thread.status !== "failed";
if (thread.latestRunId === null && thread.activeProviderThreadId === null && !parkAtIdle) {
return null;
}
const status = parkAtIdle ? "idle" : (thread.activityRunStatus ?? thread.status);
return {
status,
activeRunId: thread.activeRunId,
activityStartedAt:
thread.activityRunStartedAt === undefined
? undefined
: nullableIso(thread.activityRunStartedAt),
providerInstanceId: thread.providerInstanceId,
providerName: null,
lastError: thread.lastError ?? null,
lastErrorClass: thread.lastErrorClass ?? null,
lastErrorCode: thread.lastErrorCode ?? null,
usageLimitResetAt: thread.usageLimitResetAt ?? null,
updatedAt: iso(thread.updatedAt),
};
}
export function scopeProject(
environmentId: EnvironmentId,
project: OrchestrationProjectShell,
): EnvironmentProject {
return { ...project, environmentId };
}
export type PendingSubagentRequest = "approval" | "user_input";
export function presentThreadShell(
environmentId: EnvironmentId,
thread: OrchestrationV2ThreadShell,
pendingSubagentRequest: PendingSubagentRequest | null = null,
): EnvironmentThreadShell {
const updatedAt = iso(thread.updatedAt);
const latestRun =
thread.latestRunId === null
? null
: ({
runId: thread.latestRunId,
status: thread.status === "idle" ? "completed" : thread.status,
requestedAt: nullableIso(thread.latestRunRequestedAt ?? null),
startedAt: nullableIso(thread.latestRunStartedAt ?? null),
completedAt:
thread.latestRunCompletedAt === undefined
? thread.status === "idle" || terminalRunStatus(thread.status)
? updatedAt
: null
: nullableIso(thread.latestRunCompletedAt),
assistantMessageId: null,
} satisfies ThreadRunSummary);
const runtime = shellRuntime(thread);
return {
environmentId,
id: thread.id,
projectId: thread.projectId,
title:
thread.lineage.relationshipToParent === "subagent"
? formatSubagentDisplayTitle(thread.title)
: thread.title,
providerInstanceId: thread.providerInstanceId,
modelSelection: thread.modelSelection,
runtimeMode: thread.runtimeMode,
interactionMode: thread.interactionMode,
branch: thread.branch,
worktreePath: thread.worktreePath,
pullRequests: threadPullRequestsOf(thread),
linkedPullRequest: thread.linkedPullRequest ?? null,
branchPullRequest: thread.branchPullRequest ?? null,
lineage: thread.lineage,
forkedFrom: thread.forkedFrom,
linkOrigin: thread.linkOrigin ?? null,
delegatedFrom: thread.delegatedFrom ?? null,
activeProviderThreadId: thread.activeProviderThreadId,
latestRun,
runtime,
blockedOnThreadWait: thread.blockedOnThreadWait ?? false,
latestUserMessageAt: nullableIso(thread.latestUserMessageAt),
...(thread.latestUserAuthoredMessageAt === undefined
? {}
: { latestUserAuthoredMessageAt: nullableIso(thread.latestUserAuthoredMessageAt) }),
hasPendingApprovals:
thread.pendingRuntimeRequest !== null &&
thread.pendingRuntimeRequest.kind !== "user_input" &&
thread.pendingRuntimeRequest.kind !== "auth_refresh",
// Async questions count too, so a thread with any open question leaves Working.
hasPendingUserInput: thread.pendingRuntimeRequest?.kind === "user_input",
pendingUserInputAt:
thread.pendingRuntimeRequest?.kind === "user_input"
? iso(thread.pendingRuntimeRequest.createdAt)
: null,
pendingSubagentRequest,
pendingGuestMessageCount: thread.pendingGuestMessageCount ?? 0,
hasActionableProposedPlan: thread.hasActionableProposedPlan,
pendingBackgroundTasks: thread.pendingBackgroundTasks ?? [],
providerInstanceHistory: thread.providerInstanceHistory ?? [],
goal: thread.goal ?? null,
itemCount: thread.itemCount,
visibleItemCount: thread.visibleItemCount,
createdAt: iso(thread.createdAt),
updatedAt,
archivedAt: nullableIso(thread.archivedAt),
settledOverride: thread.settledOverride,
settledAt: nullableIso(thread.settledAt),
unsettledAt: nullableIso(thread.unsettledAt ?? null),
snoozedUntil: nullableIso(thread.snoozedUntil ?? null),
snoozedAt: nullableIso(thread.snoozedAt ?? null),
limitRecovery: thread.limitRecovery ?? null,
pinnedAt: nullableIso(thread.pinnedAt ?? null),
autoSettleDisabledAt: nullableIso(thread.autoSettleDisabledAt ?? null),
pinOrderKey: thread.pinOrderKey ?? null,
activeOrderKey: thread.activeOrderKey ?? null,
...(thread.lastVisitedAt === undefined
? {}
: { lastVisitedAt: nullableIso(thread.lastVisitedAt) }),
opens: thread.opens ?? null,
titleRegeneration:
thread.titleRegeneration == null
? null
: {
requestId: thread.titleRegeneration.requestId,
startedAt: iso(thread.titleRegeneration.startedAt),
},
deletedAt: nullableIso(thread.deletedAt),
source: thread,
};
}
export function scopeThreadShell(
environmentId: EnvironmentId,
thread: OrchestrationV2ThreadShell,
): EnvironmentThreadShell {
return presentThreadShell(environmentId, thread);
}
const THREAD_PROVIDER_STACK_LIMIT = 3;
export function resolveThreadProviderStack(
thread: Pick<EnvironmentThreadShell, "providerInstanceHistory" | "modelSelection" | "runtime">,
): ReadonlyArray<ProviderInstanceId> {
const current = thread.runtime?.providerInstanceId ?? thread.modelSelection.instanceId;
const previous = thread.providerInstanceHistory.filter((instanceId) => instanceId !== current);
return [...previous.slice(-(THREAD_PROVIDER_STACK_LIMIT - 1)), current];
}
/**
* Both shell and detail timers count from the activity-owning run's work
* start, never last activity. A wake keeps the start of the work it continues.
*/
export function resolveThreadWorkingStartedAt(input: {
readonly latestRun: Pick<
ThreadRunSummary,
"runId" | "startedAt" | "requestedAt" | "completedAt"
> | null;
readonly runtime: Pick<ThreadRuntimeSummary, "activeRunId" | "activityStartedAt"> | null;
}): string | null {
const valid = (value: string | null | undefined) =>
value != null && Number.isFinite(Date.parse(value)) ? value : null;
if (input.runtime?.activityStartedAt !== undefined) return valid(input.runtime.activityStartedAt);
const run = input.latestRun;
if (run?.completedAt === null && run.runId === input.runtime?.activeRunId) {
return valid(run.startedAt) ?? valid(run.requestedAt);
}
return null;
}
export function formatWorkingDurationLabel(elapsedMs: number): string {
const seconds = Number.isFinite(elapsedMs) ? Math.max(0, Math.floor(elapsedMs / 1000)) : 0;
if (seconds < 60) return `${seconds}s`;
const minutes = Math.floor(seconds / 60);
if (minutes < 60) return `${minutes}m`;
return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
}