openclaw-scheduler 0.2.0

package/docs/plans/2026-03-09-fix-typescript-types.md

@@ -0,0 +1,91 @@
+**Status: Completed**
+
+# Fix TypeScript Type Definitions Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make index.d.ts accurately reflect every exported JS function, parameter, and return type.
+
+**Architecture:** Single-file rewrite of index.d.ts plus expanded types-smoke.ts. No JS changes.
+
+**Tech Stack:** TypeScript declarations, tsc --noEmit for validation.
+
+---
+
+### Task 1: Rewrite index.d.ts record interfaces
+
+**Files:**
+- Modify: `index.d.ts`
+
+**Step 1:** Rewrite all record interfaces to include every column from schema.sql:
+- `JobSpec`: add 17 missing fields (payload_scope, payload_model, payload_thinking, delivery_guarantee, job_class, preferred_session_key, job_type, watchdog_*, consecutive_errors, queued_count, run_now)
+- `JobRecord`: add created_at, updated_at, last_run_at
+- `RunRecord`: add started_at, finished_at, duration_ms, last_heartbeat, session_key, session_id, dispatched_at, run_timeout_ms, context_summary, replay_of, idempotency_key
+- `MessageRecord`: add all 16 missing columns (team_id through owner)
+- `ApprovalRecord`: add dispatch_queue_id, requested_at, resolved_at, resolved_by, notes
+- `AgentRecord`: add last_seen_at, created_at
+- Add new `DispatchRecord` interface with all job_dispatch_queue columns
+- Fix `ShellResult` to add stdoutTruncated, stderrTruncated fields
+- Add `PartialShellResult` (return type of extractShellResultFromRun)
+- Type `SCHEDULER_SCHEMAS` with its actual structure
+
+**Step 2:** Run `npm run typecheck` -- expect failure (smoke test uses old shapes)
+
+### Task 2: Rewrite index.d.ts function declarations
+
+**Files:**
+- Modify: `index.d.ts`
+
+**Step 1:** Add all 26 missing function declarations:
+- jobs: pruneExpiredJobs, detectCycle, getChainDepth, getDispatchBacklogCount, canEnqueueDispatch, cancelJob, hasRunningRunForPool, hasRunningRun
+- messages: getTeamMessages, ackMessage, expireMessages, pruneMessages, recordMessageAttempt, listMessageReceipts
+- gateway: runAgentTurn, runAgentTurnWithActivityTimeout, sendSystemEvent, invokeGatewayTool, listSessions, getAllSubAgentSessions
+- approval: countPendingApprovalsForJob, getTimedOutApprovals, pruneApprovals
+- runs: updateHeartbeat, getRunningRunsByPool
+- paths: resolveBackupStagingDir
+- dispatch-queue: listDispatchesForJob
+
+**Step 2:** Fix 4 wrong return types:
+- runJobNow: returns JobRecord & { dispatch_id, dispatch_kind } | null
+- resolveApproval: returns ApprovalRecord
+- deliverMessage: returns Promise<{ ok: true; parts: number; lastResponse: unknown }>
+- extractShellResultFromRun: returns PartialShellResult | null
+
+**Step 3:** Replace Record<string, unknown> params with named fields:
+- sendMessage opts
+- createRun opts
+- finishRun opts
+- normalizeShellResult params
+- buildTriggeredRunContext params
+- listJobs opts
+- resolveSchedulerDbPath params
+- resolveArtifactsDir params
+- upsertAgent opts
+
+**Step 4:** Run `npm run typecheck` -- expect failure (smoke test)
+
+### Task 3: Expand types-smoke.ts
+
+**Files:**
+- Modify: `types-smoke.ts`
+
+**Step 1:** Add smoke tests exercising:
+- All 26 newly typed functions (at type level, not runtime)
+- Watchdog JobSpec fields
+- DispatchRecord interface
+- Gateway function signatures
+- Message ack and team functions
+- Approval timeout/prune functions
+- PartialShellResult from extractShellResultFromRun
+- RunRecord time fields (started_at, finished_at)
+
+**Step 2:** Run `npm run typecheck` -- must pass
+
+**Step 3:** Run `npm test` -- must still pass (581 tests, no JS changes)
+
+### Task 4: Commit
+
+```bash
+git add index.d.ts types-smoke.ts
+git commit -m "Complete TypeScript type coverage for all exported APIs"
+```

