@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.1

package/src/component.ts

@@ -0,0 +1,73 @@
+import { componentFeatures } from "./features"
+import { BusEvent } from "@ericsanchezok/synergy-harness/bus/bus-event"
+import { Vcs } from "./project/vcs"
+import { Ide } from "./project/ide"
+import { ReviewState } from "./review/state"
+import { ExecutionSchema } from "./execution/schema"
+import { registerProjectMigrations } from "./project/migration"
+import { PushBridge } from "./push/bridge"
+import type { RuntimeComponent } from "@ericsanchezok/synergy-harness/lifecycle"
+import { version } from "../package.json" with { type: "json" }
+import { registerWorkbenchAgents } from "./agents"
+import { registerProjectTools } from "./project/tools"
+import { registerProjectStartup } from "./project/startup"
+import { registerProjectSessionHealth } from "./project/session-health"
+import { registerConfig } from "./config-schema"
+import { Usage } from "@ericsanchezok/synergy-harness/usage"
+import { ExecutionService } from "./execution/service"
+import { WorkbenchPresentation } from "./presentation/service"
+import { registerPresentationTools } from "./presentation/tools"
+
+export function workbench(): RuntimeComponent {
+  return {
+    id: "workbench",
+    features: componentFeatures,
+    apiVersion: 1,
+    version,
+    requires: { "local-runtime": version },
+    workers: { agent: new URL("./worker.ts", import.meta.url) },
+    services() {
+      let dispose: (() => void) | undefined
+      let stopUsage: (() => Promise<void>) | undefined
+      let stopExecution: (() => void) | undefined
+      let stopPresentation: (() => void) | undefined
+      return {
+        resident: {
+          async start() {
+            dispose = PushBridge.init()
+            stopUsage = Usage.service()
+            stopExecution = ExecutionService.init()
+            stopPresentation = WorkbenchPresentation.init()
+          },
+          async stop() {
+            stopPresentation?.()
+            stopPresentation = undefined
+            await stopUsage?.()
+            stopExecution?.()
+            stopUsage = undefined
+            dispose?.()
+            dispose = undefined
+            await PushBridge.flush()
+          },
+        },
+      }
+    },
+    adapters: { cli: new URL("./cli-adapter.ts", import.meta.url), http: new URL("./http.ts", import.meta.url) },
+    register() {
+      BusEvent.register(
+        ...Object.values(Vcs.Event),
+        ...Object.values(Ide.Event),
+        ReviewState.Updated,
+        ExecutionSchema.Updated,
+        ExecutionSchema.ProjectionUpdated,
+      )
+      registerConfig()
+      registerProjectMigrations()
+      registerWorkbenchAgents()
+      registerProjectTools()
+      registerPresentationTools()
+      registerProjectStartup()
+      registerProjectSessionHealth()
+    },
+  }
+}

package/src/config-schema.ts

