Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

4.3 KB
Raw Blame
/** Small native identity records needed by session control, independent of optional readers. */
import { isAbsolute, resolve } from 'node:path'
import { identityBytes, IdentityReadUnavailable } from './identityScan.js'

export const UNSETTLED: unique symbol = Symbol('unsettled')
type Field = readonly string[]
export interface SessionHeader {
  bytes: readonly number[]
  type: string
  id: { field: Field; pattern: RegExp }
  cwd: Field
}
export interface SessionFolder {
  prefix: string; suffix: string; trim: RegExp; mangle: RegExp; replacement: string
}
export interface RunIdentity {
  bytes: readonly number[]
  cwd: Field
  run: readonly { field: Field; value: string }[]
  /** A field that marks a record the engine writes ahead of the workspace header (Muse 1.4's retained permission
   *  frame): such records are skipped, and the header is the first record without it. */
  preamble?: Field
}
export interface NativeSessionHead { sessionId: string; cwd: string }

function valueAt(value: unknown, field: Field): unknown {
  for (const key of field) {
    if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
    value = (value as Record<string, unknown>)[key]
  }
  return value
}
function parsed(line: string): unknown {
  try { return JSON.parse(line) } catch { return null }
}

export function sessionFolder(rule: SessionFolder, cwd: string): string {
  return rule.prefix + cwd.replace(rule.trim, '').replace(rule.mangle, rule.replacement) + rule.suffix
}

/** A complete first JSON entry; blank/malformed lines are skipped, another valid entry refuses it.
 * The optional reader supplies its own I/O wrapper to retain its scan's read-failure evidence. */
export async function readSessionHeader(rule: SessionHeader, read: (bytes: number) => Promise<string>): Promise<NativeSessionHead | null | typeof UNSETTLED> {
  for (const bytes of rule.bytes) {
    const head = await read(bytes)
    for (const line of head.split('\n').slice(0, -1)) {
      if (!line.trim()) continue
      const record = parsed(line)
      if (record === null) continue
      if (valueAt(record, ['type']) !== rule.type) return null
      const id = valueAt(record, rule.id.field)
      const cwd = valueAt(record, rule.cwd)
      return typeof id === 'string' && rule.id.pattern.test(id)
        && typeof cwd === 'string' && cwd.startsWith('/') ? { sessionId: id, cwd: resolve(cwd) } : null
    }
    if (Buffer.byteLength(head) < bytes) return UNSETTLED
  }
  return null
}

/** A workspace in line one and a declared run marker. A bound never establishes absence:
 * if relevant evidence lies beyond it, the caller holds the lookup instead of guessing a sibling. */
export async function readRunIdentity(rule: RunIdentity, path: string, matches: (cwd: string) => Promise<boolean>): Promise<{ cwd: string } | null> {
  for (const bytes of rule.bytes) {
    const head = await identityBytes(path, bytes + 1).catch(error => {
      if (error instanceof IdentityReadUnavailable) throw error
      throw new IdentityReadUnavailable('the workspace identity could not be read')
    })
    const complete = head.length <= bytes
    const lines = head.subarray(0, bytes).toString('utf8').split('\n')
    if (!complete) lines.pop()
    if (!lines.length) continue
    let first = 0
    while (rule.preamble && first < lines.length) {
      const record = parsed(lines[first]!)
      if (record === null || valueAt(record, rule.preamble) === undefined) break
      first++
    }
    if (first === lines.length) {
      // Only preamble so far: the header lies beyond this head, or nowhere.
      if (complete) throw new IdentityReadUnavailable('the workspace header is incomplete or invalid')
      continue
    }
    const cwd = valueAt(parsed(lines[first]!), rule.cwd)
    if (typeof cwd !== 'string' || !isAbsolute(cwd)) throw new IdentityReadUnavailable('the workspace header is incomplete or invalid')
    if (!await matches(cwd)) return null
    let malformed = false
    for (const line of lines) {
      const record = parsed(line)
      if (line.trim() && record === null) malformed = true
      if (rule.run.every(part => valueAt(record, part.field) === part.value)) return { cwd }
    }
    if (complete) {
      if (malformed) throw new IdentityReadUnavailable('the run identity is incomplete or invalid')
      return null
    }
  }
  throw new IdentityReadUnavailable('the run identity exceeds the bounded read')
}