opencode-codeops 1.8.1 → 1.10.0

package/bin/lib/reasoning-effort.d.mts

@@ -0,0 +1,85 @@
+/**
+ * Type declarations for the CodeOps adaptive reasoning-effort helper.
+ *
+ * The helper is plain JavaScript so `node --test` can exercise it directly;
+ * these declarations give the TypeScript plugin entry point typed access.
+ */
+
+/** A level from the four-level suggestion vocabulary. */
+export type EffortLevel = "low" | "medium" | "high" | "max"
+
+/** A reasoning value accepted by `routing.roles.<agent>.reasoning`. */
+export type RoutingReasoning =
+  | "none"
+  | "minimal"
+  | "low"
+  | "medium"
+  | "high"
+  | "xhigh"
+  | "max"
+
+/** The four levels a plan or skill may suggest. */
+export declare const EFFORT_LEVELS: readonly EffortLevel[]
+
+/** Check whether a value is one of the four suggestion levels. */
+export declare function isEffortLevel(value: unknown): value is EffortLevel
+
+/** The reasoning values accepted by routing role entries. */
+export declare const ROUTING_REASONING_VALUES: readonly RoutingReasoning[]
+
+/** Check whether a value is a valid routing reasoning entry. */
+export declare function isRoutingReasoning(value: unknown): value is RoutingReasoning
+
+/** Find the first valid dispatch marker across message text parts. */
+export declare function findEffortMarker(texts: unknown): EffortLevel | undefined
+
+/** Candidate sources for {@link resolveEffort}. */
+export interface ResolveEffortInput {
+  marker?: unknown
+  session?: unknown
+  routing?: unknown
+}
+
+/** Resolve the effective level from the explicit sources, most specific first. */
+export declare function resolveEffort(
+  input?: ResolveEffortInput
+): EffortLevel | RoutingReasoning | undefined
+
+/** Compute the session state-file path inside the session temp directory. */
+export declare function sessionEffortPath(sessionID?: string, base?: string): string
+
+/** Parse session state-file text into a validated level. */
+export declare function parseStateFile(text: string): EffortLevel | undefined
+
+/** Read the session's reasoning-effort state file. */
+export declare function readSessionEffort(
+  sessionID?: string,
+  base?: string
+): EffortLevel | undefined
+
+/** Read an agent's explicit reasoning entry from the project routing config. */
+export declare function readRoutingReasoning(
+  config: unknown,
+  agent: unknown
+): RoutingReasoning | undefined
+
+/** Extract the model's runtime variant record, when the host exposes one. */
+export declare function extractModelVariants(
+  model: unknown
+): Record<string, unknown> | undefined
+
+/** Check whether a model advertises reasoning support. */
+export declare function modelSupportsReasoning(model: unknown): boolean
+
+/** Merge the model's variant options for a level into the request options. */
+export declare function applyEffort(
+  options: Record<string, unknown>,
+  level: unknown,
+  model: unknown
+): Record<string, unknown>
+
+/** Recursively merge plain objects into a new object. */
+export declare function deepMergePlain(
+  target: unknown,
+  source: unknown
+): Record<string, unknown>

