opencode-turnstile 0.0.0-stage → 0.1.0

package/src/types.ts

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Shared type definitions for the turnstile plugin: the
+ * OpenCode v2 host wire shape, hook payloads, and gate-state structures.
+ *
+ * The host boundary is intentionally permissive: payloads crossing the
+ * plugin boundary are typed as optional fields so a host that omits or
+ * reshapes a field fails open instead of failing hard.
+ */
+
+/** Task dispatch input as delivered by the host's `task`/`subagent` tools. */
+export interface TaskInput {
+  subagent_type?: unknown
+  agent?: unknown
+  subagent?: unknown
+  prompt?: unknown
+  description?: unknown
+  command?: unknown
+  cmd?: unknown
+}
+
+/** Tool result as delivered by the host's `execute.after` hook. */
+export interface ToolResult {
+  output?: unknown
+  title?: unknown
+  input?: unknown
+  metadata?: { exit?: unknown; exitCode?: unknown; code?: unknown }
+}
+
+/** Payload of the `tool.execute.before` and `tool.execute.after` hooks. */
+export interface ToolHookEvent {
+  tool?: unknown
+  sessionID?: unknown
+  input?: TaskInput
+  result?: ToolResult
+}
+
+/** Payload of the `session.prompt` hook. */
+export interface PromptHookProperties {
+  sessionID?: unknown
+}
+
+/** Generation draft passed to the `session.generate` hook. */
+export interface GenerateDraft {
+  agent?: unknown
+  options?: { temperature?: number }
+}
+
+/** Compaction draft passed to the `session.compaction` hook. */
+export interface CompactionDraft {
+  system?: Array<{ type: string; text?: string }>
+}
+
+/** Session record returned by the host's `session.get`. */
+export interface SessionRecord {
+  parentID?: unknown
+  data?: { parentID?: unknown }
+}
+
+/** Properties bag carried by host stream events. */
+export interface EventProperties {
+  type?: unknown
+  sessionID?: unknown
+  parentID?: unknown
+  directory?: unknown
+  location?: { directory?: unknown }
+  part?: { type?: unknown; text?: unknown; sessionID?: unknown }
+  text?: unknown
+  delta?: unknown
+  error?: unknown
+}
+
+/** A single host stream event delivered by `event.subscribe`. */
+export interface StreamEvent {
+  type: string
+  data?: EventProperties
+  properties?: EventProperties
+}
+
+/** Gate state for one parent session. */
+export interface GateState {
+  hasGatePass: boolean
+  /** True when this task's plan has a current plan-reviewer APPROVE. */
+  hasPlanVerdict: boolean
+  verdicts: string[]
+  reviewRounds: number
+  reads: number
+  seen: Set<string>
+}
+
+/** One first-sight marker observation returned by the marker parser. */
+export interface MarkerEvent {
+  kind: "gate" | "verdict"
+  marker: string
+  result?: "PASS" | "FAIL"
+  rounds?: number
+  /** Marker matches observed in the same text but not journaled
+   *  (latest-wins policy); 0 when this was the only match. */
+  suppressed: number
+}
+
+/** Agent names turnstile recognizes in dispatches and generation drafts. */
+export interface TurnstileAgents {
+  reviewer: string
+  /** Plan reviewer: adversarial review of the implementation plan. */
+  planReviewer: string
+  executor: string
+  testRunner: string
+  debugger: string
+  /** Agents contracted to emit GATE/VERDICT markers (bare-output check). */
+  bareOutput: string[]
+}
+
+/**
+ * Layered plugin configuration. Defaults in `src/config.ts`; user overrides
+ * via `~/.config/opencode/turnstile.json`, then env vars, then injected
+ * options (tests). Read once at setup; restart sessions to apply.
+ */
+export interface TurnstileConfig {
+  /** Directory holding the JSONL journal and trace files. */
+  metricsDir: string
+  /** Rotate a journal file when it exceeds this many bytes. */
+  journalMaxBytes: number
+  /** Number of rotated journal generations to keep. */
+  journalMaxGenerations: number
+  /**
+   * Max reviewer dispatches per task; the cap counts dispatches, applies
+   * regardless of gate state, and is bypassed by an explicit waiver.
+   */
+  maxReviewerRounds: number
+  /** Cap on tracked sessions (LRU); oldest state evicted beyond this. */
+  maxSessions: number
+  /** Whole-file read count at which the horizon warning is injected. */
+  readWarn: number
+  /** Whole-file read count at which further reads are blocked. */
+  readBlock: number
+  /** Literal marker that waives the reviewer gate when in the prompt. */
+  waiverMarker: string
+  /** Project-relative directory scanned for `## Decomposition` plans. */
+  plansDir: string
+  /** Whether the human-readable trace file is written (JSONL journal always). */
+  trace: boolean
+  /** Agent names turnstile recognizes. */
+  agents: TurnstileAgents
+  /** Gate marker regex source (compiled with `gm`). */
+  gateMarker: string
+  /** Verdict marker regex source (compiled with `gm`). */
+  verdictMarker: string
+}
+
+/** Options accepted by the plugin factory; tests inject config and env here. */
+export interface TurnstileOptions {
+  /** Overrides applied last, on top of file and env layers. */
+  config?: Partial<TurnstileConfig>
+  /** Environment for config resolution; defaults to `process.env`. */
+  env?: Record<string, string | undefined>
+}
+
+/**
+ * The v2 promise-plugin host shape (verified against opencode v2.0.22).
+ *
+ * Hook callback payloads are typed `any` at this wire boundary only; the
+ * host does not expose stable payload types. Every function turnstile
+ * defines has concrete parameter and return types; the `any` ends here.
+ */
+export type Host = {
+  tool?: {
+    hook?: (name: string, cb: (event: any) => Promise<void> | void) => Promise<unknown>
+  }
+  session?: {
+    hook?: (name: string, cb: (input: any) => Promise<void> | void) => Promise<unknown>
+    get?: (input: { sessionID: string }, options?: any) => Promise<SessionRecord | undefined>
+  }
+  event?: {
+    subscribe?: (options?: { signal?: AbortSignal }) => AsyncIterable<StreamEvent>
+  }
+}

