opencode-orchestrator-uni 0.4.0 → 0.5.1

package/lib/tools.ts

@@ -1,10 +1,10 @@
 /**
  * tools — registration of the kit's deterministic, read-only audit tools.
  *
- * `registerAuditTools(ctx)` publishes four tools in the `orch_uni` namespace
+ * `registerAuditTools(ctx)` publishes five tools in the `orch_uni` namespace
  * (effective names `orch_uni_validate_report`, `orch_uni_context_lint`,
- * `orch_uni_snapshot`, `orch_uni_sessions`) and returns a cleanup that stops the
- * background session-index subscription:
+ * `orch_uni_snapshot`, `orch_uni_sessions`, `orch_uni_session_stats`) and returns
+ * a cleanup that stops the background session-index subscription:
  *
  * - `validate_report` — extract the SGR JSON block of an agent report, resolve
  *   its schema, validate it and report prompt-level warnings;
@@ -14,11 +14,12 @@
  * - `snapshot` — deterministic revision of a directory tree (per-file sha256 +
  *   aggregate hash) for "the state the verdict was fixed on";
  * - `sessions` — child sessions of a session (agent, model, cost, tokens, time),
- *   read through the plugin's session API only.
+ *   read through the plugin's session API only;
+ * - `session_stats` — the session-protocol counters and limits of one session.
  *
  * Every tool answers with a JSON text body. Failures are typed (`E_*`) codes in
  * the body rather than thrown tool errors, so an agent can branch on the code.
- * All four are read-only: they never write to the workspace or the config; the
+ * All five are read-only: they never write to the workspace or the config; the
  * only state `sessions` keeps is a plugin-scoped session index in `ctx.storage`
  * (see the `sessions` tool notes below).
  */
@@ -28,6 +29,7 @@ import { fileURLToPath } from "node:url"
 import type { Plugin } from "@opencode/plugin"
 import { lintContext } from "./context-lint"
 import { checkReport, type JsonSchemaNode, type ValidationCode } from "./report-schema"
+import { compactionLimitReached, type SessionBudgetReport } from "./session-budget"
 import { DEFAULT_EXCLUDE, isSnapshotFailure, snapshotTree } from "./snapshot"
 
 /** Tool namespace; effective names become `orch_uni_<name>`. */
@@ -39,6 +41,7 @@ export const TOOL_IDS: readonly string[] = [
   "orch_uni_context_lint",
   "orch_uni_snapshot",
   "orch_uni_sessions",
+  "orch_uni_session_stats",
 ]
 
 /** Directory holding the shipped report schemas (`schemas/*.json`). */
@@ -144,6 +147,31 @@ function asRecord(input: unknown): Record<string, unknown> | undefined {
     : undefined
 }
 
+/**
+ * `session.get` failures that mean the session is genuinely absent.
+ *
+ * A live host may throw with an empty message but a typed `_tag`/`name`/`code`;
+ * the message regex is only a narrow fallback, so a transient `unknown database`
+ * or `unknown host` stays `E_INTERNAL` and cannot masquerade as a missing session.
+ */
+function isNotFoundError(error: unknown): boolean {
+  const record = asRecord(error)
+  if (record !== undefined) {
+    for (const field of ["_tag", "name", "code"] as const) {
+      const value = record[field]
+      if (
+        value === "Session.NotFoundError" ||
+        value === "SessionNotFoundError" ||
+        value === "NotFoundError" ||
+        value === "ENOENT"
+      ) {
+        return true
+      }
+    }
+  }
+  return /session.*not.?found|unknown session/i.test(errorMessage(error))
+}
+
 /** `validate_report` input contract. */
 const VALIDATE_REPORT_INPUT = {
   type: "object",
@@ -207,6 +235,14 @@ const SESSIONS_INPUT = {
   },
 } as const
 
