Skip to content

Commit 88eb405

Browse files
steipetesteipete
committed
docs: document tool utility helpers
1 parent 36ae3dd commit 88eb405

9 files changed

Lines changed: 43 additions & 4 deletions

‎src/agents/live-auth-keys.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Regression coverage for live-test provider API-key discovery.
3+
* Verifies env precedence, manifest fallback, and non-secret error classifiers.
4+
*/
15
import { beforeAll, describe, expect, it, vi } from "vitest";
26

37
vi.unmock("../secrets/provider-env-vars.js");

‎src/agents/live-auth-keys.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/**
2+
* Live-test provider API-key discovery.
3+
* Reads provider-specific and manifest-declared env names without logging or
4+
* exposing secret values, with explicit single-key pins for flaky live lanes.
5+
*/
16
import {
27
normalizeLowercaseStringOrEmpty,
38
normalizeOptionalString,
@@ -6,8 +11,6 @@ import { normalizeStringEntries } from "@openclaw/normalization-core/string-norm
611
import { getProviderEnvVars } from "../secrets/provider-env-vars.js";
712
import { normalizeProviderId } from "./model-selection.js";
813

9-
// Live-test credential discovery. Provider-specific env names take precedence,
10-
// then manifest-declared env vars fill in fallback API keys.
1114
const KEY_SPLIT_RE = /[\s,;]+/g;
1215
const GOOGLE_LIVE_SINGLE_KEY = "OPENCLAW_LIVE_GEMINI_KEY";
1316

‎src/agents/provider-stream.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/**
2+
* Provider stream registration entry point.
3+
* Resolves plugin-owned or transport-aware stream functions and registers the
4+
* model API once a concrete stream implementation exists.
5+
*/
16
import type { OpenClawConfig } from "../config/types.openclaw.js";
27
import type { Api, Model } from "../llm/types.js";
38
import { resolveProviderStreamFn } from "../plugins/provider-runtime.js";

‎src/agents/session-dirs.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/**
2+
* Agent session directory discovery helpers.
3+
* Lists per-agent `sessions` directories under state roots in sorted order for
4+
* callers that scan persisted session stores.
5+
*/
16
import fsSync, { type Dirent } from "node:fs";
27
import fs from "node:fs/promises";
38
import path from "node:path";

‎src/agents/tool-display-common.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/**
2+
* Shared compact tool-call display helpers.
3+
* Redacts and summarizes arguments into short labels/details for chat and UI
4+
* tool update streams.
5+
*/
16
import {
27
normalizeLowercaseStringOrEmpty,
38
normalizeOptionalString,
@@ -7,20 +12,20 @@ import { redactToolPayloadText } from "../logging/redact.js";
712
import { resolveExecDetail, type ToolDetailMode } from "./tool-display-exec.js";
813
import { asRecord } from "./tool-display-record.js";
914

10-
// Shared formatting helpers for compact tool-call display labels. Display text
11-
// is redacted and summarized so tool updates stay readable in chat/UI streams.
1215
type ToolDisplayActionSpec = {
1316
label?: string;
1417
detailKeys?: string[];
1518
};
1619

20+
/** Display metadata for a tool and optional per-action labels/details. */
1721
export type ToolDisplaySpec = {
1822
title?: string;
1923
label?: string;
2024
detailKeys?: string[];
2125
actions?: Record<string, ToolDisplayActionSpec>;
2226
};
2327

28+
/** Normalized display target for code/search bridge tools. */
2429
export type ToolSearchCodeDisplayTarget = {
2530
toolName: string;
2631
displayToolName?: string;

‎src/agents/tool-display.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Regression coverage for compact tool display formatting.
3+
* Ensures tool names, actions, and details stay readable and redacted.
4+
*/
15
import { describe, expect, it } from "vitest";
26
import { resolveToolSearchCodeDisplayTarget } from "./tool-display-common.js";
37
import { resolveExecDetail } from "./tool-display-exec.js";

‎src/agents/tool-policy.plugin-only-allowlist.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Regression coverage for plugin-only tool allowlist analysis.
3+
* Confirms plugin group expansion and unknown allowlist reporting.
4+
*/
15
import { describe, expect, it } from "vitest";
26
import {
37
analyzeAllowlistByToolType,

‎src/agents/tool-policy.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
1+
/**
2+
* Regression coverage for core tool allow/deny policy helpers.
3+
* Verifies sandbox policy resolution, explicit lists, and tool matching.
4+
*/
15
import { describe, expect, it } from "vitest";
26
import type { OpenClawConfig } from "../config/config.js";
37
import { pickSandboxToolPolicy } from "./sandbox-tool-policy.js";

‎src/agents/tool-policy.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
/**
2+
* Tool allow/deny policy helpers.
3+
* Normalizes core and plugin tool groups, expands plugin entries, and extracts
4+
* explicit operator allow/deny lists.
5+
*/
16
import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
27
import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
38
import { IMPLICIT_ALLOW_ALL_FROM_ALSO_ALLOW } from "./sandbox-tool-policy.js";

0 commit comments

Comments
 (0)