@nifrajs/coding-agent 3.2.0

package/src/subagents.ts

@@ -0,0 +1,210 @@
+import { relative, resolve, sep } from "node:path"
+
+export interface SubagentSpec {
+  readonly id: string
+  readonly role: string
+  readonly prompt: string
+  readonly capabilities?: readonly string[]
+  readonly maxDepth?: number
+  readonly timeoutMs?: number
+  readonly cwd?: string
+}
+
+export interface SubagentResult {
+  readonly id: string
+  readonly role: string
+  readonly ok: boolean
+  readonly output?: unknown
+  readonly error?: string
+}
+
+export interface SubagentExecutor {
+  run(input: {
+    readonly spec: SubagentSpec
+    readonly signal: AbortSignal
+    readonly cwd?: string
+  }): unknown | PromiseLike<unknown>
+}
+
+export interface SubagentWorkspaceLease {
+  readonly cwd: string
+  readonly cleanup?: () => void | PromiseLike<void>
+}
+
+/** Workspace policy seam for callers that need project boundaries or isolated worktrees. */
+export interface SubagentWorkspacePolicy {
+  readonly root: string
+  readonly allowedRoots?: readonly string[]
+  readonly isolatedWorktree?: (
+    spec: SubagentSpec,
+    signal: AbortSignal,
+  ) => SubagentWorkspaceLease | PromiseLike<SubagentWorkspaceLease>
+}
+
+export interface SubagentRunnerOptions {
+  readonly maxChildren?: number
+  readonly maxDepth?: number
+  readonly depth?: number
+  readonly signal?: AbortSignal
+  readonly allowedCapabilities?: readonly string[]
+  readonly workspace?: SubagentWorkspacePolicy
+}
+
+/** Explicitly bounded child execution. Recursive fan-out is impossible without a caller budget. */
+export class BoundedSubagentRunner {
+  private readonly executor: SubagentExecutor
+  private readonly options: Required<
+    Pick<SubagentRunnerOptions, "maxChildren" | "maxDepth" | "depth">
+  > &
+    SubagentRunnerOptions
+  private children = 0
+
+  constructor(executor: SubagentExecutor, options: SubagentRunnerOptions = {}) {
+    this.executor = executor
+    this.options = {
+      ...options,
+      maxChildren: options.maxChildren ?? 4,
+      maxDepth: options.maxDepth ?? 2,
+      depth: options.depth ?? 0,
+    }
+    if (this.options.maxChildren < 1 || this.options.maxDepth < 0 || this.options.depth < 0)
+      throw new RangeError(
+        "subagents: limits must be non-negative and maxChildren must be positive",
+      )
+  }
+
+  async run(spec: SubagentSpec): Promise<SubagentResult> {
+    if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(spec.id))
+      return { id: spec.id, role: spec.role, ok: false, error: "invalid subagent id" }
+    if (++this.children > this.options.maxChildren)
+      return { id: spec.id, role: spec.role, ok: false, error: "subagent child limit exceeded" }
+    if (this.options.depth > this.options.maxDepth)
+      return { id: spec.id, role: spec.role, ok: false, error: "subagent depth limit exceeded" }
+    if (spec.prompt.length === 0 || spec.prompt.length > 16_384)
+      return {
+        id: spec.id,
+        role: spec.role,
+        ok: false,
+        error: "subagent prompt is empty or too long",
+      }
+    if (
+      spec.timeoutMs !== undefined &&
+      (!Number.isSafeInteger(spec.timeoutMs) ||
+        spec.timeoutMs < 1 ||
+        spec.timeoutMs > 24 * 60 * 60_000)
+    )
+      return { id: spec.id, role: spec.role, ok: false, error: "subagent timeout is invalid" }
+    const allowed =
+      this.options.allowedCapabilities === undefined
+        ? undefined
+        : new Set(this.options.allowedCapabilities)
+    const denied = spec.capabilities?.find(
+      (capability) => allowed !== undefined && !allowed.has(capability),
+    )
+    if (denied !== undefined)
+      return {
+        id: spec.id,
+        role: spec.role,
+        ok: false,
+        error: `subagent capability denied: ${denied}`,
+      }
+    const controller = new AbortController()
+    const onAbort = (): void => controller.abort(this.options.signal?.reason)
+    this.options.signal?.addEventListener("abort", onAbort, { once: true })
+    const timeout =
+      spec.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => controller.abort("timeout"), spec.timeoutMs)
+    let workspace: SubagentWorkspaceLease | undefined
+    try {
+      const requestedCwd =
+        spec.cwd === undefined
+          ? this.options.workspace?.root
+          : this.options.workspace === undefined
+            ? resolve(spec.cwd)
+            : resolve(this.options.workspace.root, spec.cwd)
+      if (requestedCwd !== undefined && this.options.workspace !== undefined) {
+        if (!within(this.options.workspace.root, requestedCwd))
+          return {
+            id: spec.id,
+            role: spec.role,
+            ok: false,
+            error: "subagent workspace escapes policy root",
+          }
+        const allowedRoots = this.options.workspace.allowedRoots ?? [this.options.workspace.root]
+        if (!allowedRoots.some((root) => within(root, requestedCwd)))
+          return {
+            id: spec.id,
+            role: spec.role,
+            ok: false,
+            error: "subagent workspace is not in an allowed root",
+          }
+      }
+      if (this.options.workspace?.isolatedWorktree !== undefined) {
+        workspace = await this.options.workspace.isolatedWorktree(spec, controller.signal)
+      } else if (requestedCwd !== undefined) {
+        workspace = { cwd: requestedCwd }
+      }
+      if (workspace !== undefined && this.options.workspace !== undefined) {
+        const allowedRoots = this.options.workspace.allowedRoots ?? [this.options.workspace.root]
+        if (
+          !within(this.options.workspace.root, workspace.cwd) ||
+          !allowedRoots.some((root) => within(root, workspace!.cwd))
+        )
+          return {
+            id: spec.id,
+            role: spec.role,
+            ok: false,
+            error: "isolated worktree escapes workspace policy",
+          }
+      }
+      const output = await this.executor.run({
+        spec,
+        signal: controller.signal,
+        ...(workspace === undefined ? {} : { cwd: workspace.cwd }),
+      })
+      return { id: spec.id, role: spec.role, ok: true, output }
+    } catch (error) {
+      return {
+        id: spec.id,
+        role: spec.role,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    } finally {
+      await workspace?.cleanup?.()
+      if (timeout !== undefined) clearTimeout(timeout)
+      this.options.signal?.removeEventListener("abort", onAbort)
+    }
+  }
+
+  async runMany(
+    specs: readonly SubagentSpec[],
+    maxConcurrency = this.options.maxChildren,
+  ): Promise<readonly SubagentResult[]> {
+    if (specs.length > this.options.maxChildren) throw new Error("subagent child limit exceeded")
+    if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1)
+      throw new RangeError("subagents: maxConcurrency must be positive")
+    const results: SubagentResult[] = new Array(specs.length)
+    let next = 0
+    const worker = async (): Promise<void> => {
+      for (;;) {
+        const index = next++
+        if (index >= specs.length) return
+        results[index] = await this.run(specs[index]!)
+      }
+    }
+    await Promise.all(
+      Array.from({ length: Math.min(maxConcurrency, specs.length) }, () => worker()),
+    )
+    return results
+  }
+}
+
+function within(root: string, candidate: string): boolean {
+  const relativePath = relative(resolve(root), resolve(candidate))
+  return (
+    relativePath === "" ||
+    (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !relativePath.startsWith("/"))
+  )
+}