@@ -0,0 +1,289 @@
+import { ConfigDomain } from "@ericsanchezok/synergy-harness/config/domain"
+import z from "zod"
+import { ConfigExtensions } from "@ericsanchezok/synergy-harness/config/extensions"
+export const Keybinds = z
+  .object({
+    leader: z.string().optional().default("ctrl+x").describe("Leader key for keybind combinations"),
+    app_exit: z.string().optional().default("ctrl+c,ctrl+d,<leader>q").describe("Exit the application"),
+    editor_open: z.string().optional().default("<leader>e").describe("Open external editor"),
+    theme_list: z.string().optional().default("<leader>t").describe("List available themes"),
+    sidebar_toggle: z.string().optional().default("<leader>b").describe("Toggle sidebar"),
+    scrollbar_toggle: z.string().optional().default("none").describe("Toggle session scrollbar"),
+    username_toggle: z.string().optional().default("none").describe("Toggle username visibility"),
+    status_view: z.string().optional().default("<leader>s").describe("View status"),
+    session_export: z.string().optional().default("<leader>x").describe("Export session to editor"),
+    session_new: z.string().optional().default("<leader>n").describe("Create a new session"),
+    session_list: z.string().optional().default("<leader>l").describe("List all sessions"),
+    session_timeline: z.string().optional().default("<leader>g").describe("Show session timeline"),
+    session_fork: z.string().optional().default("none").describe("Fork session from message"),
+    session_rename: z.string().optional().default("none").describe("Rename session"),
+    session_interrupt: z.string().optional().default("escape").describe("Interrupt current session"),
+    session_compact: z.string().optional().default("<leader>c").describe("Compact the session"),
+    messages_page_up: z.string().optional().default("pageup").describe("Scroll messages up by one page"),
+    messages_page_down: z.string().optional().default("pagedown").describe("Scroll messages down by one page"),
+    messages_half_page_up: z.string().optional().default("ctrl+alt+u").describe("Scroll messages up by half page"),
+    messages_half_page_down: z.string().optional().default("ctrl+alt+d").describe("Scroll messages down by half page"),
+    messages_first: z.string().optional().default("ctrl+g,home").describe("Navigate to first message"),
+    messages_last: z.string().optional().default("ctrl+alt+g,end").describe("Navigate to last message"),
+    messages_next: z.string().optional().default("none").describe("Navigate to next message"),
+    messages_previous: z.string().optional().default("none").describe("Navigate to previous message"),
+    messages_last_user: z.string().optional().default("none").describe("Navigate to last user message"),
+    messages_copy: z.string().optional().default("<leader>y").describe("Copy message"),
+    messages_undo: z.string().optional().default("<leader>u").describe("Undo message history only"),
+    messages_redo: z.string().optional().default("<leader>r").describe("Redo message history only"),
+    messages_toggle_conceal: z
+      .string()
+      .optional()
+      .default("<leader>h")
+      .describe("Toggle code block concealment in messages"),
+    tool_details: z.string().optional().default("none").describe("Toggle tool details visibility"),
+    model_list: z.string().optional().default("<leader>m").describe("List available models"),
+    model_cycle_recent: z.string().optional().default("f2").describe("Next recently used model"),
+    model_cycle_recent_reverse: z.string().optional().default("shift+f2").describe("Previous recently used model"),
+    model_cycle_favorite: z.string().optional().default("none").describe("Next favorite model"),
+    model_cycle_favorite_reverse: z.string().optional().default("none").describe("Previous favorite model"),
+    command_list: z.string().optional().default("ctrl+p").describe("List available commands"),
+    agent_list: z.string().optional().default("<leader>a").describe("List agents"),
+    agent_cycle: z.string().optional().default("tab").describe("Next agent"),
+    agent_cycle_reverse: z.string().optional().default("shift+tab").describe("Previous agent"),
+    variant_cycle: z.string().optional().default("ctrl+t").describe("Cycle model variants"),
+    input_clear: z.string().optional().default("ctrl+c").describe("Clear input field"),
+    input_paste: z.string().optional().default("ctrl+v").describe("Paste from clipboard"),
+    input_submit: z.string().optional().default("return").describe("Submit input"),
+    input_newline: z
+      .string()
+      .optional()
+      .default("shift+return,ctrl+return,alt+return,ctrl+j")
+      .describe("Insert newline in input"),
+    input_move_left: z.string().optional().default("left,ctrl+b").describe("Move cursor left in input"),
+    input_move_right: z.string().optional().default("right,ctrl+f").describe("Move cursor right in input"),
+    input_move_up: z.string().optional().default("up").describe("Move cursor up in input"),
+    input_move_down: z.string().optional().default("down").describe("Move cursor down in input"),
+    input_select_left: z.string().optional().default("shift+left").describe("Select left in input"),
+    input_select_right: z.string().optional().default("shift+right").describe("Select right in input"),
+    input_select_up: z.string().optional().default("shift+up").describe("Select up in input"),
+    input_select_down: z.string().optional().default("shift+down").describe("Select down in input"),
+    input_line_home: z.string().optional().default("ctrl+a").describe("Move to start of line in input"),
+    input_line_end: z.string().optional().default("ctrl+e").describe("Move to end of line in input"),
+    input_select_line_home: z.string().optional().default("ctrl+shift+a").describe("Select to start of line in input"),
+    input_select_line_end: z.string().optional().default("ctrl+shift+e").describe("Select to end of line in input"),
+    input_visual_line_home: z.string().optional().default("alt+a").describe("Move to start of visual line in input"),
+    input_visual_line_end: z.string().optional().default("alt+e").describe("Move to end of visual line in input"),
+    input_select_visual_line_home: z
+      .string()
+      .optional()
+      .default("alt+shift+a")
+      .describe("Select to start of visual line in input"),
+    input_select_visual_line_end: z
+      .string()
+      .optional()
+      .default("alt+shift+e")
+      .describe("Select to end of visual line in input"),
+    input_buffer_home: z.string().optional().default("home").describe("Move to start of buffer in input"),
+    input_buffer_end: z.string().optional().default("end").describe("Move to end of buffer in input"),
+    input_select_buffer_home: z
+      .string()
+      .optional()
+      .default("shift+home")
+      .describe("Select to start of buffer in input"),
+    input_select_buffer_end: z.string().optional().default("shift+end").describe("Select to end of buffer in input"),
+    input_delete_line: z.string().optional().default("ctrl+shift+d").describe("Delete line in input"),
+    input_delete_to_line_end: z.string().optional().default("ctrl+k").describe("Delete to end of line in input"),
+    input_delete_to_line_start: z.string().optional().default("ctrl+u").describe("Delete to start of line in input"),
+    input_backspace: z.string().optional().default("backspace,shift+backspace").describe("Backspace in input"),
+    input_delete: z.string().optional().default("ctrl+d,delete,shift+delete").describe("Delete character in input"),
+    input_undo: z.string().optional().default("ctrl+-,super+z").describe("Undo in input"),
+    input_redo: z.string().optional().default("ctrl+.,super+shift+z").describe("Redo in input"),
+    input_word_forward: z
+      .string()
+      .optional()
+      .default("alt+f,alt+right,ctrl+right")
+      .describe("Move word forward in input"),
+    input_word_backward: z
+      .string()
+      .optional()
+      .default("alt+b,alt+left,ctrl+left")
+      .describe("Move word backward in input"),
+    input_select_word_forward: z
+      .string()
+      .optional()
+      .default("alt+shift+f,alt+shift+right")
+      .describe("Select word forward in input"),
+    input_select_word_backward: z
+      .string()
+      .optional()
+      .default("alt+shift+b,alt+shift+left")
+      .describe("Select word backward in input"),
+    input_delete_word_forward: z
+      .string()
+      .optional()
+      .default("alt+d,alt+delete,ctrl+delete")
+      .describe("Delete word forward in input"),
+    input_delete_word_backward: z
+      .string()
+      .optional()
+      .default("ctrl+w,ctrl+backspace,alt+backspace")
+      .describe("Delete word backward in input"),
+    history_previous: z.string().optional().default("up").describe("Previous history item"),
+    history_next: z.string().optional().default("down").describe("Next history item"),
+    session_child_cycle: z.string().optional().default("<leader>right").describe("Next child session"),
+    session_child_cycle_reverse: z.string().optional().default("<leader>left").describe("Previous child session"),
+    session_parent: z.string().optional().default("<leader>up").describe("Go to parent session"),
+    terminal_suspend: z.string().optional().default("ctrl+z").describe("Suspend terminal"),
+    terminal_title_toggle: z.string().optional().default("none").describe("Toggle terminal title"),
+    tips_toggle: z.string().optional().default("<leader>h").describe("Toggle tips on home screen"),
+  })
+  .strict()
+  .meta({
+    ref: "KeybindsConfig",
+  })
+
+export const Layout = z.enum(["auto", "stretch"]).meta({
+  ref: "LayoutConfig",
+})
+
+export type Layout = z.infer<typeof Layout>
+
+const QuickSwitcherModel = z
+  .object({
+    providerID: z.string().describe("Provider id for the quick switcher model preference"),
+    modelID: z.string().describe("Model id for the quick switcher model preference"),
+    state: z.enum(["add", "remove"]).describe("Whether to force-add or force-remove the model from the quick switcher"),
+  })
+  .strict()
+  .meta({ ref: "QuickSwitcherModelConfig" })
+
+export type QuickSwitcherModel = z.infer<typeof QuickSwitcherModel>
+
+export const QuickSwitcher = z
+  .object({
+    models: z.array(QuickSwitcherModel).optional().describe("Per-model quick switcher visibility preferences"),
+  })
+  .strict()
+  .meta({ ref: "QuickSwitcherConfig" })
+
+export type QuickSwitcher = z.infer<typeof QuickSwitcher>
+
+export const ConfigShape = {
+  locale: z.enum(["system", "en", "zh-CN"]).optional().describe("UI locale (system = follow OS, default: system)"),
+  theme: z.string().optional().describe("Theme name to use for the interface"),
+  activityDisplay: z
+    .enum(["full", "balanced", "minimal"])
+    .optional()
+    .describe(
+      "Execution process detail: full = expanded process, balanced = current stage with completed process collapsed, minimal = compact progress. All modes use the same process view (default: balanced)",
+    ),
+  defaultSessionWorkspace: z
+    .enum(["main", "worktree"])
+    .optional()
+    .describe(
+      "Default workspace for new sessions started from the Web composer: main = run in the main checkout, " +
+        "worktree = start each new session in an isolated git worktree (default: main). " +
+        "Programmatic session creation (API, channels, Cortex) always uses the main checkout.",
+    ),
+  defaultSessionEnvironmentProfile: z
+    .string()
+    .min(1)
+    .nullable()
+    .optional()
+    .describe(
+      "Execution profile for new Web/Desktop composer sessions. Omitted follows the global resource default; null disables execution selection. References an existing global profile without defining hosts or credentials.",
+    ),
+  keybinds: Keybinds.optional().describe("Custom keybind configurations"),
+  compactReasoning: z
+    .boolean()
+    .optional()
+    .describe("Show a compact reasoning preview in the execution process (default: false)"),
+  preferWorkBrief: z
+    .boolean()
+    .optional()
+    .describe("Prefer a tool call's purpose description over its action and target when available (default: false)"),
+  quick_switcher: QuickSwitcher.optional().describe("Quick switcher model visibility preferences"),
+  welcomeGames: z
+    .boolean()
+    .optional()
+    .describe("Show interactive games on the new-task greeting (default: true). Set false to render a plain greeting."),
+  layout: Layout.optional().describe("@deprecated Always uses stretch layout."),
+  toast: z
+    .object({
+      muted: z
+        .array(z.enum(["info", "success", "warning", "error"]))
+        .optional()
+        .describe("Toast types to suppress. The underlying logic still runs but the visual card is not rendered."),
+      durationOverrides: z
+        .record(z.enum(["info", "success", "warning", "error"]), z.number().int().positive().max(30000))
+        .optional()
+        .describe("Override auto-dismiss duration in ms per toast type (max 30s)."),
+    })
+    .strict()
+    .optional()
+    .describe("Toast notification preferences"),
+}
+
+export type ConfigValues = z.output<z.ZodObject<typeof ConfigShape>>
+
+declare module "@ericsanchezok/synergy-harness/config/schema" {
+  interface ConfigExtensionShape extends ConfigShapeType {}
+}
+type ConfigShapeType = typeof ConfigShape
+
+const contribution: ConfigExtensions.Contribution = {
+  shape: ConfigShape,
+  references(raw, providerID) {
+    const config = raw as ConfigValues
+    return (config.quick_switcher?.models ?? []).flatMap((model, index) =>
+      model.providerID === providerID ? [`quick_switcher.models[${index}]`] : [],
+    )
+  },
+  normalize(raw) {
+    const result = raw as ConfigValues
+    if (result.activityDisplay === undefined) result.activityDisplay = "balanced"
+    if (result.compactReasoning === undefined) result.compactReasoning = false
+    if (result.preferWorkBrief === undefined) result.preferWorkBrief = false
+    if (!result.keybinds) result.keybinds = Keybinds.parse({})
+  },
+}
+
+export function registerConfig() {
+  ConfigExtensions.register("workbench", contribution)
+  for (const domain of [
+    {
+      id: "general",
+      filename: "00-general.jsonc",
+      label: "General",
+      ownedKeys: [
+        "theme",
+        "keybinds",
+        "toast",
+        "compactReasoning",
+        "preferWorkBrief",
+        "welcomeGames",
+        "locale",
+        "activityDisplay",
+        "defaultSessionWorkspace",
+        "defaultSessionEnvironmentProfile",
+        "layout",
+      ],
+      mergePolicy: "merge",
+      reloadTargets: ["config"],
+      uiSection: "general",
+      importable: true,
+    },
+    {
+      id: "models",
+      filename: "10-models.jsonc",
+      label: "Models",
+      ownedKeys: ["quick_switcher"],
+      mergePolicy: "merge",
+      reloadTargets: ["config"],
+      uiSection: "models",
+      importable: true,
+    },
+  ] satisfies ConfigDomain.Definition[])
+    ConfigDomain.register(domain)
+}
+
+export async function readConfig(): Promise<ConfigValues> {
+  const { Config } = await import("@ericsanchezok/synergy-harness/config/config")
+  return Config.current()
+}

