Skip to content

Commit 34f7d78

Browse files
steipetesteipete
committed
docs: document cli agent helpers
1 parent 2583737 commit 34f7d78

4 files changed

Lines changed: 43 additions & 0 deletions

File tree

‎src/agents/cli-auth-epoch.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Builds auth-state epochs for CLI-backed runtimes so reusable sessions reset
3+
* when the owning local credential identity changes.
4+
*/
15
import crypto from "node:crypto";
26
import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
37
import { loadAuthProfileStoreForRuntime } from "./auth-profiles/store.js";
@@ -27,12 +31,15 @@ const defaultCliAuthEpochDeps: CliAuthEpochDeps = {
2731

2832
const cliAuthEpochDeps: CliAuthEpochDeps = { ...defaultCliAuthEpochDeps };
2933

34+
/** Version salt for CLI auth epoch encoding semantics. */
3035
export const CLI_AUTH_EPOCH_VERSION = 5;
3136

37+
/** Overrides credential readers for auth-epoch unit tests. */
3238
export function setCliAuthEpochTestDeps(overrides: Partial<CliAuthEpochDeps>): void {
3339
Object.assign(cliAuthEpochDeps, overrides);
3440
}
3541

42+
/** Restores default credential readers after auth-epoch unit tests. */
3643
export function resetCliAuthEpochTestDeps(): void {
3744
Object.assign(cliAuthEpochDeps, defaultCliAuthEpochDeps);
3845
}
@@ -198,6 +205,7 @@ function getAuthProfileCredential(
198205
return store.profiles[authProfileId];
199206
}
200207

208+
/** Resolves the stable auth epoch hash for a CLI runtime/provider session. */
201209
export async function resolveCliAuthEpoch(params: {
202210
provider: string;
203211
authProfileId?: string;

‎src/agents/cli-backends.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
/**
2+
* Resolves CLI runtime backends registered by plugins or setup metadata.
3+
*/
14
import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
25
import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
36
import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
@@ -34,6 +37,7 @@ const defaultCliBackendsDeps: CliBackendsDeps = {
3437

3538
let cliBackendsDeps: CliBackendsDeps = defaultCliBackendsDeps;
3639

40+
/** Fully merged CLI backend definition used by agent runner execution. */
3741
export type ResolvedCliBackend = {
3842
id: string;
3943
modelProvider?: string;
@@ -60,6 +64,7 @@ type ResolvedCliBackendLiveTest = {
6064
dockerBinaryName?: string;
6165
};
6266

67+
/** Binding between a model provider and the CLI runtime that serves it. */
6368
export type CliRuntimeModelBackendBinding = {
6469
provider: string;
6570
runtime: string;
@@ -184,6 +189,7 @@ function addCliRuntimeModelBinding(
184189
});
185190
}
186191

192+
/** Lists model-provider to CLI-runtime bindings from runtime and optional setup registries. */
187193
export function listCliRuntimeModelBackendBindings(
188194
params: {
189195
config?: OpenClawConfig;
@@ -216,6 +222,7 @@ export function listCliRuntimeModelBackendBindings(
216222
);
217223
}
218224

225+
/** Lists CLI runtime ids that alias canonical model providers. */
219226
export function listCliRuntimeProviderIds(
220227
params: {
221228
config?: OpenClawConfig;
@@ -235,6 +242,7 @@ export function listCliRuntimeProviderIds(
235242
].toSorted();
236243
}
237244

245+
/** Resolves the canonical model provider served by a CLI runtime id. */
238246
export function resolveCliRuntimeCanonicalProvider(params: {
239247
runtime: string | undefined;
240248
config?: OpenClawConfig;
@@ -262,6 +270,7 @@ export function resolveCliRuntimeCanonicalProvider(params: {
262270
return setupBackend ? resolveCliBackendModelProvider(setupBackend.backend) : undefined;
263271
}
264272

273+
/** Resolves the binding for one provider/runtime pair when registered. */
265274
export function resolveCliRuntimeModelBackendBinding(params: {
266275
provider: string | undefined;
267276
runtime: string | undefined;
@@ -301,6 +310,7 @@ export function resolveCliRuntimeModelBackendBinding(params: {
301310
: undefined;
302311
}
303312

313+
/** Checks whether a runtime is registered to serve a model provider. */
304314
export function isCliRuntimeModelBackendForProvider(params: {
305315
provider: string | undefined;
306316
runtime: string | undefined;
@@ -353,6 +363,7 @@ function mergeBackendConfig(base: CliBackendConfig, override?: CliBackendConfig)
353363
};
354364
}
355365

366+
/** Resolves live-test defaults advertised by a CLI backend plugin. */
356367
export function resolveCliBackendLiveTest(provider: string): ResolvedCliBackendLiveTest | null {
357368
const normalized = normalizeBackendKey(provider);
358369
const entry =
@@ -373,6 +384,7 @@ export function resolveCliBackendLiveTest(provider: string): ResolvedCliBackendL
373384
};
374385
}
375386

387+
/** Resolves the executable CLI backend config after plugin defaults and user overrides. */
376388
export function resolveCliBackendConfig(
377389
provider: string,
378390
cfg?: OpenClawConfig,
@@ -484,6 +496,7 @@ export function resolveCliBackendConfig(
484496
};
485497
}
486498

499+
/** Test-only dependency controls for CLI backend registry resolution. */
487500
export const testing = {
488501
resetDepsForTest(): void {
489502
cliBackendsDeps = defaultCliBackendsDeps;

‎src/agents/cli-credentials.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Reads and refreshes credentials stored by external CLI runtimes such as
3+
* Claude Code, Codex, Gemini, and MiniMax.
4+
*/
15
import { execFileSync, execSync } from "node:child_process";
26
import { createHash } from "node:crypto";
37
import fs from "node:fs";
@@ -36,13 +40,15 @@ let codexCliCache: CachedValue<CodexCliCredential> | null = null;
3640
let minimaxCliCache: CachedValue<MiniMaxCliCredential> | null = null;
3741
let geminiCliCache: CachedValue<GeminiCliCredential> | null = null;
3842

43+
/** Clears in-memory CLI credential caches for isolated tests. */
3944
export function resetCliCredentialCachesForTest(): void {
4045
claudeCliCache = null;
4146
codexCliCache = null;
4247
minimaxCliCache = null;
4348
geminiCliCache = null;
4449
}
4550

51+
/** Credential shape parsed from Claude Code CLI storage. */
4652
export type ClaudeCliCredential =
4753
| {
4854
type: "oauth";
@@ -58,6 +64,7 @@ export type ClaudeCliCredential =
5864
expires: number;
5965
};
6066

67+
/** Credential shape parsed from Codex CLI storage. */
6168
export type CodexCliCredential = {
6269
type: "oauth";
6370
provider: OAuthProvider;
@@ -68,6 +75,7 @@ export type CodexCliCredential = {
6875
idToken?: string;
6976
};
7077

78+
/** Credential shape parsed from MiniMax portal CLI storage. */
7179
export type MiniMaxCliCredential = {
7280
type: "oauth";
7381
provider: "minimax-portal";
@@ -76,6 +84,7 @@ export type MiniMaxCliCredential = {
7684
expires: number;
7785
};
7886

87+
/** Credential shape parsed from Gemini CLI storage. */
7988
export type GeminiCliCredential = {
8089
type: "oauth";
8190
provider: "google-gemini-cli";
@@ -437,6 +446,7 @@ function readClaudeCliKeychainCredentials(
437446
}
438447
}
439448

449+
/** Reads Claude CLI credentials from macOS Keychain or the CLI credential file. */
440450
export function readClaudeCliCredentials(options?: {
441451
allowKeychainPrompt?: boolean;
442452
platform?: NodeJS.Platform;
@@ -494,6 +504,7 @@ export function readClaudeCliCredentialsCached(options?: {
494504
});
495505
}
496506

507+
/** Writes refreshed Claude OAuth tokens back to the Claude CLI macOS Keychain item. */
497508
export function writeClaudeCliKeychainCredentials(
498509
newCredentials: OAuthCredentials,
499510
options?: { execFileSync?: ExecFileSyncFn },
@@ -550,6 +561,7 @@ export function writeClaudeCliKeychainCredentials(
550561
}
551562
}
552563

564+
/** Writes refreshed Claude OAuth tokens back to the Claude CLI credential file. */
553565
export function writeClaudeCliFileCredentials(
554566
newCredentials: OAuthCredentials,
555567
options?: ClaudeCliFileOptions,
@@ -592,6 +604,7 @@ export function writeClaudeCliFileCredentials(
592604
}
593605
}
594606

607+
/** Writes refreshed Claude OAuth tokens to the preferred Claude CLI credential store. */
595608
export function writeClaudeCliCredentials(
596609
newCredentials: OAuthCredentials,
597610
options?: ClaudeCliWriteOptions,
@@ -612,6 +625,7 @@ export function writeClaudeCliCredentials(
612625
return writeFile(newCredentials, { homeDir: options?.homeDir });
613626
}
614627

628+
/** Reads Codex CLI OAuth credentials from Keychain or CODEX_HOME auth.json. */
615629
export function readCodexCliCredentials(options?: {
616630
codexHome?: string;
617631
allowKeychainPrompt?: boolean;
@@ -673,6 +687,7 @@ export function readCodexCliCredentials(options?: {
673687
};
674688
}
675689

690+
/** Reads Codex CLI credentials with optional short-lived cache and file fingerprinting. */
676691
export function readCodexCliCredentialsCached(options?: {
677692
codexHome?: string;
678693
allowKeychainPrompt?: boolean;
@@ -703,6 +718,7 @@ export function readCodexCliCredentialsCached(options?: {
703718
});
704719
}
705720

721+
/** Reads MiniMax CLI credentials with optional short-lived cache. */
706722
export function readMiniMaxCliCredentialsCached(options?: {
707723
ttlMs?: number;
708724
homeDir?: string;
@@ -720,6 +736,7 @@ export function readMiniMaxCliCredentialsCached(options?: {
720736
});
721737
}
722738

739+
/** Reads Gemini CLI credentials with optional short-lived cache. */
723740
export function readGeminiCliCredentialsCached(options?: {
724741
ttlMs?: number;
725742
homeDir?: string;

‎src/agents/cli-output.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -316,6 +316,7 @@ function shouldUnwrapNestedCliResultText(params: {
316316
}
317317

318318
/** Parses JSON CLI output, including mixed stdout that contains embedded JSON objects. */
319+
/** Parses a single JSON payload emitted by a CLI backend. */
319320
export function parseCliJson(
320321
raw: string,
321322
backend: CliBackendConfig,
@@ -624,6 +625,7 @@ function dispatchClaudeCliStreamingToolEvent(params: {
624625
}
625626

626627
/** Creates an incremental JSONL parser for CLI streaming responses and tool events. */
628+
/** Creates a stateful parser for streaming JSONL CLI backend output. */
627629
export function createCliJsonlStreamingParser(params: {
628630
backend: CliBackendConfig;
629631
providerId: string;
@@ -751,6 +753,7 @@ export function createCliJsonlStreamingParser(params: {
751753
}
752754

753755
/** Parses complete JSONL CLI output into the final assistant result and metadata. */
756+
/** Parses complete JSONL output from a CLI backend into normalized text and metadata. */
754757
export function parseCliJsonl(
755758
raw: string,
756759
backend: CliBackendConfig,
@@ -803,6 +806,7 @@ export function parseCliJsonl(
803806
}
804807

805808
/** Parses CLI output according to the backend output mode with text fallback. */
809+
/** Parses CLI backend output using the configured JSON/JSONL/plain-text mode. */
806810
export function parseCliOutput(params: {
807811
raw: string;
808812
backend: CliBackendConfig;
@@ -831,6 +835,7 @@ export function parseCliOutput(params: {
831835
}
832836

833837
/** Extracts the most specific structured CLI error message from mixed or JSON output. */
838+
/** Extracts a human-readable error message from mixed CLI stderr/stdout text. */
834839
export function extractCliErrorMessage(raw: string): string | null {
835840
const parsedRecords = parseJsonRecordCandidates(raw);
836841
if (parsedRecords.length === 0) {

0 commit comments

Comments
 (0)