package/src/tools.ts

@@ -0,0 +1,52 @@
+import { type NifraContextOptions, type NifraContextResult, runNifraContext } from "./context.ts"
+import {
+  runNifraVerification,
+  type VerificationOptions,
+  type VerificationResult,
+} from "./verification.ts"
+
+export interface NifraAgentTool {
+  readonly name: "nifra.context" | "nifra.check" | "nifra.assure" | "nifra.test"
+  readonly description: string
+  readonly capability: "process"
+  execute(): Promise<NifraContextResult | VerificationResult>
+}
+
+/** Short, provider-neutral instructions injected into Pi only when the optional agent is used. */
+export const NIFRA_AGENT_INSTRUCTIONS = `
+You are operating inside a Nifra project. Before making framework changes, use \`nifra context\` when available to inspect the current typed project surfaces. After changes, run \`nifra check --json\` and, when assurance is configured, \`nifra assure --json\`. Treat failed checks as structured repair work. Keep changes scoped, preserve existing user edits, and never expose secrets in responses or session notes.
+`.trim()
+
+/** Optional first-party tool descriptors. The Pi adapter can register these through an extension. */
+export function createNifraTools(
+  options: NifraContextOptions & Pick<VerificationOptions, "command">,
+): readonly NifraAgentTool[] {
+  const verification = (name: "check" | "assure" | "test"): Promise<VerificationResult> =>
+    runNifraVerification(name, options)
+  return Object.freeze([
+    {
+      name: "nifra.context",
+      description: "Read the current Nifra project context and machine-readable agent surfaces.",
+      capability: "process",
+      execute: () => runNifraContext(options),
+    },
+    {
+      name: "nifra.check",
+      description: "Run the Nifra typed contract check and return structured diagnostics.",
+      capability: "process",
+      execute: () => verification("check"),
+    },
+    {
+      name: "nifra.assure",
+      description: "Run Nifra capability assurance and return structured diagnostics.",
+      capability: "process",
+      execute: () => verification("assure"),
+    },
+    {
+      name: "nifra.test",
+      description: "Run the configured Nifra test command with bounded output.",
+      capability: "process",
+      execute: () => verification("test"),
+    },
+  ])
+}

