contracts v0.2.0: engine steps, approval.requested, provider status

- Events: step.started/finished, permission.denied, provider.status, approval.requested
- ENGINE_STEPS, PROVIDER_STATES; StartOptions allows "codehands" and models?
- Project.repoKey?, Session.updatedAt? (optional, local-first)
- README: new events, approve/reject outcomes. Tests for event order.

Author: imtahirabatool

README.md

@@ -103,8 +103,15 @@ interface RunnerEvent {
 | `task.finished` | The agent finished. Now awaiting approval | `total_cost_usd`, `usage`, `num_turns`, `result`, `diffStat` |
 | `task.failed` | The run cannot continue | `reason`, plus details |
 | `task.stopped` | A person stopped it | |
+| `step.started` | v0.2.0. The engine began a step | `step` |
+| `step.finished` | v0.2.0. The engine ended a step | `step`, `ok`, `costUsd?` |
+| `permission.denied` | v0.2.0. The agent tried something and was blocked | `tool`, `reason`, `input?` |
+| `provider.status` | v0.2.0. The model provider can't serve the run | `state`, `message`, `code?` (HTTP status or CLI error), `retryAt?` |
+| `approval.requested` | v0.2.0. Sent right after `task.finished`. The session is now `awaiting_approval` | `diffStat` |
 
-Payloads are open on purpose in v0.1.0. The fields above are what the runner sends today; read them defensively.
+Payloads are open on purpose. The fields above are what the runner sends today; read them defensively.
+
+`step` is one of `ENGINE_STEPS`: `analyze`, `plan`, `implement`, `test`, `review`, always in that order. `state` is one of `PROVIDER_STATES`: `rate_limited`, `auth_expired`, `usage_limit`, `subscription_inactive`, `down`.
 
 ### The `Runner` interface
 
@@ -124,12 +131,24 @@ interface StartOptions {
   sessionId: string;    // a UUID, also reused as Claude Code's --session-id
   repoPath: string;
   prompt: string;
-  agent: "claude-code" | "codex";
-  model?: string;
+  agent: "claude-code" | "codex" | "codehands"; // "codehands" (the engine) since v0.2.0
+  model?: string;       // one model for the whole run
+  models?: Partial<Record<StepName, string>>;   // v0.2.0: per engine step, e.g. { plan: "claude-opus-5-5" }
   budgetUsd?: number;
 }
 ```
 
+A step with no entry in `models` uses `model`.
+
+`approve` and `reject` send no event. The promise is the outcome:
+
+| Call | Resolves | Throws |
+| --- | --- | --- |
+| `approve` | Committed on the task's branch, worktree removed. Status `approved` | The status stays `awaiting_approval`. The error says why (for example, the agent changed nothing) |
+| `reject` | Worktree and branch deleted. Status `rejected` | The status stays `awaiting_approval`. The error says why |
+
+The daemon writes the new status and records the outcome itself.
+
 `start` and `resume` return an async iterable, so the caller just loops:
 
 ```ts
@@ -140,16 +159,16 @@ for await (const event of runner.start(options)) {
 
 ## Contracts still to write
 
-The design in [codehands-docs](https://github.com/devweekends/codehands-docs#contracts) names four contracts. v0.1.0 covers C5 and the first half of C2. The rest arrive as minor versions.
+The design in [codehands-docs](https://github.com/devweekends/codehands-docs#contracts) names four contracts. The rest arrive as minor versions.
 
-| ID | Contract | In v0.1.0 | Still to add | Owner |
+| ID | Contract | Done so far | Still to add | Owner |
 | --- | --- | --- | --- | --- |
 | L1 | Local DB: the tables in `~/.codehands/state.db` and which process may write each | No | Table types for `tasks`, `commands`, `sessions`, `events`, `provider_status`, and the writer of each | Midhat |
-| C2 | Runner | `Runner`, `StartOptions`, events | Model per phase, preferences and memory in `StartOptions`; a `provider.status` event | Tahira |
-| C3 | Cloud API | No | Sign up, log in, log out, device tokens; `push(changes)`, `pull(cursor)`; record versions | Memoona |
-| C5 | Sessions | Yes | `Project` keyed by repo identity (a hash of the origin URL) instead of a folder path | Midhat, Tahira |
+| C2 | Runner | `Runner`, `StartOptions`, events. v0.2.0: engine steps, model per step, `permission.denied`, `provider.status` | Preferences and memory in `StartOptions` | Tahira |
+| C3 | Cloud API | Yes: sign up, log in, log out, devices, `push`, `pull` (`cloud-api.ts`) | | Memoona |
+| C5 | Sessions | Yes. v0.2.0: `Project.repoKey`, `Session.updatedAt` | Make `repoKey` and `updatedAt` required once every writer sets them | Midhat, Tahira |
 
-The provider failure states the C2 event will carry are fixed already: `rate_limited`, `auth_expired`, `usage_limit`, `subscription_inactive`, `down`. Their meaning is in the [docs README](https://github.com/devweekends/codehands-docs#provider-failures).
+The meaning of each provider failure state is in the [docs README](https://github.com/devweekends/codehands-docs#provider-failures).
 
 ## Using it from another repo
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehands/contracts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared types, event names and session states for Code Hands AI",
   "type": "module",
   "main": "dist/index.js",

src/runner.ts

@@ -14,9 +14,29 @@ export const RUNNER_EVENT_TYPES = [
   "task.finished",
   "task.failed",
   "task.stopped",
+  // v0.2.0
+  "step.started",           // { step: StepName }. Only the engine sends it
+  "step.finished",          // { step: StepName, ok: boolean, costUsd?: number }
+  "permission.denied",      // { tool, reason, input? }. The agent wanted to do something and was blocked
+  "provider.status",        // { state: ProviderState, message, code?, retryAt?: ISO time }. code: HTTP status or CLI error
+  "approval.requested",     // { diffStat }. Right after task.finished: the session is now awaiting_approval
 ] as const;
 export type RunnerEventType = (typeof RUNNER_EVENT_TYPES)[number];
 
+// The engine's steps, in order (agent: "codehands").
+export const ENGINE_STEPS = ["analyze", "plan", "implement", "test", "review"] as const;
+export type StepName = (typeof ENGINE_STEPS)[number];
+
+// Why the model provider can't serve a run right now. Meanings: codehands-docs#provider-failures.
+export const PROVIDER_STATES = [
+  "rate_limited",
+  "auth_expired",
+  "usage_limit",
+  "subscription_inactive",
+  "down",
+] as const;
+export type ProviderState = (typeof PROVIDER_STATES)[number];
+
 export interface RunnerEvent {
   sessionId: string;
   seq: number;              // 1, 2, 3 … per session. Lets the phone catch up after a reconnect
@@ -30,8 +50,9 @@ export interface StartOptions {
   sessionId: string;        // UUID from the server, reused as Claude's --session-id
   repoPath: string;
   prompt: string;
-  agent: Exclude<AgentKind, "codehands">;
-  model?: string;
+  agent: AgentKind;         // v0.2.0: "codehands" (the engine) is allowed
+  model?: string;           // one model for the whole run
+  models?: Partial<Record<StepName, string>>; // v0.2.0: model per engine step, falls back to model
   budgetUsd?: number;
 }
 

src/session.ts

@@ -1,4 +1,5 @@
 // Rows the state API stores (Midhat) and the apps read (Tania, Memoona).
+// Local-first (v0.2.0): the real rows live in the daemon's ~/.codehands/state.db, the cloud keeps a synced copy.
 
 export type SessionStatus =
   | "queued"
@@ -13,7 +14,13 @@ export type AgentKind = "claude-code" | "codex" | "codehands";
 export type CommandKind = "start" | "stop" | "resume" | "approve" | "reject";
 
 export interface Device { id: string; userId: string; name: string; lastSeenAt: string }
-export interface Project { id: string; deviceId: string; name: string; path: string }
+export interface Project {
+  id: string;
+  deviceId: string;
+  name: string;
+  path: string;             // a folder on this machine. Never synced
+  repoKey?: string;         // v0.2.0: first 12 chars of sha1(origin url or path). Same on every machine, safe to sync
+}
 
 export interface Session {
   id: string;
@@ -26,6 +33,7 @@ export interface Session {
   baseCommit?: string;
   diff?: string;
   createdAt: string;
+  updatedAt?: string;       // v0.2.0: set on every change. Sync keeps the newer copy
 }
 
 export interface Command {

test/session.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { canTransition, RUNNER_EVENT_TYPES } from "../src/index.js";
+import { canTransition, ENGINE_STEPS, PROVIDER_STATES, RUNNER_EVENT_TYPES } from "../src/index.js";
 
 describe("session transitions", () => {
   it("allows the happy path", () => {
@@ -23,4 +23,21 @@ describe("event names", () => {
   it("has no duplicates", () => {
     expect(new Set(RUNNER_EVENT_TYPES).size).toBe(RUNNER_EVENT_TYPES.length);
   });
+
+  it("keeps every v0.1.0 event, in the same order", () => {
+    expect(RUNNER_EVENT_TYPES.slice(0, 10)).toEqual([
+      "task.started", "message", "file.read", "file.changed", "command.started",
+      "command.finished", "test.result", "task.finished", "task.failed", "task.stopped",
+    ]);
+  });
+});
+
+describe("engine steps and provider states", () => {
+  it("runs the engine steps in order", () => {
+    expect(ENGINE_STEPS).toEqual(["analyze", "plan", "implement", "test", "review"]);
+  });
+
+  it("has no duplicate provider states", () => {
+    expect(new Set(PROVIDER_STATES).size).toBe(PROVIDER_STATES.length);
+  });
 });