Skip to content

A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.

4.4 KB
Raw Blame
// The record of a memory change that is about to be published.
//
// A change touches more than one file (the entry, the Index that links a topic, the
// change log), and each of them is written on its own, so an interruption can leave
// half of it done: an entry without its row in the change log, a topic without its
// link. This keeps the record of what the change will do, so the change can be
// finished later instead of being half done.
//
// The record is written before the change is published, and it is what accepts the
// change: before the record is there, nothing has changed. It holds the files to
// write, the files to remove, and the row that goes with them in the change log, so
// finishing a change later is the same work as publishing it in the first place.
import { readFileSync } from 'node:fs'
import { join, relative, resolve, sep } from 'node:path'

// The record inside the memory folder.
export const PENDING_FILE = 'pending.json'
// A record that cannot be read or understood stops the memory: what it would have
// changed is unknown, so nothing goes on until it is fixed.
const PENDING = 'memory/pending'
// A change is one entry, so its record stays small; a larger one was not written by
// this.
const MAX_BYTES = 1_048_576

export function pendingPath(root) {
  return join(root, PENDING_FILE)
}

// A path inside the memory folder, as the record holds it: relative, so the folder
// can be moved, and never outside it.
export function inside(root, path) {
  const base = resolve(root)
  const full = resolve(base, path)
  if (full !== base && !full.startsWith(base + sep)) throw new Error(`the path ${path} is outside the memory folder`)
  return full
}

// The path of a file in the memory folder, as the record holds it.
export function relativePath(root, path) {
  return relative(resolve(root), resolve(path)).split(sep).join('/')
}

// The record of a change: what it does, and the row that goes with it.
export function record({ id, time, op, scope, steps, row }) {
  return { id, time, op, scope, steps, row: { time, id, ...row } }
}

// The record of a change, as it is written down. A record that would be too large is
// refused: the memory folder holds one change at a time, and a record that cannot be
// read back would stop the memory for good. The size is the same one the read side
// uses, so a record that is written can always be read.
export function serialize(record) {
  const text = JSON.stringify(record)
  const size = Buffer.byteLength(text)
  if (size > MAX_BYTES) {
    throw Object.assign(new Error(`The memory change is too large to record (${size} of ${MAX_BYTES} bytes). Make the memory file smaller first.`), { code: 'memory/too-large' })
  }
  return text
}

// The record waiting to be finished, if there is one. A record that cannot be read
// or understood is an error, not an empty record: the change it holds is unknown,
// and a change that is half done must not be passed over.
export function read(root) {
  const path = pendingPath(root)
  let text
  try {
    text = readFileSync(path, 'utf8')
  } catch (error) {
    if (error?.code === 'ENOENT') return undefined
    throw Object.assign(new Error(`${PENDING_FILE} could not be read (${error?.code ?? error?.message})`), { code: PENDING })
  }
  if (Buffer.byteLength(text) > MAX_BYTES) {
    throw Object.assign(new Error(`${PENDING_FILE} is larger than a memory change record`), { code: PENDING })
  }
  let value
  try {
    value = JSON.parse(text)
  } catch (error) {
    throw Object.assign(new Error(`${PENDING_FILE} is not readable (${error.message})`), { code: PENDING })
  }
  if (!wellFormed(value)) throw Object.assign(new Error(`${PENDING_FILE} is not a memory change record`), { code: PENDING })
  return value
}

const wellFormed = (value) => {
  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
  if (typeof value.id !== 'string' || value.id === '') return false
  if (typeof value.op !== 'string' || typeof value.scope !== 'string') return false
  if (!Array.isArray(value.steps) || value.steps.length === 0) return false
  if (!value.steps.every(step => step !== null && typeof step === 'object' && typeof step.path === 'string' && step.path !== ''
    && (step.action === 'remove' ? step.text === undefined : step.action === 'write' && typeof step.text === 'string'))) return false
  if (value.row === null || typeof value.row !== 'object' || Array.isArray(value.row)) return false
  return typeof value.row.id === 'string' && value.row.id !== ''
}