// @effect-diagnostics nodeBuiltinImport:off
import {
type ChatAttachment,
type ModelSelection,
type OrchestrationV2ConversationMessage,
type OrchestrationV2ExecutionNode,
type OrchestrationV2PlanArtifact,
type OrchestrationV2PlanStep,
type OrchestrationV2ProviderCapabilities,
type OrchestrationV2ProviderFailure,
type OrchestrationV2ProviderRetry,
type OrchestrationV2ProviderSession,
type OrchestrationV2ProviderThread,
type OrchestrationV2ProviderThreadNativeMetadata,
type OrchestrationV2ProviderTurn,
type OrchestrationV2RuntimeRequest,
type OrchestrationV2Subagent,
type OrchestrationV2TurnItem,
type OrchestrationV2UserInputQuestion,
type OrchestrationV2WebSearchResult,
type ProviderApprovalDecision,
type ProviderApprovalOption,
type ProviderInstanceId,
type ProviderInteractionMode,
type ProviderDriverKind,
type ProviderRequestKind,
type ProviderThreadId,
type ProviderUserInputAnswers,
type RuntimeMode,
type RuntimeRequestId,
type ThreadTokenUsageSnapshot,
type ThreadId,
isRuntimeModeAbove,
type TurnTokenUsage,
} from "@t3tools/contracts";
import { AgentScope, AgentScopeThreadId } from "@t3tools/shared/AgentScope";
import { HTML_RENDER_TOOL_NAME } from "@t3tools/shared/htmlRender";
import { modelSelectionsEqual } from "@t3tools/shared/model";
import { type SelfInvocation, selfInvocationArgs } from "@t3tools/shared/nodeRuntime";
import { resolveT3McpToolId } from "@t3tools/shared/t3McpToolPresentation";
import {
SEND_TO_USER_TOOL_NAME,
compactDynamicToolOutput,
htmlRenderFromToolItem,
mcpToolResultOutput,
sentMessageFromToolItem,
} from "@t3tools/shared/toolOutput";
import { FILE_HEADERS_ONLY, formatPatch, structuredPatch } from "diff";
import * as Cause from "effect/Cause";
import * as Clock from "effect/Clock";
import * as SecureRandom from "effect/crypto/SecureRandom";
import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Equal from "effect/Equal";
import * as Exit from "effect/Exit";
import * as FileSystem from "effect/FileSystem";
import * as Fiber from "effect/Fiber";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
import * as Ref from "effect/Ref";
import * as Result from "effect/Result";
import * as Schema from "effect/Schema";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as EffectAcpErrors from "effect-acp/errors";
import type * as EffectAcpProtocol from "effect-acp/protocol";
import type * as EffectAcpSchema from "effect-acp/compat";
import { formatReadToolLabel, formatSearchToolLabel } from "@t3tools/shared/toolActivity";
import * as ProviderHost from "@t3tools/provider-core/server/ProviderHost";
import { makeAcpMcpOverAcpBridge, type AcpMcpOverAcpBridge } from "./mcpOverAcpBridge.ts";
import { mcpToolPresentation } from "@t3tools/provider-core/server/mcpToolPresentation";
import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
import * as McpProviderSession from "@t3tools/provider-core/server/mcpSession";
import {
applyAcpAgentTerminalUpdate,
acpContentBlockDisplayText,
embeddedTerminalIdsFromSessionUpdate,
extractMcpToolCallIdentity,
findModelConfigOption,
mergeToolCallState,
parsePermissionRequest,
parseSessionUpdateEvent,
toolCallVisibleOutputChanged,
withTrackedPermissionToolCall,
type AcpPlanUpdate,
type AcpAgentTerminalState,
type AcpSessionModeState,
type AcpToolCallState,
} from "./runtimeModel.ts";
import {
acpClientExecuteDisposition,
acpMcpToolApprovalElicitationDisposition,
acpPermissionDisposition,
type AcpPermissionDisposition,
makeAcpClientPolicyGrants,
unknownRecord,
} from "./clientPolicy.ts";
import { parseElicitationForm } from "./elicitationForm.ts";
import {
makeAcpClientTerminals,
resolveEmbeddedTerminalContent,
type AcpClientTerminals,
} from "./clientTerminals.ts";
import {
ACP_EMPTY_OPTION_VALUE,
ACP_SESSION_MODE_OPTION_ID,
flattenSelectChoices,
} from "./sessionConfig.ts";
import * as AcpSessionRuntime from "./AcpSessionRuntime.ts";
import {
t3AcpPromptWithInstructions,
type T3AcpInstructionState,
} from "@t3tools/provider-core/server/orchestrationInstructions";
import { buildRuntimeInstructions } from "@t3tools/provider-core/server/runtimeInstructions";
import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator";
import type * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
import {
type BackgroundWork,
type BackgroundWorkReport,
backgroundWorkNotification,
} from "@t3tools/provider-core/server/notification";
import {
makeProviderFailure,
makeProviderRetryTurnItem,
} from "@t3tools/provider-core/server/failure";
import { acpSelectionTransition } from "@t3tools/provider-core/server/selectionTransition";
import {
isProviderNativeImageAttachment,
providerMessageTextWithAttachmentPaths,
} from "@t3tools/provider-core/server/attachmentPrompt";
import {
makeSubagentChildThread,
makeSubagentConversationArtifacts,
subagentThreadTitle,
} from "@t3tools/provider-core/server/subagentProjection";
import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
export const ACP_PROTOCOL = "acp.ndjson-jsonrpc" as const;
// Grok summaries can trail hydrated tools by over two seconds; shorter waits split the wake.
const ACP_DEFERRED_FINALIZE_DEBOUNCE: Duration.Input = "3000 millis";
// A model can stay silent this long before the first token of a reply the agent started itself.
const ACP_OPEN_REPLY_QUIET_LIMIT: Duration.Input = "2 minutes";
const ACP_BUSY_PROMPT_RETRY_INTERVAL: Duration.Input = "1 second";
// pi-agent-core agents (oh-my-pi) end a turn while background work runs and reject
// prompts until it finishes; the prompt is resent rather than failing the turn.
function isAgentBusyPromptError(error: EffectAcpErrors.AcpError): boolean {
return (
error._tag === "AcpRequestError" && error.errorMessage.startsWith("Agent is already processing")
);
}
function sendPromptWhenIdle(
turn: { readonly interrupted: boolean; readonly finalized: boolean },
prompt: () => Effect.Effect,
): Effect.Effect {
// A Stop can land during the wait, so the flags are rechecked before each resend.
const stopped = () => turn.interrupted || turn.finalized;
return prompt().pipe(
Effect.catchIf(
(error) => isAgentBusyPromptError(error) && !stopped(),
(error) =>
Effect.sleep(ACP_BUSY_PROMPT_RETRY_INTERVAL).pipe(
Effect.andThen(
Effect.suspend(() =>
stopped() ? Effect.fail(error) : sendPromptWhenIdle(turn, prompt),
),
),
),
),
);
}
/**
* Emit first chunks and segment-close events immediately; coalesce later chunks into full-text snapshots.
* This avoids quadratic output; scheduled flushes can run late under host load.
*/
const ACP_TEXT_FLUSH_INTERVAL: Duration.Input = "50 millis";
// Subagent messages are stored as finished, so they skip the server's paragraph
// throttle and every snapshot is persisted. Match that throttle's 400 ms cadence.
const ACP_SUBAGENT_TEXT_FLUSH_INTERVAL: Duration.Input = "400 millis";
// Output of the running prompt. Session metadata and unknown updates do not reset its timeout.
const ACP_PROMPT_ACTIVITY_UPDATES: ReadonlySet = new Set([
"agent_message",
"agent_message_chunk",
"agent_thought",
"agent_thought_chunk",
"tool_call",
"tool_call_update",
"tool_call_content_chunk",
"terminal_output_chunk",
"terminal_update",
"plan",
"plan_update",
"plan_removed",
"compaction_update",
"compaction_summary_chunk",
]);
export interface AcpAdapterV2RuntimeInput {
readonly cwd: string;
readonly runtimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy;
readonly mcpServers: ReadonlyArray;
readonly acpMcpServers?: ReadonlyArray;
readonly httpMcpServers?: ReadonlyArray;
readonly processEnvironment?: NodeJS.ProcessEnv;
readonly resumeSessionId?: string;
readonly interruptPromptOnCancel?: boolean;
readonly sessionMeta?: NonNullable;
readonly clientCapabilities: EffectAcpSchema.InitializeRequest["clientCapabilities"];
readonly clientInfo: AcpSessionRuntime.AcpSessionRuntimeOptions["clientInfo"];
readonly requestLogger?: NonNullable;
readonly protocolLogging: NonNullable<
AcpSessionRuntime.AcpSessionRuntimeOptions["protocolLogging"]
>;
readonly onTermination: NonNullable;
readonly onOutgoingResponseFailure?: AcpSessionRuntime.AcpSessionRuntimeOptions["onOutgoingResponseFailure"];
readonly onOutgoingResponse?: AcpSessionRuntime.AcpSessionRuntimeOptions["onOutgoingResponse"];
readonly onIncomingRequest?: AcpSessionRuntime.AcpSessionRuntimeOptions["onIncomingRequest"];
}
export type AcpAdapterV2NativeLogging = Pick<
AcpSessionRuntime.AcpSessionRuntimeOptions,
"requestLogger" | "protocolLogging"
>;
export interface AcpAdapterV2UserInputRequest {
readonly nativeItemId: string;
readonly nativeRequestId: string;
readonly questions: ReadonlyArray;
}
export interface AcpAdapterV2ExtensionContext {
readonly runtime: AcpSessionRuntime.AcpSessionRuntime["Service"];
readonly reportProviderRetry: (input: {
readonly sessionId: string;
readonly failure: OrchestrationV2ProviderFailure;
}) => Effect.Effect;
readonly finishSubagent: (notice: {
readonly sessionId: string;
readonly childSessionId: string;
readonly status: "completed" | "failed" | "cancelled";
readonly result: string | null;
}) => Effect.Effect;
readonly applyBackgroundTaskMutation: (mutation: {
readonly sessionId: string;
readonly taskId: string;
readonly status: "running" | "completed" | "failed";
readonly output?: string;
readonly report?: BackgroundWork;
}) => Effect.Effect;
/** For compactions reported outside ACP `compaction_update`. */
readonly markSessionCompacted: (sessionId: string) => Effect.Effect;
/**
* For agents that hold `session/prompt` past their foreground work on ACP v1. An idle settles
* the run only after a `running` report during it, so an earlier prompt's idle cannot.
*/
readonly reportForegroundWork: (notice: {
readonly sessionId: string;
readonly state: "running" | "idle";
}) => Effect.Effect;
readonly requestUserInput: (
input: AcpAdapterV2UserInputRequest,
requestContext: EffectAcpProtocol.AcpRequestContext,
) => Effect.Effect<
{
readonly acknowledgeNativeResponse: Effect.Effect;
readonly answers: ProviderUserInputAnswers | null;
},
EffectAcpErrors.AcpError
>;
readonly captureProposedPlan: (input: { readonly planMarkdown: string }) => Effect.Effect;
readonly lastProposedPlanMarkdown: Effect.Effect;
}
/**
* Raised when an agent does not accept the session's model selection: the
* session's model option does not offer it, or the agent answers the write
* with invalid params. `makeProviderFailure` shows its message to the user;
* the agent's reply stays on `cause`.
*/
class AcpModelSelectionError extends Schema.TaggedError()(
"AcpModelSelectionError",
{
model: Schema.String,
cause: Schema.Defect(),
},
) {
override get message(): string {
return `The agent did not accept the model "${this.model}". Choose another model for this provider, then retry.`;
}
}
/**
* Maps one per-turn usage sample (flavors with reportsPerTurnPromptUsage)
* directly onto TurnTokenUsage: the response's counters already cover exactly
* this prompt.
*/
export function acpPerTurnPromptUsage(
usage: EffectAcpSchema.Usage | null | undefined,
hasSubagents: boolean,
terminalStatus: OrchestrationV2ProviderTurn["status"],
geminiUsage = false,
): TurnTokenUsage {
if (usage == null) {
return { usageScope: "main_agent", usageStatus: "unavailable", hasSubagents };
}
const inputTokens = geminiUsage
? usage.inputTokens + (usage.cachedReadTokens ?? 0)
: usage.inputTokens;
const outputTokens = geminiUsage
? usage.outputTokens + (usage.thoughtTokens ?? 0)
: usage.outputTokens;
// TurnTokenUsage contract: input includes cache read + write and reasoning
// is a subset of output, so clamp counters that exceed their parent and
// drop the ones the agent left unset. Cache writes are capped at whatever
// cache reads leave of input, so the pair cannot exceed it.
const clampSubset = (value: number | null | undefined, parent: number) =>
value == null ? undefined : Math.min(value, parent);
const cachedInputTokens = clampSubset(usage.cachedReadTokens, inputTokens);
const cacheCreationTokens = clampSubset(
usage.cachedWriteTokens,
inputTokens - (cachedInputTokens ?? 0),
);
const reasoningTokens = clampSubset(usage.thoughtTokens, outputTokens);
return {
usageScope: "main_agent",
usageStatus: terminalStatus === "completed" ? "complete" : "partial",
hasSubagents,
inputTokens,
outputTokens,
...(cachedInputTokens === undefined ? {} : { cachedInputTokens }),
...(cacheCreationTokens === undefined ? {} : { cacheCreationTokens }),
...(reasoningTokens === undefined ? {} : { reasoningTokens }),
};
}
interface AcpPromptOutcomeFailure {
readonly failure: OrchestrationV2ProviderFailure;
readonly threadDisposition: "reusable" | "broken";
}
export interface AcpAdapterV2Flavor {
readonly buildAttachmentPrompt?: (input: {
readonly text: string;
readonly attachments: ReadonlyArray;
readonly resolveAttachmentPath: (attachment: ChatAttachment) => string | null;
readonly promptCapabilities: EffectAcpSchema.AgentCapabilities["promptCapabilities"];
readonly agentVersion: string | undefined;
/** The session's model after selection, with its display name when the agent lists it. */
readonly currentModel: { readonly id: string; readonly name: string | undefined } | undefined;
}) => Effect.Effect, EffectAcpErrors.AcpError>;
readonly promptFailure?: (cause: unknown) => OrchestrationV2ProviderFailure;
/**
* Runs before `session/prompt`. The returned check sees a prompt the agent ended
* without an error or cancel, and reports a failure its stop reason hid. A reported
* failure restarts the runtime before the next turn. A `broken` thread's native
* history is unusable, so the next turn falls back to a fresh session.
*/
readonly watchPromptOutcome?: (
sessionId: string,
) => Effect.Effect<
(result: EffectAcpSchema.PromptResponse) => Effect.Effect
>;
readonly requiresSignIn?: (cause: unknown) => boolean;
/**
* Runs before attachment paths, T3 instructions and native slash-command detection,
* so a rewrite can turn the user's text into a native command.
*/
readonly rewriteUserText?: (
text: string,
turnInput: ProviderAdapter.ProviderAdapterV2TurnInput,
) => Effect.Effect;
readonly driver: ProviderDriverKind;
readonly capabilities: OrchestrationV2ProviderCapabilities;
readonly supportsNativeGoals?: Effect.Effect;
readonly clientCapabilitiesMeta?: NonNullable<
EffectAcpSchema.InitializeRequest["clientCapabilities"]
>["_meta"];
readonly mcpOverHttp?: boolean;
/** The agent has no tool search of its own, so T3 lists optional tools on demand. */
readonly deferMcpTools?: boolean;
readonly normalizeSessionUpdate?: (
notification: EffectAcpSchema.SessionNotification,
) => EffectAcpSchema.SessionNotification;
/**
* Agent updates that belong to no turn (Kiro's own cloud-config fetch). They
* are dropped before anything reads them, so they neither show in the turn
* nor count as it starting.
*/
readonly ignoreSessionUpdate?: (notification: EffectAcpSchema.SessionNotification) => boolean;
readonly onAvailableCommandsUpdate?: (
commands: ReadonlyArray,
) => Effect.Effect;
readonly onSessionConfigurationUpdate?: (
configOptions: ReadonlyArray,
modeState: AcpSessionModeState | undefined,
modelState: EffectAcpSchema.SessionModelState | null | undefined,
) => Effect.Effect;
readonly onUrlElicitation?: (input: {
readonly elicitationId: string;
readonly url: string;
readonly message: string;
}) => Effect.Effect;
readonly extractElicitationForm?: (request: EffectAcpSchema.CreateElicitationRequest) =>
| {
readonly questions: ReadonlyArray;
readonly respond: (
answers: ProviderUserInputAnswers,
) => EffectAcpSchema.CreateElicitationResponse;
}
| undefined;
readonly withRuntimeStartup?: (effect: Effect.Effect) => Effect.Effect;
readonly makeRuntime: (
input: AcpAdapterV2RuntimeInput,
) => Effect.Effect<
AcpSessionRuntime.AcpSessionRuntime["Service"],
EffectAcpErrors.AcpError,
ChildProcessSpawner.ChildProcessSpawner | SecureRandom.SecureRandom | Scope.Scope
>;
readonly customModels?: ReadonlyArray;
/** The agent may run another model than session/new reports, so the model is always written. */
readonly alwaysSetModel?: boolean;
/** Values the client shows for options a new session's selection leaves unset. */
readonly unsetOptionDefaults?: Effect.Effect>;
readonly resolveModelId?: (selection: ModelSelection) => string | undefined;
/**
* The agent advertises its model option only after `session/new` returns
* (Kiro sends it in a `config_option_update`), so in-session model switching
* is not inferred from the setup result.
*/
readonly modelOptionArrivesLate?: boolean;
readonly getModelContextWindow?: (
selection: ModelSelection,
session: AcpSessionRuntime.AcpSessionRuntimeStartResult,
) => number | undefined;
readonly applyModelSelection?: (input: {
readonly runtime: AcpSessionRuntime.AcpSessionRuntime["Service"];
readonly startResult: AcpSessionRuntime.AcpSessionRuntimeStartResult;
readonly modelSelection: ModelSelection;
}) => Effect.Effect;
/**
* Model-selection option ids `applyModelSelection` sets itself under a
* native id, which the generic option loop then skips (Kiro's
* `reasoningEffort` is its `effortLevel`).
*/
readonly ownedModelOptionIds?: ReadonlyArray;
readonly lockSessionModeToPolicy?: true;
readonly sessionModeForPolicy?: (
policy: ProviderAdapter.ProviderAdapterV2RuntimePolicy,
) => string | undefined;
/**
* Native select-option values to apply for a runtime policy (e.g. Kiro's
* `autopilot`), set on every session configure. A value the session does
* not advertise is skipped; an agent rejecting it fails the session.
*/
readonly sessionConfigForPolicy?: (
policy: ProviderAdapter.ProviderAdapterV2RuntimePolicy,
) => ReadonlyArray<{ readonly id: string; readonly value: string }>;
/**
* The runtime mode a native session mode grants, for flavors whose modes are permission levels.
* Under a policy ceiling, a mode the user picks that this does not place under it is not applied.
*/
readonly runtimeModeForSessionMode?: (modeId: string) => RuntimeMode | undefined;
readonly clientFileSystem?: {
readonly readTextFile: (
request: EffectAcpSchema.ReadTextFileRequest,
cwd: string | null,
) => Effect.Effect;
readonly writeTextFile?: (
request: EffectAcpSchema.WriteTextFileRequest,
cwd: string | null,
) => Effect.Effect;
};
readonly extractPermissionQuestion?: (request: EffectAcpSchema.RequestPermissionRequest) =>
| {
readonly question: OrchestrationV2UserInputQuestion;
readonly respond: (
answers: ProviderUserInputAnswers,
) => EffectAcpSchema.RequestPermissionResponse | undefined;
}
| undefined;
/** Grok Auto asks only about classifier refusals; T3 policy must not auto-approve them. */
readonly permissionDisposition?: (
policy: ProviderAdapter.ProviderAdapterV2RuntimePolicy,
request: EffectAcpSchema.RequestPermissionRequest,
) => AcpPermissionDisposition;
readonly approvalOptions?: (
request: EffectAcpSchema.RequestPermissionRequest,
) => ReadonlyArray;
/** Options T3 may answer with; the rest (e.g. Devin's bypass-permissions plan exit) are never sent. */
readonly answerablePermissionOptions?: (
request: EffectAcpSchema.RequestPermissionRequest,
) => ReadonlyArray;
readonly onSessionEvent?: (
event: AcpSessionRuntime.AcpSessionRuntimeEvent,
) => Effect.Effect;
readonly subagentsIdleOnTurnCompletion?: boolean;
readonly supportsCompaction?: boolean;
/** Sends `/compact` as a prompt, only to sessions whose advertised commands include `compact`. */
readonly compactViaAdvertisedCommand?: boolean;
/**
* Native steering: `send` queues a message into the running turn and returns the
* agent's id for it, which `injectedSteerId` reads from the update that delivers it.
* No id means the running turn reads the message once the agent accepts it.
*/
readonly steering?: {
readonly send: (
runtime: AcpSessionRuntime.AcpSessionRuntime["Service"],
sessionId: string,
text: string,
images: ReadonlyArray,
) => Effect.Effect;
readonly injectedSteerId?: (
notification: EffectAcpSchema.SessionNotification,
) => string | undefined;
};
/**
* Native fork from an earlier turn. `nativeTurnId` reads the agent's id for a running
* turn's prompt, which the turn keeps as its native ref; forking from that turn sends
* `forkMeta(id)` as the `session/fork` `_meta`.
*/
readonly forkFromTurn?: {
readonly supported: (
initializeResult: AcpSessionRuntime.AcpSessionRuntimeStartResult["initializeResult"],
) => boolean;
readonly nativeTurnId: (
notification: EffectAcpSchema.SessionNotification,
) => string | undefined;
readonly forkMeta: (
nativeTurnId: string,
) => NonNullable;
};
/**
* Compacts with the agent's own request, for agents that answer a `/compact` prompt as chat.
* Compaction is refused when `supported` rejects the running agent's `initialize` result.
*/
readonly compactSession?: {
readonly supported: (
initializeResult: AcpSessionRuntime.AcpSessionRuntimeStartResult["initializeResult"],
) => boolean;
readonly compact: (
runtime: AcpSessionRuntime.AcpSessionRuntime["Service"],
sessionId: string,
) => Effect.Effect;
};
readonly runtimeHarness?: string;
readonly registerExtensions?: (
context: AcpAdapterV2ExtensionContext,
) => Effect.Effect;
readonly extractSubagentSessionEvent?: (
notification: EffectAcpSchema.SessionNotification,
) => AcpSubagentSessionEvent | undefined;
readonly extractSubagentUpdate?: (
toolCall: AcpToolCallState,
) => AcpAdapterV2SubagentUpdate | undefined;
readonly isProvisionalSubagentTool?: (toolCall: AcpToolCallState) => boolean;
readonly normalizeToolCall?: (toolCall: AcpToolCallState) => AcpToolCallState;
readonly isCancelledToolCall?: (payload: unknown) => boolean;
readonly extractProposedPlanMarkdown?: (toolCall: AcpToolCallState) => string | undefined;
readonly extractBackgroundTaskId?: (toolCall: AcpToolCallState) => string | undefined;
/** Distinguishes commands from monitors when lifecycle notifications omit their kind. */
readonly isBackgroundCommandTool?: (toolCall: AcpToolCallState) => boolean;
readonly extractBackgroundToolMutation?: (text: string) => ReadonlyArray<{
readonly taskId: string;
readonly status: "running" | "completed" | "failed";
readonly appendOutput: string;
}>;
readonly extractSubagentEndNotice?: (text: string) =>
| {
readonly childSessionId: string;
readonly status: "completed" | "failed";
}
| undefined;
readonly extractBackgroundTaskCompletion?: (toolCall: AcpToolCallState) => ReadonlyArray<{
readonly taskId: string;
readonly status: "running" | "completed" | "failed";
readonly appendOutput: string;
}>;
readonly isPersistentBackgroundTool?: (toolCall: AcpToolCallState) => boolean;
/**
* A tool the agent goes on running after its prompt ends, and reports on by itself when the
* tool ends. With `deferFinalizeForBackgroundWork`, the turn stays open until then.
*/
readonly toolOutlivesPrompt?: (toolCall: AcpToolCallState) => boolean;
readonly isProviderWakeNotification?: (
notification: EffectAcpSchema.SessionNotification,
) => boolean;
readonly deferFinalizeForBackgroundWork?: AcpNegotiatedFlag;
/**
* Every model reply ends with `usage_update`, also the ones the agent starts with no prompt
* open. A turn that ends on the deferred finalize waits for it instead of the short debounce.
*/
readonly replyEndsWithUsageUpdate?: boolean;
readonly assertComplete?: Effect.Effect;
/** Interrupt the local prompt fiber before `session/cancel` (Grok wedged prompts). */
readonly interruptPromptOnCancel?: boolean;
/**
* Hold `session/cancel` until an update after `session/prompt` matches `isStart`,
* or `bound` has passed; skip it if the prompt settles first. Kiro 2.27.1 can
* drop a cancel sent just after the prompt and run the turn to completion.
*/
readonly cancelAfterPromptStarts?: {
readonly isStart: (update: EffectAcpSchema.SessionUpdate) => boolean;
readonly bound: Duration.Input;
};
/**
* The agent's PromptResponse.usage counters read per-turn. The ACP spec
* leaves usage semantics open, so this stays unset until proven live.
*/
readonly reportsPerTurnPromptUsage?: boolean;
/** Gemini-style usage: inputTokens leaves out cachedReadTokens, outputTokens leaves out thoughtTokens. */
readonly geminiPromptUsage?: boolean;
/**
* Fails a dispatched prompt after this long with no update for its session while no
* agent request, tool or subagent is open, and replaces the agent before the next turn.
*/
readonly promptInactivityTimeout?: Duration.Input;
/** Grok can retain task_already_running until process exit. */
readonly restartRuntimeAfterInterrupt?: boolean;
/** Prompt failures after which the agent process keeps failing until replaced. */
readonly restartRuntimeAfterPromptError?: (error: unknown) => boolean;
readonly restartRuntimeOnEveryInterrupt?: boolean;
readonly terminateRuntimeProcessGroupOnInterrupt?: boolean;
readonly preserveRuntimeOnSettledInterrupt?: boolean;
readonly enablePostSettleContinuation?: AcpNegotiatedFlag;
/** A native request after prompt settlement starts a continuation before it is handled. */
readonly wakeOnDetachedRequest?: boolean;
/** Settle on native idle after the accepted user echo, only on negotiated ACP v2. */
readonly followAgentWorkState?: boolean;
/**
* Grok CLI currently accepts and vision-processes image blocks while still
* reporting the capability as false; without this override, screenshot turns
* fail before `session/prompt`.
*/
readonly supportsImagePrompts?: boolean;
/**
* True when this session's native system prompt carries T3's PR-linking instructions, so
* turns omit them. Must use the same negotiated check that sent them on session setup.
*/
readonly sessionCarriesPullRequestLinking?: (
initializeResult: EffectAcpSchema.InitializeResponse,
) => boolean;
}
/**
* A flavor flag that is either fixed, or read from the agent's `initialize` result for
* agents identified only there, such as one launched through a wrapper command.
*/
type AcpNegotiatedFlag =
| boolean
| ((initializeResult: EffectAcpSchema.InitializeResponse) => boolean);
const readNegotiatedFlag = (
flag: AcpNegotiatedFlag | undefined,
initializeResult: EffectAcpSchema.InitializeResponse,
) => (typeof flag === "function" ? flag(initializeResult) : flag === true);
function acpSupportsImagePrompts(input: {
readonly flavorSupportsImagePrompts?: boolean | undefined;
readonly negotiatedImage?: boolean | undefined;
}): boolean {
return input.flavorSupportsImagePrompts === true || input.negotiatedImage === true;
}
export function acpScopedNativeId(instanceId: ProviderInstanceId, nativeId: string): string {
return `provider-instance:${encodeURIComponent(instanceId)}:${nativeId}`;
}
function acpProviderItemNativeId(input: {
readonly instanceId: ProviderInstanceId;
readonly itemIdentityVersion: 2 | undefined;
readonly nativeId: string;
}): string {
return input.itemIdentityVersion === 2
? acpScopedNativeId(input.instanceId, input.nativeId)
: input.nativeId;
}
export type AcpSubagentSessionEvent =
| {
readonly type: "state";
readonly childSessionId: string;
readonly parentSessionId: string;
readonly status: "running" | "completed" | "failed" | "cancelled";
readonly result: string | null;
}
| {
readonly type: "delegation";
readonly childSessionId: string;
readonly parentSessionId: string | null;
readonly delegationId: string;
readonly prompt: string;
};
export interface AcpAdapterV2SubagentUpdate {
readonly nativeTaskId: string;
readonly prompt: string;
readonly title: string | null;
readonly model: string | null;
readonly status:
| "pending"
| "running"
| "idle"
| "completed"
| "failed"
| "interrupted"
| "cancelled";
readonly childSessionId: string | null;
readonly result: string | null;
readonly suppressNormalTool?: boolean;
}
export interface AcpAdapterV2Options {
readonly instanceId: ProviderInstanceId;
readonly flavor: AcpAdapterV2Flavor;
readonly selfInvocation: SelfInvocation;
readonly clientTerminals?: {
readonly environment?: NodeJS.ProcessEnv;
readonly shellCommands?: boolean;
};
readonly nativeLogging?: (threadId: ThreadId) => AcpAdapterV2NativeLogging;
readonly continuationRequests?: {
readonly offer: (
request: ProviderContinuationRequests.ProviderContinuationRequest,
) => Effect.Effect;
};
readonly testHooks?: {
readonly onDeferredFinalizeScheduled?: (debounce: Duration.Input) => Effect.Effect;
/** `cancelAfterPromptStarts`: Stop is holding `session/cancel` until the prompt starts. */
readonly onCancelHeld?: () => Effect.Effect;
readonly afterPromptWireSettled?: () => Effect.Effect;
readonly afterPromptSettledWithBackgroundWork?: () => Effect.Effect;
readonly afterPromptCallback?: () => Effect.Effect;
readonly onNativeResponseLifecycle?: (event: {
readonly generation?: number;
readonly requestId?: string;
readonly type:
| "admission_rejected"
| "failed"
| "late_noop"
| "registered"
| "removed"
| "timer_exited"
| "timer_started"
| "watcher_exited"
| "watcher_started";
}) => Effect.Effect;
};
}
export const AcpProviderCapabilitiesV2 = {
sessions: {
supportsMultipleProviderThreadsPerSession: false,
supportsModelSwitchInSession: false,
supportsProviderSwitchingViaHandoff: true,
supportsRuntimeModeSwitchInSession: false,
pendingRequestsSurviveRestart: false,
},
threads: {
canCreateEmptyThread: true,
canReadThreadSnapshot: false,
canRollbackThread: true,
canForkThread: false,
canForkFromTurn: false,
canForkFromSubagentThread: false,
exposesNativeThreadId: true,
},
turns: {
exposesNativeTurnId: false,
emitsTurnStarted: true,
emitsTurnCompleted: true,
supportsInterrupt: true,
supportsActiveSteering: false,
supportsSteeringByInterruptRestart: true,
supportsQueuedMessages: true,
terminalStatusQuality: "strong",
},
streaming: {
streamsAssistantText: true,
streamsReasoning: true,
streamsToolOutput: true,
streamsPlanText: false,
emitsMessageCompleted: true,
},
tools: {
exposesToolItemIds: true,
emitsToolStarted: true,
emitsToolCompleted: true,
emitsToolOutput: true,
supportsMcpTools: false,
supportsDynamicToolCallbacks: false,
},
approvals: {
supportsCommandApproval: true,
supportsFileReadApproval: true,
supportsFileChangeApproval: true,
supportsApplyPatchApproval: false,
approvalsHaveNativeRequestIds: false,
approvalCallbacksAreLiveOnly: true,
approvalsCanOriginateFromSubagents: false,
},
planning: {
emitsPlanUpdated: true,
emitsTodoList: true,
emitsProposedPlan: false,
supportsStructuredQuestions: true,
planDeltasHaveItemIds: false,
},
subagents: {
supportsSubagents: false,
exposesSubagentThreadIds: false,
emitsSubagentLifecycle: false,
canWaitForSubagents: false,
canCloseSubagents: false,
canForkSubagentThread: false,
},
context: {
acceptsSystemContext: false,
acceptsDeveloperContext: false,
acceptsSyntheticUserContext: true,
canGenerateSummaries: true,
canConsumeHandoffSummaries: true,
supportsDeltaHandoff: true,
supportsFullThreadHandoff: true,
maxRecommendedHandoffChars: null,
},
checkpointing: {
appCanCheckpointFilesystem: true,
supportsNestedCheckpointScopes: true,
// ACP lacks truncation; rollback starts a fresh agent session and turn start replays the kept history.
providerCanRollbackConversation: false,
providerRollbackReturnsSnapshot: true,
providerCanReadConversationSnapshot: false,
},
identity: {
nativeThreadIds: "strong",
nativeTurnIds: "weak",
nativeItemIds: "weak",
nativeRequestIds: "weak",
},
runtimePolicy: {
enforcement: "client-boundary",
},
} satisfies OrchestrationV2ProviderCapabilities;
const STEER_DELIVERY_BOUND = "2 seconds";
/**
* `session/fork` `_meta` for a fork from `providerTurnId`: none for the session head,
* the flavor's meta for a turn the agent named, or `null` when the agent can't fork there.
*/
function forkFromTurnMetaFor(input: {
readonly driver: ProviderDriverKind;
readonly flavor: Pick;
readonly canForkFromTurn: boolean;
readonly forkInput: ProviderAdapter.ProviderAdapterV2ForkThreadInput;
}): NonNullable | undefined | null {
const { forkInput } = input;
if (forkInput.providerTurnId === undefined) return undefined;
const turns = (forkInput.sourceProviderTurns ?? []).filter(
(turn) => turn.providerThreadId === forkInput.sourceProviderThread.id,
);
const target = turns.find((turn) => turn.id === forkInput.providerTurnId);
if (target === undefined) return null;
if (turns.every((turn) => turn.ordinal <= target.ordinal)) return undefined;
const ref = target.nativeTurnRef;
if (
input.flavor.forkFromTurn === undefined ||
!input.canForkFromTurn ||
ref === null ||
ref.driver !== input.driver ||
ref.strength !== "strong" ||
ref.nativeId === null
) {
return null;
}
return input.flavor.forkFromTurn.forkMeta(ref.nativeId);
}
function isCompactionMessage(message: ProviderAdapter.ProviderAdapterV2TurnMessage): boolean {
return message.text.trim() === "/compact" && message.attachments.length === 0;
}
/** `/compact`, optionally followed by preservation instructions that some agents accept. */
function isCompactCommand(message: ProviderAdapter.ProviderAdapterV2TurnMessage): boolean {
return /^\/compact(?:\s|$)/.test(message.text.trim()) && message.attachments.length === 0;
}
function negotiatedCapabilities(
base: OrchestrationV2ProviderCapabilities,
started: AcpSessionRuntime.AcpSessionRuntimeStartResult,
modelOptionArrivesLate: boolean,
forksFromTurn: boolean,
): OrchestrationV2ProviderCapabilities {
const agent = started.initializeResult.agentCapabilities ?? {};
const session = agent.sessionCapabilities;
const setup = started.sessionSetupResult;
const canSwitchModel =
modelOptionArrivesLate ||
findModelConfigOption(setup.configOptions) !== undefined ||
setup.models != null;
const canLoad = agent.loadSession === true;
const canFork = session?.fork != null;
return {
...base,
sessions: {
...base.sessions,
supportsModelSwitchInSession: canSwitchModel,
},
threads: {
...base.threads,
canReadThreadSnapshot: canLoad,
canForkThread: canFork,
canForkFromTurn: canFork && forksFromTurn,
},
tools: {
...base.tools,
supportsMcpTools: true,
},
checkpointing: {
...base.checkpointing,
providerCanReadConversationSnapshot: canLoad,
},
};
}
interface AcpMcpContext {
readonly servers: ReadonlyArray;
readonly acpServers: ReadonlyArray;
readonly httpServers: ReadonlyArray;
readonly processEnvironment?: NodeJS.ProcessEnv;
readonly endpoint?: string;
readonly authorization?: string;
}
function acpMcpContext(
session: McpProviderSession.McpProviderSessionConfig | undefined,
self: SelfInvocation,
mcpOverHttp: boolean | undefined,
deferMcpTools: boolean | undefined,
): AcpMcpContext {
if (session === undefined) {
return { servers: [], acpServers: [], httpServers: [] };
}
// codex-acp 1.2.0 and pi-acp drop injected HTTP servers, so HTTP is opt-in per flavor.
return {
servers: [
{
name: "t3-code",
command: self.command,
args: [...selfInvocationArgs(self, ["acp-mcp-bridge"])],
env: [
{ name: "ELECTRON_RUN_AS_NODE", value: "1" },
{ name: "T3_ACP_MCP_ENDPOINT", value: session.endpoint },
{ name: "T3_ACP_MCP_AUTHORIZATION", value: session.authorizationHeader },
],
},
],
acpServers: [{ type: "acp", name: "t3-code", serverId: "t3-code" }],
httpServers:
mcpOverHttp === true
? [
{
type: "http",
name: "t3-code",
url: session.endpoint,
headers: [
{ name: "Authorization", value: session.authorizationHeader },
...(deferMcpTools === true
? [{ name: McpProviderSession.MCP_TOOL_EXPOSURE_HEADER, value: "deferred" }]
: []),
],
},
]
: [],
endpoint: session.endpoint,
authorization: session.authorizationHeader,
processEnvironment: {
// The thread id every process the agent starts inherits, so a tool run
// from its shell can find its T3 thread. Claude and Codex sessions set
// the same variable (PortScanner.AGENT_THREAD_ENV; a string literal here
// because this package cannot reach apps/server).
T3CODE_THREAD_ID: session.threadId,
T3_ACP_MCP_ENDPOINT: session.endpoint,
T3_ACP_MCP_AUTHORIZATION: session.authorizationHeader,
T3_ACP_MCP_NODE: self.command,
...(self.entrypoint === undefined ? {} : { T3_ACP_MCP_ENTRYPOINT: self.entrypoint }),
},
};
}
function acpMcpActivation(context: AcpMcpContext) {
return {
mcpServers: context.servers,
acpMcpServers: context.acpServers,
httpMcpServers: context.httpServers,
};
}
function nativeThreadId(
driver: ProviderDriverKind,
thread: OrchestrationV2ProviderThread,
): Effect.Effect {
const id = thread.nativeThreadRef?.nativeId;
if (id === null || id === undefined || id.trim().length === 0) {
return Effect.fail(
new ProviderAdapter.ProviderAdapterProtocolError({
driver,
detail: `Provider thread ${thread.id} is missing its ACP session id`,
}),
);
}
return Effect.succeed(id);
}
function makeProviderThread(input: {
readonly driver: ProviderDriverKind;
readonly providerInstanceId: ProviderInstanceId;
readonly idAllocator: IdAllocator.IdAllocatorV2["Service"];
readonly appThreadId: OrchestrationV2ProviderThread["appThreadId"];
readonly providerSessionId: OrchestrationV2ProviderThread["providerSessionId"];
readonly nativeThreadId: string;
readonly ownerNodeId?: OrchestrationV2ProviderThread["ownerNodeId"];
readonly forkedFrom?: OrchestrationV2ProviderThread["forkedFrom"];
readonly itemIdentityVersion?: 2;
readonly now: DateTime.Utc;
}): OrchestrationV2ProviderThread {
return {
id: input.idAllocator.derive.providerThread({
driver: input.driver,
providerInstanceId: input.providerInstanceId,
nativeThreadId: input.nativeThreadId,
}),
driver: input.driver,
providerInstanceId: input.providerInstanceId,
providerSessionId: input.providerSessionId,
appThreadId: input.appThreadId,
ownerNodeId: input.ownerNodeId ?? null,
nativeThreadRef: {
driver: input.driver,
nativeId: input.nativeThreadId,
strength: "strong",
},
nativeConversationHeadRef: null,
status: "idle",
firstRunOrdinal: null,
lastRunOrdinal: null,
handoffIds: [],
forkedFrom: input.forkedFrom ?? null,
contextUsage: null,
nativeMetadata:
input.itemIdentityVersion === undefined
? null
: { itemIdentityVersion: input.itemIdentityVersion },
createdAt: input.now,
updatedAt: input.now,
};
}
/** Stop reasons where the agent ended without finishing. ACP asks clients to show refusals. */
export function acpUnfinishedStopMessage(
stopReason: EffectAcpSchema.StopReason | null | undefined,
): string | undefined {
switch (stopReason) {
case "refusal":
return "The agent refused this request. The agent's next turn won't include this message or its reply.";
case "max_tokens":
return "The agent stopped because its reply reached the output token limit.";
case "max_turn_requests":
return "The agent stopped because it reached its request limit for this turn.";
default:
return undefined;
}
}
function appendToolContentText(content: unknown, text: string): unknown[] {
const next: unknown[] = Array.isArray(content) ? [...content] : [];
const last = unknownRecord(next.at(-1));
const lastContent = unknownRecord(last?.content);
if (
last?.type === "content" &&
lastContent?.type === "text" &&
typeof lastContent.text === "string"
) {
next[next.length - 1] = {
...last,
content: { ...lastContent, text: `${lastContent.text}${text}` },
};
} else {
next.push({ type: "content", content: { type: "text", text } });
}
return next;
}
function acpMcpToolCallOutput(rawOutput: unknown): unknown {
const record = unknownRecord(rawOutput);
if (record === undefined) return rawOutput;
if (!("result" in record) && !("error" in record)) return rawOutput;
const result = unknownRecord(record.result);
const resultOutput = result === undefined ? undefined : mcpToolResultOutput(result);
const errorMessage = unknownRecord(record.error)?.message;
if (typeof errorMessage !== "string") {
return resultOutput ?? rawOutput;
}
return resultOutput === undefined
? { error: errorMessage }
: { error: errorMessage, result: resultOutput };
}
function nonEmptyText(value: unknown, fallback: string): string {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
}
function decodeByteText(value: unknown): string | undefined {
if (!Array.isArray(value) || value.length === 0) return undefined;
if (!value.every((entry) => typeof entry === "number" && Number.isInteger(entry))) {
return undefined;
}
try {
const text = new TextDecoder().decode(Uint8Array.from(value as number[]));
return text.length > 0 ? text : undefined;
} catch {
return undefined;
}
}
function textFromUnknown(value: unknown): string | undefined {
if (typeof value === "string") {
return value;
}
const fromBytes = decodeByteText(value);
if (fromBytes !== undefined) {
return fromBytes;
}
if (Array.isArray(value)) {
const parts = value.flatMap((entry) => {
const text = textFromUnknown(entry);
return text === undefined || text.length === 0 ? [] : [text];
});
return parts.length === 0 ? undefined : parts.join("\n");
}
const record = unknownRecord(value);
if (record === undefined) {
return undefined;
}
for (const key of [
"output_for_prompt",
"stdout",
"stderr",
"output",
"combinedOutput",
"combined_output",
"content",
"text",
"message",
]) {
const direct = record[key];
if (typeof direct === "string" && direct.length > 0) {
return direct;
}
const decoded = decodeByteText(direct);
if (decoded !== undefined) {
return decoded;
}
const text = textFromUnknown(direct);
if (text !== undefined && text.length > 0) {
return text;
}
}
const result = unknownRecord(record.Result) ?? unknownRecord(record.result);
if (result !== undefined) {
return textFromUnknown(result);
}
return undefined;
}
function commandExitCode(value: unknown): number | undefined {
const record = unknownRecord(value);
for (const key of ["exitCode", "exit_code", "code"]) {
const candidate = record?.[key];
if (typeof candidate === "number" && Number.isInteger(candidate)) {
return candidate;
}
}
return undefined;
}
/**
* Mid-stream Grok Bash re-reports carry exit_code 0 while still in progress;
* interrupted tools must not retain that stale success code.
*/
function acpProjectedCommandExitCode(
status: "pending" | "running" | "waiting" | "completed" | "failed" | "interrupted",
rawOutput: unknown,
): number | undefined {
if (status !== "completed" && status !== "failed") {
return undefined;
}
return commandExitCode(rawOutput);
}
function structuredFileChanges(toolCall: AcpToolCallState) {
const content = toolCall.data.content;
if (!Array.isArray(content)) return [];
return content.flatMap((entry) => {
const diff = unknownRecord(entry);
if (diff?.type !== "diff" || !Array.isArray(diff.changes)) return [];
return diff.changes.flatMap((candidate) => {
const change = unknownRecord(candidate);
const operation = typeof change?.operation === "string" ? change.operation.trim() : "";
const path = typeof change?.path === "string" ? change.path.trim() : "";
if (operation.length === 0 || path.length === 0) return [];
const oldPath = typeof change?.oldPath === "string" ? change.oldPath.trim() : "";
const fileType = typeof change?.fileType === "string" ? change.fileType.trim() : "";
const mimeType = typeof change?.mimeType === "string" ? change.mimeType.trim() : "";
return [
{
operation,
path,
...(oldPath.length === 0 ? {} : { oldPath }),
...(fileType.length === 0 ? {} : { fileType }),
...(mimeType.length === 0 ? {} : { mimeType }),
},
];
});
});
}
// Bound diff search to protect the event loop; empty-sided diffs need no search.
const ACP_V1_DIFF_MAX_EDITS = 1_000;
/**
* A `snippet` patch has no known location. Keep its recorded text, so no view numbers it
* from line 1.
*/
export function acpToolCallSnippetEdit(content: unknown) {
if (!Array.isArray(content)) return undefined;
const diffs = content.flatMap((entry) => {
const diff = unknownRecord(entry);
return diff?.type === "diff" ? [diff] : [];
});
const diff = diffs.length === 1 ? diffs[0] : undefined;
if (diff === undefined || unknownRecord(diff.patch)?.format !== "snippet") return undefined;
return typeof diff.oldText === "string" && typeof diff.newText === "string"
? { oldStr: diff.oldText, newStr: diff.newText }
: undefined;
}
/**
* No preview when a flavor marked a diff `omitted` (too large) or `snippet` (line unknown);
* the checkpoint diff shows it.
*/
function acpToolCallDiffUnpreviewable(content: unknown): boolean {
return (
Array.isArray(content) &&
content.some((entry) => {
const format = unknownRecord(unknownRecord(entry)?.patch)?.format;
return format === "omitted" || format === "snippet";
})
);
}
export function acpToolCallDiffPatch(content: unknown): string | undefined {
if (!Array.isArray(content) || acpToolCallDiffUnpreviewable(content)) {
return undefined;
}
const diffs = content.flatMap((entry) => {
const diff = unknownRecord(entry);
return diff?.type === "diff" ? [diff] : [];
});
const patches = diffs.flatMap((diff): ReadonlyArray<{ text: string; path?: string }> => {
const patch = unknownRecord(diff.patch);
if (typeof patch?.text === "string") {
const change =
Array.isArray(diff.changes) && diff.changes.length === 1
? unknownRecord(diff.changes[0])
: undefined;
if (
patch.format === "git_patch" &&
patch.text.trimStart().startsWith("@@ ") &&
typeof change?.path === "string"
) {
const oldPath = typeof change.oldPath === "string" ? change.oldPath : change.path;
const before = change.operation === "add" ? "/dev/null" : JSON.stringify(`a/${oldPath}`);
const after =
change.operation === "delete" ? "/dev/null" : JSON.stringify(`b/${change.path}`);
return [
{
text: `diff --git ${JSON.stringify(`a/${oldPath}`)} ${JSON.stringify(`b/${change.path}`)}\n--- ${before}\n+++ ${after}\n${patch.text.trimStart()}`,
},
];
}
return [{ text: patch.text }];
}
if (typeof diff.path !== "string" || typeof diff.newText !== "string") return [];
const oldText = typeof diff.oldText === "string" ? diff.oldText : undefined;
const structured = structuredPatch(
oldText === undefined ? "/dev/null" : diff.path,
diff.path,
oldText ?? "",
diff.newText,
undefined,
undefined,
{
context: 3,
maxEditLength: oldText && diff.newText ? ACP_V1_DIFF_MAX_EDITS : Number.POSITIVE_INFINITY,
},
);
return structured === undefined || structured.hunks.length === 0
? []
: [{ text: formatPatch(structured, FILE_HEADERS_ONLY), path: diff.path }];
});
// Diff parsers split at Git headers once one exists, so every section then needs its own.
const hasGitHeader = patches.some(({ text }) => /^diff --git /m.test(text));
return patches.length === 0
? undefined
: patches
.map(({ text, path }) =>
hasGitHeader && path !== undefined
? `diff --git ${JSON.stringify(`a/${path}`)} ${JSON.stringify(`b/${path}`)}\n${text}`
: text,
)
.join("\n");
}
function resolvedPathInfo(
toolCall: AcpToolCallState,
): { readonly path: string; readonly fromQuery: boolean } | undefined {
const locations = toolCall.data.locations;
if (Array.isArray(locations)) {
for (const location of locations) {
const path = unknownRecord(location)?.path;
if (typeof path === "string" && path.trim().length > 0) {
return { path: path.trim(), fromQuery: false };
}
}
}
const rawInput = unknownRecord(toolCall.data.rawInput);
for (const key of ["path", "filePath", "file_path", "url"]) {
const candidate = rawInput?.[key];
if (typeof candidate === "string" && candidate.trim().length > 0) {
return { path: candidate.trim(), fromQuery: false };
}
}
for (const key of ["query", "pattern"]) {
const candidate = rawInput?.[key];
if (typeof candidate === "string" && candidate.trim().length > 0) {
return { path: candidate.trim(), fromQuery: true };
}
}
return undefined;
}
function pathFromToolCall(toolCall: AcpToolCallState): string | undefined {
return resolvedPathInfo(toolCall)?.path;
}
function acpBackendWebSearch(
rawInput: Record | undefined,
rawOutput: unknown,
title?: string | null,
):
| { readonly query: string | undefined; readonly results: OrchestrationV2WebSearchResult[] }
| undefined {
const variant = typeof rawInput?.variant === "string" ? rawInput.variant.toLowerCase() : "";
const rawOutputRecord = unknownRecord(rawOutput);
const action = unknownRecord(rawOutputRecord?.action);
const isWebSearchTitle =
/^\s*(?:web search|search the web|(?:run(?:ning)?\s+)?(?:web_search|search_web)\s*$)/iu.test(
title ?? "",
);
const isWebSearchVariant = [
"xsearch",
"websearch",
"web_search",
"search_web",
"web-search",
].includes(variant);
if (!isWebSearchVariant && action?.type !== "search" && !isWebSearchTitle) {
return undefined;
}
let args: Record | undefined;
if (typeof rawOutputRecord?.input === "string") {
try {
args = unknownRecord(JSON.parse(rawOutputRecord.input));
} catch {
args = undefined;
}
}
const argsText = Object.entries(args ?? {})
.filter(([, value]) => typeof value === "string" || typeof value === "number")
.map(([key, value]) => `${key}: ${value}`)
.join(", ");
const query = [
action?.query,
args?.query,
rawInput?.query,
rawInput?.search_query,
rawInput?.q,
argsText,
]
.find((value): value is string => typeof value === "string" && value.trim().length > 0)
?.trim();
const urls = new Set();
for (const source of Array.isArray(action?.sources) ? action.sources : []) {
const url = unknownRecord(source)?.url;
if (typeof url === "string" && url.trim().length > 0) urls.add(url.trim());
}
if (urls.size === 0) {
for (const match of textFromUnknown(rawOutput)?.matchAll(/https?:\/\/[^\s<>"]+/gu) ?? []) {
urls.add(trimCitationUrl(match[0]));
}
}
return { query, results: [...urls].map((url) => ({ url })) };
}
// Prose citations end in punctuation or a closing bracket that is not part of the URL.
function trimCitationUrl(raw: string): string {
let url = raw;
for (;;) {
const trimmed = url.replace(/[.,;:]+$/u, "");
const close = trimmed.at(-1);
const open = close === ")" ? "(" : close === "]" ? "[" : undefined;
if (open && close && trimmed.split(open).length < trimmed.split(close).length) {
url = trimmed.slice(0, -1);
} else if (trimmed === url) {
return url;
} else {
url = trimmed;
}
}
}
function providerRequestKind(kind: string | "unknown"): ProviderRequestKind {
switch (kind) {
case "execute":
return "command";
case "read":
case "search":
case "fetch":
return "file-read";
case "edit":
case "delete":
case "move":
return "file-change";
default:
return "command";
}
}
function toolStatus(
status: AcpToolCallState["status"],
): "pending" | "running" | "waiting" | "completed" | "failed" {
switch (status) {
case "completed":
return "completed";
case "failed":
return "failed";
case "pending":
return "pending";
case "requiresAction":
return "waiting";
default:
return "running";
}
}
type ProjectedToolStatus = ReturnType | "interrupted";
/**
* Some agents answer Stop's `session/cancel` by failing the tools and subagents
* that were running (Kiro: "Tool execution was cancelled by the user."). After
* Stop, a failure is shown as the interruption it was.
*/
function stoppedToolStatus(
turn: Pick,
tool: AcpToolCallState,
): "interrupted" | undefined {
return turn.interrupted && tool.status === "failed" ? "interrupted" : undefined;
}
function nodeStatus(status: ProjectedToolStatus): OrchestrationV2ExecutionNode["status"] {
return status === "pending" ? "running" : status;
}
function completedAtForStatus(status: ProjectedToolStatus, now: DateTime.Utc): DateTime.Utc | null {
return status === "completed" || status === "failed" || status === "interrupted" ? now : null;
}
// Copilot advertises URL ids such as `https://agentclientprotocol.com/protocol/session-modes#plan`.
function isAcpPlanModeId(id: string): boolean {
const name = id.slice(id.lastIndexOf("#") + 1);
return name === "plan" || name === "architect";
}
function selectPermissionOptionId(
request: EffectAcpSchema.RequestPermissionRequest,
decision: Exclude,
): string | undefined {
const optionIdOfKind = (kind: EffectAcpSchema.PermissionOption["kind"]) =>
request.options.find((option) => option.kind === kind)?.optionId;
if (decision === "acceptForSession") {
// Agents may offer only allow_once, and answering "cancelled" would stop the turn the user approved.
return optionIdOfKind("allow_always") ?? optionIdOfKind("allow_once");
}
return optionIdOfKind(decision === "accept" ? "allow_once" : "reject_once");
}
// Prefer allow-once; allow-always can persist beyond the session.
function selectAutoApprovedPermissionOption(
request: EffectAcpSchema.RequestPermissionRequest,
): string | undefined {
return (
selectPermissionOptionId(request, "accept") ??
selectPermissionOptionId(request, "acceptForSession")
);
}
interface ActiveTextSegment {
readonly nativeItemId: string;
readonly startedAt: DateTime.Utc;
sourceMessageId: string | null;
text: string;
// The running node and first text have been emitted.
emitted: boolean;
// Text changed since the last emission; a delayed flush is scheduled.
dirty: boolean;
}
interface ActiveTextStream {
current: ActiveTextSegment | null;
nextSegment: number;
readonly closedNamedSegments: Map;
}
interface AcpNativeBuildConfiguration {
readonly modeId?: string;
readonly configOptions: ReadonlyArray<{ readonly id: string; readonly value: string }>;
}
interface ActiveAcpTurn {
readonly input: ProviderAdapter.ProviderAdapterV2TurnInput;
readonly providerTurnId: OrchestrationV2ProviderTurn["id"];
readonly nativeThreadId: string;
readonly nativeTurnId: string;
readonly startedAt: DateTime.Utc;
readonly completed: Deferred.Deferred;
readonly itemOrdinals: Map;
readonly outgoingPrompt?: ReadonlyArray | undefined;
consumedPromptMessageId?: string;
readonly user: ActiveTextStream;
readonly assistant: ActiveTextStream;
readonly reasoning: ActiveTextStream;
providerRetry?:
| {
readonly failure: OrchestrationV2ProviderFailure;
readonly retry: OrchestrationV2ProviderRetry;
readonly startedAt: DateTime.Utc;
readonly itemOrdinal: number;
}
| undefined;
contextUsage: ThreadTokenUsageSnapshot | null;
nativeMetadata: OrchestrationV2ProviderThreadNativeMetadata | null;
readonly tools: Map;
/** Tools the agent failed after Stop; later updates keep them interrupted. */
readonly stoppedToolCallIds: Set;
/** Per-call send_to_user outcome once settled, so replays never consume a sibling record. */
readonly claimedSentMessages: Map;
readonly toolUpdatesSkipped: Map;
readonly toolStartedAt: Map;
readonly subagents: Map;
readonly subagentsBySessionId: Map;
readonly pendingSubagentNotifications: Map>;
readonly toolCallIdsByBackgroundTaskId: Map;
/** Command ACKs register null; terminal results wait here for prompt settlement. */
readonly backgroundCommands: Map<
string,
{ readonly status: "completed" | "failed"; readonly output?: string } | null
>;
readonly persistentBackgroundTaskIds: Set;
/** Monitor end notices lack output; wait for hydration or the safety timeout. */
readonly awaitingBackgroundHydration: Set;
readonly pendingInjectedReport: Set;
/** Reports can precede monitor end notices; consume their completion marker without re-arming. */
earlyInjectedReportObserved: boolean;
readonly plans: Map<
string,
{
readonly id: OrchestrationV2PlanArtifact["id"];
readonly startedAt: DateTime.Utc;
/** The turn that first reported the plan; later turns update its rows. */
readonly origin: {
readonly runId: ActiveAcpTurn["input"]["runId"];
readonly rootNodeId: ActiveAcpTurn["input"]["rootNodeId"];
readonly providerThreadId: ActiveAcpTurn["input"]["providerThread"]["id"];
readonly providerTurnId: ActiveAcpTurn["providerTurnId"];
readonly nativeItemId: string;
readonly ordinal: number;
};
latest: OrchestrationV2PlanArtifact | null;
}
>;
interrupted: boolean;
finalized: boolean;
finalizedStatus: "completed" | "interrupted" | "failed" | "cancelled" | null;
promptSettled: boolean;
promptSettledStatus: "completed" | "interrupted" | "failed" | "cancelled" | null;
workAccepted: boolean;
readonly promptWireSettled: Deferred.Deferred;
/** Completed once `session/prompt` is the runtime's active prompt. */
readonly promptDispatched: Deferred.Deferred;
/** Frees the runtime for the next prompt while the agent still holds this one's response. */
readonly foregroundIdle: Deferred.Deferred;
/** Clock millis just before `session/prompt` was handed to the runtime. */
promptSentAt: number | null;
/** Completed when an update after dispatch matches `cancelAfterPromptStarts.isStart`. */
readonly promptStarted: Deferred.Deferred;
promptUsage: EffectAcpSchema.Usage | undefined;
backgroundFinalizeGeneration: number;
/** `replyEndsWithUsageUpdate`: output arrived and its closing `usage_update` has not. */
replyOpen: boolean;
/** The agent's own id for this turn's prompt, from `forkFromTurn.nativeTurnId`. */
nativePromptId: string | undefined;
/** Clock millis of the prompt's last progress, for `promptInactivityTimeout`. */
lastProgressAt: number;
inactivityWatchdog: Fiber.Fiber | undefined;
}
type AcpRuntimeTeardownState =
| { readonly _tag: "Idle" }
| {
readonly _tag: "InProgress";
readonly completed: Deferred.Deferred;
}
| { readonly _tag: "Failed"; readonly error: ProviderAdapter.ProviderAdapterProtocolError };
function acpRootSessionUpdateIngestsOutput(
notification: EffectAcpSchema.SessionNotification,
): boolean {
const update = notification.update;
switch (update.sessionUpdate) {
case "agent_message_chunk":
case "agent_thought_chunk":
return (acpContentBlockDisplayText(update.content)?.length ?? 0) > 0;
case "agent_message":
case "agent_thought":
return (update.content ?? []).some(
(content) => (acpContentBlockDisplayText(content)?.length ?? 0) > 0,
);
case "tool_call":
case "tool_call_update":
case "plan":
case "plan_update":
case "plan_removed":
case "compaction_update":
case "compaction_summary_chunk":
return parseSessionUpdateEvent(notification).events.some(
(event) => event._tag === "ToolCallUpdated" || event._tag === "PlanUpdated",
);
default:
return false;
}
}
/** Monitor wakes arrive as their own chunk led by a tagged ``; bare mentions are content. */
const acpIsMonitorChatter = (text: string) =>
/^\s*(?: = {},
): boolean {
if (!acpRootSessionUpdateIngestsOutput(notification)) return false;
const update = notification.update;
if (
(update.sessionUpdate === "user_message_chunk" ||
update.sessionUpdate === "agent_message_chunk") &&
update.content.type === "text"
) {
const text = update.content.text;
if ((flavor.extractBackgroundToolMutation?.(text) ?? []).length > 0) return false;
if (update.sessionUpdate === "agent_message_chunk" && text.trim().length === 0) return false;
if (acpIsMonitorChatter(text)) return false;
}
return true;
}
/** Still-running tool updates can outlast the quiet window; they must not offer completion wakes. */
export function acpPostSettleContinuationOfferEvidence(
notification: EffectAcpSchema.SessionNotification,
flavor: Pick = {},
): boolean {
if (!acpPostSettleWakeEvidence(notification, flavor)) {
return false;
}
const update = notification.update;
if (update.sessionUpdate === "agent_message_chunk") {
return (acpContentBlockDisplayText(update.content)?.trim().length ?? 0) > 0;
}
if (update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update") {
return parseSessionUpdateEvent(notification).events.some((event) => {
if (event._tag !== "ToolCallUpdated") return false;
// Grok monitor start ACKs say completed while the task is still running.
const toolCall = flavor.normalizeToolCall?.(event.toolCall) ?? event.toolCall;
return toolCall.status === "completed" || toolCall.status === "failed";
});
}
return false;
}
function acpPostSettleWakeShouldBuffer(
notification: EffectAcpSchema.SessionNotification,
backgroundWorkRunning: boolean,
): boolean {
if (!backgroundWorkRunning) return true;
const update = notification.update;
return (
update.sessionUpdate !== "agent_message_chunk" && update.sessionUpdate !== "agent_thought_chunk"
);
}
/**
* An app-owned wake (a delegated child finishing) is injected by the
* orchestrator, not typed by the user. It reports on a sibling child and says
* nothing about this session's own pending wake frames, so it must not discard
* them the way a real user turn does.
*/
function acpIsAppOwnedWakeTurn(message: {
readonly createdBy: string;
readonly creationSource: string;
}): boolean {
return message.createdBy === "agent" && message.creationSource === "server";
}
function acpIsProviderContinuationMessage(message: {
readonly createdBy: string;
readonly creationSource: string;
}): boolean {
return message.createdBy === "agent" && message.creationSource === "provider";
}
function acpCarryoverTerminalShouldClearContinuation(input: {
readonly continuationOffered: boolean;
readonly wakeBufferLength: number;
}): boolean {
return !input.continuationOffered && input.wakeBufferLength === 0;
}
function acpTurnStartShouldPreserveContinuation(input: {
readonly continuationRequested: boolean;
readonly isContinuationTurn: boolean;
readonly wakeBufferLength: number;
}): boolean {
return !input.isContinuationTurn && input.continuationRequested && input.wakeBufferLength > 0;
}
function acpPostSettleMonitorPromptShouldSuppress(
mutation:
| {
readonly taskId: string;
readonly status: "running" | "completed" | "failed";
}
| undefined,
): boolean {
return mutation?.status === "running";
}
export function acpCompletedTurnShouldTerminalizeTool(
tool: AcpToolCallState & { readonly backgroundCommandTaskId?: string },
flavor: Pick,
): boolean {
const status = toolStatus(tool.status);
if (status !== "pending" && status !== "running") return false;
// Progress output replaces the start ACK, so the registered task id outlives it.
if (tool.backgroundCommandTaskId !== undefined) return false;
if (flavor.extractBackgroundTaskId?.(tool) !== undefined) return false;
return flavor.extractSubagentUpdate?.(tool) === undefined;
}
interface ActiveAcpSubagent {
task: OrchestrationV2Subagent;
readonly childThreadId: ThreadId;
readonly childRootNodeId: OrchestrationV2ExecutionNode["id"];
readonly turnItemId: OrchestrationV2TurnItem["id"];
turnItemOrdinal: number;
providerTurnId: OrchestrationV2ProviderTurn["id"];
readonly parentProviderThreadId: ProviderThreadId;
childSessionId: string | null;
assistantText: string;
readonly assistantMessages: Map;
// Messages whose latest text waits for a delayed flush.
readonly pendingAssistantMessages: Set;
readonly childItemOrdinals: Map;
nextChildOrdinal: number;
terminalStatusProjected: boolean;
readonly toolState: Pick;
// ACP has no interrupted tool status; keep forced interruption across late updates.
readonly interruptedToolIds: Set;
readonly toolSessionIds: Map;
}
interface AcpNativeChildSession {
parentSessionId: string | null;
status: "running" | "completed" | "failed" | "cancelled";
result: string | null;
delegationId: string | null;
prompt: string;
subagent: ActiveAcpSubagent | undefined;
owner: ActiveAcpTurn | undefined;
readonly pending: Array;
}
function acpSubagentStatusIsTerminal(status: OrchestrationV2Subagent["status"]): boolean {
return (
status === "completed" ||
status === "failed" ||
status === "interrupted" ||
status === "cancelled" ||
status === "idle"
);
}
function acpSubagentStatusBlocksTurnSettlement(status: OrchestrationV2Subagent["status"]): boolean {
return status === "running" || status === "pending";
}
function acpSubagentHasPendingBackgroundWork(subagent: ActiveAcpSubagent): boolean {
return (
acpSubagentStatusBlocksTurnSettlement(subagent.task.status) || !subagent.terminalStatusProjected
);
}
type AcpCarryoverSubagents = {
readonly sessionId: string;
/** The root's subscriber keeps ingesting, so late child terminals can still project. */
readonly projectsLateTerminals: boolean;
readonly subagents: ReadonlyArray;
};
type PendingRuntimeRequest = {
readonly generation: number;
readonly nativeResponseAcknowledgement: Deferred.Deferred;
readonly transportRequestId: string;
readonly requestId: RuntimeRequestId;
readonly runtimeRequest: OrchestrationV2RuntimeRequest;
readonly node: OrchestrationV2ExecutionNode;
readonly turnItem: OrchestrationV2TurnItem;
} & (
| {
readonly type: "approval";
readonly decision: Deferred.Deferred;
}
| {
readonly type: "user_input";
readonly answers: Deferred.Deferred;
}
);
/** Writers update `order` and `messages` in place; readers copy them out. */
interface SnapshotMessageState {
readonly order: Array;
readonly messages: Map;
/** Messages loaded from thought chunks; `messages` stores them as assistant text. */
readonly reasoningIds: ReadonlySet;
loadingRole: "user" | "assistant" | "thought" | null;
loadingMessageId: string | null;
loadingIndex: number;
}
const emptySnapshotState = (): SnapshotMessageState => ({
order: [],
messages: new Map(),
reasoningIds: new Set(),
loadingRole: null,
loadingMessageId: null,
loadingIndex: 0,
});
/** How long a Stop waits for the agent to confirm before the user is offered Force stop. */
const ACP_STOP_CONFIRM_TIMEOUT_MS = 10_000;
const TOOL_UPDATE_PERSIST_EVERY = 10;
// CommandOutputHub reads the last 256 KiB; retain more so its display cut stays unchanged.
const MAX_AGENT_TERMINAL_OUTPUT_CHARS = 320 * 1024;
// Agents can resend whole calls while streaming arguments.
function shouldPersistToolUpdate(
context: Pick,
key: string,
previous: AcpToolCallState | undefined,
next: AcpToolCallState,
reportedStatus: AcpToolCallState["status"],
): boolean {
const skipped = context.toolUpdatesSkipped.get(key) ?? 0;
const persist =
reportedStatus === "completed" ||
reportedStatus === "failed" ||
previous === undefined ||
previous.status !== next.status ||
previous.title !== next.title ||
toolCallVisibleOutputChanged(previous, next) ||
skipped + 1 >= TOOL_UPDATE_PERSIST_EVERY;
context.toolUpdatesSkipped.set(key, persist ? 0 : skipped + 1);
return persist;
}
export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
options: AcpAdapterV2Options,
) {
const random = yield* SecureRandom.SecureRandom;
const fileSystem = yield* FileSystem.FileSystem;
const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
const agentScope = yield* AgentScope;
const idAllocator = yield* IdAllocator.IdAllocatorV2;
const host = yield* ProviderHost.ProviderHost;
const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
const { flavor, selfInvocation: self } = options;
const readMcpContext = (threadId: ThreadId | null) =>
threadId === null
? Effect.succeed(acpMcpContext(undefined, self, flavor.mcpOverHttp, flavor.deferMcpTools))
: mcpSessions
.read(threadId)
.pipe(
Effect.map((session) =>
acpMcpContext(session, self, flavor.mcpOverHttp, flavor.deferMcpTools),
),
);
const driver = flavor.driver;
const continuationRequests = options.continuationRequests;
const readCapabilities = Effect.gen(function* () {
if (flavor.supportsNativeGoals === undefined) return flavor.capabilities;
return {
...flavor.capabilities,
turns: {
...flavor.capabilities.turns,
supportsNativeGoals: yield* flavor.supportsNativeGoals,
},
};
});
return ProviderAdapter.ProviderAdapterV2.of({
instanceId: options.instanceId,
driver,
getCapabilities: Effect.fn("AcpAdapter.getCapabilities")(function* () {
return yield* readCapabilities;
}),
planSelectionTransition: Effect.fn("AcpAdapter.planSelectionTransition")(function (input) {
return Effect.succeed(acpSelectionTransition(input));
}),
openSession: Effect.fn("AcpAdapterV2.openSession")(
function* (input: ProviderAdapter.ProviderAdapterV2OpenSessionInput) {
const sessionScope = yield* Effect.scope;
let itemIdentityVersion: 2 | undefined =
input.initialProviderItemIdentityVersion ??
(input.initialNativeThreadId === undefined ? 2 : undefined);
const providerNativeId = (nativeId: string) =>
acpProviderItemNativeId({
instanceId: options.instanceId,
itemIdentityVersion,
nativeId,
});
const providerNodeId = (nativeItemId: string) =>
idAllocator.derive.nodeFromProviderItem({
driver,
nativeItemId: providerNativeId(nativeItemId),
});
const providerMessageId = (nativeItemId: string) =>
idAllocator.derive.messageFromProviderItem({
driver,
nativeItemId: providerNativeId(nativeItemId),
});
const providerTurnItemId = (nativeItemId: string) =>
idAllocator.derive.turnItemFromProviderItem({
driver,
nativeItemId: providerNativeId(nativeItemId),
});
const deriveProviderTurnId = (nativeTurnId: string) =>
idAllocator.derive.providerTurn({
driver,
nativeTurnId: providerNativeId(nativeTurnId),
});
const useProviderThreadIdentity = (thread: OrchestrationV2ProviderThread): void => {
itemIdentityVersion = thread.nativeMetadata?.itemIdentityVersion;
};
const terminalEnvironmentBySessionId = new Map();
interface PendingTerminalEnvironment {
readonly environment: NodeJS.ProcessEnv | undefined;
readonly claimUnknownSession: boolean;
readonly sessionId: string | null;
}
let pendingTerminalEnvironment: PendingTerminalEnvironment | null = {
environment: (yield* readMcpContext(input.threadId)).processEnvironment,
claimUnknownSession: input.initialNativeThreadId === undefined,
sessionId: input.initialNativeThreadId ?? null,
};
const prepareTerminalEnvironment = (
mcpContext: AcpMcpContext,
sessionId?: string,
): void => {
pendingTerminalEnvironment = {
environment: mcpContext.processEnvironment,
claimUnknownSession: false,
sessionId: sessionId ?? null,
};
};
const prepareClaimableTerminalEnvironment = (mcpContext: AcpMcpContext): void => {
pendingTerminalEnvironment = {
environment: mcpContext.processEnvironment,
claimUnknownSession: true,
sessionId: null,
};
};
const rememberTerminalEnvironment = (
sessionId: string,
mcpContext: AcpMcpContext,
): void => {
const environment = mcpContext.processEnvironment;
pendingTerminalEnvironment = null;
if (environment === undefined) {
terminalEnvironmentBySessionId.delete(sessionId);
} else {
terminalEnvironmentBySessionId.set(sessionId, environment);
}
};
const clientTerminals: AcpClientTerminals | undefined =
options.clientTerminals === undefined
? undefined
: yield* makeAcpClientTerminals({
defaultCwd: input.runtimePolicy.cwd ?? process.cwd(),
environment: options.clientTerminals.environment,
shellCommands: options.clientTerminals.shellCommands,
environmentForSession: (sessionId) => {
const remembered = terminalEnvironmentBySessionId.get(sessionId);
if (remembered !== undefined) return remembered;
if (pendingTerminalEnvironment === null) return undefined;
if (
pendingTerminalEnvironment.sessionId === null &&
pendingTerminalEnvironment.claimUnknownSession
) {
pendingTerminalEnvironment = {
...pendingTerminalEnvironment,
sessionId,
};
}
return pendingTerminalEnvironment.sessionId === sessionId
? pendingTerminalEnvironment.environment
: undefined;
},
}).pipe(
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, childProcessSpawner),
);
if (clientTerminals !== undefined) {
yield* Scope.addFinalizer(sessionScope, clientTerminals.disposeAll);
}
const sessionScopedId = (sessionId: string, nativeId: string): string =>
JSON.stringify([sessionId, nativeId]);
const embeddedTerminalsByToolCallId = new Map<
string,
{
readonly sessionId: string;
readonly terminalIds: ReadonlyArray;
readonly toolCallId: string;
}
>();
const toolCallIdsByAgentTerminalId = new Map>();
const agentTerminalsById = new Map();
const rememberEmbeddedTerminals = (input: {
readonly sessionId: string;
readonly toolCallId: string;
readonly terminalIds: ReadonlyArray;
}): void => {
const toolCallKey = sessionScopedId(input.sessionId, input.toolCallId);
for (const terminalId of embeddedTerminalsByToolCallId.get(toolCallKey)?.terminalIds ??
[]) {
const terminalKey = sessionScopedId(input.sessionId, terminalId);
const toolCallIds = toolCallIdsByAgentTerminalId.get(terminalKey);
toolCallIds?.delete(input.toolCallId);
if (toolCallIds?.size === 0) toolCallIdsByAgentTerminalId.delete(terminalKey);
}
embeddedTerminalsByToolCallId.delete(toolCallKey);
embeddedTerminalsByToolCallId.set(toolCallKey, {
sessionId: input.sessionId,
terminalIds: input.terminalIds,
toolCallId: input.toolCallId,
});
for (const terminalId of input.terminalIds) {
const terminalKey = sessionScopedId(input.sessionId, terminalId);
const toolCallIds = toolCallIdsByAgentTerminalId.get(terminalKey) ?? new Set();
toolCallIds.add(input.toolCallId);
toolCallIdsByAgentTerminalId.set(terminalKey, toolCallIds);
}
for (const oldest of embeddedTerminalsByToolCallId.keys()) {
if (embeddedTerminalsByToolCallId.size <= 256) break;
const remembered = embeddedTerminalsByToolCallId.get(oldest);
if (remembered === undefined) continue;
for (const terminalId of remembered.terminalIds) {
const terminalKey = sessionScopedId(remembered.sessionId, terminalId);
const toolCallIds = toolCallIdsByAgentTerminalId.get(terminalKey);
toolCallIds?.delete(remembered.toolCallId);
if (toolCallIds?.size === 0) toolCallIdsByAgentTerminalId.delete(terminalKey);
}
embeddedTerminalsByToolCallId.delete(oldest);
}
};
const embeddedTerminalCommands = (
sessionId: string,
toolCallId: string,
): ReadonlyArray =>
(
embeddedTerminalsByToolCallId.get(sessionScopedId(sessionId, toolCallId))
?.terminalIds ?? []
).flatMap((terminalId) => {
const command =
clientTerminals?.readCommandLine(terminalId) ??
agentTerminalsById.get(sessionScopedId(sessionId, terminalId))?.command;
return command === undefined ? [] : [command];
});
// Client terminals run with server privileges; apply turn policy and prior user approvals.
const clientPolicyGrants = makeAcpClientPolicyGrants();
let latestRuntimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy =
input.runtimePolicy;
const events = yield* Queue.unbounded();
const activeTurn = yield* Ref.make(null);
// Keyed by the agent's steer id; an injection can arrive before its send returns.
const steerInjections = new Map>();
const steerInjection = (steerId: string) => {
const existing = steerInjections.get(steerId);
if (existing !== undefined) return existing;
const created = Deferred.makeUnsafe();
steerInjections.set(steerId, created);
return created;
};
let pendingStopCloseTurn: ActiveAcpTurn | null = null;
let followsAgentWorkState = false;
let postSettleContinuationEnabled = false;
let defersFinalizeForBackgroundWork = false;
let agentWork: Extract<
EffectAcpSchema.SessionUpdate,
{ sessionUpdate: "state_update" }
> | null = null;
// The root's last reportForegroundWork state; undefined until the agent reports one.
let rootForegroundWork: "running" | "idle" | undefined;
const agentRequests = new Set