docs: document task execution helpers

steipete · steipete · commit 606e3d78669a · 2026-06-04T03:44:45.000-04:00
diff --git a/src/tasks/detached-task-runtime-contract.ts b/src/tasks/detached-task-runtime-contract.ts
@@ -1,3 +1,4 @@
+// Defines the detached task runtime contract and spawn options.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type {
   TaskDeliveryState,
diff --git a/src/tasks/detached-task-runtime-state.ts b/src/tasks/detached-task-runtime-state.ts
@@ -1,3 +1,4 @@
+// Tracks detached task runtime state and spawned process handles.
 import type {
   DetachedTaskLifecycleRuntime,
   DetachedTaskLifecycleRuntimeRegistration,
diff --git a/src/tasks/detached-task-runtime.ts b/src/tasks/detached-task-runtime.ts
@@ -1,3 +1,4 @@
+// Provides the runtime adapter for detached task execution.
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import type {
   DetachedTaskRecoveryAttemptParams,
diff --git a/src/tasks/task-completion-contract.ts b/src/tasks/task-completion-contract.ts
@@ -1,3 +1,4 @@
+// Defines task terminal outcome contracts used by completion handling.
 import type { TaskTerminalOutcome } from "./task-registry.types.js";
 
 /** Terminal fields required when a mandatory detached task completion is invalid. */
diff --git a/src/tasks/task-executor.test.ts b/src/tasks/task-executor.test.ts
@@ -1,3 +1,4 @@
+// Covers task executor runtime selection, lifecycle updates, and error paths.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { resetAgentEventsForTest, resetAgentRunContextForTest } from "../infra/agent-events.js";
 import { resetHeartbeatWakeStateForTests } from "../infra/heartbeat-wake.js";
diff --git a/src/tasks/task-executor.ts b/src/tasks/task-executor.ts
@@ -1,3 +1,4 @@
+// Executes task records through configured runtimes and updates registry state.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { createSubsystemLogger } from "../logging/subsystem.js";
 import type {
diff --git a/src/tasks/task-flow-registry.audit.test.ts b/src/tasks/task-flow-registry.audit.test.ts
@@ -1,3 +1,4 @@
+// Covers managed task-flow audit summaries and stale-flow classification.
 import { afterEach, describe, expect, it } from "vitest";
 import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
 import { createRunningTaskRun as createRunningTaskRunOrNull } from "./task-executor.js";
diff --git a/src/tasks/task-flow-registry.maintenance.test.ts b/src/tasks/task-flow-registry.maintenance.test.ts
@@ -1,3 +1,4 @@
+// Covers maintenance reconciliation for managed task-flow records.
 import { afterEach, describe, expect, it } from "vitest";
 import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
 import { createRunningTaskRun as createRunningTaskRunOrNull } from "./task-executor.js";
diff --git a/src/tasks/task-flow-registry.maintenance.ts b/src/tasks/task-flow-registry.maintenance.ts
@@ -1,3 +1,4 @@
+// Reconciles stale task-flow records with their child task state.
 import { listTasksForFlowId } from "./runtime-internal.js";
 import {
   listTaskFlowAuditFindings,
diff --git a/src/tasks/task-flow-registry.store.test.ts b/src/tasks/task-flow-registry.store.test.ts
@@ -1,3 +1,4 @@
+// Covers task-flow registry store persistence, events, and state queries.
 import { statSync } from "node:fs";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
diff --git a/src/tasks/task-flow-registry.store.types.ts b/src/tasks/task-flow-registry.store.types.ts
@@ -1,3 +1,4 @@
+// Defines storage contracts for managed task-flow records.
 import type { TaskFlowRecord } from "./task-flow-registry.types.js";
 
 /** Full task-flow registry snapshot used for persistence restore and replacement writes. */
diff --git a/src/tasks/task-flow-registry.ts b/src/tasks/task-flow-registry.ts
@@ -1,3 +1,4 @@
+// Coordinates managed task-flow creation, updates, ownership, and snapshots.
 import crypto from "node:crypto";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import { formatErrorMessage } from "../infra/errors.js";
diff --git a/src/tasks/task-owner-access.test.ts b/src/tasks/task-owner-access.test.ts
@@ -1,3 +1,4 @@
+// Verifies requester and owner access checks for task records.
 import { afterEach, describe, expect, it } from "vitest";
 import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";
 import {
diff --git a/src/tasks/task-owner-access.ts b/src/tasks/task-owner-access.ts
@@ -1,3 +1,4 @@
+// Normalizes task owner keys and checks requester access to task records.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
   findTaskByRunId,
diff --git a/src/tasks/task-registry-control.types.ts b/src/tasks/task-registry-control.types.ts
@@ -1,3 +1,4 @@
+// Defines task control runtime contracts exposed to command surfaces.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
 /** Admin cancellation hook for ACP sessions owned by task records. */
diff --git a/src/tasks/task-registry.audit.shared.ts b/src/tasks/task-registry.audit.shared.ts
@@ -1,3 +1,4 @@
+// Shares task audit classification helpers across registry audit modules.
 import type { TaskRecord } from "./task-registry.types.js";
 
 /** Severity used by task registry audit findings. */
diff --git a/src/tasks/task-registry.audit.ts b/src/tasks/task-registry.audit.ts
@@ -1,3 +1,4 @@
+// Produces task registry audit summaries for diagnostics and maintenance.
 import {
   compareTaskAuditFindingSortKeys,
   createEmptyTaskAuditSummary,
diff --git a/src/tasks/task-registry.maintenance.ts b/src/tasks/task-registry.maintenance.ts
@@ -1,3 +1,4 @@
+// Reconciles stale or lost task registry records during maintenance passes.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/tasks/task-registry.process-state.test.ts b/src/tasks/task-registry.process-state.test.ts
@@ -1,3 +1,4 @@
+// Verifies process-state persistence across fresh task registry module loads.
 import { importFreshModule } from "openclaw/plugin-sdk/test-fixtures";
 import { describe, expect, it } from "vitest";
 
diff --git a/src/tasks/task-registry.process-state.ts b/src/tasks/task-registry.process-state.ts
@@ -1,3 +1,4 @@
+// Tracks task process state transitions used to reconcile running work.
 import type { TaskDeliveryState, TaskRecord } from "./task-registry.types.js";
 
 /** Process-local indexes backing task lookup, owner access, and pending delivery scans. */
diff --git a/src/tasks/task-registry.store.ts b/src/tasks/task-registry.store.ts
@@ -1,3 +1,4 @@
+// Stores task registry records in memory and bridges persistence runtime hooks.
 import {
   closeTaskRegistryDatabase,
   deleteTaskAndDeliveryStateFromSqlite,
diff --git a/src/tasks/task-registry.store.types.ts b/src/tasks/task-registry.store.types.ts
@@ -1,3 +1,4 @@
+// Defines storage contracts for task registry records and observer events.
 import type { TaskDeliveryState, TaskRecord } from "./task-registry.types.js";
 
 /** Full task registry snapshot used for persistence restore and replacement writes. */
diff --git a/src/tasks/task-registry.test.ts b/src/tasks/task-registry.test.ts
@@ -1,3 +1,4 @@
+// Covers task registry lifecycle, delivery, notification, and query behavior.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { AcpSessionStoreEntry } from "../acp/runtime/session-meta.js";
 import { startAcpSpawnParentStreamRelay } from "../agents/acp-spawn-parent-stream.js";
diff --git a/src/tasks/task-registry.types.ts b/src/tasks/task-registry.types.ts
@@ -1,3 +1,4 @@
+// Defines task registry records, statuses, delivery state, and parser helpers.
 import type { DeliveryContext } from "../utils/delivery-context.types.js";
 
 /** Runtime family that owns a task run lifecycle. */

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Defines the detached task runtime contract and spawn options.`
`1`	`2`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`2`	`3`	`import type {`
`3`	`4`	`TaskDeliveryState,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Tracks detached task runtime state and spawned process handles.`
`1`	`2`	`import type {`
`2`	`3`	`DetachedTaskLifecycleRuntime,`
`3`	`4`	`DetachedTaskLifecycleRuntimeRegistration,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Provides the runtime adapter for detached task execution.`
`1`	`2`	`import { createSubsystemLogger } from "../logging/subsystem.js";`
`2`	`3`	`import type {`
`3`	`4`	`DetachedTaskRecoveryAttemptParams,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Defines task terminal outcome contracts used by completion handling.`
`1`	`2`	`import type { TaskTerminalOutcome } from "./task-registry.types.js";`
`2`	`3`
`3`	`4`	`/** Terminal fields required when a mandatory detached task completion is invalid. */`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers task executor runtime selection, lifecycle updates, and error paths.`
`1`	`2`	`import { afterEach, describe, expect, it, vi } from "vitest";`
`2`	`3`	`import { resetAgentEventsForTest, resetAgentRunContextForTest } from "../infra/agent-events.js";`
`3`	`4`	`import { resetHeartbeatWakeStateForTests } from "../infra/heartbeat-wake.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Executes task records through configured runtimes and updates registry state.`
`1`	`2`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`2`	`3`	`import { createSubsystemLogger } from "../logging/subsystem.js";`
`3`	`4`	`import type {`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers managed task-flow audit summaries and stale-flow classification.`
`1`	`2`	`import { afterEach, describe, expect, it } from "vitest";`
`2`	`3`	`import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";`
`3`	`4`	`import { createRunningTaskRun as createRunningTaskRunOrNull } from "./task-executor.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers maintenance reconciliation for managed task-flow records.`
`1`	`2`	`import { afterEach, describe, expect, it } from "vitest";`
`2`	`3`	`import { withOpenClawTestState } from "../test-utils/openclaw-test-state.js";`
`3`	`4`	`import { createRunningTaskRun as createRunningTaskRunOrNull } from "./task-executor.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Reconciles stale task-flow records with their child task state.`
`1`	`2`	`import { listTasksForFlowId } from "./runtime-internal.js";`
`2`	`3`	`import {`
`3`	`4`	`listTaskFlowAuditFindings,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers task-flow registry store persistence, events, and state queries.`
`1`	`2`	`import { statSync } from "node:fs";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";`