opencode-orchestrator-uni 0.4.0 → 0.5.0

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/package.json

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