package/src/execution/activity.ts

@@ -0,0 +1,83 @@
+import type { ExecutionSchema } from "./schema"
+
+export namespace ExecutionActivity {
+  export type Segment = { runID: string | null; from: number; to: number; count: number; rounds: number }
+  export function project(rows: readonly ExecutionSchema.Node[], root: string) {
+    const byID = new Map(rows.map((node) => [node.id, node]))
+    const requests = new Set(rows.filter((node) => node.evidenceKind === "attempt").map((node) => node.parentID))
+    const instructions = new Set(
+      rows.filter((node) => node.kind === "subtask").map((node) => node.sessionID + ":" + node.runID),
+    )
+    const nodes = rows
+      .filter(
+        (node) =>
+          node.kind === "subtask" ||
+          node.kind === "tool" ||
+          (node.kind === "input" &&
+            (node.sessionID === root || !instructions.has(node.sessionID + ":" + node.runID))) ||
+          node.evidenceKind === "attempt" ||
+          (node.evidenceKind === "call" && !requests.has(node.id)),
+      )
+      .map((node, index) => ({
+        ...node,
+        activity: {
+          index,
+          count: 1,
+          endIndex: index,
+          instruction: node.kind === "subtask" || (node.kind === "input" && node.sessionID !== root),
+        },
+      }))
+    const segments: Segment[] = []
+    for (const node of nodes) {
+      let ancestor: ExecutionSchema.Node | undefined = node
+      const seen = new Set<string>()
+      while (ancestor && ancestor.sessionID !== root && ancestor.parentID && !seen.has(ancestor.id)) {
+        seen.add(ancestor.id)
+        ancestor = byID.get(ancestor.parentID)
+      }
+      const runID = ancestor?.sessionID === root ? ancestor.runID : null
+      const last = segments.at(-1)
+      if (last?.runID === runID) {
+        last.to = node.activity.index
+        last.count++
+      } else segments.push({ runID, from: node.activity.index, to: node.activity.index, count: 1, rounds: 1 })
+    }
+    const chunks: Segment[] = []
+    const size = Math.max(1, Math.ceil(segments.length / 160))
+    for (let index = 0; index < segments.length; index += size) {
+      const values = segments.slice(index, index + size)
+      chunks.push({
+        runID: values.length === 1 ? values[0].runID : null,
+        from: values[0].from,
+        to: values.at(-1)!.to,
+        count: values.reduce((sum, value) => sum + value.count, 0),
+        rounds: new Set(values.map((value) => value.runID)).size,
+      })
+    }
+    return {
+      nodes,
+      segments: chunks,
+      humanInputs: nodes.filter((node) => node.kind === "input" && !node.activity.instruction).length,
+      taskInstructions: nodes.filter((node) => node.activity.instruction).length,
+    }
+  }
+  export function aggregate(nodes: ReturnType<typeof project>["nodes"], kind: "input" | "model" | "tool") {
+    const lane = nodes.filter((node) =>
+      kind === "input"
+        ? node.kind === "input" || node.kind === "subtask"
+        : kind === "model"
+          ? node.evidenceKind === "call" || node.evidenceKind === "attempt"
+          : node.kind === "tool",
+    )
+    const size = Math.max(1, Math.ceil(lane.length / 160))
+    const result = []
+    for (let index = 0; index < lane.length; index += size) {
+      const bucket = lane.slice(index, index + size)
+      result.push({
+        ...bucket[0],
+        activity: { ...bucket[0].activity, count: bucket.length, endIndex: bucket.at(-1)!.activity.index },
+      })
+    }
+    return result
+  }
+}

