@cleocode/goal 0.0.0-stage → 0.9.0

package/src/engine/tick.ts

@@ -0,0 +1,207 @@
+// v0.7.0 - the `ocg tick` entry point: RECORD the turn, DECIDE, then act.
+//
+// CLEO's Stop dispatcher spawns `ocg tick` with the harness's Stop JSON on stdin
+// and reads JSON ONLY from stdout:
+//   {"decision":"block","reason":"<continuation>"}  keep the agent working
+//   {"final":false}                                 hold the session open
+//   anything else (including non-JSON, or nothing)  no live goal
+// Logs go to stderr. It runs only where `.opencode/goals/` exists.
+//
+// v0.6.0 made the tick decide; it was read-only, so nothing advanced the counters
+// the stall, recovery, wrap-up and claim decisions read - a goal could never be
+// driven to an end outside OpenCode. v0.7.0 records the turn first (through OCG's
+// own store, in the adapter's own shape) and RUNS the verification of a claim, so
+// a host-only goal can actually reach `complete`. Everything it records is what a
+// Stop-time observer can know or recover from the payload - never a guess, and a
+// missing payload, transcript or store is a stated degradation, not an error.
+
+import { existsSync } from "node:fs"
+import { join } from "node:path"
+import type { Contract } from "../contract/types"
+import { renderTailNote } from "../contract/render"
+import { budgetUse, setStatus, TERMINAL as TERMINAL_STATUSES, type RunState } from "./state"
+import { continuationTail, decide, type LoopLimits, type LoopSignals } from "./loop"
+import { recordTurn } from "./tick-record"
+import type { VerifyOutcome } from "../verify/pipeline"
+
+/** The plugin's own defaults, so a tick agrees with the adapter unless overridden. */
+export const TICK_LIMITS: LoopLimits = { blockerRepeats: 3, stallTurns: 3, recoveryAt: 2, backstopTurns: 200 }
+export const TICK_COOLDOWN_MS = 1_500
+/** CLEO caps a forwarded reason at 4000 characters. */
+export const REASON_CAP = 4_000
+
+/** The store surface the tick writes through - OCG's own store, never a hand edit. */
+export type TickStore = {
+  slugs: () => string[]
+  readRun: (slug: string) => RunState | undefined
+  writeRun: (state: RunState) => void
+  readContract: (slug: string) => { contract?: Contract; text: string } | undefined
+  ledger: (slug: string, event: Record<string, unknown> & { type: string }) => void
+  evidence: (slug: string, runId: string, name: string, data: unknown) => string
+}
+
+export type TickDeps = {
+  root: string
+  store: TickStore
+  /** The repository fingerprint now (git), or undefined when it cannot be taken. */
+  fingerprint?: () => string | undefined
+  /** Run the claim verification. Absent means the tick cannot finish a goal. */
+  verify?: (state: RunState, contract: Contract, contractText: string) => Promise<VerifyOutcome>
+  /** The raw harness Stop payload, when the harness passed one. */
+  payload?: string
+  readTranscript?: (path: string) => string | undefined
+  limits?: LoopLimits
+  cooldownMs?: number
+  now?: number
+}
+
+export type TickResult = {
+  /** Exactly what goes to stdout (empty when no goal is live). */
+  stdout: string
+  /** Lines for stderr. */
+  log: string[]
+}
+
+const BLOCK = (reason: string) => JSON.stringify({ decision: "block", reason })
+const HOLD = JSON.stringify({ final: false })
+const why = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/** The newest non-terminal run in the project, by `updatedAt`.
+ *
+ * An absent or unreadable store is a stated degradation, never an exception: a
+ * crash looks exactly like "no live goal" to the dispatcher (empty stdout), which
+ * would silently drop the run. If a record cannot be read we cannot rule out a
+ * live goal, so the caller HOLDS rather than printing nothing. */
+function liveRun(store: TickStore, log: string[]): { live?: RunState; unreadable: boolean } {
+  let slugs: string[]
+  try {
+    slugs = store.slugs()
+  } catch (error) {
+    log.push(`could not read the run store (${why(error)}); cannot rule out a live goal`)
+    return { unreadable: true }
+  }
+  let live: RunState | undefined
+  let unreadable = false
+  for (const slug of slugs) {
+    let state: RunState | undefined
+    try {
+      state = store.readRun(slug)
+    } catch (error) {
+      log.push(`could not read the run record for ${slug} (${why(error)}); cannot rule it out`)
+      unreadable = true
+      continue
+    }
+    if (!state?.slug || TERMINAL_STATUSES.includes(state.status)) continue
+    if (!live || (state.updatedAt ?? 0) > (live.updatedAt ?? 0)) live = state
+  }
+  return { live, unreadable }
+}
+
+export async function tick(deps: TickDeps): Promise<TickResult> {
+  const log: string[] = []
+  const now = deps.now ?? Date.now()
+  const limits = deps.limits ?? TICK_LIMITS
+  // Outside a goal project there is nothing to tick at all - print nothing.
+  if (!existsSync(join(deps.root, ".opencode", "goals"))) {
+    log.push("no .opencode/goals directory; nothing to tick")
+    return { stdout: "", log }
+  }
+  const { live, unreadable } = liveRun(deps.store, log)
+  if (!live && unreadable) {
+    log.push("a run record could not be read; cannot rule out a live goal - holding")
+    return { stdout: HOLD, log }
+  }
+  if (!live) {
+    log.push("no live goal here; nothing to tick")
+    return { stdout: "", log }
+  }
+  let read: { contract?: Contract; text: string } | undefined
+  try {
+    read = deps.store.readContract(live.slug)
+  } catch (error) {
+    log.push(`could not read the contract for ${live.slug} (${why(error)}); holding`)
+    return { stdout: HOLD, log }
+  }
+  if (!read?.contract) {
+    log.push(`goal ${live.slug} has no readable contract; holding`)
+    return { stdout: HOLD, log }
+  }
+  const contract = read.contract
+
+  // ── 1. RECORD the turn, through OCG's own store, in the adapter's own shape.
+  const record = recordTurn(live, contract, { fingerprint: deps.fingerprint ?? (() => undefined), ...(deps.payload ? { payload: deps.payload } : {}), ...(deps.readTranscript ? { readTranscript: deps.readTranscript } : {}), now })
+  deps.store.ledger(live.slug, {
+    type: "turn",
+    turn: live.turn,
+    kind: "tick",
+    tools: live.turnFacts.tools,
+    activity: live.turnFacts.tools > 0,
+    changed: record.changed,
+    progress: record.progress,
+    noProgress: live.counters.noProgress,
+  })
+  deps.store.writeRun(live)
+  log.push(`recorded turn ${record.turn} for ${live.slug} (${record.progress ? "progress" : "no progress"}${record.claimHonoured ? ", claim honoured" : ""})`)
+  for (const gap of record.couldNotSee) log.push(`could not see ${gap}`)
+
+  // ── 2. DECIDE, with the same pure function the OpenCode adapter uses.
+  const signals: LoopSignals = {
+    turn: "succeeded",
+    ...(live.pending ? { pending: live.pending.kind } : {}),
+    changed: record.changed,
+    progressRecorded: record.progress,
+    stepsChanged: false,
+    activeStalled: false,
+    stallReason: `stalled: no change the host could see for ${live.counters.noProgress} turns`,
+    onStall: contract.autonomy.on_stall,
+    budgetRatio: budgetUse(live, contract).ratio,
+    backstop: false,
+    cooldownMs: deps.cooldownMs ?? TICK_COOLDOWN_MS,
+    now,
+  }
+  const action = decide(live, signals, limits)
+
+  // ── 3. ACT.
+  switch (action.kind) {
+    case "verify": {
+      if (!deps.verify) {
+        log.push("a claim is pending but this tick cannot verify; holding")
+        return { stdout: HOLD, log }
+      }
+      live.claim = undefined
+      setStatus(live, "verifying", "tick verification")
+      deps.store.ledger(live.slug, { type: "verify-start", source: "claim", turn: live.turn })
+      deps.store.writeRun(live)
+      const outcome = await deps.verify(live, contract, read.text)
+      for (const r of outcome.results) live.criteria[r.id] = { status: r.pass ? "pass" : "fail", by: r.by, at: now, detail: r.detail.slice(0, 600), rejections: live.criteria[r.id]?.rejections ?? 0 }
+      live.verdict = { passed: outcome.passed, lines: outcome.lines.slice(0, 20), at: now, turn: live.turn }
+      deps.store.evidence(live.slug, live.runId, `verify-tick-${live.turn}`, outcome)
+      if (outcome.passed) {
+        setStatus(live, "complete", "all required criteria verified")
+        deps.store.ledger(live.slug, { type: "complete", turn: live.turn })
+        deps.store.writeRun(live)
+        log.push(`goal ${live.slug} complete: ${outcome.lines[0] ?? "all required criteria verified"}`)
+        return { stdout: "", log } // no live goal remains; the harness session may end
+      }
+      // Not proven: keep the run going and hand the agent the verdict.
+      setStatus(live, "running")
+      deps.store.writeRun(live)
+      log.push(`goal ${live.slug} did not pass verification: ${outcome.lines.slice(0, 2).join(" ").slice(0, 200)}`)
+      return { stdout: BLOCK(renderTailNote(live, contract, "verdict", now).slice(0, REASON_CAP)), log }
+    }
+    case "admit":
+    case "schedule": {
+      const tail = continuationTail(action)!
+      deps.store.writeRun(live)
+      const reason = renderTailNote(live, contract, tail, now).slice(0, REASON_CAP)
+      log.push(`goal ${live.slug}: decision ${action.kind}; continuing with the ${tail} continuation (${reason.length} chars)`)
+      return { stdout: BLOCK(reason), log }
+    }
+    default: {
+      if (action.kind === "stop") setStatus(live, action.status, action.reason)
+      deps.store.writeRun(live)
+      log.push(`goal ${live.slug}: decision ${action.kind}${action.kind === "stop" ? ` (${action.code})` : ""}; holding the session`)
+      return { stdout: HOLD, log }
+    }
+  }
+}