package/src/ui.ts

@@ -0,0 +1,137 @@
+import { publicErrorMessage } from "./errors.ts"
+
+export type UiExtensionSlot = "sidebar" | "main" | "timeline" | "diff" | "workflow" | "status"
+
+export interface UiThemeDescriptor {
+  readonly name: string
+  readonly accent?: string
+  readonly density?: "compact" | "comfortable"
+}
+
+export interface UiStatusWidget {
+  readonly text: string
+  readonly tone?: "neutral" | "positive" | "warning" | "danger"
+}
+
+export interface UiExtensionManifest {
+  readonly id: string
+  readonly revision: string
+  readonly slot: UiExtensionSlot
+  readonly label: string
+  readonly capabilities?: readonly string[]
+  readonly theme?: UiThemeDescriptor
+  readonly status?: UiStatusWidget
+}
+
+export interface UiExtensionHostOptions {
+  readonly trustedCapabilities?: readonly string[]
+  readonly maxExtensions?: number
+}
+
+export interface UiReloadResult {
+  readonly revision: string
+  readonly active: readonly UiExtensionManifest[]
+  readonly rolledBack: boolean
+  readonly error?: string
+}
+
+/** Data-only UI extension registry. The stable Workbench shell owns rendering and approval UX. */
+export class UiExtensionHost {
+  private readonly options: Required<Pick<UiExtensionHostOptions, "maxExtensions">> &
+    UiExtensionHostOptions
+  private active: readonly UiExtensionManifest[] = []
+  private revision = "0"
+
+  constructor(options: UiExtensionHostOptions = {}) {
+    this.options = { ...options, maxExtensions: options.maxExtensions ?? 32 }
+    if (!Number.isSafeInteger(this.options.maxExtensions) || this.options.maxExtensions < 1)
+      throw new RangeError("ui extensions: maxExtensions must be positive")
+  }
+
+  get extensions(): readonly UiExtensionManifest[] {
+    return this.active
+  }
+  get currentRevision(): string {
+    return this.revision
+  }
+
+  /** Validate a candidate graph without changing the active shell-owned graph. */
+  preview(manifests: readonly UiExtensionManifest[]): UiReloadResult {
+    try {
+      const active = validateManifests(manifests, this.options)
+      return {
+        revision: `preview:${this.revision}`,
+        active,
+        rolledBack: false,
+      }
+    } catch (error) {
+      return {
+        revision: this.revision,
+        active: this.active,
+        rolledBack: true,
+        error: publicErrorMessage(error, "UI extension preview failed"),
+      }
+    }
+  }
+
+  reload(manifests: readonly UiExtensionManifest[]): UiReloadResult {
+    try {
+      const active = validateManifests(manifests, this.options)
+      this.active = active
+      this.revision = `${Date.now().toString(36)}-${this.active.length}`
+      return { revision: this.revision, active: this.active, rolledBack: false }
+    } catch (error) {
+      return {
+        revision: this.revision,
+        active: this.active,
+        rolledBack: true,
+        error: publicErrorMessage(error, "UI extension reload failed"),
+      }
+    }
+  }
+}
+
+function validateManifests(
+  manifests: readonly UiExtensionManifest[],
+  options: UiExtensionHostOptions & { readonly maxExtensions: number },
+): readonly UiExtensionManifest[] {
+  if (manifests.length > options.maxExtensions) throw new Error("ui extension limit exceeded")
+  const trusted = new Set(options.trustedCapabilities ?? [])
+  const ids = new Set<string>()
+  return Object.freeze(
+    manifests.map((manifest) => {
+      if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(manifest.id))
+        throw new Error(`invalid UI extension id: ${manifest.id}`)
+      if (!/^[a-zA-Z0-9._:-]{1,64}$/.test(manifest.revision))
+        throw new Error(`invalid UI extension revision: ${manifest.id}`)
+      if (!manifest.label || manifest.label.length > 120)
+        throw new Error(`invalid UI extension label: ${manifest.id}`)
+      if (manifest.theme !== undefined) {
+        if (!/^[a-z][a-z0-9._-]{0,31}$/.test(manifest.theme.name))
+          throw new Error(`invalid UI theme: ${manifest.id}`)
+        if (manifest.theme.accent !== undefined && !/^#[0-9a-fA-F]{6}$/.test(manifest.theme.accent))
+          throw new Error(`invalid UI theme accent: ${manifest.id}`)
+      }
+      if (manifest.status !== undefined) {
+        if (!manifest.status.text || manifest.status.text.length > 160)
+          throw new Error(`invalid UI status widget: ${manifest.id}`)
+        if (
+          manifest.status.tone !== undefined &&
+          !["neutral", "positive", "warning", "danger"].includes(manifest.status.tone)
+        )
+          throw new Error(`invalid UI status tone: ${manifest.id}`)
+      }
+      if (ids.has(manifest.id)) throw new Error(`duplicate UI extension: ${manifest.id}`)
+      ids.add(manifest.id)
+      const denied = (manifest.capabilities ?? []).find((capability) => !trusted.has(capability))
+      if (denied !== undefined)
+        throw new Error(`UI extension ${manifest.id} requires untrusted capability: ${denied}`)
+      return Object.freeze({
+        ...manifest,
+        capabilities: Object.freeze([...(manifest.capabilities ?? [])]),
+        ...(manifest.theme === undefined ? {} : { theme: Object.freeze({ ...manifest.theme }) }),
+        ...(manifest.status === undefined ? {} : { status: Object.freeze({ ...manifest.status }) }),
+      })
+    }),
+  )
+}

