opencode-orchestrator-uni 0.3.1 → 0.5.0

package/lib/tools.ts

@@ -1,20 +1,25 @@
 /**
  * tools — registration of the kit's deterministic, read-only audit tools.
  *
- * `registerAuditTools(ctx)` publishes three tools in the `orch_uni` namespace
- * (effective names `orch_uni_validate_report`, `orch_uni_snapshot`, `orch_uni_sessions`)
- * and returns a cleanup that stops the background session-index subscription:
+ * `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`, `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;
+ * - `context_lint` — deterministic, read-only checks for AGENTS.md/SPEC.md/CLAUDE.md:
+ *   budget, vague phrases, duplicates, broken relative links, placeholders,
+ *   dates in the first lines, required sections;
  * - `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 three 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).
  */
@@ -22,14 +27,22 @@ import { readdir, readFile } from "node:fs/promises"
 import path from "node:path"
 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>`. */
 export const TOOL_NAMESPACE = "orch_uni"
 
 /** Effective tool names as they appear to a model. */
-export const TOOL_IDS: readonly string[] = ["orch_uni_validate_report", "orch_uni_snapshot", "orch_uni_sessions"]
+export const TOOL_IDS: readonly string[] = [
+  "orch_uni_validate_report",
+  "orch_uni_context_lint",
+  "orch_uni_snapshot",
+  "orch_uni_sessions",
+  "orch_uni_session_stats",
+]
 
 /** Directory holding the shipped report schemas (`schemas/*.json`). */
 export const SCHEMAS_DIRECTORY = fileURLToPath(new URL("../schemas/", import.meta.url))
@@ -134,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",
@@ -144,6 +182,36 @@ const VALIDATE_REPORT_INPUT = {
   },
 } as const
 
