pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.11

package/src/pantheon/v2-tools.ts

@@ -0,0 +1,418 @@
+/**
+ * V2 tool surface — the Pantheon tools that are self-sufficient on the
+ * OpenCode V2 host, declared for `ctx.tool.transform`'s `draft.add`.
+ *
+ * ## Why only three tools
+ *
+ * A V2 tool can only be served here when it needs no V1 infrastructure. The
+ * three goal tools (`pantheon_goal_create`, `pantheon_goal_get`,
+ * `pantheon_goal_update`) are NOT: `GoalLoopDeps` requires a `GoalStore`, a
+ * `GoalLoopClient` and a `BackgroundJobBoard`, none of which exist on the V2
+ * `PluginContext`, and `getV2BridgeFromContext` resolves to `null` outside V1.
+ * They are therefore absent from this surface rather than registered as
+ * placeholders that resolve to a message — a placeholder still fails the host's
+ * output contract on every call, so it buys nothing. See
+ * `V2_UNSUPPORTED_FEATURES` in `../plugin-v2.ts` (marker `goal-tools`).
+ *
+ * `hashline_edit` (pure filesystem), `pantheon_cost` (reads `opencode.db`) and
+ * `pantheon_model` (reads/writes `active-preset.json`) need none of that, so
+ * they are wired to their real V1 implementations.
+ *
+ * ## The output declaration is mandatory
+ *
+ * The host enforces a biconditional between a tool's declared `output` and the
+ * value its `execute` resolves to (opencode 2.0.22):
+ *
+ *   `def.output === undefined` and `'output' in result`   -> throws
+ *     "Tool result declared output without an output schema"
+ *   `def.output !== undefined` and `!('output' in result)` -> throws
+ *     "Tool did not return its declared output"
+ *
+ * Declaring `output` and returning it are therefore one decision, not two. The
+ * first branch is the historical Pantheon defect; the second is why the two
+ * must move together. `V2ToolDef` makes the field required so TypeScript
+ * rejects a tool that forgets it.
+ *
+ * @module pantheon/v2-tools
+ */
+
+import { createCostCommand } from './cost-command.ts'
+import { createHashlineEditTool, type HashlineToolResult } from './hashline/tool.ts'
+import { createModelCommand } from './model-command.ts'
+import type { ToolContextLike } from './tool-context.ts'
+import { createV2VisionTool, type V2VisionRuntime } from './v2-vision.ts'
+
+// ─── Contract types ─────────────────────────────────────────────────────
+
+/**
+ * V2 tool result shape.
+ *
+ * The V1 SDK types `ToolResult` as `string | { output: string, ... }`, but the
+ * V2 beta host reads a field off the resolved value and throws when a tool
+ * resolves to a bare string. Always resolve to the object shape — it satisfies
+ * both the SDK union and the beta host.
+ *
+ * `title` and `metadata` are part of the shape because `hashline_edit` returns
+ * them on success (see `HashlineToolResult`); the host spreads `metadata`
+ * through when present, so they are carried rather than dropped.
+ */
+export interface V2ToolResult {
+  output: string
+  title?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * A V2 tool definition ready for registration.
+ *
+ * `output` is REQUIRED, not optional: an omitted declaration is precisely the
+ * condition the host rejects at runtime, so making it optional would let the
+ * defect return silently.
+ */
+export interface V2ToolDef {
+  name: string
+  description: string
+  input: Record<string, unknown>
+  output: Record<string, unknown>
+  execute: (input: Record<string, unknown>, context: unknown) => Promise<V2ToolResult>
+}
+
+// ─── Context adapter ────────────────────────────────────────────────────
+
+/**
+ * Project the host's V2 tool context onto the structural `ToolContextLike`.
+ *
+ * The host may omit `directory`/`worktree`; `hashline_edit` then falls back to
+ * `process.cwd()` through its own `resolveFile` containment guard, so an absent
+ * field degrades safely rather than throwing.
+ */
+function toolContext(context: unknown): ToolContextLike {
+  const ctx = (context ?? {}) as Partial<ToolContextLike>
+  return {
+    sessionID: typeof ctx.sessionID === 'string' ? ctx.sessionID : 'v2-unknown',
+    // Spread rather than assign `undefined`: the project compiles with
+    // exactOptionalPropertyTypes, so an explicit undefined is not assignable.
+    ...(typeof ctx.directory === 'string' ? { directory: ctx.directory } : {}),
+    ...(typeof ctx.worktree === 'string' ? { worktree: ctx.worktree } : {}),
+    ...(typeof ctx.agent === 'string' ? { agent: ctx.agent } : {}),
+  }
+}
+
+/** Error text for an unexpected throw, without leaking a stack trace. */
+function errorText(prefix: string, err: unknown): string {
+  return `${prefix}: ${err instanceof Error ? err.message : String(err)}`
+}
+
+// ─── hashline_edit ──────────────────────────────────────────────────────
+
+/** JSON Schema for `hashline_edit`, mirroring the V1 zod args exactly. */
+const HASHLINE_EDIT_INPUT: Record<string, unknown> = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['file', 'edits'],
+  properties: {
+    file: {
+      type: 'string',
+      minLength: 1,
+      description: 'File to edit. Absolute, or relative to the worktree.',
+    },
+    edits: {
+      type: 'array',
+      minItems: 1,
+      description:
+        'Edits to apply. All refs are validated against the ORIGINAL file before anything is written.',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['op', 'ref'],
+        properties: {
+          op: { type: 'string', enum: ['replace', 'append', 'prepend', 'delete'] },
+          ref: {
+            type: 'string',
+            minLength: 1,
+            description: 'Anchor ref "LINE#TAG" against the ORIGINAL snapshot.',
+          },
+          endRef: {
+            type: 'string',
+            minLength: 1,
+            description: 'Optional range end for replace/delete, as "LINE#TAG".',
+          },
+          lines: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Replacement lines (replace only).',
+          },
+          content: {
+            type: 'string',
+            description: 'Text to insert (append/prepend); split on newlines.',
+          },
+        },
+      },
+    },
+  },
+}
+
+/** Coerced `hashline_edit` args, structurally equal to the V1 zod inference. */
+interface HashlineEditArgs {
+  file: string
+  edits: Array<{
+    op: 'replace' | 'append' | 'prepend' | 'delete'
+    ref: string
+    endRef?: string
+    lines?: string[]
+    content?: string
+  }>
+}
+
+const HASHLINE_OPS = new Set(['replace', 'append', 'prepend', 'delete'])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Re-validate the host-provided input against the declared JSON Schema.
+ *
+ * The host validates `input` before `execute`, but this wrapper is also the
+ * direct programmatic entry point (tests, embedded callers), so it must not
+ * assume a pre-validated shape. Failures are returned as error-as-text, the
+ * same contract the V1 tool uses for user errors.
+ */
+function coerceHashlineEditArgs(input: Record<string, unknown>):
+  | {
+      ok: true
+      args: HashlineEditArgs
+    }
+  | { ok: false; error: string } {
+  const file = input.file
+  if (typeof file !== 'string' || file.length === 0) {
+    return { ok: false, error: 'hashline_edit: "file" must be a non-empty string' }
+  }
+  const rawEdits = input.edits
+  if (!Array.isArray(rawEdits) || rawEdits.length === 0) {
+    return { ok: false, error: 'hashline_edit: "edits" must be a non-empty array' }
+  }
+  const edits: HashlineEditArgs['edits'] = []
+  for (const [i, raw] of rawEdits.entries()) {
+    if (!isRecord(raw)) {
+      return { ok: false, error: `hashline_edit: edit (index ${i}) must be an object` }
+    }
+    const op = raw.op
+    if (typeof op !== 'string' || !HASHLINE_OPS.has(op)) {
+      return {
+        ok: false,
+        error: `hashline_edit: edit (index ${i}) "op" must be one of replace, append, prepend, delete`,
+      }
+    }
+    const ref = raw.ref
+    if (typeof ref !== 'string' || ref.length === 0) {
+      return {
+        ok: false,
+        error: `hashline_edit: edit (index ${i}) "ref" must be a non-empty string`,
+      }
+    }
+    let lines: string[] | undefined
+    if (raw.lines !== undefined) {
+      if (!Array.isArray(raw.lines) || raw.lines.some((l) => typeof l !== 'string')) {
+        return {
+          ok: false,
+          error: `hashline_edit: edit (index ${i}) "lines" must be a string array`,
+        }
+      }
+      lines = raw.lines as string[]
+    }
+    if (raw.content !== undefined && typeof raw.content !== 'string') {
+      return { ok: false, error: `hashline_edit: edit (index ${i}) "content" must be a string` }
+    }
+    if (raw.endRef !== undefined && typeof raw.endRef !== 'string') {
+      return { ok: false, error: `hashline_edit: edit (index ${i}) "endRef" must be a string` }
+    }
+    edits.push({
+      op: op as HashlineEditArgs['edits'][number]['op'],
+      ref,
+      // Conditional spread: exactOptionalPropertyTypes forbids `prop: undefined`.
+      ...(typeof raw.endRef === 'string' ? { endRef: raw.endRef } : {}),
+      ...(lines === undefined ? {} : { lines }),
+      ...(typeof raw.content === 'string' ? { content: raw.content } : {}),
+    })
+  }
+  return { ok: true, args: { file, edits } }
+}
+
+const hashlineEdit = createHashlineEditTool()
+
+/**
+ * Wrap the V1 `hashline_edit` tool for the V2 surface.
+ *
+ * The V1 tool returns error-as-text for user errors and the success object
+ * `{ title, output, metadata }`. Both are carried: the `output` string always
+ * satisfies the host's declaration, and `title`/`metadata` survive because the
+ * host spreads metadata through.
+ */
+async function executeHashlineEdit(
+  input: Record<string, unknown>,
+  context: unknown,
+): Promise<V2ToolResult> {
+  const coerced = coerceHashlineEditArgs(input)
+  if (!coerced.ok) return { output: coerced.error }
+  let result: HashlineToolResult
+  try {
+    result = await hashlineEdit.execute(coerced.args, toolContext(context))
+  } catch (err: unknown) {
+    // The V1 tool does not throw for user errors; this is defence in depth so
+    // an unexpected throw surfaces as text instead of an absent tool result.
+    return { output: errorText('hashline_edit failed', err) }
+  }
+  if (typeof result === 'string') return { output: result }
+  return {
+    output: result.output,
+    ...(result.title === undefined ? {} : { title: result.title }),
+    ...(result.metadata === undefined ? {} : { metadata: result.metadata }),
+  }
+}
+
+// ─── pantheon_cost ──────────────────────────────────────────────────────
+
+/** JSON Schema for `pantheon_cost`, mirroring the V1 zod args. */
+const COST_INPUT: Record<string, unknown> = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    days: {
+      type: 'integer',
+      minimum: 1,
+      maximum: 365,
+      description: 'Reporting window in days (default 7).',
+    },
+  },
+}
+
+/** Validate `days` exactly as the V1 zod schema does; absent means default. */
+function coerceDays(value: unknown): { ok: true; days?: number } | { ok: false; error: string } {
+  if (value === undefined) return { ok: true }
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 365) {
+    return { ok: false, error: 'pantheon_cost: "days" must be an integer between 1 and 365' }
+  }
+  return { ok: true, days: value }
+}
+
+const costCommand = createCostCommand()
+
+async function executeCost(
+  input: Record<string, unknown>,
+  context: unknown,
+): Promise<V2ToolResult> {
+  const days = coerceDays(input.days)
+  if (!days.ok) return { output: days.error }
+  // The V1 tool already wraps its whole body and reports failures as text.
+  const output = await costCommand.pantheon_cost.execute({ days: days.days }, toolContext(context))
+  return { output }
+}
+
+// ─── pantheon_model ─────────────────────────────────────────────────────
+
+/** JSON Schema for V2 `pantheon_model`; global scope is intentionally absent. */
+const MODEL_INPUT: Record<string, unknown> = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: 'string',
+      enum: ['status', 'show', 'set', 'reset'],
+      description: 'Operation to perform. Defaults to status when agent/model are absent.',
+    },
+    agent: { type: 'string', description: 'Agent name (one of the 14 canonical agents).' },
+    model: { type: 'string', description: 'Model in provider/model-id format; used by set.' },
+    effort: {
+      type: 'string',
+      enum: ['low', 'medium', 'high'],
+      description: 'Reasoning effort (variant), clamped to model capability.',
+    },
+    scope: {
+      type: 'string',
+      enum: ['project'],
+      description: 'Project scope only; global overrides are not supported in V2.',
+    },
+  },
+}
+
+const modelCommand = createModelCommand({ v2Mode: true })
+
+async function executeModel(
+  input: Record<string, unknown>,
+  context: unknown,
+): Promise<V2ToolResult> {
+  if (input.scope !== undefined && input.scope !== 'project') {
+    return { output: 'Error: V2 pantheon_model is project-only; global scope is not supported.' }
+  }
+  if (Object.hasOwn(input, 'confirm') || Object.hasOwn(input, 'authorize_global')) {
+    return {
+      output:
+        'Error: V2 pantheon_model does not accept authorization flags; global authorization is not supported by this tool.',
+    }
+  }
+  // The V1 tool validates its own args (zod) and reports failures as text.
+  const output = await modelCommand.pantheon_model.execute(
+    input as Parameters<typeof modelCommand.pantheon_model.execute>[0],
+    toolContext(context),
+  )
+  return { output }
+}
+
+// ─── Tool set ───────────────────────────────────────────────────────────
+
+/**
+ * Build the V2 tool definitions.
+ *
+ * Every entry declares `output`. An empty object is the host's own marker for
+ * "declared, unconstrained" (its MCP bridge uses `output: g.outputSchema ??
+ * {}`), so it satisfies the declaration without adding a second way for a tool
+ * to fail validation. The protection against forgetting the field is the
+ * required `output` on `V2ToolDef`, not the emptiness of this schema.
+ *
+ * The three tool instances (`hashlineEdit`, `costCommand`, `modelCommand`) are
+ * module-level consts created once at import, not per call. What matters for
+ * this function is only that it allocates a fresh descriptor array each call,
+ * so a caller cannot mutate another's definitions. None of the three factories
+ * performs filesystem or database work at construction, so importing this
+ * module stays side-effect free.
+ */
+export function createV2ToolDefinitions(visionRuntime?: V2VisionRuntime): V2ToolDef[] {
+  const definitions: V2ToolDef[] = [
+    {
+      name: 'hashline_edit',
+      description:
+        'Edit a file anchored by hashline refs (LINE#TAG) instead of raw line numbers. ' +
+        'Ops: replace (ref..endRef or single ref → lines), append/prepend (anchor ref → content), ' +
+        'delete (ref..endRef). ALL refs must be validated against the ORIGINAL file before ' +
+        'anything is written; on mismatch the tool returns an error with a re-tagged excerpt ' +
+        'and a Did-you-mean suggestion, and nothing is modified.',
+      input: HASHLINE_EDIT_INPUT,
+      output: {},
+      execute: executeHashlineEdit,
+    },
+    {
+      name: 'pantheon_cost',
+      description:
+        'Report input, output, and total token usage by agent and phase over the last N days, ' +
+        'read from opencode.db (read-only, no monetary values).',
+      input: COST_INPUT,
+      output: {},
+      execute: executeCost,
+    },
+    {
+      name: 'pantheon_model',
+      description:
+        'Show, set, or reset explicit per-agent project-scoped model overrides in active-preset.json. ' +
+        'V2 ignores static preset names and PANTHEON_MODEL_PRESET; no wizard or implicit model ' +
+        'selection. Global overrides are not read or written in V2; future global support requires ' +
+        'separate explicit authorization. Pass action="status" to read project-scoped overrides. ' +
+        'Never writes .env or top-level model/small_model.',
+      input: MODEL_INPUT,
+      output: {},
+      execute: executeModel,
+    },
+  ]
+  if (visionRuntime) definitions.push(createV2VisionTool(visionRuntime))
+  return definitions
+}

