refactor(cron): rename scheduler feature to cron

Rename the recurring-jobs feature scheduler->cron to disambiguate from the legacy ScheduledRun system (/api/scheduled), which is left untouched: - ScheduledJob->CronJob, SchedulerService->CronService - /api/scheduler/jobs -> /api/cron/jobs; SSE scheduler:* -> cron:* - state keys cronJobs/cronJobRuns - files moved to src/cron/, cron-routes.ts, cron-port.ts, types/cron.ts - frontend cron-ui.js, #cronModal, menu "Cron" - docs moved to docs/cron-discovery.md + docs/cron-build-brief.md, README guides - new tests: cron-service.test.ts, cron-time.test.ts Green: tsc, lint, frontend-syntax, format, 30 cron + 9 legacy scheduled-runs tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PmvZR12aX2v8K7YhqxPUAU
2026-10-03 22:19:42 +02:00 · 2026-06-29 11:35:56 +05:30
parent 2d2f4e592b
commit 9feaa0d6e5
27 changed files with 1383 additions and 370 deletions
@@ -0,0 +1,588 @@
+# Claude Code Build Brief: Add Scheduling to Codeman
+
+## 0. Purpose of This Brief
+
+You are Claude Code working inside the Codeman repository.
+
+Your task is to add a **small, reliable scheduling layer** to Codeman while preserving Codeman's existing architecture and session-management behavior.
+
+This is not a greenfield rewrite. This is not a full product rebuild. This is a focused extension.
+
+The target user wants Codeman-like tmux/web/session management, but with first-class scheduled jobs for Claude, Codex, OpenCode, Terminal, or any other configurable coding-agent harness.
+
+---
+
+## 1. Non-Negotiable Goal
+
+Add scheduling to Codeman so a user can define a scheduled coding-agent job that:
+
+1. Has a name.
+2. Uses an existing Codeman-supported agent/session type where possible.
+3. Has a working directory.
+4. Has a prompt or prompt file.
+5. Has a schedule.
+6. Can be enabled or disabled.
+7. Can be manually run now.
+8. When due, creates a Codeman/tmux session.
+9. Sends the configured prompt into that session.
+10. Records last run, next run, status, and run history.
+
+The first working version should prioritize **scheduling correctness and reuse of Codeman's existing tmux/session system** over UI polish.
+
+---
+
+## 2. Core Architectural Rule
+
+Do **not** rebuild Codeman's session layer.
+
+Reuse existing Codeman functionality for:
+
+- Creating sessions.
+- Naming sessions.
+- Launching Claude/Codex/OpenCode/Terminal sessions.
+- Sending input into sessions.
+- Displaying sessions in the web UI.
+- Killing sessions.
+- Tracking session status if already supported.
+
+If an internal API/service/function already exists, reuse it.
+
+If no reusable function exists, create a thin wrapper around the existing implementation rather than duplicating logic.
+
+---
+
+## 3. Product Boundary
+
+This build is **Codeman + Scheduler**.
+
+It is not yet:
+
+- A full quota engine.
+- A full lock manager.
+- A replacement for Codeman's terminal UI.
+- A new FastAPI application.
+- A multi-tenant SaaS platform.
+- A complex cron-management product.
+- A full agent autonomy framework.
+
+Keep the build small and shippable.
+
+---
+
+## 4. Required Working Scope for v0.1
+
+Implement the following minimum features.
+
+### 4.1 Scheduled Jobs List
+
+Create a UI page showing all scheduled jobs.
+
+Each row/card should show:
+
+- Job name.
+- Agent/session type.
+- Working directory.
+- Schedule type.
+- Enabled/disabled state.
+- Last run time.
+- Next run time.
+- Last run status.
+- Actions:
+  - Run Now.
+  - Enable/Disable.
+  - Edit.
+  - Delete.
+
+### 4.2 Create/Edit Scheduled Job
+
+Create a form for scheduled jobs with these fields:
+
+- `name`
+- `agent_type`
+  - Reuse Codeman's existing session/agent types where possible.
+  - Include at least Terminal/custom command if supported.
+- `working_directory`
+- `launch_command` if needed by Codeman's model.
+- `prompt_mode`
+  - `inline_text`
+  - `prompt_file_path`
+- `prompt_text`
+- `prompt_file_path`
+- `input_mode`
+  - `paste`
+  - `typed`
+- `schedule_type`
+  - `once`
+  - `interval_minutes`
+  - `daily_time`
+  - `weekly_time`
+- `run_at` for one-time jobs.
+- `interval_minutes` for interval jobs.
+- `daily_time` for daily jobs.
+- `weekly_days` and `weekly_time` for weekly jobs.
+- `enabled`
+- `notes` optional.
+
+Do not build a complex visual cron editor in v0.1.
+
+### 4.3 Run Now
+
+Every scheduled job must support a `Run Now` action.
+
+Run Now should:
+
+1. Create a new session through Codeman's existing session creation logic.
+2. Send the configured prompt into the session using Codeman's existing input mechanism.
+3. Create a run-history record.
+4. Update last-run fields.
+5. Redirect or link the user to the created Codeman session.
+
+### 4.4 Background Scheduler Loop
+
+Add a small background scheduler loop that runs inside the Codeman backend process.
+
+The loop should:
+
+1. Wake every 15-60 seconds.
+2. Load enabled schedules.
+3. Find schedules where `next_run_at <= now`.
+4. Create a scheduled run.
+5. Launch the session using existing Codeman session logic.
+6. Send the prompt.
+7. Record run history.
+8. Compute the next run time.
+9. Avoid duplicate launches if the loop overlaps or restarts.
+
+Keep this simple and robust.
+
+### 4.5 Run History
+
+Every scheduled execution should create a run-history record.
+
+Track:
+
+- `id`
+- `scheduled_job_id`
+- `session_id` or Codeman session reference.
+- `session_name` if applicable.
+- `started_at`
+- `finished_at` optional.
+- `status`
+  - `created`
+  - `session_started`
+  - `prompt_sent`
+  - `failed`
+- `error_message` optional.
+- `trigger_type`
+  - `scheduled`
+  - `manual_run_now`
+- `created_session_url` or route reference if easy.
+
+---
+
+## 5. Scheduling Rules
+
+### 5.1 Once
+
+Run at a specific date/time.
+
+After successful launch:
+
+- Set `enabled = false`, or mark as completed.
+
+### 5.2 Interval
+
+Run every N minutes.
+
+Example:
+
+- Every 60 minutes.
+- Every 240 minutes.
+
+After launch:
+
+- `next_run_at = now + interval_minutes`.
+
+### 5.3 Daily
+
+Run every day at HH:MM.
+
+After launch:
+
+- Compute the next occurrence of HH:MM after now.
+
+### 5.4 Weekly
+
+Run on selected weekdays at HH:MM.
+
+After launch:
+
+- Compute the next selected weekday/time after now.
+
+### 5.5 Timezone
+
+Use the server's local timezone for v0.1 unless Codeman already has timezone handling.
+
+Add a visible note in the UI:
+
+> Times use the server's local timezone.
+
+Do not overbuild timezone support in v0.1.
+
+---
+
+## 6. Data Storage Decision
+
+First inspect Codeman's existing persistence model.
+
+If Codeman already has a database or persistence layer:
+
+- Reuse it.
+- Add scheduled job and scheduled run models/tables/records using the existing pattern.
+
+If Codeman uses files or JSON state:
+
+- Use the same style for v0.1.
+- Prefer simple persistence over introducing a heavy new dependency.
+
+If there is no appropriate persistence layer:
+
+- Add SQLite only if it fits the codebase cleanly.
+- Otherwise use a JSON file store for the first version.
+
+Do not introduce Postgres, Redis, Celery, or a separate scheduler service.
+
+---
+
+## 7. Concurrency and Duplicate-Run Guard
+
+Implement a basic duplicate-run guard.
+
+A schedule should not launch twice for the same due time.
+
+Minimum acceptable approach:
+
+- Before launching, create/update a run record with a `created` or `launching` state.
+- Use a schedule-level `last_triggered_at` or `last_due_key` to avoid double launching.
+- If launch fails, record failure clearly.
+
+Do not build distributed locks. Codeman is expected to be local/single-instance for v0.1.
+
+---
+
+## 8. Multi-Session Warning
+
+When the user clicks `Run Now`, show a warning if there are already active sessions for the same agent type.
+
+Minimum behavior:
+
+- If active sessions exist, show a confirmation warning.
+- User can continue anyway.
+
+For scheduled automatic runs:
+
+- Add a setting on the scheduled job:
+  - `warn_only`
+  - `skip_if_same_agent_running`
+
+Default:
+
+- `warn_only` for manual runs.
+- `skip_if_same_agent_running = false` for automatic runs unless easy to implement.
+
+Do not build a complete quota engine in v0.1.
+
+---
+
+## 9. Prompt Sending Rules
+
+The scheduler must support sending the configured prompt into the created session.
+
+Prompt source:
+
+1. Inline prompt text.
+2. Prompt file path.
+
+Input mode:
+
+1. Paste mode.
+2. Typed mode.
+
+If only one input mode is easy with Codeman's current internals, implement that first and structure the code so the other can be added later.
+
+Important:
+
+- Do not send prompts to a session if session creation failed.
+- Record prompt-send success/failure in run history.
+- Save enough metadata to understand what prompt was used.
+
+---
+
+## 10. UI Bifurcation
+
+Keep UI changes cleanly separated.
+
+Add scheduler UI under a clear navigation item:
+
+- `Scheduled Jobs`
+
+Do not clutter the existing session dashboard.
+
+The existing session dashboard may show sessions created by scheduled jobs, but the scheduling controls should live in their own section.
+
+Recommended pages/routes:
+
+- `/schedules`
+- `/schedules/new`
+- `/schedules/:id`
+- `/schedules/:id/edit`
+- `/schedules/:id/run-now`
+- `/schedules/:id/enable`
+- `/schedules/:id/disable`
+- `/schedules/:id/delete`
+
+Use Codeman's existing frontend conventions and routing style.
+
+---
+
+## 11. Backend Bifurcation
+
+Keep scheduler code separate from existing session code.
+
+Recommended logical modules, adapted to Codeman's actual structure:
+
+- `scheduler/model` or equivalent.
+- `scheduler/store` or equivalent.
+- `scheduler/service` for schedule calculations and launch logic.
+- `scheduler/loop` for the background due-job checker.
+- `scheduler/routes` for API/UI endpoints.
+- `scheduler/time` for next-run calculations.
+
+Do not mix scheduling logic directly into terminal rendering, xterm handling, or low-level tmux code.
+
+The scheduler service should call session services; it should not own tmux directly unless Codeman has no session abstraction.
+
+---
+
+## 12. Required Discovery Phase Before Coding
+
+Before implementing, inspect the Codeman repo and produce a short architecture note in the terminal or in a file called:
+
+`docs/cron-discovery.md`
+
+This note must identify:
+
+1. Where session creation happens.
+2. Where agent/session types are defined.
+3. Where input is sent into a session.
+4. Where active sessions are listed.
+5. Where session kill/delete is handled.
+6. How session state is stored.
+7. Whether there is existing persistence.
+8. Where backend routes live.
+9. Where frontend pages/components live.
+10. The smallest integration points for scheduling.
+
+Do not start coding until this discovery is complete.
+
+---
+
+## 13. Implementation Phases
+
+### Phase 1: Discovery
+
+Deliverable:
+
+- `docs/cron-discovery.md`
+
+Must answer the 10 discovery questions above.
+
+### Phase 2: Data Model / Persistence
+
+Deliverable:
+
+- Scheduled job persistence.
+- Scheduled run history persistence.
+- Basic create/read/update/delete operations.
+
+### Phase 3: Scheduler Calculation Logic
+
+Deliverable:
+
+- Functions to compute `next_run_at` for:
+  - once
+  - interval
+  - daily
+  - weekly
+
+Add tests if the repo has an existing test setup.
+
+### Phase 4: Manual Run Now
+
+Deliverable:
+
+- Create scheduled job.
+- Click Run Now.
+- Codeman session is created.
+- Prompt is sent.
+- Run history is recorded.
+- UI links to the session.
+
+This is the most important milestone.
+
+### Phase 5: Background Scheduler Loop
+
+Deliverable:
+
+- Enabled schedules launch automatically when due.
+- Run history is recorded.
+- `last_run_at` and `next_run_at` update.
+- Duplicate launch guard exists.
+
+### Phase 6: UI Polish Only After Functionality
+
+Deliverable:
+
+- Scheduled jobs list is readable.
+- Create/edit form is usable.
+- Status labels are clear.
+- Errors are visible.
+
+Do not polish before Phase 4 works.
+
+---
+
+## 14. Acceptance Criteria
+
+The build is acceptable when all these pass.
+
+### Manual Run
+
+1. Create a schedule/job with inline prompt.
+2. Click Run Now.
+3. A new Codeman/tmux session starts.
+4. Prompt is sent into that session.
+5. The created session is visible in Codeman's normal session UI.
+6. Run history shows success or failure.
+
+### One-Time Schedule
+
+1. Create a one-time schedule 2 minutes in the future.
+2. Wait for it to become due.
+3. Scheduler launches a session.
+4. Prompt is sent.
+5. Schedule does not repeatedly launch forever.
+
+### Interval Schedule
+
+1. Create interval schedule every 2 minutes.
+2. It launches once when due.
+3. It computes the next due time.
+4. It does not launch duplicates for the same due time.
+
+### Daily Schedule
+
+1. Create daily schedule at a time a few minutes ahead.
+2. It launches when due.
+3. Next run becomes tomorrow at the same time.
+
+### Disable Schedule
+
+1. Disable a schedule.
+2. It does not launch even when due.
+
+### Error Handling
+
+1. Invalid working directory produces visible error.
+2. Invalid prompt file produces visible error.
+3. Failed session launch creates failed run-history entry.
+
+---
+
+## 15. Explicitly Out of Scope for v0.1
+
+Do not implement these unless all required scope is already working:
+
+- Full quota engine.
+- Advanced lock manager.
+- Post-run git inspection reports.
+- Complex recurring calendar UI.
+- User accounts / RBAC.
+- External distributed workers.
+- Redis.
+- Postgres.
+- Celery.
+- Kubernetes.
+- A separate Python service.
+- Full visual cron editor.
+- AI-generated follow-up prompts.
+- Automatic continuation after idle.
+- Any attempt to bypass agent quotas or platform limits.
+
+---
+
+## 16. Quality Rules
+
+Follow these rules while coding:
+
+1. Reuse existing Codeman services and conventions.
+2. Keep scheduler code isolated.
+3. Prefer boring, readable code over clever abstractions.
+4. Add error messages that a human can understand.
+5. Do not break existing Codeman sessions.
+6. Do not rename existing core concepts unnecessarily.
+7. Do not introduce large dependencies without strong reason.
+8. Keep v0.1 local-first and single-instance.
+9. Commit in logical chunks if git is available.
+10. After coding, provide a final implementation summary.
+
+---
+
+## 17. Final Response Required from Claude Code
+
+At the end, report:
+
+1. Files changed.
+2. New routes/pages added.
+3. New data structures added.
+4. How the scheduler loop works.
+5. How to run the app.
+6. How to test manual Run Now.
+7. How to test scheduled execution.
+8. Known limitations.
+9. Suggested v0.2 improvements.
+
+---
+
+## 18. v0.2 Ideas, Not for Current Build
+
+Keep these in mind but do not build unless v0.1 is complete:
+
+- Quota-aware scheduling.
+- Manual takeover locks.
+- Post-idle inspection.
+- Git diff reports.
+- Schedule groups.
+- Prompt templates.
+- Agent-specific concurrency rules.
+- Better timezone support.
+- Audit events.
+- More advanced cron expressions.
+
+---
+
+## 19. Final Reminder
+
+The goal is to add **scheduling** to Codeman quickly and cleanly.
+
+Do not drift into building a new platform.
+
+The highest-priority path is:
+
+1. Discover existing Codeman integration points.
+2. Add scheduled job persistence.
+3. Add Run Now.
+4. Add background due-job loop.
+5. Add minimal UI.
+6. Verify that scheduled jobs create real Codeman/tmux sessions and send prompts.
+
@@ -0,0 +1,138 @@
+# CRON_DISCOVERY.md
+
+Phase 1 deliverable for the "Add Scheduling to Codeman" build brief.
+This documents the existing Codeman architecture and the smallest integration
+points for a cron. **No session/tmux logic will be rebuilt** —
+the new code is purely a trigger + persistence + history layer on top of the
+existing primitives.
+
+Stack: `aicodeman` v1.2.1 — Fastify 5 backend, `node-pty` + tmux sessions,
+vanilla-JS SPA frontend served as static assets, JSON file state store, zod
+validation, ports-based dependency injection.
+
+---
+
+## 0. Critical finding: an existing `ScheduledRun` is NOT a cron
+
+Codeman already has a `ScheduledRun` concept (`/api/scheduled`,
+`src/web/ports/infra-port.ts:14-26`, `src/web/server.ts:1480-1605`). It is a
+**run-now, duration-bounded autonomous loop**: given `{prompt, workingDir,
+durationMinutes}` it immediately spawns/kills throwaway sessions in a loop until
+the duration elapses. It has **no** time-based triggering, recurrence
+(once/interval/daily/weekly), enable/disable, next-run calculation, run history,
+or persistence across restarts.
+
+Therefore the brief's core (the calendar/cron trigger layer) does **not** exist
+and must be built. The execution primitives it sits on top of **do** exist and
+will be reused. To honor brief §16 ("do not rename existing core concepts"), the
+new feature is named **`CronJob`** (with **`CronJobRun`** history
+records), kept distinct from the existing `ScheduledRun`.
+
+---
+
+## 1. Where session creation happens
+
+- Canonical create flow: `POST /api/sessions`,
+  `src/web/routes/session-routes.ts:262-438`.
+  - `new Session({ workingDir, mode, ... })` (`src/session.ts:421-570`)
+  - `ctx.addSession(session)` → `ctx.setupSessionListeners(session)` →
+    `ctx.persistSessionState(session)` (all via `SessionPort`).
+- `SessionPort` interface: `src/web/ports/session-port.ts:8-16`.
+- **Integration point:** the cron service will mirror this exact sequence
+  (create → addSession → setupSessionListeners → start) via `SessionPort`,
+  not reimplement it.
+
+## 2. Where agent/session types are defined
+
+- `type SessionMode = 'claude' | 'shell' | 'opencode' | 'codex' | 'gemini'`
+  (`src/types/session.ts:43-44`). `shell` covers the brief's "Terminal/custom".
+- CLI availability resolvers in `src/utils/{claude,codex,gemini,opencode}-cli-resolver.ts`.
+- **Integration point:** the job's `agentType` reuses `SessionMode` verbatim.
+
+## 3. Where input is sent into a session
+
+- Raw / paste: `session.write(data)` (`src/session.ts:2243-2247`) — direct PTY write.
+- Typed (recommended): `session.writeViaMux(data)` (`src/session.ts:2301-2311`)
+  — tmux `send-keys`, falls back to PTY. Submit requires trailing `\r`.
+- **Integration point:** prompt delivery uses `writeViaMux` (typed) by default,
+  `write` (paste) as the alternate `input_mode`.
+
+## 4. Where active sessions are listed
+
+- `ctx.sessions: ReadonlyMap<string, Session>` (`SessionPort`).
+- Filters: `Array.from(ctx.sessions.values()).filter(s => s.mode === X)` and
+  `.isBusy()` / `.isIdle()` (`src/session-manager.ts:220-247`).
+- **Integration point:** the §8 multi-session warning queries this map.
+
+## 5. Where session kill/delete is handled
+
+- `ctx.cleanupSession(sessionId, killMux?, reason?)`
+  (`SessionPort`; impl `src/web/server.ts:997-1152`). Underlying
+  `session.stop(killMux)` at `src/session.ts:2498-2585`.
+- The cron does **not** kill sessions it launches (the brief wants them
+  visible in the normal session UI); cleanup stays user-driven.
+
+## 6. How session state is stored / 7. Existing persistence
+
+- JSON file store: `~/.codeman/state.json` (+ `state-inner.json` for Ralph).
+  `StateStore` class `src/state-store.ts:71`; `AppState` interface
+  `src/types/app-state.ts:99-114`.
+- Pattern: declare a field on `AppState`, add typed get/set methods on
+  `StateStore` that mutate in-memory state and call the debounced `save()`
+  (500ms debounce, atomic temp-file+rename, `.bak` backup, circuit breaker).
+- **Integration point:** add `cronJobs?: Record<string, CronJob>` and
+  `cronJobRuns?: Record<string, CronJobRun>` to `AppState`, with
+  matching `StateStore` accessors. No new DB (brief §6 forbids Postgres/Redis).
+
+## 8. Where backend routes live
+
+- Route modules: `src/web/routes/*.ts`; barrel `src/web/routes/index.ts`;
+  registered in `WebServer.setupRoutes()` `src/web/server.ts:858-876` with a
+  single `ctx` object from `createRouteContext()` (`src/web/server.ts:553-613`)
+  that satisfies all port interfaces.
+- Validation: zod schemas in `src/web/schemas.ts`, applied via
+  `parseBody(Schema, req.body)` (`src/web/route-helpers.ts:101-111`).
+- Errors: `createErrorResponse(ApiErrorCode.X, msg)` / `ApiResponse`
+  (`src/types/api.ts`), auto-mapped to HTTP status by a `preSerialization` hook
+  (`src/web/server.ts:644-659`).
+- SSE: `ctx.broadcast(SseEvent.X, data)` (`EventPort`,
+  `src/web/sse-events.ts`); frontend mirror in `src/web/public/constants.js`.
+- **Integration point:** new `cron-routes.ts` registered alongside the
+  others; new zod schema; new `SseEvent` constants for job list/run changes.
+
+## 9. Where frontend pages/components live
+
+- Vanilla-JS SPA: single `src/web/public/index.html` + feature mixin files
+  (`Object.assign(CodemanApp.prototype, {...})`). API via `api-client.js`
+  (`_apiJson/_apiPost/_apiDelete`). Build = esbuild minify + content-hash, no
+  bundler (`scripts/build.mjs`).
+- UI is panels/modals toggled by JS classes; forms use `.form-row` / `.modal`
+  conventions (`styles.css`). SSE handler map in `app.js`.
+- **Integration point:** add a new `cron-ui.js` mixin + a panel/modal in
+  `index.html` + nav entry, following the orchestrator/respawn panel pattern.
+
+## 10. Background-loop pattern (for the due-checker)
+
+- Established pattern: `this.cleanup.setInterval(fn, intervalMs, {description})`
+  in `WebServer.start()` (`src/web/server.ts:~1942-1966`), auto-disposed in
+  `WebServer.stop()` via `this.cleanup.dispose()` (`src/web/server.ts:2336`).
+  RalphLoop (`src/ralph-loop.ts:268-286`) shows the self-rescheduling guard idiom.
+- **Integration point:** register a 30s cron tick via `cleanup.setInterval`;
+  no manual shutdown wiring needed.
+
+---
+
+## Smallest integration points (summary)
+
+| New piece | Reuses | Location |
+| --- | --- | --- |
+| `CronJob` / `CronJobRun` types | — (new) | `src/types/cron.ts` |
+| Persistence | `StateStore` / `AppState` | `src/types/app-state.ts`, `src/state-store.ts` |
+| Next-run time math | — (new, pure, unit-tested) | `src/cron/cron-time.ts` |
+| Launch + send prompt | `SessionPort` (`addSession`/listeners/`writeViaMux`) | `src/cron/cron-service.ts` |
+| Background due loop | `cleanup.setInterval` pattern | `src/cron/cron-loop.ts` |
+| Routes + schema | route/ports/zod/SSE patterns | `src/web/routes/cron-routes.ts`, `src/web/schemas.ts`, `src/web/sse-events.ts` |
+| UI | panel/modal/mixin conventions | `src/web/public/cron-ui.js`, `index.html` |
+
+Nothing in the session, tmux, persistence, routing, or SSE subsystems is
+rewritten — the cron is additive and calls existing services.