+/** `context_lint` input contract. */
+const CONTEXT_LINT_INPUT = {
+  type: "object",
+  properties: {
+    path: {
+      type: "string",
+      description:
+        "File or directory to inspect, absolute or relative to the location directory. Default: the location directory.",
+    },
+    max_lines: { type: "number", description: "AGENTS/CLAUDE line budget. Default: 200." },
+    max_tokens: { type: "number", description: "AGENTS/CLAUDE estimated token budget. Default: 2500." },
+    max_words: {
+      type: "number",
+      description: "SPEC word budget. Default: 1500 (the authoring target); the documented ceiling is 2000.",
+    },
+    max_file_bytes: { type: "number", description: "Largest file that may be read, in bytes. Default: 2000000." },
+    max_files: { type: "number", description: "Most files a directory target may expand to. Default: 500." },
+    max_findings: {
+      type: "number",
+      description:
+        "Per-file cap: MINOR/INFO findings kept, and the hard cap for MAJOR (excess becomes one MAJOR truncated finding). Default: 100.",
+    },
+    max_total_findings: {
+      type: "number",
+      description:
+        "Global cap for all findings; MAJOR are kept first, the MAJOR overflow becomes one MAJOR truncated marker in closing_list. Default: 1000.",
+    },
+  },
+} as const
+
 /** `snapshot` input contract. */
 const SNAPSHOT_INPUT = {
   type: "object",
@@ -167,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
@@ -349,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
 }
 
 /**
@@ -437,6 +515,75 @@ export async function registerAuditTools(
     return json({ root: outcome.root, files: outcome.files, aggregate: outcome.aggregate })
   }
 
+  const contextLintTool = async (
+    input: unknown,
+    toolContext: { readonly signal?: AbortSignal } | undefined,
+  ): Promise<{ content: string }> => {
+    // A failure is not a report: it carries the `context-lint-failure/v1` id so it
+    // validates against that schema and never passes as a `context-lint/v1` report.
+    const lintFailure = (code: string, message: string, extra: Record<string, unknown> = {}) =>
+      failure(code, message, { schema: "context-lint-failure/v1", ...extra })
+    const record = input === undefined ? {} : asRecord(input)
+    if (record === undefined)
+      return lintFailure(
+        "E_INPUT",
+        "input must be an object ({path?, max_lines?, max_tokens?, max_words?, max_file_bytes?, max_files?, max_findings?, max_total_findings?})",
+      )
+    const {
+      path: target,
+      max_lines,
+      max_tokens,
+      max_words,
+      max_file_bytes,
+      max_files,
+      max_findings,
+      max_total_findings,
+    } = record
+    if (target !== undefined && (typeof target !== "string" || target === "")) {
+      return lintFailure("E_INPUT", '"path" must be a non-empty string')
+    }
+    for (const [key, value] of [
+      ["max_lines", max_lines],
+      ["max_tokens", max_tokens],
+      ["max_words", max_words],
+      ["max_file_bytes", max_file_bytes],
+      ["max_files", max_files],
+      ["max_findings", max_findings],
+      ["max_total_findings", max_total_findings],
+    ] as const) {
+      if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value <= 0)) {
+        return lintFailure("E_INPUT", `"${key}" must be a positive number`)
+      }
+    }
+    // The host may call an executor without a context (`execute(input, {})`), and
+    // some builds pass no signal at all: fall back to a local controller instead
+    // of throwing on `undefined.signal`.
+    const controller = new AbortController()
+    const signal = toolContext?.signal ?? controller.signal
+    if (signal.aborted) return lintFailure("E_ABORTED", "context lint aborted")
+    const outcome = await lintContext({
+      root: directory,
+      ...(target === undefined ? {} : { target: target as string }),
+      ...(max_lines === undefined ? {} : { maxLines: max_lines as number }),
+      ...(max_tokens === undefined ? {} : { maxTokens: max_tokens as number }),
+      ...(max_words === undefined ? {} : { maxWords: max_words as number }),
+      ...(max_file_bytes === undefined ? {} : { maxFileBytes: max_file_bytes as number }),
+      ...(max_files === undefined ? {} : { maxFiles: max_files as number }),
+      ...(max_findings === undefined ? {} : { maxFindingsPerFile: max_findings as number }),
+      ...(max_total_findings === undefined ? {} : { maxTotalFindings: max_total_findings as number }),
+      signal,
+    })
+    if (!outcome.ok) {
+      const extra: Record<string, unknown> = {}
+      if (outcome.path !== undefined) extra.path = outcome.path
+      if (outcome.bytes !== undefined) extra.bytes = outcome.bytes
+      if (outcome.files !== undefined) extra.files = outcome.files
+      if (outcome.max !== undefined) extra.max = outcome.max
+      return lintFailure(outcome.code, outcome.message, extra)
+    }
+    return json(outcome)
+  }
+
   const sessionsTool = async (
     input: unknown,
     toolContext: { readonly signal: AbortSignal; readonly sessionID: string },
@@ -537,18 +684,124 @@ 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,
       description:
-        "Deterministic, read-only tools of the orchestrator agent kit (SGR validation, state snapshots, session accounting).",
+        "Deterministic, read-only tools of the orchestrator agent kit (SGR validation, context-file lint, state snapshots, session accounting).",
+    })
+    editor.add({
+      name: "context_lint",
+      description:
+        "Deterministic, read-only audit of AGENTS.md/SPEC.md/CLAUDE.md: line/token/word budget, distinct vague phrases, duplicate lines, " +
+        "broken relative links, placeholders, dates in the first three lines, required sections, AC test columns. " +
+        "A directory target is scanned to depth 3 and capped at max_files (the walk stops at the first file above the limit); " +
+        "a scan started at the root also picks up fixture trees such as eval/ (pass an explicit path for the canonical files); " +
+        "undocumented directories below depth 3, unclosed fences and links that resolve outside the workspace root are reported " +
+        "as INFO findings and never checked silently. Commands count only inside code, a Task table or a Commands section; " +
+        "tokens are estimated as Cyrillic/3 + the rest/4. " +
+        "Returns JSON {schema, ok, verdict, closing_list, files, summary, truncated?}; each file carries lines, words, chars " +
+        "and tokens_est. A per-file cap drops findings and sets truncated=true, max_total_findings keeps MAJOR first and turns " +
+        "the MAJOR overflow into one MAJOR truncated finding in closing_list. A file target is capped by max_file_bytes, " +
+        'also while it is read. A failure is JSON {schema:"context-lint-failure/v1", ok:false, code, message, path?, bytes?, ' +
+        "files?, max?} with a typed code " +
+        "(E_INPUT|E_NOT_FOUND|E_NO_FILES|E_IO|E_ABORTED|E_LIMIT_FILE|E_LIMIT_FILES|E_OUT_OF_ROOT).",
+      input: CONTEXT_LINT_INPUT,
+      options: { namespace: TOOL_NAMESPACE, codemode: true },
+      execute: contextLintTool,
     })
     editor.add({
       name: "validate_report",
@@ -578,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/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-orchestrator-uni",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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",

package/schemas/context-lint-failure.v1.json

@@ -0,0 +1,29 @@
+{
+  "id": "context-lint-failure/v1",
+  "schema": {
+    "type": "object",
+    "required": ["schema", "ok", "code", "message"],
+    "properties": {
+      "schema": { "type": "string", "const": "context-lint-failure/v1" },
+      "ok": { "type": "boolean", "const": false },
+      "code": {
+        "type": "string",
+        "enum": [
+          "E_INPUT",
+          "E_NOT_FOUND",
+          "E_NO_FILES",
+          "E_IO",
+          "E_ABORTED",
+          "E_LIMIT_FILE",
+          "E_LIMIT_FILES",
+          "E_OUT_OF_ROOT"
+        ]
+      },
+      "message": { "type": "string" },
+      "path": { "type": "string" },
+      "bytes": { "type": "number" },
+      "files": { "type": "number" },
+      "max": { "type": "number" }
+    }
+  }
+}

package/schemas/context-lint.v1.json

@@ -0,0 +1,58 @@
+{
+  "id": "context-lint/v1",
+  "schema": {
+    "type": "object",
+    "required": ["schema", "verdict", "closing_list", "files", "summary"],
+    "properties": {
+      "schema": { "type": "string", "const": "context-lint/v1" },
+      "ok": { "type": "boolean" },
+      "verdict": { "type": "string", "enum": ["pass", "fail"] },
+      "closing_list": { "type": "array", "items": { "type": "string" } },
+      "truncated": { "type": "boolean" },
+      "files": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["path", "kind", "lines", "words", "tokens_est", "findings"],
+          "properties": {
+            "path": { "type": "string" },
+            "kind": { "type": "string", "enum": ["agents", "spec", "claude", "other"] },
+            "lines": { "type": "number" },
+            "words": { "type": "number" },
+            "chars": { "type": "number" },
+            "tokens_est": { "type": "number" },
+            "truncated": { "type": "boolean" },
+            "findings": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["id", "severity", "kind", "evidence", "detail", "fix"],
+                "properties": {
+                  "id": { "type": "string" },
+                  "severity": { "type": "string", "enum": ["MAJOR", "MINOR", "INFO"] },
+                  "kind": {
+                    "type": "string",
+                    "enum": [
+                      "budget",
+                      "vague",
+                      "duplicate",
+                      "broken_link",
+                      "missing_section",
+                      "conflict",
+                      "unverified_command",
+                      "other"
+                    ]
+                  },
+                  "evidence": { "type": "string" },
+                  "detail": { "type": "string" },
+                  "fix": { "type": "string" }
+                }
+              }
+            }
+          }
+        }
+      },
+      "summary": { "type": "string" }
+    }
+  }
+}