@agfpd/iapeer 0.4.115 → 0.4.117

package/src/opencode/journal.ts

@@ -0,0 +1,143 @@
+// Core-side reader/writer of the OpenCode observability ABI (docs/20 §Observability ABI).
+// The in-process plugin (iapeer-plugin.mjs) is the producer while the process lives; the core
+// writes ONLY when the process is gone (supervisor death record) — so the journal stays
+// single-writer at every instant. seq continues from the journal tail.
+import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs'
+
+export type OpencodeStatus = 'starting' | 'idle' | 'busy' | 'approval' | 'error' | 'stopped'
+
+export interface OpencodeState {
+  schema: 1
+  identity: string
+  cwd: string
+  sessionID: string | null
+  launchID: string
+  startedAt: number
+  lastEventSeq: number
+  lastActivityMs: number
+  status: OpencodeStatus
+  error?: string
+}
+
+export interface OpencodeJournalLine {
+  schema: 1
+  seq: number
+  time: number
+  identity: string
+  launchID: string
+  sessionID: string | null
+  type: string
+  properties: unknown
+  nativeID: string | null
+}
+
+export function readOpencodeState(path: string): OpencodeState | null {
+  try {
+    const s = JSON.parse(readFileSync(path, 'utf8')) as OpencodeState
+    return s && typeof s === 'object' && typeof s.launchID === 'string' ? s : null
+  } catch {
+    return null
+  }
+}
+
+function writeStateAtomic(path: string, state: OpencodeState): void {
+  const tmp = `${path}.${process.pid}.tmp`
+  writeFileSync(tmp, JSON.stringify(state) + '\n', { mode: 0o600 })
+  renameSync(tmp, path)
+}
+
+/** Parsed journal lines appended at or after byte `offset` (a partial trailing line is skipped). */
+export function readJournalFrom(path: string, offset: number): { lines: OpencodeJournalLine[]; end: number } {
+  if (!existsSync(path)) return { lines: [], end: 0 }
+  const fd = openSync(path, 'r')
+  try {
+    const size = fstatSync(fd).size
+    if (size <= offset) return { lines: [], end: size }
+    const buf = Buffer.alloc(size - offset)
+    readSync(fd, buf, 0, buf.length, offset)
+    const text = buf.toString('utf8')
+    const lastNl = text.lastIndexOf('\n')
+    if (lastNl < 0) return { lines: [], end: offset }
+    const lines: OpencodeJournalLine[] = []
+    for (const raw of text.slice(0, lastNl).split('\n')) {
+      if (!raw) continue
+      try {
+        lines.push(JSON.parse(raw) as OpencodeJournalLine)
+      } catch {
+        /* a malformed line is not ours to repair; consumers dedup by seq */
+      }
+    }
+    return { lines, end: offset + Buffer.byteLength(text.slice(0, lastNl + 1)) }
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/** Last `seq` in the journal (tail read; the journal never shrinks). 0 when absent/empty. */
+export function lastJournalSeq(path: string): number {
+  if (!existsSync(path)) return 0
+  const fd = openSync(path, 'r')
+  try {
+    const size = fstatSync(fd).size
+    let span = 4096
+    while (true) {
+      const start = Math.max(0, size - span)
+      const buf = Buffer.alloc(size - start)
+      readSync(fd, buf, 0, buf.length, start)
+      const lines = buf.toString('utf8').split('\n').filter(Boolean)
+      for (let i = lines.length - 1; i >= (start === 0 ? 0 : 1); i--) {
+        try {
+          const seq = (JSON.parse(lines[i]!) as { seq?: unknown }).seq
+          if (Number.isInteger(seq)) return seq as number
+        } catch {
+          /* skip */
+        }
+      }
+      if (start === 0) return 0
+      span *= 4
+    }
+  } finally {
+    closeSync(fd)
+  }
+}
+
+export function fileMtimeMs(path: string): number | null {
+  try {
+    return statSync(path).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Supervisor-side death record: the process is gone, so the plugin cannot write `stopped`
+ * (dispose does not run on a signal). Appends exactly one `runtime.stopped` for the launch in
+ * state.json and flips status → stopped. Idempotent: a launch whose state already says stopped
+ * (graceful dispose wrote it) is left untouched. No state file → nothing launched → no record.
+ */
+export function recordOpencodeStopped(
+  paths: { state: string; events: string },
+  info: { reason: string; exitCode?: number; signal?: string },
+  now: number = Date.now(),
+): boolean {
+  const state = readOpencodeState(paths.state)
+  if (!state || state.status === 'stopped') return false
+  const seq = lastJournalSeq(paths.events) + 1
+  const properties: Record<string, unknown> = { reason: info.reason }
+  if (info.exitCode !== undefined) properties.exitCode = info.exitCode
+  if (info.signal !== undefined) properties.signal = info.signal
+  const line: OpencodeJournalLine = {
+    schema: 1,
+    seq,
+    time: now,
+    identity: state.identity,
+    launchID: state.launchID,
+    sessionID: state.sessionID,
+    type: 'runtime.stopped',
+    properties,
+    nativeID: null,
+  }
+  appendFileSync(paths.events, JSON.stringify(line) + '\n', { mode: 0o600 })
+  writeStateAtomic(paths.state, { ...state, status: 'stopped', lastEventSeq: seq, lastActivityMs: now })
+  return true
+}

package/src/provision/index.ts

@@ -141,7 +141,7 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
         const { runProvisionCommand } = await import('../enable/provisionCommand.ts')
         const { appendLifecycleEvent } = await import('../lifecycle/eventlog.ts')
         const { pluginLogsDir } = await import('../storage/index.ts')
-        const agentic = profile.runtimes.filter((r): r is 'claude' | 'codex' => r === 'claude' || r === 'codex')
+        const agentic = profile.runtimes.filter(r => r === 'claude' || r === 'codex' || r === 'opencode')
         for (const rt of agentic) {
           const o = runProvisionCommand({
             block: slot.provision,
@@ -182,6 +182,36 @@ export async function provisionPeer(opts: ProvisionPeerOptions): Promise<Provisi
     opts.warn?.(`memory birth-time hook failed: ${e instanceof Error ? e.message : String(e)}`)
   }
 
+  // Capability-plugin lifecycle (docs/21): every registered capability provisions its
+  // surfaces for every agent endpoint the peer declares (occasion=birth). This joint
+  // also runs for add-runtime / default-runtime convergence (they call initPeer →
+  // here), so a new endpoint is never left without the host's capabilities.
+  // Idempotency is the plugin's obligation; a failure is LOUD but never kills a birth.
+  try {
+    const { runCapabilityLifecycle, listCapabilities } = await import('../capability/index.ts')
+    const { appendLifecycleEvent } = await import('../lifecycle/eventlog.ts')
+    const { pluginLogsDir } = await import('../storage/index.ts')
+    for (const bad of listCapabilities({ env }).invalid) {
+      opts.warn?.(`capability declaration ${bad.file} is INVALID (${bad.error}) — not provisioned for "${profile.personality}"`)
+    }
+    for (const run of runCapabilityLifecycle({ kind: 'provision', personality: profile.personality, cwd, runtimes: profile.runtimes, occasion: 'birth', env })) {
+      const o = run.outcome
+      appendLifecycleEvent(
+        pluginLogsDir('iapeer', { env }),
+        { ev: 'capability-provision', capability: run.capability, identity: `${run.runtime}-${profile.personality}`, occasion: 'birth', state: o.state, exit: o.exitCode ?? undefined, ms: o.durationMs, detail: o.detail },
+        { env },
+      )
+      if (o.state !== 'ok') {
+        opts.warn?.(
+          `capability ${run.capability} provision (${run.runtime}) ${o.state.toUpperCase()} for "${profile.personality}"` +
+            `${o.detail ? `: ${o.detail}` : ''} — repair: iapeer capability sync ${run.capability}`,
+        )
+      }
+    }
+  } catch (e) {
+    opts.warn?.(`capability birth-time hook failed: ${e instanceof Error ? e.message : String(e)}`)
+  }
+
   // wake_policy:"ephemeral" sanity (M2 edge cases — warn, don't refuse: the policy
   // lives in the hand-editable local profile, provision just surfaces the mismatch):
   //   • + interfaces.telegram: ephemeral WINS in resolveWakeMode (explicit policy

package/src/storage/index.ts

@@ -29,6 +29,7 @@ import {
   STATE_DIR,
   SUPPORTED_LOCAL_RUNTIMES,
   isRuntime,
+  isValidName,
   type Runtime,
   type SupportedLocalRuntime,
 } from '../core/constants.ts'
@@ -347,3 +348,52 @@ export function writeFileAtomic(path: string, data: string, mode: number = FILE_
   // The durability core (fsync-before-rename + looped writeSync) lives in ONE place — see atomicWrite.ts.
   writeFileAtomicRaw(path, data, mode)
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Daemon URL resolution (router.json published by the daemon, else the default)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Fallback HTTP-MCP daemon port when no router.json is published yet (the daemon
+ *  binds this stable loopback port by default; init before daemon-start uses it). */
+export const DEFAULT_DAEMON_MCP_PORT = 8765
+
+/**
+ * Resolve the daemon HTTP-MCP URL to write into a peer's `.mcp.json`. Primary: the
+ * `tcp` field of the daemon's discovery file `~/.iapeer/state/iapeer/router.json`
+ * (published live by the daemon). Fallback: the well-known default loopback URL —
+ * so `iapeer init` works even before the daemon is started (the daemon binds the
+ * same stable port; IAPEER_PORT overrides it at the daemon, not here).
+ */
+export function resolveDaemonMcpUrl(options: StorageOptions = {}): string {
+  const routerJson = join(pluginStateDir('iapeer', options), 'router.json')
+  try {
+    const parsed = JSON.parse(readFileSync(routerJson, 'utf8')) as { tcp?: unknown }
+    if (typeof parsed.tcp === 'string' && parsed.tcp) return parsed.tcp
+  } catch {
+    /* no router.json (daemon not started) → the well-known default below */
+  }
+  const env = options.env ?? process.env
+  const port = env.IAPEER_PORT?.trim() || String(DEFAULT_DAEMON_MCP_PORT)
+  return `http://127.0.0.1:${port}/mcp`
+}
+
+/**
+ * The core-owned private directory of an OpenCode endpoint: <root>/state/opencode/<personality>.
+ * The SINGLE layout authority — opencodePaths and the provider/capability command placeholder
+ * {privateDir} both resolve through it. Runtime state of the core lives under state/, never in the
+ * agent's working tree (the default peer cwd is <root>/peers/<p>).
+ */
+export function opencodePrivateDir(personality: string, options: StorageOptions = {}): string {
+  return join(options.rootDir ?? resolveGlobalRoot(options.env), STATE_DIR, 'opencode', personality)
+}
+
+/**
+ * The core-owned private directory of an endpoint (personality × runtime), or undefined when that
+ * runtime has none (today only opencode has one). The ONE answer every consumer gets — the launch
+ * adapter, provider/capability commands ({privateDir} / IAPEER_PRIVATE_DIR), the fleet snapshot
+ * (`runtimes[].private_dir`) and `iapeer private-dir`. Consumers never derive it themselves.
+ */
+export function endpointPrivateDir(runtime: string, personality: string, options: StorageOptions = {}): string | undefined {
+  if (runtime !== 'opencode' || !isValidName(personality)) return undefined
+  return opencodePrivateDir(personality, options)
+}

package/src/supervisor/daemon.ts

@@ -13,7 +13,7 @@
 import { Terminal } from '@xterm/headless'
 import { SerializeAddon } from '@xterm/addon-serialize'
 import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, statSync, unlinkSync, writeFileSync, writeSync } from 'node:fs'
-import { dirname } from 'node:path'
+import { dirname, join } from 'node:path'
 import {
   BackpressureWriter,
   FRAME_DATA,
@@ -34,6 +34,7 @@ import { claudeAdapter } from '../launch/adapters/claude.ts'
 import { approvalModeOf, readPeerProfile, type ApprovalMode } from '../identity/index.ts'
 import { routeCircuitBreaker } from './approvalRoute.ts'
 import { killPtyDescendants } from './processTree.ts'
+import { recordOpencodeStopped } from '../opencode/journal.ts'
 
 /** Resolve a runtime launcher from the host AT CALL TIME — env override (IAPEER_<RT>_BIN, the same
  *  knob the rest of the foundation uses) → PATH lookup — never a baked machine-specific path. Returns
@@ -323,6 +324,25 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     }
   }
 
+  // OpenCode (docs/20): the in-process plugin cannot record its own death on a signal (dispose does
+  // not run), so the host records `runtime.stopped` + state=stopped once the child is gone. Idempotent
+  // with a graceful dispose (state already stopped → no second record). Best-effort, never blocks.
+  let structuralStopRecorded = false
+  const recordStructuralStop = (reason: string, exitCode?: number, signal?: number | string): void => {
+    if (structuralStopRecorded || runtime !== 'opencode') return
+    structuralStopRecorded = true
+    const dir = (env as Record<string, string | undefined>).IAPEER_OPENCODE_DIR
+    if (!dir) return
+    try {
+      recordOpencodeStopped(
+        { state: join(dir, 'state.json'), events: join(dir, 'events.jsonl') },
+        { reason, ...(exitCode !== undefined ? { exitCode } : {}), ...(signal !== undefined ? { signal: String(signal) } : {}) },
+      )
+    } catch (e) {
+      appendExitEvent({ ev: 'opencode-stop-record-failed', identity: session, reason: (e as Error).message })
+    }
+  }
+
   const child = Bun.spawn(CMD, {
     cwd: opts.cwd ?? runDir,
     env,
@@ -375,6 +395,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
         const status = exitCode ?? c.exitCode
         const signal = signalCode ?? c.signalCode
         exitLogged = true // this IS the death record — shutdown below must not write a second one
+        recordStructuralStop('child-exit', status ?? undefined, signal ?? undefined)
         appendExitEvent({
           ev: 'session-exit',
           identity: session,
@@ -618,6 +639,7 @@ export function runSupervisorDaemon(opts: SupervisorDaemonOptions): void {
     } catch {
       /* */
     }
+    recordStructuralStop(cause)
     try {
       server.stop(true)
     } catch {

package/src/transport/index.ts

@@ -331,7 +331,16 @@ export async function deliverWarm(
   // receives the WIRE form its parser expects. Rendered BEFORE deliverViaHost so
   // the transcript-confirm matches the text actually delivered. fail-open inside
   // the renderer: a render problem degrades to the wire form, never to a loss.
-  const payload = isSupportedLocalRuntime(target.runtime) ? renderEnvelopeForAgent(envelope) : envelope
+  // Agent = a model reads the text: every TUI-kind adapter (claude/codex/opencode), not the local
+  // support list (an adapter can exist before its runtime is advertised for discovery).
+  const agentTarget = (() => {
+    try {
+      return getAdapter(target.runtime).kind === 'tui'
+    } catch {
+      return isSupportedLocalRuntime(target.runtime)
+    }
+  })()
+  const payload = agentTarget ? renderEnvelopeForAgent(envelope) : envelope
   const address = target.address
   const prev = deliverTails.get(address) ?? Promise.resolve()
   // run AFTER prev settles (success or failure) — a prior delivery's error must not stall the chain
@@ -357,6 +366,16 @@ async function deliverViaHost(
   env: NodeJS.ProcessEnv = process.env,
 ): Promise<Result<void>> {
   const adapter = getAdapter(target.runtime)
+  // STRUCTURAL runtime (opencode): no pty paste at all — the adapter's deliver acknowledges only once
+  // THIS message is persisted natively (docs/20), so its ack IS the message-specific landed-confirm.
+  if (adapter.deliveryConfirm === 'structural') {
+    if (!adapter.deliver) return err(`runtime "${target.runtime}" declares structural delivery without a deliver hook`)
+    const r = await adapter.deliver({ personality: target.personality, identity: target.address }, envelope, env)
+    if (!r.ok) {
+      return err(`peer "${target.personality}" (${target.runtime}) deliver failed: ${r.error ?? 'unknown error'}; message NOT delivered`)
+    }
+    return ok(undefined)
+  }
   // Baseline the transcript/session-jsonl file SIZES BEFORE delivery (per-runtime candidate files).
   // The landed-confirm reads ONLY the bytes appended past this baseline, so a record carrying our
   // envelope can only be one written in RESPONSE to this delivery — never a pre-existing copy.
@@ -923,7 +942,13 @@ export async function executeControlOnTarget(
   command: ControlCommand,
   seam: ControlHostSeam = {},
 ): Promise<Result<void>> {
-  const plan = getAdapter(target.runtime).executeControl(command)
+  const adapter = getAdapter(target.runtime)
+  // Structural runtime (opencode): control goes through the runtime's native channel, never pty keys.
+  if (adapter.control) {
+    const r = await adapter.control({ personality: target.personality, identity: target.address }, command, process.env)
+    return r.ok ? ok(undefined) : err(`control "${command.name}" failed for "${target.personality}" (${target.runtime}): ${r.error ?? 'unknown error'}`)
+  }
+  const plan = adapter.executeControl(command)
   if (!plan) {
     return err(`runtime "${target.runtime}" does not support control command "${command.name}"`)
   }
@@ -1203,6 +1228,8 @@ function delay(ms: number): Promise<void> {
  *  held. No pane-log dir / unreadable model → don't hold (deliver, never stall). */
 async function shouldQueueForComposer(target: DeliveryTarget, logDir: string | undefined): Promise<boolean> {
   if (!isSupportedLocalRuntime(target.runtime) || !hasAttachedSupervisorClient(target.address)) return false
+  // A structural runtime never shares the human's composer (delivery bypasses the pty) → never hold.
+  if (getAdapter(target.runtime).deliveryConfirm === 'structural') return false
   if (!logDir) return false // no pane-log dir → cannot read occupancy → don't hold (deliver, never stall)
   return paneLogComposerOccupied(`${logDir}/${target.address}.log`, hostGeometry(target.address).cols, hostGeometry(target.address).rows, target.runtime)
 }