Skip to content

Commit 05289f1

Browse files
steipetesteipete
committed
docs: document acp turn control plane
1 parent d88b06c commit 05289f1

16 files changed

Lines changed: 36 additions & 0 deletions

‎src/acp/control-plane/manager.status.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Reads ACP session status from the runtime and reconciles persisted identity metadata. */
12
import { resolveSessionIdentityFromMeta } from "@openclaw/acp-core/runtime/session-identity";
23
import type {
34
AcpRuntime,

‎src/acp/control-plane/manager.test-helpers.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Shared ACP manager test harness, mocks, fixtures, and assertion helpers. */
12
import type { AcpRuntime, AcpRuntimeCapabilities } from "@openclaw/acp-core/runtime/types";
23
import { afterEach, beforeEach, expect, vi } from "vitest";
34
import { resetAcpManagerTaskStateForTests } from "../../../test/helpers/acp-manager-task-state.js";

‎src/acp/control-plane/manager.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Tests ACP session manager resolution, turn execution, state transitions, and cleanup. */
12
import { setTimeout as scheduleNativeTimeout } from "node:timers";
23
import { setTimeout as sleep } from "node:timers/promises";
34
import { MAX_TIMER_TIMEOUT_MS } from "@openclaw/normalization-core/number-coercion";

‎src/acp/control-plane/manager.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Public singleton facade for the ACP session manager control plane. */
12
import { AcpSessionManager } from "./manager.core.js";
23

34
export { AcpSessionManager } from "./manager.core.js";

‎src/acp/control-plane/manager.turn-results.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Tests ACP turn terminal results and detached-task progress outcomes. */
12
import { describe, expect, it, vi } from "vitest";
23
import {
34
requireTaskByRunId,

‎src/acp/control-plane/manager.turn-runner.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Runs ACP turns, failover, timeout cleanup, and detached-task progress mirroring. */
12
import type { AcpRuntime, AcpRuntimeHandle } from "@openclaw/acp-core/runtime/types";
23
import { logVerbose } from "../../globals.js";
34
import { AcpRuntimeError, formatAcpErrorChain, toAcpRuntimeError } from "../runtime/errors.js";
@@ -47,6 +48,7 @@ type ApplyRuntimeControls = (params: {
4748
meta: SessionAcpMeta;
4849
}) => Promise<void>;
4950

51+
/** Executes one ACP prompt turn against the selected backend and records terminal state. */
5052
export async function runManagerTurn(params: {
5153
input: AcpRunTurnInput;
5254
sessionKey: string;

‎src/acp/control-plane/manager.turn-stream.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Normalizes ACP runtime turn event/result streams into manager-facing outcomes. */
12
import type {
23
AcpRuntime,
34
AcpRuntimeEvent,
@@ -8,6 +9,7 @@ import { AcpRuntimeError } from "../runtime/errors.js";
89
import { normalizeAcpErrorCode } from "./manager.utils.js";
910
import { normalizeText } from "./runtime-options.js";
1011

12+
/** Mutable gate used to suppress late events after timeout/cancel races. */
1113
export type AcpTurnEventGate = {
1214
open: boolean;
1315
};
@@ -104,6 +106,7 @@ async function notifyTerminalResult(params: {
104106
});
105107
}
106108

109+
/** Consumes runtime turn APIs and emits normalized events while tracking output/terminal state. */
107110
export async function consumeAcpTurnStream(params: {
108111
runtime: AcpRuntime;
109112
turn: AcpRuntimeTurnInput;

‎src/acp/control-plane/manager.turn-timeout.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Timeout and cleanup helpers for long-running ACP turns. */
12
import type { AcpRuntimeSessionMode } from "@openclaw/acp-core/runtime/types";
23
import { clampTimerTimeoutMs } from "@openclaw/normalization-core/number-coercion";
34
import { resolveAgentTimeoutMs } from "../../agents/timeout.js";
@@ -29,6 +30,7 @@ export function resolveTurnTimeoutMs(params: {
2930
});
3031
}
3132

33+
/** Awaits a turn promise with bounded timeout handling and late-error logging. */
3234
export async function awaitTurnWithTimeout<T>(params: {
3335
sessionKey: string;
3436
turnPromise: Promise<T>;
@@ -107,6 +109,7 @@ export async function awaitTurnWithTimeout<T>(params: {
107109
}
108110
}
109111

112+
/** Cancels a timed-out turn and clears non-persistent cached runtime state. */
110113
export async function cleanupTimedOutTurn(params: {
111114
sessionKey: string;
112115
activeTurn: ActiveTurnState;

‎src/acp/control-plane/manager.types.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Shared types and dependency wiring for the ACP session manager control plane. */
12
import type {
23
AcpRuntime,
34
AcpRuntimeCapabilities,
@@ -39,6 +40,7 @@ export type AcpSessionResolution =
3940
meta: SessionAcpMeta;
4041
};
4142

43+
/** Input required to create or resume an ACP runtime session. */
4244
export type AcpInitializeSessionInput = {
4345
cfg: OpenClawConfig;
4446
sessionKey: string;
@@ -55,6 +57,7 @@ export type AcpTurnAttachment = {
5557
data: string;
5658
};
5759

60+
/** Input for one ACP prompt turn routed through the manager. */
5861
export type AcpRunTurnInput = {
5962
cfg: OpenClawConfig;
6063
sessionKey: string;
@@ -72,6 +75,7 @@ export type AcpTurnLifecycleEvent = {
7275
at: number;
7376
};
7477

78+
/** Input for closing, resetting, or cleaning up an ACP session. */
7579
export type AcpCloseSessionInput = {
7680
cfg: OpenClawConfig;
7781
sessionKey: string;
@@ -88,6 +92,7 @@ export type AcpCloseSessionResult = {
8892
metaCleared: boolean;
8993
};
9094

95+
/** User-facing session status assembled from persisted metadata and runtime status. */
9196
export type AcpSessionStatus = {
9297
sessionKey: string;
9398
backend: string;
@@ -102,6 +107,7 @@ export type AcpSessionStatus = {
102107
lastError?: string;
103108
};
104109

110+
/** Process-local ACP manager counters exposed for diagnostics. */
105111
export type AcpManagerObservabilitySnapshot = {
106112
runtimeCache: {
107113
activeSessions: number;

‎src/acp/control-plane/manager.utils.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Shared ACP manager normalization, resolution, and error helpers. */
12
import { ACP_ERROR_CODES, AcpRuntimeError } from "@openclaw/acp-core/runtime/errors";
23
import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
34
import {
@@ -19,13 +20,15 @@ export function resolveAcpAgentFromSessionKey(sessionKey: string, fallback = "ma
1920
return normalizeAgentId(parsed?.agentId ?? fallback);
2021
}
2122

23+
/** Builds the stale-session error shown when ACP metadata is missing. */
2224
export function resolveMissingMetaError(sessionKey: string): AcpRuntimeError {
2325
return new AcpRuntimeError(
2426
"ACP_SESSION_INIT_FAILED",
2527
`ACP metadata is missing for ${sessionKey}. Recreate this ACP session with /acp spawn and rebind the thread.`,
2628
);
2729
}
2830

31+
/** Converts a session resolution union into the runtime error callers should throw. */
2932
export function resolveAcpSessionResolutionError(
3033
resolution: AcpSessionResolution,
3134
): AcpRuntimeError | null {
@@ -41,6 +44,7 @@ export function resolveAcpSessionResolutionError(
4144
);
4245
}
4346

47+
/** Returns ready ACP metadata or throws the matching resolution error. */
4448
export function requireReadySessionMeta(resolution: AcpSessionResolution): SessionAcpMeta {
4549
if (resolution.kind === "ready") {
4650
return resolution.meta;
@@ -52,6 +56,7 @@ function normalizeSessionKey(sessionKey: string): string {
5256
return sessionKey.trim();
5357
}
5458

59+
/** Canonicalizes aliases and main-session keys before ACP metadata lookup. */
5560
export function canonicalizeAcpSessionKey(params: {
5661
cfg: OpenClawConfig;
5762
sessionKey: string;
@@ -79,10 +84,12 @@ export function canonicalizeAcpSessionKey(params: {
7984
return lowered;
8085
}
8186

87+
/** Normalizes session keys for process-local actor maps. */
8288
export function normalizeActorKey(sessionKey: string): string {
8389
return normalizeLowercaseStringOrEmpty(sessionKey);
8490
}
8591

92+
/** Restricts runtime-provided error codes to the ACP error-code enum. */
8693
export function normalizeAcpErrorCode(code: string | undefined): AcpRuntimeError["code"] {
8794
if (!code) {
8895
return "ACP_TURN_FAILED";

0 commit comments

Comments
 (0)