// @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 {
compactDynamicToolOutput,
htmlRenderFromToolItem,
mcpToolResultOutput,
} 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 {
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";
/**
* 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";
// Output of the running prompt. Session metadata and unknown updates do not reset its timeout.
const ACP_PROMPT_ACTIVITY_UPDATES: ReadonlySet<string> = 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<EffectAcpSchema.McpServer>;
readonly acpMcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
readonly httpMcpServers?: ReadonlyArray<EffectAcpSchema.McpServer>;
readonly processEnvironment?: NodeJS.ProcessEnv;
readonly resumeSessionId?: string;
readonly interruptPromptOnCancel?: boolean;
readonly clientCapabilities: EffectAcpSchema.InitializeRequest["clientCapabilities"];
readonly clientInfo: AcpSessionRuntime.AcpSessionRuntimeOptions["clientInfo"];
readonly requestLogger?: NonNullable<AcpSessionRuntime.AcpSessionRuntimeOptions["requestLogger"]>;
readonly protocolLogging: NonNullable<
AcpSessionRuntime.AcpSessionRuntimeOptions["protocolLogging"]
>;
readonly onTermination: NonNullable<AcpSessionRuntime.AcpSessionRuntimeOptions["onTermination"]>;
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<OrchestrationV2UserInputQuestion>;
}
export interface AcpAdapterV2ExtensionContext {
readonly runtime: AcpSessionRuntime.AcpSessionRuntime["Service"];
readonly reportProviderRetry: (input: {
readonly sessionId: string;
readonly failure: OrchestrationV2ProviderFailure;
}) => Effect.Effect<void>;
readonly finishSubagent: (notice: {
readonly sessionId: string;
readonly childSessionId: string;
readonly status: "completed" | "failed" | "cancelled";
readonly result: string | null;
}) => Effect.Effect<void>;
readonly applyBackgroundTaskMutation: (mutation: {
readonly sessionId: string;
readonly taskId: string;
readonly status: "running" | "completed" | "failed";
readonly output?: string;
readonly report?: BackgroundWork;
}) => Effect.Effect<void>;
readonly requestUserInput: (
input: AcpAdapterV2UserInputRequest,
requestContext: EffectAcpProtocol.AcpRequestContext,
) => Effect.Effect<
{
readonly acknowledgeNativeResponse: Effect.Effect<void, EffectAcpErrors.AcpError>;
readonly answers: ProviderUserInputAnswers | null;
},
EffectAcpErrors.AcpError
>;
readonly captureProposedPlan: (input: { readonly planMarkdown: string }) => Effect.Effect<void>;
readonly lastProposedPlanMarkdown: Effect.Effect<string | undefined>;
}
/**
* 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>()(
"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 }),
};
}
export interface AcpAdapterV2Flavor {
readonly buildPrompt?: (input: {
readonly text: string;
readonly attachments: ReadonlyArray<ChatAttachment>;
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<ReadonlyArray<EffectAcpSchema.ContentBlock>, 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.
*/
readonly watchPromptOutcome?: (
sessionId: string,
) => Effect.Effect<
(
result: EffectAcpSchema.PromptResponse,
) => Effect.Effect<OrchestrationV2ProviderFailure | undefined>
>;
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<string, never, ChildProcessSpawner.ChildProcessSpawner>;
readonly driver: ProviderDriverKind;
readonly capabilities: OrchestrationV2ProviderCapabilities;
readonly clientCapabilitiesMeta?: NonNullable<
EffectAcpSchema.InitializeRequest["clientCapabilities"]
>["_meta"];
readonly mcpOverHttp?: 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<EffectAcpSchema.AvailableCommand>,
) => Effect.Effect<void>;
readonly onSessionConfigurationUpdate?: (
configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption>,
modeState: AcpSessionModeState | undefined,
modelState: EffectAcpSchema.SessionModelState | null | undefined,
) => Effect.Effect<void>;
readonly onUrlElicitation?: (input: {
readonly elicitationId: string;
readonly url: string;
readonly message: string;
}) => Effect.Effect<boolean>;
readonly extractElicitationForm?: (request: EffectAcpSchema.CreateElicitationRequest) =>
| {
readonly questions: ReadonlyArray<OrchestrationV2UserInputQuestion>;
readonly respond: (
answers: ProviderUserInputAnswers,
) => EffectAcpSchema.CreateElicitationResponse;
}
| undefined;
readonly withRuntimeStartup?: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
readonly makeRuntime: (
input: AcpAdapterV2RuntimeInput,
) => Effect.Effect<
AcpSessionRuntime.AcpSessionRuntime["Service"],
EffectAcpErrors.AcpError,
ChildProcessSpawner.ChildProcessSpawner | SecureRandom.SecureRandom | Scope.Scope
>;
readonly customModels?: ReadonlyArray<string>;
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<string | undefined, EffectAcpErrors.AcpError>;
/**
* 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<string>;
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<EffectAcpSchema.ReadTextFileResponse, EffectAcpErrors.AcpError>;
readonly writeTextFile?: (
request: EffectAcpSchema.WriteTextFileRequest,
cwd: string | null,
) => Effect.Effect<EffectAcpSchema.WriteTextFileResponse, EffectAcpErrors.AcpError>;
};
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<ProviderApprovalOption>;
readonly onSessionEvent?: (
event: AcpSessionRuntime.AcpSessionRuntimeEvent,
) => Effect.Effect<void>;
readonly subagentsIdleOnTurnCompletion?: boolean;
readonly supportsCompaction?: 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.
*/
readonly steering?: {
readonly send: (
runtime: AcpSessionRuntime.AcpSessionRuntime["Service"],
sessionId: string,
text: string,
) => Effect.Effect<string, EffectAcpErrors.AcpError>;
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<EffectAcpSchema.ForkSessionRequest["_meta"]>;
};
/** Compacts with the agent's own request, for agents that answer a `/compact` prompt as chat. */
readonly compactSession?: (
runtime: AcpSessionRuntime.AcpSessionRuntime["Service"],
sessionId: string,
) => Effect.Effect<void, EffectAcpErrors.AcpError>;
readonly runtimeHarness?: string;
readonly registerExtensions?: (
context: AcpAdapterV2ExtensionContext,
) => Effect.Effect<void, EffectAcpErrors.AcpError>;
readonly extractSubagentSessionEvent?: (
notification: EffectAcpSchema.SessionNotification,
) => AcpSubagentSessionEvent | undefined;
readonly extractSubagentUpdate?: (
toolCall: AcpToolCallState,
) => AcpAdapterV2SubagentUpdate | undefined;
readonly isProvisionalSubagentTool?: (toolCall: AcpToolCallState) => boolean;
readonly normalizeToolCall?: (toolCall: AcpToolCallState) => AcpToolCallState;
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;
readonly isProviderWakeNotification?: (
notification: EffectAcpSchema.SessionNotification,
) => boolean;
readonly deferFinalizeForBackgroundWork?: boolean;
readonly assertComplete?: Effect.Effect<void, EffectAcpErrors.AcpError>;
/** 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?: 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;
}
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<void>;
};
readonly testHooks?: {
readonly onDeferredFinalizeScheduled?: (debounce: Duration.Input) => Effect.Effect<void>;
/** `cancelAfterPromptStarts`: Stop is holding `session/cancel` until the prompt starts. */
readonly onCancelHeld?: () => Effect.Effect<void>;
readonly afterPromptWireSettled?: () => Effect.Effect<void>;
readonly afterPromptSettledWithBackgroundWork?: () => Effect.Effect<void>;
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<void>;
};
}
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 restores T3 checkpoints and starts a fresh agent session.
providerCanRollbackConversation: true,
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<AcpAdapterV2Flavor, "forkFromTurn">;
readonly canForkFromTurn: boolean;
readonly forkInput: ProviderAdapter.ProviderAdapterV2ForkThreadInput;
}): NonNullable<EffectAcpSchema.ForkSessionRequest["_meta"]> | 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;
}
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<EffectAcpSchema.McpServer>;
readonly acpServers: ReadonlyArray<EffectAcpSchema.McpServer>;
readonly httpServers: ReadonlyArray<EffectAcpSchema.McpServer>;
readonly processEnvironment?: NodeJS.ProcessEnv;
readonly endpoint?: string;
readonly authorization?: string;
}
function acpMcpContext(
session: McpProviderSession.McpProviderSessionConfig | undefined,
self: SelfInvocation,
mcpOverHttp: 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 }],
},
]
: [],
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<string, ProviderAdapter.ProviderAdapterProtocolError> {
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,
};
}
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 pathFromToolCall(toolCall: AcpToolCallState): string | 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.trim();
}
}
}
const rawInput = unknownRecord(toolCall.data.rawInput);
for (const key of ["path", "filePath", "file_path", "url", "query", "pattern"]) {
const candidate = rawInput?.[key];
if (typeof candidate === "string" && candidate.trim().length > 0) {
return candidate.trim();
}
}
return undefined;
}
function acpBackendWebSearch(
rawInput: Record<string, unknown> | undefined,
rawOutput: Record<string, unknown> | undefined,
):
| { readonly query: string | undefined; readonly results: OrchestrationV2WebSearchResult[] }
| undefined {
const variant = typeof rawInput?.variant === "string" ? rawInput.variant.toLowerCase() : "";
const action = unknownRecord(rawOutput?.action);
if (variant !== "xsearch" && variant !== "websearch" && action?.type !== "search") {
return undefined;
}
let args: Record<string, unknown> | undefined;
if (typeof rawOutput?.input === "string") {
try {
args = unknownRecord(JSON.parse(rawOutput.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, argsText]
.find((value): value is string => typeof value === "string" && value.trim().length > 0)
?.trim();
const urls = new Set<string>();
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());
}
return { query, results: [...urls].map((url) => ({ url })) };
}
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<typeof toolStatus> | "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<ActiveAcpTurn, "interrupted">,
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<ProviderApprovalDecision, "cancel">,
): string | undefined {
const optionIdOfKind = (kind: EffectAcpSchema.PermissionOption["kind"]) =>
request.options.find((option) => option.kind === kind)?.optionId.trim() || undefined;
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")
);
}
function elicitationContent(
answers: ProviderUserInputAnswers,
allowedKeys: ReadonlySet<string>,
): Record<string, EffectAcpSchema.ElicitationContentValue> {
const content: Record<string, EffectAcpSchema.ElicitationContentValue> = {};
for (const [key, value] of Object.entries(answers)) {
if (!allowedKeys.has(key)) continue;
if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
content[key] = value;
} else if (Array.isArray(value)) {
content[key] = value.filter((entry): entry is string => typeof entry === "string");
}
}
return content;
}
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;
}
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<void, never>;
readonly itemOrdinals: Map<string, number>;
readonly outgoingPrompt?: ReadonlyArray<EffectAcpSchema.ContentBlock> | 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<string, AcpToolCallState & { readonly backgroundCommandTaskId?: string }>;
readonly toolUpdatesSkipped: Map<string, number>;
readonly toolStartedAt: Map<string, DateTime.Utc>;
readonly subagents: Map<string, ActiveAcpSubagent>;
readonly subagentsBySessionId: Map<string, ActiveAcpSubagent>;
readonly pendingSubagentNotifications: Map<string, Array<EffectAcpSchema.SessionNotification>>;
readonly toolCallIdsByBackgroundTaskId: Map<string, string>;
/** 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<string>;
/** Monitor end notices lack output; wait for hydration or the safety timeout. */
readonly awaitingBackgroundHydration: Set<string>;
readonly pendingInjectedReport: Set<string>;
/** 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;
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<void, never>;
/** Completed once `session/prompt` is the runtime's active prompt. */
readonly promptDispatched: Deferred.Deferred<void, never>;
/** 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<void, never>;
promptUsage: EffectAcpSchema.Usage | undefined;
backgroundFinalizeGeneration: number;
/** 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<void> | undefined;
}
type AcpRuntimeTeardownState =
| { readonly _tag: "Idle" }
| {
readonly _tag: "InProgress";
readonly completed: Deferred.Deferred<void, ProviderAdapter.ProviderAdapterProtocolError>;
}
| { 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;
}
}
export function acpPostSettleWakeEvidence(
notification: EffectAcpSchema.SessionNotification,
flavor: Pick<AcpAdapterV2Flavor, "extractBackgroundToolMutation"> = {},
): 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 (/<monitor-event\b/i.test(text) || /Monitor\s+["']?[0-9a-f-]{8,}["']?\s+ended/i.test(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<AcpAdapterV2Flavor, "extractBackgroundToolMutation" | "normalizeToolCall"> = {},
): 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,
flavor: Pick<AcpAdapterV2Flavor, "extractBackgroundTaskId" | "extractSubagentUpdate">,
): boolean {
const status = toolStatus(tool.status);
if (status !== "pending" && status !== "running") 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<string, string>;
readonly childItemOrdinals: Map<string, number>;
nextChildOrdinal: number;
terminalStatusProjected: boolean;
readonly toolState: Pick<ActiveAcpTurn, "tools" | "toolUpdatesSkipped" | "toolStartedAt">;
readonly toolSessionIds: Map<string, string>;
}
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<EffectAcpSchema.SessionNotification>;
}
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<ActiveAcpSubagent>;
};
type PendingRuntimeRequest = {
readonly generation: number;
readonly nativeResponseAcknowledgement: Deferred.Deferred<void, EffectAcpErrors.AcpError>;
readonly transportRequestId: string;
readonly requestId: RuntimeRequestId;
readonly runtimeRequest: OrchestrationV2RuntimeRequest;
readonly node: OrchestrationV2ExecutionNode;
readonly turnItem: OrchestrationV2TurnItem;
} & (
| {
readonly type: "approval";
readonly decision: Deferred.Deferred<ProviderApprovalDecision>;
}
| {
readonly type: "user_input";
readonly answers: Deferred.Deferred<ProviderUserInputAnswers | null>;
}
);
interface SnapshotMessageState {
readonly order: Array<string>;
readonly messages: Map<string, OrchestrationV2ConversationMessage>;
loadingRole: "user" | "assistant" | "thought" | null;
loadingMessageId: string | null;
loadingIndex: number;
}
/** 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<ActiveAcpTurn, "toolUpdatesSkipped">,
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))
: mcpSessions
.read(threadId)
.pipe(Effect.map((session) => acpMcpContext(session, self, flavor.mcpOverHttp)));
const driver = flavor.driver;
const continuationRequests = options.continuationRequests;
const postSettleContinuationEnabled =
flavor.enablePostSettleContinuation === true && continuationRequests !== undefined;
return ProviderAdapter.ProviderAdapterV2.of({
instanceId: options.instanceId,
driver,
getCapabilities: Effect.fn("AcpAdapter.getCapabilities")(function () {
return Effect.succeed(flavor.capabilities);
}),
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,
});