docs: document bash process helpers

steipete · steipete · commit c7a8114f540f · 2026-06-03T22:54:12.000-04:00
diff --git a/src/agents/bash-process-references.ts b/src/agents/bash-process-references.ts
@@ -1,6 +1,8 @@
 import { listRunningSessions } from "./bash-process-registry.js";
 import { deriveSessionName } from "./bash-tools.shared.js";
 
+// Builds compact references for currently running background process sessions.
+// These references are surfaced to agents so they can reconnect to prior work.
 const DEFAULT_ACTIVE_PROCESS_LIMIT = 8;
 const MAX_COMMAND_LABEL_CHARS = 140;
 
@@ -27,6 +29,7 @@ function truncate(value: string, maxChars: number): string {
   return `${value.slice(0, Math.max(0, maxChars - 3))}...`;
 }
 
+/** List active background process sessions for one scope key, newest first. */
 export function listActiveProcessSessionReferences(params: {
   scopeKey?: string;
   now?: number;
diff --git a/src/agents/bash-tools.exec-approval-followup-state.ts b/src/agents/bash-tools.exec-approval-followup-state.ts
@@ -6,6 +6,9 @@ import {
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { ExecElevatedDefaults } from "./bash-tools.exec-types.js";
 
+// Short-lived in-memory handoff state for exec approval follow-up turns. The
+// handoff carries elevated defaults across the approval response without
+// persisting operator approval state longer than the TTL.
 const EXEC_APPROVAL_FOLLOWUP_IDEMPOTENCY_PREFIX = "exec-approval-followup:";
 const EXEC_APPROVAL_FOLLOWUP_IDEMPOTENCY_NONCE_MARKER = ":nonce:";
 const EXEC_APPROVAL_FOLLOWUP_RUNTIME_HANDOFF_TTL_MS = 5 * 60 * 1000;
@@ -66,6 +69,7 @@ function pruneExpiredExecApprovalFollowupRuntimeHandoffs(nowMs: number): void {
   }
 }
 
+/** Build the idempotency key used for an exec approval follow-up. */
 export function buildExecApprovalFollowupIdempotencyKey(params: {
   approvalId: string;
   nonce?: string;
@@ -75,6 +79,7 @@ export function buildExecApprovalFollowupIdempotencyKey(params: {
   return nonce ? `${base}${EXEC_APPROVAL_FOLLOWUP_IDEMPOTENCY_NONCE_MARKER}${nonce}` : base;
 }
 
+/** Parse the approval id embedded in a follow-up idempotency key. */
 export function parseExecApprovalFollowupApprovalId(idempotencyKey: string): string | undefined {
   const normalized = normalizeOptionalString(idempotencyKey);
   if (!normalized?.startsWith(EXEC_APPROVAL_FOLLOWUP_IDEMPOTENCY_PREFIX)) {
@@ -85,6 +90,7 @@ export function parseExecApprovalFollowupApprovalId(idempotencyKey: string): str
   return normalizeOptionalString(nonceMarker >= 0 ? body.slice(0, nonceMarker) : body);
 }
 
+/** Register a short-lived exec approval handoff for the next follow-up turn. */
 export function registerExecApprovalFollowupRuntimeHandoff(params: {
   approvalId: string;
   sessionKey: string;
@@ -121,6 +127,7 @@ export function registerExecApprovalFollowupRuntimeHandoff(params: {
   return { handoffId, idempotencyKey };
 }
 
+/** Consume a matching handoff once, validating approval/session/idempotency data. */
 export function consumeExecApprovalFollowupRuntimeHandoff(params: {
   handoffId?: string;
   approvalId?: string;
@@ -150,12 +157,15 @@ export function consumeExecApprovalFollowupRuntimeHandoff(params: {
     entry.idempotencyKey !== idempotencyKey ||
     entry.sessionKey !== sessionKey
   ) {
+    // Handoffs are single-session capabilities; mismatched follow-up metadata
+    // must not consume or expose the stored elevated defaults.
     return undefined;
   }
   execApprovalFollowupRuntimeHandoffs.delete(handoffId);
   return cloneExecApprovalFollowupRuntimeHandoff(entry);
 }
 
+/** Clear exec approval follow-up handoffs between tests. */
 export function resetExecApprovalFollowupRuntimeHandoffsForTests(): void {
   execApprovalFollowupRuntimeHandoffs.clear();
 }
diff --git a/src/agents/bash-tools.exec-approval-request.runtime.ts b/src/agents/bash-tools.exec-approval-request.runtime.ts
@@ -1,6 +1,8 @@
 import { explainShellCommand, formatCommandSpans } from "../infra/command-explainer/index.js";
 import type { ExecApprovalCommandSpan } from "../infra/exec-approvals.js";
 
+// Runtime wrapper for shell command highlighting in exec approval requests.
+/** Resolve command spans used to highlight exec approval prompts. */
 export async function resolveExecApprovalCommandSpans(
   command: string,
 ): Promise<ExecApprovalCommandSpan[] | undefined> {
diff --git a/src/agents/bash-tools.exec-host-node.types.ts b/src/agents/bash-tools.exec-host-node.types.ts
@@ -2,6 +2,8 @@ import type { ExecAsk, ExecSecurity } from "../infra/exec-approvals.js";
 import type { ExecAutoReviewer } from "../infra/exec-auto-review.js";
 import type { ExecElevatedDefaults } from "./bash-tools.exec-types.js";
 
+// Full parameter bundle for Node-hosted exec command execution. Keeping this
+// type centralized prevents the host/runtime boundary from drifting.
 export type ExecuteNodeHostCommandParams = {
   command: string;
   workdir: string | undefined;
diff --git a/src/agents/bash-tools.exec-output.ts b/src/agents/bash-tools.exec-output.ts
@@ -1,9 +1,12 @@
 const EXEC_NO_OUTPUT_PLACEHOLDER = "(no output)";
 
+// Rendering helpers for exec output/status updates.
+/** Render command output with a stable placeholder for empty output. */
 export function renderExecOutputText(value: string | undefined): string {
   return value || EXEC_NO_OUTPUT_PLACEHOLDER;
 }
 
+/** Render the text shown in exec progress updates, including warnings first. */
 export function renderExecUpdateText(params: { tailText?: string; warnings: string[] }): string {
   const warningText = params.warnings.length ? `${params.warnings.join("\n")}\n\n` : "";
   return warningText + renderExecOutputText(params.tailText);
diff --git a/src/agents/bash-tools.process-send-keys.ts b/src/agents/bash-tools.process-send-keys.ts
@@ -3,6 +3,8 @@ import { deriveSessionName } from "./bash-tools.shared.js";
 import { encodeKeySequence, hasCursorModeSensitiveKeys } from "./pty-keys.js";
 import type { AgentToolResult } from "./runtime/index.js";
 
+// Process send-keys support for background PTY sessions. It encodes symbolic,
+// hex, and literal input before writing to a live session stdin.
 export type WritableStdin = {
   write: (data: string, cb?: (err?: Error | null) => void) => void;
   end: () => void;
@@ -36,6 +38,7 @@ async function writeToStdin(stdin: WritableStdin, data: string) {
   });
 }
 
+/** Encode and write requested key data into a running process session. */
 export async function handleProcessSendKeys(params: {
   sessionId: string;
   session: ProcessSession;
@@ -50,6 +53,8 @@ export async function handleProcessSendKeys(params: {
     literal: params.literal,
   };
   if (params.session.cursorKeyMode === "unknown" && hasCursorModeSensitiveKeys(request)) {
+    // Arrow/keypad encodings depend on cursor key mode. Wait for startup output
+    // to identify the mode before sending potentially wrong bytes.
     return failText(
       `Session ${params.sessionId} cursor key mode is not known yet. Poll or log until startup output appears, then retry send-keys.`,
     );
