A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.
// 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 !== ''
}