package/bin/lib/reasoning-effort.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * Adaptive reasoning-effort helper for CodeOps sessions.
+ *
+ * The plugin needs one place to answer a simple question per request: "which
+ * reasoning level should this request use, if any?" This module answers it
+ * without any framework dependency so `node --test` can exercise every edge:
+ *
+ * - marker scanning over message text parts;
+ * - source precedence (dispatch marker, session flag, routing default);
+ * - routing-config lookup with hostile-shape tolerance;
+ * - provider-option application through the model's own variant record; and
+ * - reading the per-session state file written by the skills.
+ *
+ * Every function is deliberately total: malformed input yields "no override",
+ * never a thrown error. The plugin hooks sit on the request path, where a
+ * crash would break the user's session, so safety beats strictness here.
+ *
+ * @module lib/reasoning-effort
+ */
+
+import { lstatSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { sessionTmpDir } from "./tmp-hygiene.mjs"
+
+/**
+ * The four levels a plan or skill may suggest.
+ *
+ * These are the only values accepted in dispatch markers, session flags, and
+ * plan suggestions. Routing policy is project configuration and may name the
+ * wider provider enum instead.
+ */
+export const EFFORT_LEVELS = Object.freeze(["low", "medium", "high", "max"])
+
+/**
+ * The reasoning values accepted by `routing.roles.<agent>.reasoning` in the
+ * project configuration.
+ *
+ * The list mirrors the CodeOps config schema, which passes provider-native
+ * values through so a project can ask for `minimal` or `xhigh` even though the
+ * suggestion vocabulary only offers the four common levels.
+ */
+export const ROUTING_REASONING_VALUES = Object.freeze([
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+])
+
+/**
+ * Largest state file accepted by {@link readSessionEffort}.
+ *
+ * The real file is a few dozen bytes. The cap keeps a hostile or corrupt file
+ * from being slurped into memory if the temp directory is ever tampered with.
+ */
+const MAX_STATE_FILE_BYTES = 4096
+
+/**
+ * One standalone marker line, anchored to the whole line.
+ *
+ * The marker is intentionally different from the human-readable plan line
+ * `> **Reasoning**: ...`, so quoting a plan can never act as a machine
+ * directive. Whitespace inside the brackets is tolerated; text before or after
+ * is not.
+ */
+const MARKER_PATTERN = /^\[codeops-effort:\s*(low|medium|high|max)\]\s*$/
+
+/**
+ * Check whether a value is one of the four suggestion levels.
+ *
+ * @param value - Value to inspect
+ * @returns True only for `"low"`, `"medium"`, `"high"`, or `"max"`
+ *
+ * @example
+ * isEffortLevel("high") // true
+ * isEffortLevel("xhigh") // false
+ */
+export function isEffortLevel(value) {
+  return typeof value === "string" && EFFORT_LEVELS.includes(value)
+}
+
+/**
+ * Check whether a value is a valid routing reasoning entry.
+ *
+ * @param value - Value to inspect
+ * @returns True for any value in the routing enum
+ */
+export function isRoutingReasoning(value) {
+  return typeof value === "string" && ROUTING_REASONING_VALUES.includes(value)
+}
+
+/**
+ * Find the first valid dispatch marker across a list of message text parts.
+ *
+ * Only string entries are inspected; non-string entries (tool parts, images,
+ * malformed structures) are skipped so a hostile part can never break the
+ * request path. Lines are split on `\n`, `\r\n`, and `\r`, then trimmed before
+ * the anchored pattern is applied, so surrounding whitespace is tolerated.
+ *
+ * @param texts - Candidate text parts (usually the text of a message's parts)
+ * @returns The first valid level, or `undefined` when none is present
+ *
+ * @example
+ * findEffortMarker(["run the task", "[codeops-effort: medium]"]) // "medium"
+ */
+export function findEffortMarker(texts) {
+  if (!Array.isArray(texts)) return undefined
+  for (const text of texts) {
+    if (typeof text !== "string") continue
+    for (const line of text.split(/\r\n|\r|\n/)) {
+      const match = MARKER_PATTERN.exec(line.trim())
+      if (match) return match[1]
+    }
+  }
+  return undefined
+}
+
+/**
+ * Resolve the effective level from the three explicit sources.
+ *
+ * Precedence is "most specific wins": a dispatch marker beats a session
+ * flag, which beats a routing default. Each source is validated before it is
+ * accepted, so an invalid value is ignored rather than propagated. A
+ * non-object argument yields `undefined` instead of throwing.
+ *
+ * @param input - Candidate sources; all optional
+ * @returns The first valid value, or `undefined` when no source applies
+ *
+ * @example
+ * resolveEffort({ session: "high", routing: "low" }) // "high"
+ */
+export function resolveEffort(input) {
+  if (!isPlainObject(input)) return undefined
+  const { marker, session, routing } = input
+  if (isEffortLevel(marker)) return marker
+  if (isEffortLevel(session)) return session
+  if (isRoutingReasoning(routing)) return routing
+  return undefined
+}
+
+/**
+ * Compute the session state-file path inside the session temp directory.
+ *
+ * @param sessionID - Session identifier
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Absolute path to `reasoning-effort.json` for the session
+ */
+export function sessionEffortPath(sessionID, base) {
+  return join(sessionTmpDir(sessionID, base), "reasoning-effort.json")
+}
+
+/**
+ * Parse session state-file text into a validated level.
+ *
+ * The expected payload is `{"schema":1,"reasoning":"<level>"}` with any
+ * unknown keys ignored. Anything else — malformed JSON, the wrong schema, a
+ * level outside the four-level allowlist — yields `undefined`.
+ *
+ * @param text - Raw file contents
+ * @returns The validated level, or `undefined`
+ */
+export function parseStateFile(text) {
+  try {
+    const value = JSON.parse(text)
+    if (!isPlainObject(value)) return undefined
+    if (value.schema !== 1) return undefined
+    return isEffortLevel(value.reasoning) ? value.reasoning : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read the session's reasoning-effort state file.
+ *
+ * The file is written by `scripts/codeops_effort.py` for `--auto-effort`
+ * runs. Only a small regular file is accepted: a missing file, a non-regular
+ * file (symlinks are never followed), an oversized file, and any read or parse
+ * failure all mean "no session effort" and return `undefined`.
+ *
+ * @param sessionID - Session identifier
+ * @param base - Base temp directory (injectable for tests)
+ * @returns The session level, or `undefined`
+ */
+export function readSessionEffort(sessionID, base) {
+  try {
+    const path = sessionEffortPath(sessionID, base)
+    const info = lstatSync(path)
+    if (!info.isFile()) return undefined
+    if (info.size > MAX_STATE_FILE_BYTES) return undefined
+    return parseStateFile(readFileSync(path, "utf-8"))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read an agent's explicit reasoning entry from the project routing config.
+ *
+ * Only an own `routing.roles.<agent>.reasoning` property counts; unknown
+ * agents, missing sections, inherited properties, and malformed shapes all
+ * return `undefined` instead of throwing.
+ *
+ * @param config - Parsed `codeops/codeops.json` content (any shape)
+ * @param agent - Dispatching agent name
+ * @returns The configured routing value, or `undefined`
+ */
+export function readRoutingReasoning(config, agent) {
+  if (!isPlainObject(config)) return undefined
+  const routing = config.routing
+  if (!isPlainObject(routing)) return undefined
+  const roles = routing.roles
+  if (!isPlainObject(roles)) return undefined
+  if (typeof agent !== "string" || agent.length === 0) return undefined
+  if (!Object.prototype.hasOwnProperty.call(roles, agent)) return undefined
+  const entry = roles[agent]
+  if (!isPlainObject(entry)) return undefined
+  return isRoutingReasoning(entry.reasoning) ? entry.reasoning : undefined
+}
+
+/**
+ * Extract the model's runtime variant record, when the host exposes one.
+ *
+ * The installed SDK type does not declare `variants`, but the running host
+ * attaches it to every model. The `in` check keeps this graceful when the
+ * property is absent, and a cast is never used.
+ *
+ * @param model - Model object from the hook input
+ * @returns The variants record when it is a plain object, else `undefined`
+ */
+export function extractModelVariants(model) {
+  if (!isPlainObject(model)) return undefined
+  if (!("variants" in model)) return undefined
+  return isPlainObject(model.variants) ? model.variants : undefined
+}
+
+/**
+ * Check whether a model advertises reasoning support.
+ *
+ * @param model - Model object from the hook input
+ * @returns True only when `capabilities.reasoning` is exactly `true`
+ */
+export function modelSupportsReasoning(model) {
+  if (!isPlainObject(model)) return false
+  const capabilities = model.capabilities
+  if (!isPlainObject(capabilities)) return false
+  return capabilities.reasoning === true
+}
+
+/**
+ * Merge the model's variant options for a level into the request options.
+ *
+ * The runtime model carries a `variants` record whose entries are the exact
+ * provider options for each level (for example `reasoningEffort`, or a nested
+ * `reasoning.effort`). This function is the only place that mapping is
+ * consumed, so the plugin never hardcodes a provider key. The function is
+ * pure: it returns a new object when a change applies and the original object
+ * reference otherwise.
+ *
+ * @param options - Current provider options
+ * @param level - Candidate level from {@link resolveEffort}
+ * @param model - Model object from the hook input
+ * @returns The original options, or a new merged object when a change applies
+ */
+export function applyEffort(options, level, model) {
+  if (!isRoutingReasoning(level)) return options
+  if (!modelSupportsReasoning(model)) return options
+
+  const variants = extractModelVariants(model)
+  if (variants !== undefined) {
+    if (!Object.prototype.hasOwnProperty.call(variants, level)) return options
+    const variantOptions = variants[level]
+    if (!isPlainObject(variantOptions)) return options
+    return deepMergePlain(options, variantOptions)
+  }
+
+  return { ...options, reasoningEffort: level }
+}
+
+/**
+ * Recursively merge plain objects into a new object.
+ *
+ * Values that are not plain objects — arrays, class instances, primitives —
+ * are replaced, not merged. Neither input is mutated. The result is created
+ * with data properties, so a hostile `__proto__` key in a variant can never
+ * change the result's prototype chain.
+ *
+ * @param target - Base object
+ * @param source - Overrides to merge on top
+ * @returns A new merged plain object
+ */
+export function deepMergePlain(target, source) {
+  const result = isPlainObject(target) ? { ...target } : {}
+  if (!isPlainObject(source)) return result
+
+  for (const key of Object.keys(source)) {
+    const incoming = source[key]
+    const current = Object.prototype.hasOwnProperty.call(result, key)
+      ? result[key]
+      : undefined
+    const merged =
+      isPlainObject(incoming) && isPlainObject(current)
+        ? deepMergePlain(current, incoming)
+        : incoming
+    Object.defineProperty(result, key, {
+      value: merged,
+      writable: true,
+      enumerable: true,
+      configurable: true,
+    })
+  }
+
+  return result
+}
+
+/**
+ * Check whether a value is a plain object (not an array, class instance, or
+ * `null`).
+ *
+ * @param value - Value to inspect
+ * @returns True for `{}`-shaped objects and objects with a null prototype
+ */
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}

package/bin/lib/tmp-hygiene.d.mts

@@ -0,0 +1,38 @@
+/**
+ * Type declarations for the CodeOps temporary-directory lifecycle helper.
+ *
+ * The helper is plain JavaScript so `node --test` can exercise it directly;
+ * these declarations give the TypeScript plugin entry point typed access.
+ */
+
+/** Age after which a session directory is treated as abandoned. */
+export declare const DEFAULT_MAX_AGE_MS: number
+
+/** Directory name used when no usable session identifier exists. */
+export declare const SHARED_SESSION_NAME: string
+
+/** Resolve the CodeOps-owned temp root under a base temp directory. */
+export declare function codeopsTmpRoot(base?: string): string
+
+/** Reduce a session identifier to a safe single path segment. */
+export declare function sanitizeSessionId(sessionID?: string): string
+
+/** Compute the temp directory for one session. */
+export declare function sessionTmpDir(sessionID?: string, base?: string): string
+
+/** Create the session temp directory when it does not exist yet. */
+export declare function ensureSessionTmpDir(sessionID?: string, base?: string): string
+
+/** Inputs for a stale-directory sweep. */
+export interface CleanStaleTmpDirsOptions {
+  sessionID?: string
+  base?: string
+  maxAgeMs?: number
+  now?: number
+}
+
+/** Remove session directories abandoned by interrupted or crashed runs. */
+export declare function cleanStaleTmpDirs(options?: CleanStaleTmpDirsOptions): string[]
+
+/** Remove exactly one session's temp directory. */
+export declare function removeSessionTmpDir(sessionID?: string, base?: string): boolean

package/bin/lib/tmp-hygiene.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * Temporary-directory lifecycle for CodeOps sessions.
+ *
+ * The workspace-hygiene protocol asks every skill and agent to put scratch
+ * files under `$CODEOPS_TMPDIR` and delete them when the run completes. This
+ * module provides the safety net around that protocol:
+ *
+ * - it computes the per-session directory the plugin exports as
+ *   `$CODEOPS_TMPDIR`, under a CodeOps-owned root inside the OS temp directory;
+ * - it sweeps directories abandoned by interrupted runs once they are older
+ *   than a safety cap; and
+ * - it removes exactly one session's directory when that session is deleted.
+ *
+ * Safety is the whole point: every path derives from a sanitized session
+ * identifier, the sweep walks only the CodeOps-owned root, symlinked entries
+ * are treated as foreign, and cleanup is best effort so a failure never breaks
+ * a session.
+ *
+ * @module lib/tmp-hygiene
+ */
+
+import { lstatSync, mkdirSync, readdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join, resolve, sep } from "node:path"
+
+/**
+ * Age after which a session directory is treated as abandoned.
+ *
+ * A crashed or interrupted run leaves its directory behind; once it is this
+ * old, no live session can still need it, so the next sweep may remove it.
+ */
+export const DEFAULT_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
+
+/** Directory name used when no usable session identifier exists. */
+export const SHARED_SESSION_NAME = "shared"
+
+/**
+ * Resolve the CodeOps-owned temp root under a base temp directory.
+ *
+ * The plugin owns this subtree and nothing else under the system temp
+ * directory; keeping all CodeOps scratch under one root is what makes the
+ * automatic sweep safe.
+ *
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Path to the CodeOps temp root
+ */
+export function codeopsTmpRoot(base = tmpdir()) {
+  return join(base, "opencode", "codeops")
+}
+
+/**
+ * Reduce a session identifier to a safe single path segment.
+ *
+ * Session identifiers come from the host and must never influence the path
+ * shape: every character outside `A-Z`, `a-z`, `0-9`, `_`, and `-` is removed,
+ * so a value like `../../etc` cannot escape the temp root. An empty result
+ * falls back to a shared directory name.
+ *
+ * @param sessionID - Raw session identifier (may be missing)
+ * @returns A safe directory name
+ */
+export function sanitizeSessionId(sessionID) {
+  const cleaned = String(sessionID ?? "").replace(/[^A-Za-z0-9_-]/g, "")
+  return cleaned.length > 0 ? cleaned : SHARED_SESSION_NAME
+}
+
+/**
+ * Compute the temp directory for one session.
+ *
+ * @param sessionID - Raw session identifier (may be missing)
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Path to the session's temp directory
+ */
+export function sessionTmpDir(sessionID, base = tmpdir()) {
+  return join(codeopsTmpRoot(base), sanitizeSessionId(sessionID))
+}
+
+/**
+ * Create the session temp directory when it does not exist yet.
+ *
+ * Called while exporting the shell environment, so the directory is ready
+ * before the first command needs it.
+ *
+ * @param sessionID - Raw session identifier (may be missing)
+ * @param base - Base temp directory (injectable for tests)
+ * @returns Path to the session's temp directory
+ * @throws {Error} When the directory cannot be created
+ */
+export function ensureSessionTmpDir(sessionID, base = tmpdir()) {
+  const dir = sessionTmpDir(sessionID, base)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/**
+ * Remove session directories abandoned by interrupted or crashed runs.
+ *
+ * Only direct children of the CodeOps temp root are considered. Fresh
+ * directories, the current session's directory, plain files, and symlinks are
+ * left untouched; a symlink is never followed, so a link planted inside the
+ * root can never redirect a delete outside it. Failures are swallowed because
+ * a sweep is maintenance, not a task requirement.
+ *
+ * @param options - Sweep inputs
+ * @param options.sessionID - Current session identifier to preserve
+ * @param options.base - Base temp directory (injectable for tests)
+ * @param options.maxAgeMs - Abandonment age in milliseconds
+ * @param options.now - Current time in milliseconds (injectable for tests)
+ * @returns Paths of the directories that were removed
+ */
+export function cleanStaleTmpDirs({
+  sessionID,
+  base = tmpdir(),
+  maxAgeMs = DEFAULT_MAX_AGE_MS,
+  now = Date.now(),
+} = {}) {
+  const root = codeopsTmpRoot(base)
+  const keep = resolve(sessionTmpDir(sessionID, base))
+  const removed = []
+
+  let entries
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return removed
+  }
+
+  for (const entry of entries) {
+    // Directory entries are lstat-based, so a symlink to a directory reports
+    // as a symlink and is skipped here.
+    if (!entry.isDirectory()) continue
+
+    const full = join(root, entry.name)
+    if (resolve(full) === keep) continue
+
+    try {
+      const info = lstatSync(full)
+      if (!info.isDirectory()) continue
+      if (now - info.mtimeMs < maxAgeMs) continue
+      rmSync(full, { recursive: true, force: true })
+      removed.push(full)
+    } catch {
+      // Best effort: a directory that vanished mid-sweep is already gone.
+    }
+  }
+
+  return removed
+}
+
+/**
+ * Remove exactly one session's temp directory.
+ *
+ * Used when a session is deleted: its scratch can no longer be needed. The
+ * removal refuses anything that is not a regular directory strictly inside
+ * the CodeOps temp root, so a symlink or an unexpected path is left alone.
+ *
+ * @param sessionID - Session identifier whose directory should be removed
+ * @param base - Base temp directory (injectable for tests)
+ * @returns True when the directory was removed
+ */
+export function removeSessionTmpDir(sessionID, base = tmpdir()) {
+  const root = resolve(codeopsTmpRoot(base))
+  const dir = sessionTmpDir(sessionID, base)
+
+  if (!resolve(dir).startsWith(root + sep)) return false
+
+  try {
+    if (!lstatSync(dir).isDirectory()) return false
+  } catch {
+    return false
+  }
+
+  try {
+    rmSync(dir, { recursive: true, force: true })
+    return true
+  } catch {
+    return false
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codeops",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "description": "Specification-first engineering for complex systems — CodeOps plugin for OpenCode",
   "type": "module",
   "engines": {