package/docs/plans/2026-03-09-test-coverage-gaps.md

@@ -0,0 +1,83 @@
+**Status: Completed**
+
+# Test Coverage Gaps Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Close 6 identified testable coverage gaps in test.js without changing any source code.
+
+**Architecture:** Add test sections to the existing test.js using the custom assert harness. All tests use in-memory SQLite.
+
+**Tech Stack:** Node.js ESM, better-sqlite3, custom test harness (assert/passed/failed counters).
+
+---
+
+### Task 1: Import dispatcher-utils.js and replace inline re-implementations
+
+**Files:**
+- Modify: `test.js` (imports at top, transient error section around line 1859)
+
+**Changes:**
+1. Add import: `import { matchesSentinel, detectTransientError, adaptiveDeferralMs, buildExecutionIntentNote, getBackoffMs, sqliteNow } from './dispatcher-utils.js';`
+2. In the "Transient Error Detection" section (~line 1859), delete the inline `TRANSIENT_ERROR_PATTERNS` array, `detectTransientError` function, and `matchesSentinel` function
+3. Add new test section "Dispatcher Utils" testing:
+   - `adaptiveDeferralMs`: depth 0 returns baseMs, depth 11 caps at 12x, result caps at 300000
+   - `buildExecutionIntentNote`: returns '' for normal jobs, returns plan note for plan intent, returns read-only note for read_only, includes both when both set
+   - `getBackoffMs`: n=1 returns 30000, n=5 returns 3600000, n=99 caps at 3600000
+   - `sqliteNow`: returns valid datetime string format
+
+### Task 2: Test dispatch-queue claim/release/setStatus
+
+**Files:**
+- Modify: `test.js`
+
+**Changes:**
+Add new test section "Dispatch Queue Lifecycle" after existing dispatch tests:
+- `claimDispatch`: create pending dispatch, claim it, verify status='claimed' and claimed_at set; claim again returns null
+- `releaseDispatch`: claim a dispatch, release it, verify status='pending' and claimed_at cleared; release with new scheduledFor
+- `setDispatchStatus`: set to 'done', verify processed_at set; set to 'cancelled', verify processed_at set; set to 'pending', verify processed_at unchanged
+
+### Task 3: Test approval timeout/prune/count
+
+**Files:**
+- Modify: `test.js`
+
+**Changes:**
+Add to existing "v5: Approval Gates" section or new section after it:
+- `countPendingApprovalsForJob`: create 2 pending approvals, count returns 2; resolve one, count returns 1
+- `getTimedOutApprovals`: create approval, backdate requested_at past timeout, verify it appears in results with job_name/approval_timeout_s/approval_auto
+- `pruneApprovals`: create resolved approval, backdate resolved_at past retention, prune, verify deleted
+
+### Task 4: Test runs updateRunSession and updateContextSummary
+
+**Files:**
+- Modify: `test.js` (imports + new section)
+
+**Changes:**
+1. Add `updateRunSession` and `updateContextSummary` to runs.js import
+2. Add tests:
+   - `updateRunSession`: create run, call with session key/id, verify both stored on run
+   - `updateContextSummary`: create run, call with object, verify JSON stored; call with string, verify stored as-is
+
+### Task 5: Test prompt-context.js missing branches
+
+**Files:**
+- Modify: `test.js`
+
+**Changes:**
+Add to existing "Prompt Context" section:
+- Null parent run: pass `{ triggered_by_run: 'nonexistent' }` with getRunById returning undefined; verify text='', meta.parent_run_missing=true
+- No trigger: pass `{}` (no triggered_by_run); verify text='', meta is empty
+- Non-shell parent: pass parent run with status='ok', summary='Agent completed task', session_target='isolated' (no shell fields); verify text includes summary, no shell exit code
+
+### Task 6: Test migrate.js cronFromSchedule
+
+**Files:**
+- Modify: `test.js`
+
+**Changes:**
+Since `cronFromSchedule` is not exported, test it indirectly via dynamic import or extract its logic. Since we cannot modify source files, we re-implement the pure function in tests (same pattern as the original matchesSentinel approach, but documented).
+
+Actually: `cronFromSchedule` is a local function in migrate.js, not exported. We cannot test it without modifying the source. Skip this task or note it as requiring a source change.
+
+**Alternative:** Add a note that this gap requires exporting cronFromSchedule from migrate.js in a future change.