+/** `session_stats` input contract. */
+const SESSION_STATS_INPUT = {
+  type: "object",
+  properties: {
+    sessionID: { type: "string", description: "Session to report. Default: the calling session." },
+  },
+} as const
+
 interface SessionInfoLike {
   readonly id?: string
   readonly parentID?: string | null
@@ -389,10 +425,12 @@ export function resolveRoot(directory: string, input: string): string {
   return path.isAbsolute(input) ? path.normalize(input) : path.resolve(directory, input)
 }
 
-/** Optional seams for tests; the plugin calls this with no options. */
+/** Optional seams for tests; the plugin calls this with the session-budget report. */
 export interface RegisterAuditToolsOptions {
   /** Directory to read `schemas/*.json` from. Defaults to the shipped `schemas/`. */
   readonly schemasDirectory?: string
+  /** Session counters from the runtime session guard; absent in isolation. */
+  readonly sessionBudget?: SessionBudgetReport
 }
 
 /**
@@ -646,13 +684,99 @@ export async function registerAuditTools(
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error)
       if (message === "E_ABORTED" || toolContext.signal.aborted) return failure("E_ABORTED", "listing aborted")
-      if (getFn !== undefined && /not ?found|unknown/i.test(message)) {
+      if (getFn !== undefined && isNotFoundError(error)) {
         return failure("E_NOT_FOUND", `session ${parentID} was not found: ${message}`, { sessionID: parentID })
       }
       return failure("E_INTERNAL", message, { sessionID: parentID })
     }
   }
 
+  const sessionStatsTool = async (
+    input: unknown,
+    toolContext: { readonly signal: AbortSignal; readonly sessionID: string },
+  ): Promise<{ content: string }> => {
+    const record = input === undefined ? {} : asRecord(input)
+    if (record === undefined) return failure("E_INPUT", "input must be an object ({sessionID?})")
+    const { sessionID } = record
+    if (sessionID !== undefined && (typeof sessionID !== "string" || sessionID === "")) {
+      return failure("E_INPUT", '"sessionID" must be a non-empty string')
+    }
+    if (toolContext.signal.aborted) return failure("E_ABORTED", "report aborted")
+    const target = (sessionID as string | undefined) ?? toolContext.sessionID
+    const budget = options.sessionBudget
+    if (budget === undefined) {
+      return failure("E_UNAVAILABLE", "the session guard is not registered in this plugin instance", {
+        sessionID: target,
+      })
+    }
+    if (!budget.available) {
+      return failure("E_UNAVAILABLE", "the session guard is unavailable: its hooks could not be registered", {
+        sessionID: target,
+      })
+    }
+    const tracked = budget.tracked(target)
+    const counters = budget.stats(target)
+    const { session: sessionConfig, toolOutput } = budget.config
+    const guard = budget.guard()
+    const getFn = sessionMethod<SessionGetFn>(session, "get")
+    if (getFn === undefined && !tracked) {
+      return failure(
+        "E_NO_API",
+        "this OpenCode build exposes no session.get() and the session is not tracked by this plugin instance",
+        { sessionID: target },
+      )
+    }
+    let info: Record<string, unknown> | undefined
+    let getError: unknown
+    let getMissing = false
+    if (getFn !== undefined) {
+      try {
+        const fetched: SessionInfoLike | null | undefined = await getFn({ sessionID: target })
+        if (fetched === undefined || fetched === null) getMissing = true
+        else info = sessionSummary(fetched)
+      } catch (error) {
+        getError = error
+      }
+    }
+    // A session this instance never observed is only "not found" when the store
+    // says so; a transient error (lock, permission, transport) stays `E_INTERNAL`
+    // instead of masquerading as a missing session. A known session with zero
+    // requests is a valid `tracked:false` report. `session.get` returning
+    // `undefined` without an error is the store's "no such session" answer.
+    if (info === undefined && !tracked) {
+      if (getError !== undefined) {
+        const message = errorMessage(getError)
+        if (isNotFoundError(getError)) {
+          return failure("E_NOT_FOUND", `session ${target} was not found: ${message}`, { sessionID: target })
+        }
+        return failure("E_INTERNAL", message, { sessionID: target })
+      }
+      if (getMissing) {
+        return failure("E_NOT_FOUND", `session ${target} was not found`, { sessionID: target })
+      }
+    }
+    return json({
+      ok: true,
+      sessionID: target,
+      counters,
+      limits: {
+        promptTokensSoft: sessionConfig.promptTokensSoft,
+        maxCompactions: sessionConfig.maxCompactions,
+        maxToolOutputChars: toolOutput.maxChars,
+      },
+      overBudget: counters.promptTokensMax > sessionConfig.promptTokensSoft,
+      compactionLimitReached: compactionLimitReached(budget.config, counters.compactions),
+      toolsPerTurn: counters.requests > 0 ? Math.round((counters.toolCalls / counters.requests) * 100) / 100 : 0,
+      tracked,
+      guard,
+      ...(getFn === undefined
+        ? { session: null, limitations: ["session.get is unavailable in this build"] }
+        : info === undefined
+          ? {}
+          : { session: info }),
+    })
+  }
+
   await context.tool.transform((editor) => {
     editor.namespace({
       name: TOOL_NAMESPACE,
@@ -707,6 +831,20 @@ export async function registerAuditTools(
       options: { namespace: TOOL_NAMESPACE, codemode: true },
       execute: sessionsTool,
     })
+    editor.add({
+      name: "session_stats",
+      description:
+        "Session protocol counters of a session: requests, estimated prompt tokens (last/max), budget band, confirmed " +
+        "compactions and compaction attempts, failed compactions, the live compaction source, reminders injected, tool " +
+        "calls and capped tool outputs (totals and per normalized tool name), chars kept out of context, plus the " +
+        "configured limits and toolsPerTurn. Read-only; counters belong to this plugin instance. `sessionID` may name any " +
+        "session on this server, not only a child of the caller. Returns JSON {ok, sessionID, counters, limits, overBudget, " +
+        "compactionLimitReached, toolsPerTurn, tracked, guard, session?, limitations?} or a typed code " +
+        "(E_INPUT|E_NOT_FOUND|E_INTERNAL|E_NO_API|E_UNAVAILABLE|E_ABORTED).",
+      input: SESSION_STATS_INPUT,
+      options: { namespace: TOOL_NAMESPACE, codemode: true },
+      execute: sessionStatsTool,
+    })
   })
 
   return () => {

package/lib/write-guard.ts

@@ -0,0 +1,283 @@
+/**
+ * write-guard — path-root enforcement for the root orchestrator's edits.
+ *
+ * Flat `permissions` are a last-match-wins list, so they cannot express two
+ * properties at once: `reports/` is an artifact subtree (even `reports/src/x`
+ * must stay writable) while `src/`, `docs/` and the other source roots are
+ * denied at their first segment (even under an artifact-looking name such as
+ * `src/reports/x`). The rules also cannot tell a root artifact file
+ * (`state.md`) from a source file of the same name (`app/state.md`).
+ *
+ * This module implements the intended contract as a permission hook:
+ *
+ * - resolve a relative resource against the session's location directory and
+ *   strip that prefix; a resource that stays outside the location is denied —
+ *   the guard is the workspace boundary, so `reports/`, `docs/planning/` and
+ *   `audit-*` are writable only inside it. The location is read from the
+ *   session on every event (`session.get`), so a moved session is evaluated
+ *   against its new directory; the setup location is only a fallback (used when
+ *   the lookup is missing, fails or exceeds its 250 ms bound, with one warning);
+ * - normalize separators and collapse `.`/`..`, then walk the segments left to
+ *   right and let the first root decide: `reports` → allow (the whole subtree
+ *   is an artifact), `docs` + `planning` + a path whose last segment is `.md`
+ *   (any depth) → allow, any source root (`src`, `lib`, `test`, `tests`,
+ *   `agents`, `tools`, `schemas`, `eval`, `.github`) → deny. `docs` is not part
+ *   of that set: its own branch above allows nested `docs/planning/` Markdown
+ *   and denies every other `docs/` path;
+ * - with no root in the path, an artifact file (`case-*`, `risks-*`,
+ *   `handoff-*`, `decisions-*`, `state.md`) is allowed only in the location
+ *   root, under `reports/`, under `docs/planning/`, or inside an `audit-*`
+ *   directory;
+ * - everything else is denied.
+ *
+ * The hook only tightens an `edit` evaluation for the `orchestrator` agent: it
+ * runs after the flat rules, so a local `edit: allow *` on the agent (a config
+ * or a Markdown override) cannot bypass the guard. A failure anywhere in the
+ * guard is fail-open — a broken guard must never break the session.
+ */
+import type { Plugin } from "@opencode/plugin"
+
+/** Source roots that hold project code or kit content; `docs` has its own branch in `decideSegments`. */
+const SOURCE_ROOTS: ReadonlySet<string> = new Set([
+  "src",
+  "lib",
+  "test",
+  "tests",
+  "agents",
+  "tools",
+  "schemas",
+  "eval",
+  ".github",
+])
+
+/** Reserved artifact subtree: everything below it is an audit/state artifact. */
+const ARTIFACT_DIR = "reports"
+
+/** Artifact files allowed only in an artifact location (see `artifactLocation`). */
+const ARTIFACT_FILE = /^(?:case-.*|risks-.*|handoff-.*|decisions-.*|state)\.md$/
+
+/** Ad-hoc audit workspace directory; any depth below it is an artifact location. */
+const AUDIT_DIR = /^audit-/
+
+const MARKDOWN_FILE = /\.md$/
+
+/** Message attached to a denied evaluation; also shown to the model. */
+export const WRITE_GUARD_MESSAGE = "root orchestrator may edit only audit/session-state artifacts"
+
+/** Upper bound on the per-event session lookup; a hung store must not hold the edit open. */
+const SESSION_LOOKUP_TIMEOUT_MS = 250
+
+export type EditDecision = "allow" | "deny"
+
+/** Case-fold one segment the way the host resolves paths on `platform`. */
+function fold(segment: string, platform: string): string {
+  return platform === "win32" ? segment.toLowerCase() : segment
+}
+
+/** Split a path into segments, collapsing `.`/`..` and unifying separators. */
+function normalizeSegments(input: string): string[] {
+  const segments: string[] = []
+  for (const part of input.replaceAll("\\", "/").split("/")) {
+    if (part === "" || part === ".") continue
+    if (part === "..") {
+      segments.pop()
+      continue
+    }
+    segments.push(part)
+  }
+  return segments
+}
+
+/** Whether a resource names an absolute path (POSIX root or a Windows drive). */
+function isAbsolute(resource: string): boolean {
+  const normalized = resource.replaceAll("\\", "/")
+  return normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized)
+}
+
+/** Drop the location prefix when `absolute` is inside it; `undefined` otherwise. */
+function stripLocation(
+  absolute: readonly string[],
+  location: readonly string[],
+  platform: string,
+): string[] | undefined {
+  if (location.length === 0 || location.length > absolute.length) return undefined
+  for (let index = 0; index < location.length; index += 1) {
+    if (fold(absolute[index]!, platform) !== fold(location[index]!, platform)) return undefined
+  }
+  return absolute.slice(location.length)
+}
+
+/** `reports/` and `docs/planning/` already allow earlier; roots and files are checked here. */
+function artifactLocation(segments: readonly string[], platform: string): boolean {
+  if (segments.length === 1) return true
+  return segments.slice(0, -1).some((segment) => AUDIT_DIR.test(fold(segment, platform)))
+}
+
+function decideSegments(segments: readonly string[], platform: string): EditDecision {
+  for (let index = 0; index < segments.length; index += 1) {
+    const segment = segments[index]!
+    const key = fold(segment, platform)
+    if (key === ARTIFACT_DIR) return "allow"
+    // `docs` is not part of SOURCE_ROOTS: this branch allows nested planning
+    // Markdown and denies every other `docs/` path.
+    if (key === "docs") {
+      const next = segments[index + 1]
+      const last = segments.at(-1)
+      if (
+        next !== undefined &&
+        fold(next, platform) === "planning" &&
+        last !== undefined &&
+        MARKDOWN_FILE.test(fold(last, platform))
+      ) {
+        return "allow"
+      }
+      return "deny"
+    }
+    if (SOURCE_ROOTS.has(key)) return "deny"
+  }
+  const last = segments.at(-1)
+  if (last !== undefined && ARTIFACT_FILE.test(fold(last, platform)) && artifactLocation(segments, platform)) {
+    return "allow"
+  }
+  return "deny"
+}
+
+/**
+ * Decide whether the root orchestrator may write `resource` in `locationDirectory`.
+ *
+ * A relative resource is resolved against the location directory; an absolute one
+ * is used as is. The path is then reduced to its relative form: anything that stays
+ * outside the location is denied (the location is the workspace boundary), and an
+ * inside path is decided by its first segment.
+ */
+export function decideEdit(
+  resource: string,
+  locationDirectory: string,
+  platform: string = process.platform,
+): EditDecision {
+  const location = normalizeSegments(locationDirectory)
+  const raw = resource.replaceAll("\\", "/")
+  const resolved = isAbsolute(raw) ? normalizeSegments(raw) : normalizeSegments(`${location.join("/")}/${raw}`)
+  const relative = stripLocation(resolved, location, platform)
+  if (relative === undefined) return "deny"
+  return decideSegments(relative, platform)
+}
+
+export interface WriteGuardOptions {
+  /** Directory the session belongs to; relative resources resolve against it. */
+  readonly locationDirectory: string
+  /** Reports a missing host API or a registration failure (the guard stays no-op). */
+  readonly warn: (message: string) => void
+}
+
+export interface WriteGuard {
+  /** `true` when the permission hook is registered. */
+  readonly available: boolean
+  /** Disposes the hook registration; safe to call when the guard is unavailable. */
+  readonly cleanup: () => Promise<void>
+}
+
+/** The evaluate event fields the guard reads and writes (the host type is structural). */
+interface EvaluateEvent {
+  readonly sessionID?: string
+  readonly agent?: string
+  readonly action: string
+  readonly resources: readonly string[]
+  effect: "allow" | "deny" | "ask"
+  message?: string
+}
+
+/** The session surface the guard reads the current location from (structural). */
+interface SessionDirectoryApi {
+  readonly get?: (input: { readonly sessionID: string }) => Promise<unknown>
+}
+
+/**
+ * Register the path-root write guard on the host's permission hook.
+ * Never throws: an unavailable or failing host API leaves the guard as a no-op.
+ */
+export async function createWriteGuard(ctx: Plugin.Context, options: WriteGuardOptions): Promise<WriteGuard> {
+  const noop = async () => {}
+  const permission = (ctx as { readonly permission?: Plugin.Context["permission"] }).permission
+  if (permission === undefined || typeof permission.hook !== "function") {
+    options.warn("write guard: ctx.permission.hook is unavailable; the path-root guard is not registered")
+    return { available: false, cleanup: noop }
+  }
+  const session = (ctx as { readonly session?: SessionDirectoryApi }).session
+  // A failing, missing or hanging `session.get` falls back to the setup location;
+  // the warning is emitted once per guard so a persistent failure cannot flood
+  // the log on every edit (the single flag is deliberate — no counter, no reset).
+  let sessionWarned = false
+  const warnSessionOnce = (message: string): void => {
+    if (sessionWarned) return
+    sessionWarned = true
+    options.warn(message)
+  }
+  const locationFor = async (sessionID: string | undefined): Promise<string> => {
+    if (typeof session?.get !== "function") {
+      warnSessionOnce("write guard: ctx.session.get is unavailable, using the setup location")
+      return options.locationDirectory
+    }
+    if (sessionID === undefined) return options.locationDirectory
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      // The lookup is bounded: a hung session store must not hold the permission
+      // event open (fail-open covers a rejection, not a promise that never settles).
+      const lookup = session.get({ sessionID })
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(`timed out after ${SESSION_LOOKUP_TIMEOUT_MS} ms`))
+        }, SESSION_LOOKUP_TIMEOUT_MS)
+      })
+      const info = (await Promise.race([lookup, timeout])) as
+        | { readonly location?: { readonly directory?: unknown } }
+        | undefined
+      const directory = info?.location?.directory
+      if (typeof directory === "string" && directory !== "") return directory
+      warnSessionOnce("write guard: the session reports no location directory, using the setup location")
+      return options.locationDirectory
+    } catch (error) {
+      // Fail-open: an unreadable session must not break (or disable) the guard.
+      warnSessionOnce(
+        `write guard: cannot read the session directory, using the setup location: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      )
+      return options.locationDirectory
+    } finally {
+      if (timer !== undefined) clearTimeout(timer)
+    }
+  }
+  try {
+    const registration = await permission.hook("evaluate", async (event: EvaluateEvent) => {
+      try {
+        if (event.agent !== "orchestrator" || event.action !== "edit" || event.effect === "deny") return
+        // The session may have been moved since setup: the host resolves the
+        // resource against the session's current directory, so the guard must too.
+        const locationDirectory = await locationFor(event.sessionID)
+        const denied = event.resources.some((resource) => decideEdit(resource, locationDirectory) === "deny")
+        if (!denied) return
+        event.effect = "deny"
+        event.message = WRITE_GUARD_MESSAGE
+      } catch (error) {
+        // Fail-open: a broken guard must never break the session it protects.
+        options.warn(`write guard: evaluation failed: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    })
+    let disposed = false
+    return {
+      available: true,
+      cleanup: async () => {
+        // Idempotent: a repeated cleanup must not dispose the registration twice.
+        if (disposed) return
+        disposed = true
+        await registration.dispose()
+      },
+    }
+  } catch (error) {
+    options.warn(
+      `write guard: cannot register the permission hook: ${error instanceof Error ? error.message : String(error)}`,
+    )
+    return { available: false, cleanup: noop }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-orchestrator-uni",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Native OpenCode V2 plugin that registers the orchestrator agent kit (root orchestrator, audit subagents, fix-runner) and exposes the kit's process documents as the audit-kit reference.",
   "type": "module",
   "license": "MIT",