From 34f7d78449da573f3fc2c8d361d77372e0c0c4e7 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 09:02:44 -0400 Subject: [PATCH] docs: document cli agent helpers --- src/agents/cli-auth-epoch.ts | 8 ++++++++ src/agents/cli-backends.ts | 13 +++++++++++++ src/agents/cli-credentials.ts | 17 +++++++++++++++++ src/agents/cli-output.ts | 5 +++++ 4 files changed, 43 insertions(+) diff --git a/src/agents/cli-auth-epoch.ts b/src/agents/cli-auth-epoch.ts index 4967071ca6c..871e2be9e96 100644 --- a/src/agents/cli-auth-epoch.ts +++ b/src/agents/cli-auth-epoch.ts @@ -1,3 +1,7 @@ +/** + * Builds auth-state epochs for CLI-backed runtimes so reusable sessions reset + * when the owning local credential identity changes. + */ import crypto from "node:crypto"; import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce"; import { loadAuthProfileStoreForRuntime } from "./auth-profiles/store.js"; @@ -27,12 +31,15 @@ const defaultCliAuthEpochDeps: CliAuthEpochDeps = { const cliAuthEpochDeps: CliAuthEpochDeps = { ...defaultCliAuthEpochDeps }; +/** Version salt for CLI auth epoch encoding semantics. */ export const CLI_AUTH_EPOCH_VERSION = 5; +/** Overrides credential readers for auth-epoch unit tests. */ export function setCliAuthEpochTestDeps(overrides: Partial): void { Object.assign(cliAuthEpochDeps, overrides); } +/** Restores default credential readers after auth-epoch unit tests. */ export function resetCliAuthEpochTestDeps(): void { Object.assign(cliAuthEpochDeps, defaultCliAuthEpochDeps); } @@ -198,6 +205,7 @@ function getAuthProfileCredential( return store.profiles[authProfileId]; } +/** Resolves the stable auth epoch hash for a CLI runtime/provider session. */ export async function resolveCliAuthEpoch(params: { provider: string; authProfileId?: string; diff --git a/src/agents/cli-backends.ts b/src/agents/cli-backends.ts index a59aed5bdf8..0c727ddc9ff 100644 --- a/src/agents/cli-backends.ts +++ b/src/agents/cli-backends.ts @@ -1,3 +1,6 @@ +/** + * Resolves CLI runtime backends registered by plugins or setup metadata. + */ import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id"; import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce"; import { uniqueStrings } from "@openclaw/normalization-core/string-normalization"; @@ -34,6 +37,7 @@ const defaultCliBackendsDeps: CliBackendsDeps = { let cliBackendsDeps: CliBackendsDeps = defaultCliBackendsDeps; +/** Fully merged CLI backend definition used by agent runner execution. */ export type ResolvedCliBackend = { id: string; modelProvider?: string; @@ -60,6 +64,7 @@ type ResolvedCliBackendLiveTest = { dockerBinaryName?: string; }; +/** Binding between a model provider and the CLI runtime that serves it. */ export type CliRuntimeModelBackendBinding = { provider: string; runtime: string; @@ -184,6 +189,7 @@ function addCliRuntimeModelBinding( }); } +/** Lists model-provider to CLI-runtime bindings from runtime and optional setup registries. */ export function listCliRuntimeModelBackendBindings( params: { config?: OpenClawConfig; @@ -216,6 +222,7 @@ export function listCliRuntimeModelBackendBindings( ); } +/** Lists CLI runtime ids that alias canonical model providers. */ export function listCliRuntimeProviderIds( params: { config?: OpenClawConfig; @@ -235,6 +242,7 @@ export function listCliRuntimeProviderIds( ].toSorted(); } +/** Resolves the canonical model provider served by a CLI runtime id. */ export function resolveCliRuntimeCanonicalProvider(params: { runtime: string | undefined; config?: OpenClawConfig; @@ -262,6 +270,7 @@ export function resolveCliRuntimeCanonicalProvider(params: { return setupBackend ? resolveCliBackendModelProvider(setupBackend.backend) : undefined; } +/** Resolves the binding for one provider/runtime pair when registered. */ export function resolveCliRuntimeModelBackendBinding(params: { provider: string | undefined; runtime: string | undefined; @@ -301,6 +310,7 @@ export function resolveCliRuntimeModelBackendBinding(params: { : undefined; } +/** Checks whether a runtime is registered to serve a model provider. */ export function isCliRuntimeModelBackendForProvider(params: { provider: string | undefined; runtime: string | undefined; @@ -353,6 +363,7 @@ function mergeBackendConfig(base: CliBackendConfig, override?: CliBackendConfig) }; } +/** Resolves live-test defaults advertised by a CLI backend plugin. */ export function resolveCliBackendLiveTest(provider: string): ResolvedCliBackendLiveTest | null { const normalized = normalizeBackendKey(provider); const entry = @@ -373,6 +384,7 @@ export function resolveCliBackendLiveTest(provider: string): ResolvedCliBackendL }; } +/** Resolves the executable CLI backend config after plugin defaults and user overrides. */ export function resolveCliBackendConfig( provider: string, cfg?: OpenClawConfig, @@ -484,6 +496,7 @@ export function resolveCliBackendConfig( }; } +/** Test-only dependency controls for CLI backend registry resolution. */ export const testing = { resetDepsForTest(): void { cliBackendsDeps = defaultCliBackendsDeps; diff --git a/src/agents/cli-credentials.ts b/src/agents/cli-credentials.ts index 06c649ec50d..59cc5154c48 100644 --- a/src/agents/cli-credentials.ts +++ b/src/agents/cli-credentials.ts @@ -1,3 +1,7 @@ +/** + * Reads and refreshes credentials stored by external CLI runtimes such as + * Claude Code, Codex, Gemini, and MiniMax. + */ import { execFileSync, execSync } from "node:child_process"; import { createHash } from "node:crypto"; import fs from "node:fs"; @@ -36,6 +40,7 @@ let codexCliCache: CachedValue | null = null; let minimaxCliCache: CachedValue | null = null; let geminiCliCache: CachedValue | null = null; +/** Clears in-memory CLI credential caches for isolated tests. */ export function resetCliCredentialCachesForTest(): void { claudeCliCache = null; codexCliCache = null; @@ -43,6 +48,7 @@ export function resetCliCredentialCachesForTest(): void { geminiCliCache = null; } +/** Credential shape parsed from Claude Code CLI storage. */ export type ClaudeCliCredential = | { type: "oauth"; @@ -58,6 +64,7 @@ export type ClaudeCliCredential = expires: number; }; +/** Credential shape parsed from Codex CLI storage. */ export type CodexCliCredential = { type: "oauth"; provider: OAuthProvider; @@ -68,6 +75,7 @@ export type CodexCliCredential = { idToken?: string; }; +/** Credential shape parsed from MiniMax portal CLI storage. */ export type MiniMaxCliCredential = { type: "oauth"; provider: "minimax-portal"; @@ -76,6 +84,7 @@ export type MiniMaxCliCredential = { expires: number; }; +/** Credential shape parsed from Gemini CLI storage. */ export type GeminiCliCredential = { type: "oauth"; provider: "google-gemini-cli"; @@ -437,6 +446,7 @@ function readClaudeCliKeychainCredentials( } } +/** Reads Claude CLI credentials from macOS Keychain or the CLI credential file. */ export function readClaudeCliCredentials(options?: { allowKeychainPrompt?: boolean; platform?: NodeJS.Platform; @@ -494,6 +504,7 @@ export function readClaudeCliCredentialsCached(options?: { }); } +/** Writes refreshed Claude OAuth tokens back to the Claude CLI macOS Keychain item. */ export function writeClaudeCliKeychainCredentials( newCredentials: OAuthCredentials, options?: { execFileSync?: ExecFileSyncFn }, @@ -550,6 +561,7 @@ export function writeClaudeCliKeychainCredentials( } } +/** Writes refreshed Claude OAuth tokens back to the Claude CLI credential file. */ export function writeClaudeCliFileCredentials( newCredentials: OAuthCredentials, options?: ClaudeCliFileOptions, @@ -592,6 +604,7 @@ export function writeClaudeCliFileCredentials( } } +/** Writes refreshed Claude OAuth tokens to the preferred Claude CLI credential store. */ export function writeClaudeCliCredentials( newCredentials: OAuthCredentials, options?: ClaudeCliWriteOptions, @@ -612,6 +625,7 @@ export function writeClaudeCliCredentials( return writeFile(newCredentials, { homeDir: options?.homeDir }); } +/** Reads Codex CLI OAuth credentials from Keychain or CODEX_HOME auth.json. */ export function readCodexCliCredentials(options?: { codexHome?: string; allowKeychainPrompt?: boolean; @@ -673,6 +687,7 @@ export function readCodexCliCredentials(options?: { }; } +/** Reads Codex CLI credentials with optional short-lived cache and file fingerprinting. */ export function readCodexCliCredentialsCached(options?: { codexHome?: string; allowKeychainPrompt?: boolean; @@ -703,6 +718,7 @@ export function readCodexCliCredentialsCached(options?: { }); } +/** Reads MiniMax CLI credentials with optional short-lived cache. */ export function readMiniMaxCliCredentialsCached(options?: { ttlMs?: number; homeDir?: string; @@ -720,6 +736,7 @@ export function readMiniMaxCliCredentialsCached(options?: { }); } +/** Reads Gemini CLI credentials with optional short-lived cache. */ export function readGeminiCliCredentialsCached(options?: { ttlMs?: number; homeDir?: string; diff --git a/src/agents/cli-output.ts b/src/agents/cli-output.ts index e457fbeec64..a7f7e962981 100644 --- a/src/agents/cli-output.ts +++ b/src/agents/cli-output.ts @@ -316,6 +316,7 @@ function shouldUnwrapNestedCliResultText(params: { } /** Parses JSON CLI output, including mixed stdout that contains embedded JSON objects. */ +/** Parses a single JSON payload emitted by a CLI backend. */ export function parseCliJson( raw: string, backend: CliBackendConfig, @@ -624,6 +625,7 @@ function dispatchClaudeCliStreamingToolEvent(params: { } /** Creates an incremental JSONL parser for CLI streaming responses and tool events. */ +/** Creates a stateful parser for streaming JSONL CLI backend output. */ export function createCliJsonlStreamingParser(params: { backend: CliBackendConfig; providerId: string; @@ -751,6 +753,7 @@ export function createCliJsonlStreamingParser(params: { } /** Parses complete JSONL CLI output into the final assistant result and metadata. */ +/** Parses complete JSONL output from a CLI backend into normalized text and metadata. */ export function parseCliJsonl( raw: string, backend: CliBackendConfig, @@ -803,6 +806,7 @@ export function parseCliJsonl( } /** Parses CLI output according to the backend output mode with text fallback. */ +/** Parses CLI backend output using the configured JSON/JSONL/plain-text mode. */ export function parseCliOutput(params: { raw: string; backend: CliBackendConfig; @@ -831,6 +835,7 @@ export function parseCliOutput(params: { } /** Extracts the most specific structured CLI error message from mixed or JSON output. */ +/** Extracts a human-readable error message from mixed CLI stderr/stdout text. */ export function extractCliErrorMessage(raw: string): string | null { const parsedRecords = parseJsonRecordCandidates(raw); if (parsedRecords.length === 0) {