package/src/pantheon/v2-unsupported.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Type declarations for v2-unsupported.mjs (the V2 feature-reduction seed).
+ * Consumed by src/plugin-v2.ts via `import ... from './pantheon/v2-unsupported.mjs'`,
+ * and by the plain-`.mjs` install/health scripts at runtime.
+ */
+
+/** Statically-known V2 feature reductions, in report order. */
+export declare const V2_UNSUPPORTED_FEATURE_SEED: readonly string[]
+
+/** A fresh, mutable copy of the seed, so a reporter cannot mutate the shared list. */
+export declare function listV2UnsupportedFeatures(): string[]

package/src/pantheon/v2-unsupported.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * v2-unsupported.mjs — the SEED of V2 feature reductions, in plain ESM.
+ *
+ * WHY A SEPARATE PLAIN-`.mjs` MODULE: these strings must be readable by three
+ * very different consumers, and only one of them can import TypeScript.
+ *
+ *   - `src/plugin-v2.ts` (TypeScript) — owns the LIVE list, appending to it at
+ *     runtime via `markUnsupported()` when a host API turns out to be missing,
+ *     and exposes it through `getUnsupportedFeatures()`.
+ *   - `scripts/install/opencode.mjs` — reports the reduction at install time
+ *     for a V2-generation install.
+ *   - `scripts/doctor.mjs` — reports it in the health gate.
+ *
+ * The scripts are plain Node ESM and must stay that way, and `.mjs` is a
+ * REPO-WIDE INVARIANT rather than a judgement about Node: `tsx` is a
+ * devDependency only, and no plain-Node script in `scripts/` or `bin/` imports
+ * a `.ts` module — every `.ts` path there is a string to copy, stat or read as
+ * text (`scripts/install/opencode.mjs`, `scripts/probe-pantheon-cost.mjs`,
+ * `scripts/package-evidence.mjs`, `scripts/check-plugin-v2-coverage.mjs`).
+ * So a `.mjs` import is the only form all three consumers can share, and it
+ * matches the existing `src/pantheon/presets.mjs` + `.d.mts` precedent.
+ *
+ * NOT the reason: type-stripping. `package.json#engines` admits
+ * `^22.22.2 || ^24.15.0 || >=26.0.0`, every admitted version already defaults to
+ * unflagged type-stripping (it landed in 22.18.0), so that argument would not
+ * have held on any admitted version. The live hazard is that `engines` is not
+ * ENFORCED: a Node 20 user can run `doctor` and would get no type-stripping,
+ * which is an argument for a runtime version check, not for this file's shape.
+ *
+ * The SEED is the statically-known half of `getUnsupportedFeatures()`: what a
+ * migrating user loses by choosing the V2 contract, knowable with no host at
+ * all. Runtime-appended entries (`tool-transform`, `event-stream`, …) are
+ * observations about one live host and are deliberately NOT seeded here — they
+ * are not known until the plugin runs against a real V2 host.
+ *
+ * ONE SOURCE OF TRUTH: install and doctor both read the seed from here, so the
+ * two cannot drift apart, and what they report IS what this file lists. Note the
+ * scope of that claim: it holds between the SEED and the two reporters. The
+ * LIVE list `getUnsupportedFeatures()` returns is this seed PLUS markers appended
+ * at runtime (`tool-transform`, `event-stream`, …), so it is a superset and the
+ * two are expected to differ there. Do not copy these strings into a script;
+ * import them.
+ *
+ * @module v2-unsupported
+ */
+
+/**
+ * Statically-known V2 feature reductions, in the order a reader should meet
+ * them. Frozen: `plugin-v2.ts` copies it into its own mutable live array, and
+ * every other consumer goes through {@link listV2UnsupportedFeatures}.
+ *
+ * @type {readonly string[]}
+ */
+export const V2_UNSUPPORTED_FEATURE_SEED = Object.freeze([
+  'legacy-hooks',
+  // `ctx.catalog` is the one domain a live 2.0.22 host does NOT have: it is
+  // absent from `Object.keys(ctx)`, measured in
+  // tests/canary/plugin-v2-tool-canary.test.mjs. (`catalog` IS in the 1.18.33
+  // SDK's PluginContext, so the SDK types it and the host does not provide it.)
+  'catalog-transform',
+  // Adapter support, NOT host availability: 2.0.22 exposes ctx.integration and
+  // ctx.skill with callable transforms, and Pantheon deliberately registers
+  // neither. These entries record what this plugin does not implement.
+  'integration-transform',
+  // The inspected SkillEditor shape has no `source()` helper — i.e. no
+  // `SkillEditor.source()` — for adding a directory source. This is narrower
+  // than (and distinct from) ctx.skill's host availability or callable
+  // transform, which a live 2.0.22 host does provide.
+  'skill-transform',
+  // Adapter limitation, not a host gap: the goal loop needs a GoalStore, a
+  // GoalLoopClient and a BackgroundJobBoard, none of which the V2
+  // PluginContext exposes, and the V1 bridge resolves to null outside V1.
+  // pantheon_goal_create/get/update are therefore absent from the V2 surface
+  // rather than registered as non-functional placeholders.
+  'goal-tools',
+])
+
+/**
+ * A fresh, mutable copy of the seed.
+ *
+ * Callers get a copy so a reporter that sorts, filters or appends cannot reach
+ * back into the shared list — this is what makes "both surfaces report the same
+ * strings" a structural property rather than a convention.
+ *
+ * @returns {string[]}
+ */
+export function listV2UnsupportedFeatures() {
+  return [...V2_UNSUPPORTED_FEATURE_SEED]
+}