package/templates/global-AGENTS.md

@@ -0,0 +1,55 @@
+<!-- turnstile:start (managed block — edit templates/global-AGENTS.md in the
+     turnstile repo, then rerun the installer; do not edit in place) -->
+
+## Turnstile pipeline gates
+
+Order: planner → plan-reviewer → executor → test-runner → reviewer. This
+file is the source of truth for policy; the `turnstile` plugin (installed
+at `~/.config/opencode/plugins/turnstile.ts`) enforces it mechanically.
+Enforcement mechanics (regexes, thresholds, journals) are canonical in
+turnstile's README; if prose here diverges from enforcement, trust the
+plugin and fix this file. Advisory only if the plugin is absent.
+
+Plan gate: dispatch `executor` only after this task's plan-reviewer first
+line is `VERDICT: APPROVE crit=<n> high=<n> med=<n> low=<n>`, or after an
+explicit user waiver. Plan-file changes invalidate the approval — after a
+re-plan, dispatch plan-reviewer again before resuming executor work.
+
+Dispatch gate: dispatch `reviewer` only after this task's test-runner first
+line is `GATE: PASS tests=<n> passed=<n> failed=<n>`, or after an explicit
+user waiver. Max 2 reviewer dispatches per task; then escalate the open
+findings to the user.
+
+Markers (first line, machine-parseable):
+
+- test-runner: `GATE: PASS|FAIL tests=<n> passed=<n> failed=<n>`
+- reviewer: `VERDICT: APPROVE|BLOCK crit=<n> high=<n> med=<n> low=<n>`
+- plan-reviewer: `VERDICT: APPROVE|BLOCK crit=<n> high=<n> med=<n> low=<n>`
+  (first line; then an AC traceability table with `Covered-by` per AC)
+- reviewer acceptance table: add an `AC-ID` column referencing `AC-<n>`
+- planner: number criteria `AC-1…AC-n`; if the change spans >5 files or >3
+  outcomes, add `## Decomposition` with ordered `chunk-N` entries (≤5 files)
+- executor/debugger: 5-file budget; if 10 tool calls pass without a test
+  command, STOP, emit a state summary, re-anchor on the plan.
+
+Reviewer ensemble: dispatch two `reviewer` subagents on the same diff; merge
+one finding per `file+symbol` (max severity). A singleton CRITICAL/HIGH
+blocks only after re-reading the cited location; LOW singletons become
+`UNCONFIRMED` notes.
+
+Worktree/commit: git worktrees will be used, but it does not matter how they
+get created. Work inside the checkout and branch your session starts in; do
+not create/add/remove worktrees, switch branches, merge, or open PRs unless
+the user explicitly asks. On success, commit your change set with a
+conventional message and stop. If a worktree is in use, assert a `WORKTREE:`
+header for logging; otherwise skip it. Committing on a shared default branch
+means your change lands there; treat main/branch commits as high
+sensitivity; do not self-reset.
+
+Trace (works with the plugin off): append every dispatch/verdict to
+`~/.local/share/opencode/metrics/gate-events.jsonl` as
+`YYYY-MM-DD HH:MM | agent | event | detail`. The plugin also writes
+`~/.local/share/opencode/metrics/turnstile.jsonl`
+(`{ts,sessionID,type,...}`). Read: grep/glob/rg first, whole-file reads last.
+
+<!-- turnstile:end -->

package/turnstile.ts