package/src/verification.ts

@@ -0,0 +1,133 @@
+import { publicErrorDetails } from "./errors.ts"
+import { readBoundedText } from "./process.ts"
+
+export interface VerificationResult {
+  readonly name: "check" | "assure" | "test"
+  readonly ok: boolean
+  readonly status: number | null
+  readonly report?: unknown
+  readonly output?: string
+  readonly error?: string
+  readonly stack?: string
+}
+
+export interface VerificationRepairTask {
+  readonly id: string
+  readonly verification: VerificationResult["name"]
+  readonly cwd: string
+  readonly reason: string
+  readonly capabilities: readonly string[]
+  readonly output?: string
+  readonly report?: unknown
+  readonly stack?: string
+}
+
+/** Turn a failed gate into a bounded, auditable repair task for the agent loop. */
+export function createVerificationRepairTask(
+  result: VerificationResult,
+  cwd: string,
+): VerificationRepairTask | undefined {
+  if (result.ok) return undefined
+  return Object.freeze({
+    id: `verification-${result.name}-${Date.now().toString(36)}`,
+    verification: result.name,
+    cwd,
+    reason:
+      result.error ??
+      `${result.name} failed${result.status === null ? "" : ` with exit ${result.status}`}`,
+    capabilities: Object.freeze(["process", "read", "write"]),
+    ...(result.output === undefined ? {} : { output: result.output.slice(0, 32_768) }),
+    ...(result.report === undefined ? {} : { report: result.report }),
+    ...(result.stack === undefined ? {} : { stack: result.stack }),
+  })
+}
+
+export interface VerificationOptions {
+  readonly cwd: string
+  readonly command?: string
+  /** Arguments placed before the gate name; useful for portable interpreter-backed test commands. */
+  readonly commandArgs?: readonly string[]
+  readonly timeoutMs?: number
+  readonly maxOutputBytes?: number
+  readonly env?: Readonly<Record<string, string | undefined>>
+  readonly exposeErrorStacks?: boolean
+}
+
+/** Run an existing Nifra gate without importing the large framework CLI into the agent runtime. */
+export async function runNifraVerification(
+  name: "check" | "assure" | "test",
+  options: VerificationOptions,
+): Promise<VerificationResult> {
+  const command = options.command ?? "nifra"
+  const commandArgs = options.commandArgs ?? []
+  const args = name === "test" ? ["test"] : [name, "--json"]
+  const proc = Bun.spawn([command, ...commandArgs, ...args], {
+    cwd: options.cwd,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: safeEnv(options.env),
+  })
+  const timeoutMs = options.timeoutMs ?? 120_000
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    proc.kill()
+  }, timeoutMs)
+  try {
+    const [stdout, stderr, status] = await Promise.all([
+      readBoundedText(proc.stdout, options.maxOutputBytes ?? 1_048_576),
+      readBoundedText(proc.stderr, options.maxOutputBytes ?? 1_048_576),
+      proc.exited,
+    ])
+    const output = stdout.text || stderr.text
+    let report: unknown
+    try {
+      report = JSON.parse(stdout.text)
+    } catch {
+      report = undefined
+    }
+    return {
+      name,
+      ok: !timedOut && status === 0,
+      status,
+      ...(report === undefined ? {} : { report }),
+      ...(output.length === 0 ? {} : { output }),
+      ...(timedOut ? { error: `nifra ${name} timed out after ${timeoutMs}ms` } : {}),
+    }
+  } catch (error) {
+    const details = publicErrorDetails(
+      error,
+      "verification failed",
+      options.exposeErrorStacks === true,
+    )
+    return {
+      name,
+      ok: false,
+      status: null,
+      error: details.message,
+      ...(details.stack === undefined ? {} : { stack: details.stack }),
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function safeEnv(
+  overrides: Readonly<Record<string, string | undefined>> | undefined,
+): Record<string, string> {
+  const result: Record<string, string> = {}
+  for (const name of new Set([
+    "PATH",
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "CI",
+    ...Object.keys(overrides ?? {}),
+  ])) {
+    const value = overrides?.[name] ?? process.env[name]
+    if (value !== undefined) result[name] = value
+  }
+  return result
+}