diff --git a/src/plugin-sdk/file-lock.ts b/src/plugin-sdk/file-lock.ts index 9da3081623b3..0c7de7d9d1dd 100644 --- a/src/plugin-sdk/file-lock.ts +++ b/src/plugin-sdk/file-lock.ts @@ -8,6 +8,7 @@ import { import { shouldRemoveDeadOwnerOrExpiredLock } from "../infra/stale-lock-file.js"; import { getProcessStartTime } from "../shared/pid-alive.js"; +/** Retry and stale-recovery policy for acquiring a filesystem lock. */ export type FileLockOptions = { /** Retry policy used while waiting for another process or re-entrant holder to release. */ retries: { @@ -21,6 +22,7 @@ export type FileLockOptions = { stale: number; }; +/** Live file-lock handle returned after successful acquisition. */ export type FileLockHandle = { /** Absolute path to the `.lock` sidecar held for this file path. */ lockPath: string; @@ -28,9 +30,12 @@ export type FileLockHandle = { release: () => Promise; }; +/** Stable error code used when lock acquisition retries are exhausted. */ export const FILE_LOCK_TIMEOUT_ERROR_CODE = "file_lock_timeout"; +/** Stable error code used when stale lock recovery cannot proceed safely. */ export const FILE_LOCK_STALE_ERROR_CODE = "file_lock_stale"; +/** Typed error thrown when a lock cannot be acquired before timeout. */ export type FileLockTimeoutError = Error & { /** Stable error discriminator for lock acquisition timeout handling. */ code: typeof FILE_LOCK_TIMEOUT_ERROR_CODE; @@ -38,6 +43,7 @@ export type FileLockTimeoutError = Error & { lockPath: string; }; +/** Typed error thrown when a stale lock sidecar cannot be reclaimed safely. */ export type FileLockStaleError = Error & { /** Stable error discriminator for stale-lock reclaim failures. */ code: typeof FILE_LOCK_STALE_ERROR_CODE; @@ -76,10 +82,12 @@ function normalizeLockError(err: unknown): never { throw err; } +/** Reset process-local file-lock state for tests that isolate lock managers. */ export function resetFileLockStateForTest(): void { resetFileLockManagerForTest(FILE_LOCK_MANAGER_KEY, FILE_LOCK_MANAGER_KEY); } +/** Wait for process-local file-lock state to drain before test teardown. */ export async function drainFileLockStateForTest(): Promise { await drainFileLockManagerForTest(FILE_LOCK_MANAGER_KEY, FILE_LOCK_MANAGER_KEY); } diff --git a/src/plugin-sdk/gateway-method-runtime.ts b/src/plugin-sdk/gateway-method-runtime.ts index 10983f688bba..cec68043ac65 100644 --- a/src/plugin-sdk/gateway-method-runtime.ts +++ b/src/plugin-sdk/gateway-method-runtime.ts @@ -2,6 +2,7 @@ import { dispatchGatewayMethodInProcessRaw } from "../gateway/server-plugins.js"; import { getPluginRuntimeGatewayRequestScope } from "../plugins/runtime/gateway-request-scope.js"; +/** Error envelope returned by in-process Gateway method dispatch. */ export type GatewayMethodDispatchError = { /** Stable machine-readable error code returned by the Gateway method. */ code: string; @@ -15,6 +16,7 @@ export type GatewayMethodDispatchError = { retryAfterMs?: number; }; +/** Response envelope returned to plugins after dispatching a Gateway method. */ export type GatewayMethodDispatchResponse = { /** True when the Gateway method completed and `payload` contains its result. */ ok: boolean; @@ -26,6 +28,7 @@ export type GatewayMethodDispatchResponse = { meta?: Record; }; +/** Dispatch controls for plugin-initiated Gateway method calls. */ export type GatewayMethodDispatchOptions = { /** Wait for the Gateway's final response instead of returning the first response frame. */ expectFinal?: boolean; diff --git a/src/plugin-sdk/provider-selection-runtime.ts b/src/plugin-sdk/provider-selection-runtime.ts index 49211ad0a169..4cbe68cf4694 100644 --- a/src/plugin-sdk/provider-selection-runtime.ts +++ b/src/plugin-sdk/provider-selection-runtime.ts @@ -1,6 +1,7 @@ // Provider selection runtime helpers resolve plugin/provider choices from config and CLI input. import { normalizeOptionalString } from "../../packages/normalization-core/src/string-coerce.js"; +/** Provider descriptor fields needed for explicit or automatic selection. */ export type AutoSelectableProvider = { /** Provider id used for explicit config lookup and selected result metadata. */ id: string; @@ -8,6 +9,7 @@ export type AutoSelectableProvider = { autoSelectOrder?: number; }; +/** Provider selection result before capability-specific configuration checks run. */ export type ProviderSelection = { /** Normalized explicit provider id, when the caller supplied one. */ configuredProviderId?: string; @@ -17,6 +19,7 @@ export type ProviderSelection = { provider: TProvider | undefined; }; +/** Final provider resolution result including capability-specific config. */ export type ResolvedConfiguredProvider = | { /** Provider exists and passed the capability-specific configuration check. */ @@ -39,6 +42,7 @@ export type ResolvedConfiguredProvider = provider?: TProvider; }; +/** Select an explicit provider when configured, otherwise the lowest-order auto provider. */ export function selectConfiguredOrAutoProvider(params: { /** Optional explicit provider id from config or user input. */ configuredProviderId?: string; @@ -67,6 +71,7 @@ export function selectConfiguredOrAutoProvider StreamFn | undefined) | null | undefined | false; +/** Compose stream wrapper factories from left to right around a base stream function. */ export function composeProviderStreamWrappers( /** Base provider stream function to pass through the wrapper chain. */ baseStreamFn: StreamFn | undefined, @@ -235,6 +237,7 @@ export function defaultToolStreamExtraParams( }; } +/** Wrap a provider stream so callers can patch the outbound provider payload once. */ export function createPayloadPatchStreamWrapper( /** Provider stream function whose outbound payload should be patched. */ baseStreamFn: StreamFn | undefined, diff --git a/src/plugin-sdk/qa-channel-protocol.ts b/src/plugin-sdk/qa-channel-protocol.ts index a52d28900d0c..e7cb90fccaf7 100644 --- a/src/plugin-sdk/qa-channel-protocol.ts +++ b/src/plugin-sdk/qa-channel-protocol.ts @@ -1,14 +1,17 @@ // QA channel protocol helpers validate synthetic channel messages used by QA plugins. import { isRecord } from "../../packages/normalization-core/src/record-coerce.js"; +/** Conversation shape supported by the synthetic QA channel bus. */ export type QaBusConversationKind = "direct" | "channel" | "group"; +/** Addressable conversation used by QA bus messages and thread state. */ export type QaBusConversation = { id: string; kind: QaBusConversationKind; title?: string; }; +/** Media/file attachment fixture accepted by QA bus message APIs. */ export type QaBusAttachment = { id: string; kind: "image" | "video" | "audio" | "file"; @@ -24,11 +27,13 @@ export type QaBusAttachment = { transcript?: string; }; +/** Tool-call fixture attached to QA messages for agent-runtime tests. */ export type QaBusToolCall = { name: string; arguments?: Record; }; +/** Stored QA bus message after defaults, reactions, and account ids are normalized. */ export type QaBusMessage = { id: string; accountId: string; @@ -52,6 +57,7 @@ export type QaBusMessage = { }>; }; +/** Synthetic thread record created inside a QA bus conversation. */ export type QaBusThread = { id: string; accountId: string; @@ -61,6 +67,7 @@ export type QaBusThread = { createdBy: string; }; +/** Ordered event emitted by QA bus polling and state snapshots. */ export type QaBusEvent = | { cursor: number; kind: "inbound-message"; accountId: string; message: QaBusMessage } | { cursor: number; kind: "outbound-message"; accountId: string; message: QaBusMessage } @@ -76,6 +83,7 @@ export type QaBusEvent = senderId: string; }; +/** Input for injecting an inbound message from a synthetic user/channel. */ export type QaBusInboundMessageInput = { accountId?: string; conversation: QaBusConversation; @@ -90,6 +98,7 @@ export type QaBusInboundMessageInput = { toolCalls?: QaBusToolCall[]; }; +/** Input for recording an outbound message sent by an OpenClaw runtime. */ export type QaBusOutboundMessageInput = { accountId?: string; to: string; @@ -103,6 +112,7 @@ export type QaBusOutboundMessageInput = { toolCalls?: QaBusToolCall[]; }; +/** Input for creating a synthetic QA bus thread. */ export type QaBusCreateThreadInput = { accountId?: string; conversationId: string; @@ -111,6 +121,7 @@ export type QaBusCreateThreadInput = { timestamp?: number; }; +/** Input for adding a reaction event to an existing QA bus message. */ export type QaBusReactToMessageInput = { accountId?: string; messageId: string; @@ -119,6 +130,7 @@ export type QaBusReactToMessageInput = { timestamp?: number; }; +/** Input for editing an existing QA bus message. */ export type QaBusEditMessageInput = { accountId?: string; messageId: string; @@ -126,12 +138,14 @@ export type QaBusEditMessageInput = { timestamp?: number; }; +/** Input for marking an existing QA bus message as deleted. */ export type QaBusDeleteMessageInput = { accountId?: string; messageId: string; timestamp?: number; }; +/** Search filter accepted by QA bus message lookup helpers. */ export type QaBusSearchMessagesInput = { accountId?: string; query?: string; @@ -140,11 +154,13 @@ export type QaBusSearchMessagesInput = { limit?: number; }; +/** Lookup key for reading one QA bus message. */ export type QaBusReadMessageInput = { accountId?: string; messageId: string; }; +/** Cursor and timeout options used by QA bus polling. */ export type QaBusPollInput = { accountId?: string; cursor?: number; @@ -152,11 +168,13 @@ export type QaBusPollInput = { limit?: number; }; +/** Poll response containing the next cursor and ordered events. */ export type QaBusPollResult = { cursor: number; events: QaBusEvent[]; }; +/** Complete QA bus state snapshot exposed to tests and diagnostics. */ export type QaBusStateSnapshot = { cursor: number; conversations: QaBusConversation[]; @@ -212,6 +230,7 @@ function sanitizeQaBusToolCallValue(value: unknown, depth: number, key?: string) return undefined; } +/** Sanitize arbitrary tool-call arguments before storing them in QA bus messages. */ export function sanitizeQaBusToolCallArguments( value: unknown, ): Record | undefined { @@ -222,6 +241,7 @@ export function sanitizeQaBusToolCallArguments( return isRecord(sanitized) ? sanitized : undefined; } +/** Normalize and redact a bounded list of tool calls from untrusted QA input. */ export function sanitizeQaBusToolCalls(value: unknown): QaBusToolCall[] | undefined { if (!Array.isArray(value)) { return undefined; @@ -245,6 +265,7 @@ export function sanitizeQaBusToolCalls(value: unknown): QaBusToolCall[] | undefi return sanitized.length > 0 ? sanitized : undefined; } +/** Predicate input used by QA helpers that wait for bus events or messages. */ export type QaBusWaitForInput = | { timeoutMs?: number;