Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions .github/workflows/formal-verification.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
name: Formal Verification

on:
push:
branches:
- main
- master
pull_request:

jobs:
formal:
runs-on: ubuntu-latest
permissions:
contents: read
env:
TLA_TOOLS_VERSION: "1.8.0"
ALLOY_VERSION: "6.2.0"
steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup Java
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "17"

- name: Cache formal tools
uses: actions/cache@v4
with:
path: .ci-tools
key: ${{ runner.os }}-formal-tools-${{ env.TLA_TOOLS_VERSION }}-${{ env.ALLOY_VERSION }}

- name: Download formal tools
shell: bash
run: |
mkdir -p .ci-tools
if [ ! -f .ci-tools/tla2tools.jar ]; then
curl -fsSL -o .ci-tools/tla2tools.jar \
https://github.com/tlaplus/tlaplus/releases/download/v${TLA_TOOLS_VERSION}/tla2tools.jar
fi
if [ ! -f .ci-tools/alloy.jar ]; then
curl -fsSL -o .ci-tools/alloy.jar \
https://repo1.maven.org/maven2/org/alloytools/org.alloytools.alloy.dist/${ALLOY_VERSION}/org.alloytools.alloy.dist-${ALLOY_VERSION}.jar
fi

- name: Run TLA+ specifications
shell: bash
run: |
java -cp .ci-tools/tla2tools.jar tlc2.TLC -config core/spec/TaskLeaseProtocol.cfg core/spec/TaskLeaseProtocol.tla
java -cp .ci-tools/tla2tools.jar tlc2.TLC -config core/spec/TaskLifecycle.cfg core/spec/TaskLifecycle.tla
java -cp .ci-tools/tla2tools.jar tlc2.TLC -config core/spec/TaskCostConservation.cfg core/spec/TaskCostConservation.tla

- name: Run Alloy checks
shell: bash
run: |
java -jar .ci-tools/alloy.jar exec --command "check*" --output - --type none core/spec/task-structure.als
24 changes: 17 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ taskcore takes a different approach: **tasks are event streams, not records.** E
- **Invariant checking.** After every event, the system verifies 20+ structural invariants. If a bug would corrupt state, it's caught immediately — not discovered days later.
- **Safe concurrency.** Fence tokens prevent stale agents from making conflicting updates. The core rejects events from agents that no longer hold the lease.

The core is a pure TypeScript library with zero side effects. It doesn't spawn processes, make HTTP calls, or touch the filesystem (except SQLite). The middle layer adds the messy real-world stuff: process spawning, HTTP APIs, agent bridges.
The core is a pure TypeScript library with zero side effects. It doesn't spawn processes, make HTTP calls, or touch the filesystem (except SQLite). The runtime layer adds the messy real-world stuff: process spawning, HTTP APIs, worktrees, journals, and the `task` CLI.

## Architecture

Expand All @@ -25,12 +25,12 @@ The core is a pure TypeScript library with zero side effects. It doesn't spawn p
│ Pure state │ Daemon │
│ machine │ HTTP API │
│ (frozen) │ Dispatcher │
│ │ Bridges
│ │ Worktrees
│ 45 tests │ 9 tests │
└──────────────┴──────────────┘
▲ │
│ ▼
Event log Agent processes
Event log task CLI / agents
(SQLite) (openclaw agent)
```

Expand All @@ -56,11 +56,16 @@ The bridge between the pure core and the real world.
- **dispatcher.ts** — Priority-sorted dispatch, agent spawn, exit handling with exponential backoff
- **analysis.ts** — Auto-analysis: tasks with an assignee skip straight to execution
- **prompt.ts** — Prompt builder for work and review modes
- **mcp-bridge.ts** — MCP stdio server (JSON-RPC 2.0) for agents that use MCP tools
- **task-update-bridge.py** — CLI for agents to report status
- **delegate-bridge.py** — CLI for agents to create subtasks
- **journal.ts** — Task journal branches, merges, and failure-summary helpers
- **worktree.ts** — Journal/code worktree lifecycle
- **state-export.ts** — Dashboard compatibility export
- **migrate.ts** — One-shot migration from legacy `tasks.json` format

### CLI (`core/cli/` + repo root `task`)

- **task.ts** — Agent/user CLI over the daemon HTTP API; manages `.task` context, journal, review, and decomposition workflows
- **task** — Repo-local launcher that runs the built CLI or falls back to `tsx` in a source checkout

## Task Lifecycle

Every task follows a phase-based lifecycle:
Expand Down Expand Up @@ -112,6 +117,7 @@ Default: `127.0.0.1:18800`
| GET | `/health` | Health check + stats |
| GET | `/tasks` | List tasks (filters: `?phase=`, `?condition=`, `?terminal=`, `?full=true`) |
| GET | `/tasks/:id` | Get single task (full detail) |
| POST | `/tasks/:id/claim` | Atomically lease and start a task for an agent |
| GET | `/dispatchable` | List tasks ready for dispatch |
| POST | `/tasks` | Create task |
| POST | `/tasks/:id/events` | Submit raw event (fenced) |
Expand Down Expand Up @@ -151,6 +157,9 @@ curl -X POST http://127.0.0.1:18800/tasks \

# Check task state
curl http://127.0.0.1:18800/tasks/1

# Explore the CLI from this checkout
./task --help
```

### Environment Variables
Expand All @@ -163,6 +172,7 @@ curl http://127.0.0.1:18800/tasks/1
| `WORKSPACE_DIR` | `~/.openclaw/workspace` | Workspace root |
| `MAX_CONCURRENT` | 1 | Max concurrent agent dispatches |
| `TICK_INTERVAL_MS` | 2000 | Core tick interval (auto-events) |
| `DISPATCHER_ENABLED` | true | Enable built-in dispatcher loop (`true`/`false`) |
| `DISPATCH_INTERVAL_MS` | 10000 | Dispatch loop interval |
| `LEASE_TIMEOUT_MS` | 600000 | Default agent lease timeout |
| `AGENT_TIMEOUT_MS` | 600000 | Max agent runtime before SIGKILL |
Expand All @@ -189,7 +199,7 @@ npm run migrate -- --tasks-file /path/to/tasks.json --db /path/to/taskcore.db

### Near Term
- [ ] Worktree isolation for agents (each agent gets a git worktree)
- [ ] Structured decomposition via core events (currently flat `delegate`)
- [ ] Richer decomposition strategy/history as first-class core events
- [ ] Dashboard direct integration (query taskcore API instead of exporter)
- [ ] Snapshot pruning (keep only last N snapshots)

Expand Down
Loading