package/src/rpc.ts

@@ -0,0 +1,182 @@
+// Shared server↔TUI contract. A plain object (Rpc.define is an identity
+// function), so neither side needs @opencode/plugin at runtime.
+const anyObject = { type: "object", additionalProperties: true } as const
+import type { Handoff } from "./engine/state"
+import type { LaunchView } from "./engine/launches"
+export type { LaunchView } from "./engine/launches"
+// V2 RPC's schema adapter rejects regex patterns. Length is declared here;
+// the host validates hex syntax AND exact target identity before execution.
+const targetObject = { type: "object", properties: { key: { type: "string", minLength: 1, maxLength: 256 }, lock: { type: "string", minLength: 64, maxLength: 64 }, runId: { type: "string", minLength: 1, maxLength: 128 }, sessionID: { type: "string", minLength: 1, maxLength: 256 } }, required: ["key", "lock"], additionalProperties: false } as const
+
+export const GoalRpc = {
+  id: "opencode-goal",
+  methods: {
+    provenance: {
+      input: { type: "object", properties: { sessionID: { type: "string", minLength: 1, maxLength: 256 } }, additionalProperties: false },
+      output: anyObject,
+    },
+    snapshot: {
+      input: { type: "object", properties: { sessionID: { type: "string", minLength: 1, maxLength: 256 } }, required: ["sessionID"], additionalProperties: false },
+      output: anyObject,
+    },
+    list: {
+      input: { type: "object", properties: {}, additionalProperties: false },
+      output: anyObject,
+    },
+    details: {
+      input: { type: "object", properties: { key: { type: "string", minLength: 1, maxLength: 256 } }, required: ["key"], additionalProperties: false },
+      output: anyObject,
+    },
+    review: {
+      input: { type: "object", properties: { sessionID: { type: "string", minLength: 1, maxLength: 256 }, decisionId: { type: "string", minLength: 1, maxLength: 256 } }, required: ["sessionID"], additionalProperties: false },
+      output: anyObject,
+    },
+    manage: {
+      input: { type: "object", properties: { sessionID: { type: "string", minLength: 1, maxLength: 256 }, action: { type: "string", enum: ["pause", "resume", "verify", "attach", "abort", "archive"] }, target: targetObject }, required: ["sessionID", "action", "target"], additionalProperties: false },
+      output: anyObject,
+    },
+    act: {
+      input: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string", minLength: 1, maxLength: 256 },
+          action: { type: "string", enum: ["pause", "resume", "abort", "verify", "approve", "reject", "amend", "archive", "attach", "start", "start-next", "decompose"] },
+          arg: { type: "string", maxLength: 2000 },
+          decisionId: { type: "string", minLength: 1, maxLength: 256 },
+        },
+        required: ["sessionID", "action"],
+        additionalProperties: false,
+      },
+      output: anyObject,
+    },
+  },
+  events: {
+    handoff: { schema: { type: "object", properties: { fromSessionID: { type: "string" }, toSessionID: { type: "string" }, slug: { type: "string" }, runId: { type: "string" }, fallback: { type: "string" } }, required: ["fromSessionID", "toSessionID", "slug", "runId"], additionalProperties: false } },
+    updated: { schema: { type: "object", properties: { sessionID: { type: "string" }, view: anyObject }, required: ["sessionID"], additionalProperties: true } },
+    notice: { schema: { type: "object", properties: { sessionID: { type: "string" }, level: { type: "string" }, text: { type: "string" }, attention: { type: "string" } }, required: ["text"], additionalProperties: true } },
+    summary: { schema: { type: "object", properties: { sessionID: { type: "string" }, slug: { type: "string" }, status: { type: "string" }, headline: { type: "string" }, title: { type: "string" }, digest: { type: "string" }, text: { type: "string" } }, required: ["sessionID", "text"], additionalProperties: true } },
+    decision: {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          slug: { type: "string" },
+          kind: { type: "string", enum: ["needs_review", "paused-after-verdict", "blocked", "budget_limited", "amend-proposed", "supersede-ack", "complete", "start-picker", "owner-operation"] },
+          title: { type: "string" },
+          message: { type: "string" },
+          question: { type: "string" },
+          expiresAt: { type: "number" },
+          choices: { type: "array", items: { type: "object", properties: { label: { type: "string" }, act: { type: "string" }, arg: { type: "string" }, run: { type: "string" } }, required: ["label"], additionalProperties: true } },
+        },
+        required: ["sessionID", "kind", "message", "choices"],
+        additionalProperties: true,
+      },
+    },
+    // T075: whichever surface answered a decision (native form or TUI
+    // dialog) — live TUIs close their open dialog on it (suppression).
+    "decision.resolved": {
+      schema: {
+        type: "object",
+        properties: {
+          sessionID: { type: "string" },
+          kind: { type: "string" },
+          decisionId: { type: "string" },
+          via: { type: "string", enum: ["form", "dialog", "form-guidance", "amendment-invalidated"] },
+        },
+        required: ["sessionID", "kind", "via"],
+        additionalProperties: true,
+      },
+    },
+    "decision.failed": {
+      schema: { type: "object", properties: { sessionID: { type: "string" }, decisionId: { type: "string" }, message: { type: "string" } }, required: ["sessionID", "decisionId", "message"], additionalProperties: false },
+    },
+  },
+} as const
+
+export type CriterionView = {
+  id: string
+  statement: string
+  essential: boolean
+  invariant: boolean
+  kind: string
+  status: "unknown" | "pass" | "fail" | "claimed"
+  by?: string
+  detail?: string
+  at?: number
+}
+
+export type TimelineEntry = { t: number; kind: string; text: string }
+
+export type GoalView = {
+  slug: string
+  title: string
+  outcome: string
+  status: string
+  reason?: string
+  runId: string
+  /** Actual run identity for correlating admission attempts, not version labels. */
+  sessionID?: string
+  lock?: string
+  /** T106: the tuple goal_manage accepts, so a caller never loses a round to
+   * discovery after a generation change — key, runId, sessionID and lock. */
+  target?: GoalTarget
+  turn: number
+  timeline: TimelineEntry[]
+  activeMs: number
+  activeSince: number | null
+  usage: { tokens: number; cost: number }
+  budget: Array<{ name: string; used: number; limit: number }>
+  budgetRatio: number
+  criteria: CriterionView[]
+  steps: Array<{ id: string; title: string; status: string }>
+  progress?: { note: string; next?: string; at: number; turn: number }
+  verdict?: { passed: boolean; lines: string[]; at: number; turn: number }
+  blocker?: { key: string; count: number; reason: string; needs?: string }
+  wait?: { until: number; reason: string }
+  awaitingUser: boolean
+  /** T052: persistent owner-action-required state — stays until the status resolves. */
+  actionRequired?: string
+  /** T053: what the engine is doing now — the live activity tracer's feed. */
+  activity?: { kind: "turn" | "verifying" | "verifier-child" | "cooldown" | "waiting"; since: number; until?: number; detail?: string }
+  amendments: number
+  flags: number
+  updatedAt: number
+}
+
+export type GoalSummary = {
+  slug: string
+  title: string
+  status: string
+  priority?: "low" | "medium" | "high"
+  sessionID?: string
+  proven: number
+  total: number
+  terminal?: boolean
+  attachable?: boolean
+  /** Distinguishes live and archived generations even if their slugs match. */
+  key?: string
+  archived?: boolean
+  valid?: boolean
+  runId?: string
+  lock?: string
+  updatedAt?: number
+  outcome?: string
+  progress?: RunProgress
+  turn?: number
+  steps?: Array<{ id: string; title: string; status: string }>
+  /** Raw existing contract metadata: never inferred from CLEO task IDs. */
+  meta?: Record<string, unknown>
+  supersedes?: string
+  configuredAgent?: string
+  agent?: string
+  sessionTitle?: string
+  sessionState?: "present" | "elsewhere" | "missing" | "unknown" | "unassigned"
+  issues?: string[]
+  details?: { criteria: CriterionView[]; constraints: string[]; nonGoals: string[] }
+  handoff?: Handoff
+  /** Latest exact launch review/admission receipt, distinct from run status. */
+  launch?: LaunchView
+}
+export type GoalTarget = { key: string; lock: string; runId?: string; sessionID?: string }
+export type ManageAction = "pause" | "resume" | "verify" | "attach" | "abort" | "archive"
+type RunProgress = { note: string; next?: string; at: number; turn: number }