@asobacloud/nehanda 0.0.0-stage → 0.3.0

package/lib/energy-middleware.mjs

@@ -0,0 +1,318 @@
+/**
+ * energy-middleware.mjs
+ *
+ * ODSE energy normalization middleware for nehanda-cli.
+ *
+ * Intercepts MCP tool results containing energy production data and
+ * transforms them through the `odse` Python package (ona-protocol)
+ * before the model sees the payload.
+ *
+ * Flow:
+ *   1. Detect OEM brand from MCP server name (e.g. "energy-huawei" → "huawei")
+ *   2. If name doesn't resolve → fingerprint the payload fields
+ *   3. If brand identified → spawn odse-transform.py, return normalized ODS-E JSON
+ *   4. If no brand match → return payload unchanged (pass-through)
+ *
+ * Server naming convention (recommended in mcp.json):
+ *   "energy-huawei", "energy-solaredge", "energy-sungrow", etc.
+ *   Any prefix before the first hyphen-separated OEM key is stripped.
+ *
+ * No configuration required — drop a new energy MCP server into mcp.json
+ * following the naming convention and normalization happens automatically.
+ */
+
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const TRANSFORM_SCRIPT = path.join(__dirname, 'scripts', 'odse-transform.py')
+const TRANSFORM_TIMEOUT_MS = 30_000
+
+// ─── All known ODSE source keys (from odse.transformer._get_transformer) ─────
+
+const KNOWN_OEMS = new Set([
+  'huawei', 'fusionsolar',
+  'enphase', 'envoy',
+  'solarman', 'logger',
+  'solaredge',
+  'fronius',
+  'switch',
+  'solaxcloud', 'solax',
+  'fimer', 'auroravision',
+  'sma',
+  'solis', 'soliscloud',
+  'sungrow', 'isolarcloud',
+  'higeco',
+  'eskom', 'eskom_portal', 'eskom_amr', 'nrs049',
+  'sungrow_bess', 'powertitan',
+  'byd', 'byd_bess',
+  'vestas',
+  'siemens_gamesa', 'sgre',
+  'nordex',
+  'terraco',
+  'csv', 'generic_csv', 'generic',
+])
+
+// Canonical source key for known aliases — maps anything → the key odse accepts
+const OEM_ALIASES = {
+  fusionsolar: 'huawei',
+  envoy: 'enphase',
+  logger: 'solarman',
+  auroravision: 'fimer',
+  solax: 'solaxcloud',
+  soliscloud: 'solis',
+  isolarcloud: 'sungrow',
+  eskom_portal: 'eskom',
+  eskom_amr: 'eskom-amr',
+  nrs049: 'eskom-amr',
+  powertitan: 'sungrow-bess',
+  byd_bess: 'byd-bess',
+  sgre: 'siemens-gamesa',
+  generic_csv: 'generic',
+  csv: 'generic',
+}
+
+function canonicalOem(key) {
+  const k = key.toLowerCase().replace(/-/g, '_')
+  return OEM_ALIASES[k] || (KNOWN_OEMS.has(k.replace(/_/g, '-')) ? k.replace(/_/g, '-') : null)
+    || (KNOWN_OEMS.has(k) ? k : null)
+}
+
+// ─── Name-based OEM detection ─────────────────────────────────────────────────
+
+/**
+ * Attempt to extract an OEM key from the MCP server name.
+ * Handles patterns like:
+ *   "energy-huawei"     → "huawei"
+ *   "mcp-solaredge"     → "solaredge"
+ *   "power-sungrow-v2"  → "sungrow"
+ *   "huawei"            → "huawei"  (bare name)
+ *
+ * @param {string} serverName
+ * @returns {string|null}  canonical OEM key or null
+ */
+export function detectOemFromServerName(serverName) {
+  if (!serverName) return null
+  const parts = serverName.toLowerCase().split(/[-_]/)
+  // Try each segment (and pairs) as an OEM key, skipping generic prefixes
+  const SKIP = new Set(['energy', 'mcp', 'power', 'solar', 'api', 'v1', 'v2', 'v3', 'prod', 'dev'])
+  for (const part of parts) {
+    if (SKIP.has(part)) continue
+    const oem = canonicalOem(part)
+    if (oem) return oem
+  }
+  return null
+}
+
+// ─── Payload fingerprinting ───────────────────────────────────────────────────
+
+/**
+ * Field-signature fingerprints derived from ona-protocol transform YAMLs.
+ * Each entry: { oem: string, test: (parsed: any) → boolean }
+ * Ordered from most-specific to least-specific.
+ */
+const FINGERPRINTS = [
+  // Huawei FusionSolar CSV: has "inverter_state" or "run_state" columns
+  {
+    oem: 'huawei',
+    test: p =>
+      typeof p === 'string'
+        ? /inverter.?state|run.?state|fusionsolar/i.test(p)
+        : (Array.isArray(p) ? p[0] : p)?.inverter_state !== undefined,
+  },
+  // Enphase Envoy JSON array: { end_at, wh_del, devices_reporting }
+  {
+    oem: 'enphase',
+    test: p => {
+      const first = Array.isArray(p) ? p[0] : null
+      return first && 'end_at' in first && 'wh_del' in first
+    },
+  },
+  // SolarEdge: { data: { telemetries: [...] } } or { energy: { values: [...] } }
+  {
+    oem: 'solaredge',
+    test: p =>
+      p?.data?.telemetries !== undefined ||
+      p?.data?.powerDetails !== undefined ||
+      (typeof p === 'string' && /solaredge|L1Data|totalActivePower/i.test(p)),
+  },
+  // Fronius Solar API: { Head: { Timestamp }, Body: { Data: { Site } } }
+  {
+    oem: 'fronius',
+    test: p => p?.Head?.Timestamp !== undefined && p?.Body?.Data !== undefined,
+  },
+  // Sungrow iSolarCloud: has stationCode or device_type fields
+  {
+    oem: 'sungrow',
+    test: p =>
+      p?.stationCode !== undefined ||
+      p?.device_type !== undefined ||
+      (typeof p === 'string' && /isolarcloud|sungrow/i.test(p)),
+  },
+  // SMA: { records: [{ normalized: { active_power_w, status_code } }] }
+  {
+    oem: 'sma',
+    test: p => {
+      const first = Array.isArray(p?.records) ? p.records[0] : null
+      return first?.normalized?.active_power_w !== undefined && first?.normalized?.status_code !== undefined
+    },
+  },
+  // SolaxCloud: { success, result: { acpower, inverterStatus } }
+  {
+    oem: 'solaxcloud',
+    test: p =>
+      p?.result?.acpower !== undefined ||
+      p?.result?.inverterStatus !== undefined,
+  },
+  // Fimer AuroraVision: { series: [{ date, energy, unit }] }
+  {
+    oem: 'fimer',
+    test: p => Array.isArray(p?.series) && p.series[0]?.energy !== undefined && p.series[0]?.date !== undefined,
+  },
+  // Solarman logger CSV: "Update Time" + "Generation(kWh)" columns
+  {
+    oem: 'solarman',
+    test: p =>
+      typeof p === 'string' && /Update.?Time|Generation.*kWh|Device.?State/i.test(p),
+  },
+  // Vestas: CSV with wind turbine fields
+  {
+    oem: 'vestas',
+    test: p =>
+      typeof p === 'string' && /rotor_rpm|nacelle_position|wind_speed.*turbine_state/i.test(p),
+  },
+  // Siemens Gamesa: CSV with metmast + bearing_temp
+  {
+    oem: 'siemens-gamesa',
+    test: p =>
+      typeof p === 'string' && /wind_speed_metmast|bearing_temp|availability_status/i.test(p),
+  },
+  // Nordex: CSV with blade_angle + transformer_temp
+  {
+    oem: 'nordex',
+    test: p =>
+      typeof p === 'string' && /blade_angle|transformer_temp|turbine_status/i.test(p),
+  },
+  // BYD BESS: has soc or state_of_charge
+  {
+    oem: 'byd-bess',
+    test: p =>
+      p?.soc !== undefined || p?.state_of_charge !== undefined ||
+      (typeof p === 'string' && /state.?of.?charge|byd/i.test(p)),
+  },
+  // Terraco historian: { data: [{ timestamp, values: { "SITE.ActivePower": ... } }] }
+  {
+    oem: 'terraco',
+    test: p => {
+      const first = Array.isArray(p?.data) ? p.data[0] : null
+      if (!first?.values) return false
+      return Object.keys(first.values).some(k => /\.\w+/.test(k))
+    },
+  },
+  // Higeco: records with connectionStatus + powerStatus
+  {
+    oem: 'higeco',
+    test: p => {
+      const first = Array.isArray(p?.records) ? p.records[0] : null
+      return first?.normalized?.connectionStatus !== undefined
+    },
+  },
+]
+
+/**
+ * Attempt to identify an OEM from the raw payload string via field fingerprinting.
+ *
+ * @param {string} content  raw MCP tool result content
+ * @returns {string|null}   canonical OEM key or null
+ */
+export function detectOemFromPayload(content) {
+  if (!content || typeof content !== 'string') return null
+
+  // Try to parse as JSON for object-based fingerprints
+  let parsed = null
+  try { parsed = JSON.parse(content) } catch { /* not JSON — use raw string */ }
+
+  const subject = parsed ?? content
+
+  for (const { oem, test } of FINGERPRINTS) {
+    try {
+      if (test(subject)) return oem
+    } catch { /* fingerprint threw — skip */ }
+  }
+  return null
+}
+
+// ─── Transform dispatch ───────────────────────────────────────────────────────
+
+/**
+ * Run the raw payload through odse-transform.py for the given OEM source.
+ * Returns normalized ODS-E JSON string on success, null on failure (caller
+ * should fall back to the original content).
+ *
+ * @param {string} source   ODSE source key
+ * @param {string} payload  raw payload string
+ * @param {object} opts     { assetId?, timezone? }
+ * @returns {string|null}
+ */
+function runOdseTransform(source, payload, opts = {}) {
+  const args = ['python3', TRANSFORM_SCRIPT, '--source', source]
+  if (opts.assetId) args.push('--asset-id', opts.assetId)
+  if (opts.timezone) args.push('--timezone', opts.timezone)
+
+  const result = spawnSync(args[0], args.slice(1), {
+    input: payload,
+    encoding: 'utf8',
+    timeout: TRANSFORM_TIMEOUT_MS,
+    maxBuffer: 10 * 1024 * 1024,  // 10 MB
+  })
+
+  if (result.error) return null   // spawn failed (python3 not found, etc.)
+  if (result.status === 2) return null   // import/usage error — log and skip
+  if (result.status === 1) return null   // unknown source — pass through
+  if (result.status !== 0) return null
+
+  const out = (result.stdout || '').trim()
+  if (!out) return null
+  return out
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Apply ODSE energy normalization to an MCP tool result.
+ *
+ * If the server name or payload fingerprint identifies a known OEM inverter
+ * brand, the raw content is transformed to ODS-E normalized JSON.
+ * Otherwise the content is returned unchanged.
+ *
+ * @param {string} serverName   MCP server name (from mcp__<server>__<tool>)
+ * @param {string} content      raw tool result content string
+ * @param {object} opts         optional hints: { assetId?, timezone? }
+ * @returns {{ content: string, normalized: boolean, oem: string|null }}
+ */
+export async function applyEnergyNormalization(serverName, content, opts = {}) {
+  if (!content || typeof content !== 'string') {
+    return { content, normalized: false, oem: null }
+  }
+
+  // Step 1: try name-based detection
+  let oem = detectOemFromServerName(serverName)
+
+  // Step 2: fall back to payload fingerprinting
+  if (!oem) oem = detectOemFromPayload(content)
+
+  // Step 3: no match — pass through unchanged
+  if (!oem) return { content, normalized: false, oem: null }
+
+  // Step 4: run transform
+  const normalized = runOdseTransform(oem, content, opts)
+  if (!normalized) {
+    // Transform failed — return original, don't break the model turn
+    return { content, normalized: false, oem }
+  }
+
+  // Wrap with a header so the model knows this was normalized
+  const header = `[ODS-E normalized · source: ${oem}]\n`
+  return { content: header + normalized, normalized: true, oem }
+}

package/lib/hookShapeOrder.mjs

@@ -0,0 +1,30 @@
+/** CLEAN_ROOM_SPEC.md Appendix A — HookInputSchema union order (normative). */
+export const HOOK_INPUT_SCHEMA_UNION_ORDER = [
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'PermissionDenied',
+  'Notification',
+  'UserPromptSubmit',
+  'SessionStart',
+  'SessionEnd',
+  'Stop',
+  'StopFailure',
+  'SubagentStart',
+  'SubagentStop',
+  'PreCompact',
+  'PostCompact',
+  'PermissionRequest',
+  'Setup',
+  'TeammateIdle',
+  'TaskCreated',
+  'TaskCompleted',
+  'Elicitation',
+  'ElicitationResult',
+  'ConfigChange',
+  'InstructionsLoaded',
+  'WorktreeCreate',
+  'WorktreeRemove',
+  'CwdChanged',
+  'FileChanged',
+]

package/lib/hookplane.mjs

@@ -0,0 +1,228 @@
+import fs from 'node:fs'
+import { spawn } from 'node:child_process'
+import { withTransaction } from './store.mjs'
+
+const MAX_CAPTURE = 4194304
+const TRUNC_MARK = '\n[SDLC_OUTPUT_TRUNCATED]\n'
+
+function hookTimeoutMs(eventName) {
+  if (eventName === 'SessionEnd') {
+    const v = Number(process.env.SDLC_SESSIONEND_HOOK_TIMEOUT_MS)
+    return Number.isFinite(v) && v > 0 ? v : 1500
+  }
+  const v = Number(process.env.SDLC_HOOK_TIMEOUT_MS)
+  return Number.isFinite(v) && v > 0 ? v : 600000
+}
+
+/** §5.1 — matcher against event-specific field. */
+export function matcherMatches(hookEventName, matcher, ctx) {
+  const m = matcher == null || matcher === '' ? '' : String(matcher)
+  if (m === '' || m === '*') return true
+
+  const toolish = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure', 'PermissionRequest', 'PermissionDenied'])
+  if (toolish.has(hookEventName)) return matchValue(m, ctx.tool_name || '')
+  if (hookEventName === 'SessionStart') return matchValue(m, ctx.source || '')
+  if (hookEventName === 'Setup' || hookEventName === 'PreCompact' || hookEventName === 'PostCompact') return matchValue(m, ctx.trigger || '')
+  if (hookEventName === 'Notification') return matchValue(m, ctx.notification_type || '')
+  if (hookEventName === 'SessionEnd') return matchValue(m, ctx.reason || '')
+  if (hookEventName === 'StopFailure') return matchValue(m, String(ctx.error || ''))
+  if (hookEventName === 'SubagentStart' || hookEventName === 'SubagentStop') return matchValue(m, ctx.agent_type || '')
+  if (hookEventName === 'Elicitation' || hookEventName === 'ElicitationResult') return matchValue(m, ctx.mcp_server_name || '')
+  if (hookEventName === 'ConfigChange') return matchValue(m, ctx.source || '')
+  if (hookEventName === 'InstructionsLoaded') return matchValue(m, ctx.load_reason || '')
+  if (hookEventName === 'FileChanged') {
+    const base = ctx.file_path ? ctx.file_path.split(/[/\\]/).pop() : ''
+    return matchValue(m, base)
+  }
+  return true
+}
+
+function matchValue(matcher, value) {
+  if (/^[a-zA-Z0-9_|]+$/.test(matcher) && matcher.includes('|')) {
+    return matcher.split('|').includes(value)
+  }
+  try { return new RegExp(matcher).test(value) } catch { return false }
+}
+
+function baseHookInput(hook_event_name, rt) {
+  const o = {
+    hook_event_name,
+    session_id: rt.sessionId,
+    conversation_id: rt.conversationId,
+    runtime_db_path: rt.runtimeDbPath,
+    cwd: rt.cwd,
+  }
+  if (rt.permissionMode != null) o.permission_mode = rt.permissionMode
+  if (rt.agentId != null) o.agent_id = rt.agentId
+  if (rt.agentType != null) o.agent_type = rt.agentType
+  return o
+}
+
+/** §5.2 — dedup: collapse adjacent identical (hook_event, matcher, command, shell, if_condition) keeping first. */
+function hooksForEvent(settings, eventName) {
+  const raw = settings?.hooks
+  if (!Array.isArray(raw)) return []
+  const filtered = raw.filter(h => h && h.hook_event_name === eventName)
+  const deduped = []
+  for (const h of filtered) {
+    const key = `${h.hook_event_name}|${h.matcher ?? ''}|${h.command ?? ''}|${h.shell ?? 'bash'}|${h.if_condition ?? ''}`
+    if (deduped.length && deduped[deduped.length - 1]._dedupKey === key) continue
+    deduped.push({ ...h, _dedupKey: key })
+  }
+  return deduped
+}
+
+/** §5.3 — sequential hooks; §5.6 blocking merge; §5.8 async rejection. */
+export async function runHooks(db, rt, eventName, eventFields) {
+  if (process.env.SDLC_DISABLE_ALL_HOOKS === '1') return { ok: true, preTool: null, userPrompt: null }
+
+  const list = hooksForEvent(rt.settings, eventName)
+  let ordinal = 0
+  const preAgg = { permission: 'unset', blocks: [], skipRest: false }
+  let userPromptCtx = null
+
+  for (const h of list) {
+    if (preAgg.skipRest) {
+      persistSkipped(db, rt, eventName, ordinal, h, eventFields, 'prior_block_or_deny')
+      ordinal++
+      continue
+    }
+    if (!matcherMatches(eventName, h.matcher, { ...rt, ...eventFields })) continue
+
+    const shell = h.shell === 'powershell' || h.shell === 'sh' ? h.shell : 'bash'
+    const stdinObj = { ...baseHookInput(eventName, rt), ...eventFields }
+    const inputJson = JSON.stringify(stdinObj)
+    const started = new Date().toISOString()
+
+    const { exitCode, stdout, stderr } = await runHookCommand(shell, h.command, stdinObj, rt.cwd, rt.runtimeDbPath, hookTimeoutMs(eventName))
+    const completed = new Date().toISOString()
+
+    withTransaction(db, () => {
+      db.prepare(
+        `INSERT INTO hook_invocations(session_id, conversation_id, hook_event, hook_ordinal, matcher, command, tool_use_id, tool_name, input_json, exit_code, stdout_text, stderr_text, started_at, completed_at, skipped_reason) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+      ).run(rt.sessionId, rt.conversationId, eventName, ordinal, String(h.matcher ?? ''), String(h.command ?? ''), eventFields.tool_use_id ?? null, eventFields.tool_name ?? null, inputJson, exitCode, stdout, stderr, started, completed, null)
+    })
+    ordinal++
+
+    const parsed = parseHookStdout(stdout)
+    if (parsed.asyncInvalid) console.error('[SDLC] hook rejected async:true control (§5.8)')
+
+    if (eventName === 'PreToolUse') {
+      mergePreToolUse(preAgg, parsed, exitCode, stderr, ordinal - 1)
+      if (preAgg.skipRest) continue
+    } else if (eventName === 'UserPromptSubmit' && exitCode === 2) {
+      userPromptCtx = { blocked: true, stderr, ordinal: ordinal - 1 }
+      break
+    }
+  }
+
+  if (eventName === 'PreToolUse') {
+    const denied = preAgg.permission === 'deny' || preAgg.blocks.length > 0
+    let message = ''
+    if (preAgg.blocks.length) {
+      message = preAgg.blocks.sort((a, b) => a.ordinal - b.ordinal).map(b => `[${b.ordinal}] ${b.stderr}`).join('\n')
+    }
+    return {
+      ok: !denied,
+      preTool: denied ? { denied: true, message } : { denied: false, hookAsk: preAgg.permission === 'ask' },
+      userPrompt: null,
+    }
+  }
+
+  if (eventName === 'UserPromptSubmit') {
+    return { ok: !userPromptCtx?.blocked, preTool: null, userPrompt: userPromptCtx }
+  }
+
+  return { ok: true, preTool: null, userPrompt: null }
+}
+
+function persistSkipped(db, rt, eventName, ordinal, h, eventFields, reason) {
+  const stdinObj = { ...baseHookInput(eventName, rt), ...eventFields }
+  withTransaction(db, () => {
+    db.prepare(
+      `INSERT INTO hook_invocations(session_id, conversation_id, hook_event, hook_ordinal, matcher, command, tool_use_id, tool_name, input_json, exit_code, stdout_text, stderr_text, started_at, completed_at, skipped_reason) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+    ).run(rt.sessionId, rt.conversationId, eventName, ordinal, String(h.matcher ?? ''), String(h.command ?? ''), eventFields.tool_use_id ?? null, eventFields.tool_name ?? null, JSON.stringify(stdinObj), null, null, null, new Date().toISOString(), null, reason)
+  })
+}
+
+function mergePreToolUse(agg, parsed, exitCode, stderr, ord) {
+  const dec = parsed.hookSpecificOutput?.permissionDecision
+  if (dec === 'deny' || dec === 'ask' || dec === 'allow') {
+    const rank = { unset: 0, allow: 1, ask: 2, deny: 3 }
+    if ((rank[dec] ?? 0) > (rank[agg.permission] ?? 0)) agg.permission = dec
+  }
+  if (exitCode === 2) agg.blocks.push({ ordinal: ord, stderr: stderr || '' })
+  if (agg.permission === 'deny' || agg.blocks.length > 0) agg.skipRest = true
+}
+
+function parseHookStdout(stdout) {
+  const t = (stdout || '').trim()
+  if (!t.startsWith('{')) return {}
+  try {
+    const j = JSON.parse(t)
+    if (j && j.async === true) return { asyncInvalid: true }
+    return j
+  } catch { return {} }
+}
+
+function resolveBash() {
+  if (fs.existsSync('/bin/bash')) return '/bin/bash'
+  if (fs.existsSync('/usr/bin/bash')) return '/usr/bin/bash'
+  return 'bash'
+}
+
+async function runHookCommand(shell, commandString, stdinObj, cwd, runtimeDbPath, timeoutMs) {
+  const payload = JSON.stringify(stdinObj) + '\n'
+  if (!fs.existsSync(cwd)) return { exitCode: null, stdout: '', stderr: `hook cwd does not exist: ${cwd}` }
+
+  const env = { ...process.env, AGENT_SDLC_DB: runtimeDbPath, SDLC_HOOK: '1', CLAUDE_PROJECT_DIR: cwd }
+  if (!env.LANG && !env.LC_ALL) env.LANG = 'C.UTF-8'
+
+  let child
+  try {
+    if (shell === 'bash') child = spawn(resolveBash(), ['-lc', commandString], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] })
+    else if (shell === 'sh') child = spawn('/bin/sh', ['-c', commandString], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] })
+    else child = spawn('pwsh', ['-NoProfile', '-NonInteractive', '-Command', commandString], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] })
+  } catch (e) {
+    return { exitCode: null, stdout: '', stderr: String(e?.message || e) }
+  }
+
+  const stdoutP = cappedRead(child.stdout, MAX_CAPTURE)
+  const stderrP = cappedRead(child.stderr, MAX_CAPTURE)
+  child.stdin.write(payload, 'utf8')
+  child.stdin.end()
+
+  const timer = setTimeout(() => { try { child.kill('SIGKILL') } catch {} }, timeoutMs)
+  let exitCode = null
+  try {
+    exitCode = await new Promise((resolve) => {
+      child.on('error', () => resolve(null))
+      child.on('close', c => resolve(c))
+    })
+  } finally { clearTimeout(timer) }
+
+  return { exitCode, stdout: await stdoutP, stderr: await stderrP }
+}
+
+function cappedRead(stream, maxBytes) {
+  return new Promise(resolve => {
+    let total = 0; const chunks = []; let truncated = false
+    stream.on('data', buf => {
+      if (truncated) return
+      const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf)
+      if (total + b.length <= maxBytes) { chunks.push(b); total += b.length }
+      else {
+        const rest = maxBytes - total
+        if (rest > 0) chunks.push(b.subarray(0, rest))
+        total = maxBytes; truncated = true
+        try { stream.destroy() } catch {}
+      }
+    })
+    stream.on('end', () => {
+      let s = Buffer.concat(chunks).toString('utf8')
+      if (truncated) s += TRUNC_MARK
+      resolve(s)
+    })
+    stream.on('error', () => resolve(Buffer.concat(chunks).toString('utf8') + TRUNC_MARK))
+  })
+}

package/lib/instructions.mjs

@@ -0,0 +1,23 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Search for Ona.md in cwd and parent directories. Returns content or empty string. */
+export function loadInstructions(cwd) {
+  const names = ['Ona.md', '.ona/Ona.md', 'ONA.md', '.ona/ONA.md']
+  let dir = cwd
+  const visited = new Set()
+  while (dir && !visited.has(dir)) {
+    visited.add(dir)
+    for (const name of names) {
+      const full = path.join(dir, name)
+      if (fs.existsSync(full)) {
+        try { return { content: fs.readFileSync(full, 'utf8'), path: full } }
+        catch { /* unreadable */ }
+      }
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return { content: '', path: null }
+}