package/src/execution/content.ts

@@ -0,0 +1,189 @@
+import { ExecutionQueryError, queryCursor } from "./query"
+import { z } from "zod"
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context"
+import { RolloutEvidence } from "@ericsanchezok/synergy-harness/rollout"
+import { ExecutionJson } from "./json-sections"
+import { ScopeContext } from "@ericsanchezok/synergy-harness/scope/context"
+
+export namespace ExecutionContent {
+  export type Source = {
+    mediaType: string
+    bytes: number
+    status: "partial" | "complete"
+    contentVersion: string
+    sha256: string | null
+    read: (offset: number, limit: number) => Promise<z.infer<typeof RolloutEvidence.Content>>
+    stream: () => AsyncIterable<Uint8Array>
+  }
+  export const Query = z.object({
+    field: z.string().min(1).max(100),
+    runID: z.string().optional(),
+    version: z.string().max(4096).optional(),
+  })
+  export const PageQuery = Query.extend({
+    cursor: z.string().max(4096).optional(),
+    limit: z.coerce.number().int().min(1).max(500).default(100),
+  })
+  export const SearchQuery = PageQuery.extend({
+    query: z.string().min(1).max(500),
+    caseSensitive: z.preprocess((value) => (value === "false" ? false : value), z.coerce.boolean()).default(true),
+  })
+  export const Section = z.object({
+    path: z.array(z.string()),
+    kind: z.enum(["object", "array", "string", "number", "boolean", "null"]),
+    offset: z.number(),
+    bytes: z.number(),
+    role: z.string().optional(),
+    preview: z.string(),
+  })
+  export const Sections = z
+    .object({
+      contentVersion: z.string(),
+      format: z.enum(["json", "text", "partial"]),
+      items: z.array(Section),
+      total: z.number(),
+      nextCursor: z.string().nullable(),
+      truncated: z.boolean(),
+    })
+    .meta({ ref: "ExecutionContentSections" })
+  export const Search = z
+    .object({
+      contentVersion: z.string(),
+      status: z.enum(["partial", "complete"]),
+      items: z.array(z.object({ offset: z.number(), bytes: z.number(), preview: z.string() })),
+      nextCursor: z.string().nullable(),
+    })
+    .meta({ ref: "ExecutionContentSearch" })
+  const cache = RuntimeContext.state(() => ({
+    entries: new Map<string, { value: Awaited<ReturnType<typeof ExecutionJson.index>>; bytes: number }>(),
+    bytes: 0,
+  }))
+  function cursor(version: string, query: string, offset: number) {
+    return Buffer.from(JSON.stringify({ version, query, offset })).toString("base64url")
+  }
+  function position(input: string | undefined, version: string, query: string) {
+    if (!input) return 0
+    const value = queryCursor(
+      z.object({ version: z.string(), query: z.string(), offset: z.number().int().nonnegative() }),
+      input,
+    )
+    if (value.version !== version || value.query !== query)
+      throw new ExecutionQueryError("Execution content cursor does not match its version and query")
+    return value.offset
+  }
+  export async function sections(source: Source, input: z.infer<typeof PageQuery>, signal?: AbortSignal) {
+    const offset = position(input.cursor, source.contentVersion, "sections")
+    if (source.status === "partial" || !source.mediaType.includes("json"))
+      return Sections.parse({
+        contentVersion: source.contentVersion,
+        format: source.status === "partial" ? "partial" : "text",
+        items: [],
+        total: 0,
+        nextCursor: null,
+        truncated: false,
+      })
+    const state = cache()
+    const key = ScopeContext.current.scope.id + ":" + source.contentVersion
+    let value = state.entries.get(key)?.value
+    if (!value) {
+      try {
+        value = await ExecutionJson.index(source.stream(), signal)
+      } catch (error) {
+        if (!(error instanceof SyntaxError)) throw error
+        return Sections.parse({
+          contentVersion: source.contentVersion,
+          format: "text",
+          items: [],
+          total: 0,
+          nextCursor: null,
+          truncated: false,
+        })
+      }
+      const bytes = Buffer.byteLength(JSON.stringify(value))
+      if (!state.entries.has(key) && bytes <= 8 * 1024 * 1024) {
+        while (state.bytes + bytes > 8 * 1024 * 1024 && state.entries.size) {
+          const [key, entry] = state.entries.entries().next().value!
+          state.entries.delete(key)
+          state.bytes -= entry.bytes
+        }
+        state.entries.set(key, { value, bytes })
+        state.bytes += bytes
+      }
+    }
+    const items = value.items.slice(offset, offset + input.limit)
+    return Sections.parse({
+      contentVersion: source.contentVersion,
+      format: "json",
+      items,
+      total: value.items.length,
+      nextCursor:
+        offset + items.length < value.items.length
+          ? cursor(source.contentVersion, "sections", offset + items.length)
+          : null,
+      truncated: value.truncated,
+    })
+  }
+  export async function value(source: Source, path: string[], signal?: AbortSignal): Promise<unknown> {
+    let next: string | undefined
+    let section: z.infer<typeof Section> | undefined
+    do {
+      const page = await sections(source, PageQuery.parse({ field: "request", cursor: next, limit: 500 }), signal)
+      section = page.items.find((item) => JSON.stringify(item.path) === JSON.stringify(path))
+      next = page.nextCursor ?? undefined
+    } while (!section && next)
+    if (!section || section.bytes > 8 * 1024 * 1024) return undefined
+    const parts: string[] = []
+    for (let offset = section.offset; offset < section.offset + section.bytes;) {
+      signal?.throwIfAborted()
+      const page = await source.read(offset, Math.min(65_536, section.offset + section.bytes - offset))
+      parts.push(page.text)
+      offset = page.nextOffset ?? source.bytes
+    }
+    return JSON.parse(parts.join(""))
+  }
+  export async function search(source: Source, input: z.infer<typeof SearchQuery>, signal?: AbortSignal) {
+    const fingerprint = JSON.stringify([input.query, input.caseSensitive])
+    let offset = position(input.cursor, source.contentVersion, fingerprint)
+    const pattern = new RegExp(input.query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), input.caseSensitive ? "gu" : "giu")
+    const items: Array<{ offset: number; bytes: number; preview: string }> = []
+    let carry = ""
+    let carryOffset = offset
+    let next: number | null = null
+    while (offset < source.bytes) {
+      signal?.throwIfAborted()
+      const page = await source.read(offset, 65_536)
+      const text = carry + page.text
+      const base = carry ? carryOffset : offset
+      const safe = page.nextOffset === null ? text.length : Math.max(0, text.length - input.query.length - 2)
+      pattern.lastIndex = 0
+      let consumed = 0
+      for (let match = pattern.exec(text); match && match.index < safe; match = pattern.exec(text)) {
+        const start = base + Buffer.byteLength(text.slice(0, match.index))
+        const bytes = Buffer.byteLength(match[0])
+        items.push({
+          offset: start,
+          bytes,
+          preview: text.slice(Math.max(0, match.index - 60), match.index + match[0].length + 100),
+        })
+        consumed = match.index + match[0].length
+        if (items.length === input.limit) {
+          next = start + bytes
+          break
+        }
+      }
+      if (next !== null) break
+      let retained = Math.max(safe, consumed)
+      if (retained && retained < text.length && /[\uDC00-\uDFFF]/.test(text[retained])) retained--
+      carry = text.slice(retained)
+      carryOffset = base + Buffer.byteLength(text.slice(0, retained))
+      offset = page.nextOffset ?? source.bytes
+      await new Promise<void>((resolve) => setImmediate(resolve))
+    }
+    return Search.parse({
+      contentVersion: source.contentVersion,
+      status: source.status,
+      items,
+      nextCursor: next !== null && next < source.bytes ? cursor(source.contentVersion, fingerprint, next) : null,
+    })
+  }
+}