@@ -0,0 +1,82 @@
+/**
+ * turnstile: runtime enforcement of the AGENTS.md pipeline contracts.
+ *
+ * Written for OpenCode v2.x promise-plugin host (`{ id, setup }`):
+ * - `ctx.tool.hook("execute.before" | "execute.after", cb)`
+ * - `ctx.session.hook("prompt" | "generate" | "compaction", cb)`
+ * - `ctx.event.subscribe({ signal })`
+ *
+ * Enforced mechanically:
+ * - Plan-approval gate: `task` dispatches to `executor` require a current
+ *   plan-reviewer `VERDICT: APPROVE` for the task whenever a plan file
+ *   exists in `.opencode/plans/`, or an explicit user waiver (`USER
+ *   WAIVER:` literal in the prompt). Plan-file changes invalidate the
+ *   approval, forcing re-review after a re-plan.
+ * - Hard gate: `task` dispatches to `reviewer` require a recorded `GATE: PASS`
+ *   from test-runner for the current task (a later `GATE: FAIL` un-sets
+ *   it), or an explicit user waiver (the dispatch prompt must contain the
+ *   literal marker `USER WAIVER:`).
+ * - Round cap: max 2 `task -> reviewer` dispatches per task.
+ * - Horizon: read-counter backstop (warn @8, block @15 whole-file reads).
+ * - Decomposition: `task -> executor` dispatches must cite `chunk-N` / `AC-n`
+ *   when a plan file with a `## Decomposition` block exists.
+ * - Markers: `GATE:` / `VERDICT:` parsed from task results and child-session
+ *   assistant text, deduped per task (streaming re-delivery is ignored);
+ *   marker-less outputs from marker-contracted agents (test-runner/reviewer/
+ *   plan-reviewer) are journaled as violations; a plan-reviewer result's
+ *   last `VERDICT` moves the plan-approval gate (parent-keyed, journaled as
+ *   type `plan`); gate journal entries are keyed by the parent session so
+ *   replay restores where the gates look.
+ * - Trace: JSONL journal of dispatches, gate transitions, verdicts, blocked
+ *   calls, bash commands, errors.
+ * - Decoding: executor/test-runner/debugger temperature clamped ≤ 0.2;
+ *   reviewer temperature = 0.
+ * - Config: layered and read once at setup: code defaults ⊕
+ *   `~/.config/opencode/turnstile.json` ⊕ env (`TURNSTILE_TRACE`,
+ *   `TURNSTILE_METRICS_DIR`, `TURNSTILE_CONFIG`) ⊕ injected options (tests).
+ *   Invalid keys are ignored and journaled (fail-open); restart to apply.
+ *
+ * Fail-open by design: every hook body is guarded; an internal error is
+ * journaled and the tool call proceeds. Removing this file leaves the
+ * pipeline functional (prompt contracts alone).
+ *
+ * Module layout: one boundary per file; this file is the thin entry point
+ * the host loads, holding only the module shape and setup composition:
+ * - `src/types.ts`: host wire shapes and gate-state structures.
+ * - `src/journal.ts`: telemetry persistence (JSONL journal + trace).
+ * - `src/state.ts`: per-session gate state, session mapping, journal replay.
+ * - `src/markers.ts`: GATE/VERDICT parsing and dedup.
+ * - `src/gates.ts`: enforcement decisions (plan-approval gate, reviewer
+ *   gate, read horizon, decomposition).
+ * - `src/setup.ts`: hook registration and the stream-event loop.
+ */
+import { createTurnstile } from "./src/setup.ts"
+import type { Host, TurnstileOptions } from "./src/types.ts"
+
+/** The async setup function a plugin instance hands to the host. */
+export type SetupFn = (h: Host) => Promise<(() => void) | void>
+
+/**
+ * Creates a turnstile plugin bound to the given host context.
+ * @param host The OpenCode host context, or null in degraded loads.
+ * @param opts Injected config/env overrides (tests); defaults to env.
+ * @returns The plugin's setup function; resolves to a cleanup disposer.
+ */
+export const turnstile = (host: Host | undefined | null, opts?: TurnstileOptions): SetupFn =>
+  createTurnstile(host, opts)
+
+/** The module object the OpenCode host loads. */
+const module: {
+  id: string
+  server: () => Promise<Record<string, never>>
+  setup: (ctx: Host, opts?: TurnstileOptions) => Promise<(() => void) | void>
+} = {
+  id: "turnstile",
+  // Legacy v1 shape kept for loaders that require `server`; the active v2
+  // path is `setup` (same pattern as the working orca-opencode-status plugin).
+  server: async (): Promise<Record<string, never>> => ({}),
+  setup: async (ctx: Host, opts?: TurnstileOptions): Promise<(() => void) | void> =>
+    turnstile(ctx, opts)(ctx),
+}
+
+export default module