Skip to content

feat: Schedules - #472

Merged
heerambavi1998 merged 35 commits into
mainfrom
ha/schedules
Aug 28, 2026
Merged

heerambavi1998 merged 35 commits into
mainfrom
ha/schedules

Conversation

@heerambavi1998

@heerambavi1998 heerambavi1998 commented Aug 27, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds first-class cron schedules for existing agents: persist them, manage them via /api/v1/schedules, validate cron policy at write time, and advance due runs through a single-dispatcher claim path.

What's included

  • Schema (SQLite + Postgres): schedule + schedule_run, with:
    • agent FK cascade, run FK cascade
    • at most one pending run per schedule (schedule_run_pending_uq)
    • unique run names (sched:<unixSeconds>)
    • due index over scheduled rows
  • Store: IScheduleStore with SQLite/Postgres implementation
    • create/list/get/update/pause/resume schedule
    • create/delete/find pending run, trigger, finish runs)
  • API: CRUD + pause/resume under /api/v1/schedules
    • create/resume/put add schedule + pending run in one transaction
    • pause drops the pending run; delete cascades
    • agent binding is immutable after create
  • Manifest: { task, cron, timezone } — 5-field cron in an IANA zone
    • Write-time policy: next fire must exist,
    • expression must recur
    • minimum interval 1h
  • Dispatch core: dispatchDueRuns — re-read schedule in-txn, mark late runs missed, arm next slot, hand off triggered runs after the pass commits; single-dispatcher assumption (no row claim)

Design notes

  • Schedule identity is columns; schedule-shaped fields live in Zod-validated manifest (same pattern as agents/skills).
  • Runs execute as schedule.created_by; triggered_by is that userRef.
  • Lateness bound (SCHEDULE_MAX_LATENESS_SECONDS, 1h): overdue slots are recorded missed and the series advances rather than firing a stale backlog.
  • Pause/resume/put can race dispatch; uniqueness on the pending row prevents double-arming (conflict + retry on the API side).

How was this tested?

  • unit coverage for cron next-fire / min-interval / validateManifest
  • DB store tests
  • Manual testing for schedule APIs

Checklist

  • I have read the contributing guidelines
  • pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
  • Tests added/updated where it makes sense
  • No hand-edits to generated code (packages/trueforge-sdk, .github/fern/openapi/openapi.json, docs/openapi.json) — fork PRs omit SDK regen; maintainers regenerate after merge
  • Docs / .env.example updated if configuration or behavior changed

Note

Medium Risk
New background dispatch and transactional schedule/run state interact with API updates (409 races); triggered runs do not execute agents yet, so behavior is incomplete until an executor lands.

Overview
Introduces first-class cron schedules that bind to existing agents by name, send a fixed task message on each run, and are managed through new authenticated /api/v1/schedules CRUD endpoints (optional agent_name filter on list). Manifests carry 5-field cron, IANA timezone (default UTC), and active/paused status; writes run validateManifest (valid next fire, minimum 1 hour between triggers) and map InvalidCronError to 400. Create/update run in transactions that sync a single pending schedule_run when status/cron/timezone change; conflicts surface as 409 for retry.

Persistence adds schedule and schedule_run tables (Postgres + SQLite migrations) with agent FK cascade, one pending run per schedule, and dispatch-friendly indexes. IScheduleStore is wired into the server and OpenAPI/docs; the Fern trueforge-sdk gains a client.schedules resource.

A Controller runs a ~60s schedule-dispatch loop: in standalone it lives in the server process; in distributed mode a dedicated src/controller.ts entry point owns it (single replica). Due runs are handed to onTriggered (currently logTriggeredRun only—runs are marked triggered/failed and the next slot is armed; real agent execution is still TODO).

Reviewed by Cursor Bugbot for commit dc2b4bf. Bugbot is set up for automated code reviews on this repo. Configure here.

@changeset-bot

changeset-bot Bot commented Aug 27, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: dc2b4bf

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages
Name Type
@truefoundry/trueforge-sdk Patch
@truefoundry/trueforge Minor
frontend Patch
@truefoundry/trueforge-ui Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@heerambavi1998
heerambavi1998 force-pushed the ha/schedules branch 2 times, most recently from 471fa8e to 6fdbf57 Compare August 27, 2026 18:59
Comment thread packages/trueforge/src/main.ts Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 816f3fc. Configure here.

Comment thread packages/trueforge/src/runtime/cron.ts Resolved
@heerambavi1998
heerambavi1998 enabled auto-merge (squash) August 28, 2026 07:38
@heerambavi1998
heerambavi1998 merged commit a3a1395 into main Aug 28, 2026
9 checks passed
@heerambavi1998
heerambavi1998 deleted the ha/schedules branch August 28, 2026 08:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants