Durable coding-agent harnesses (Claude Code, Codex, OpenCode, Pi, fx) on a Workflow SDK World
/**
* The `SessionMachine` over one relay link (docs/workspaces.md §5.4), before it
* is branded: what the session factory (A3, `session.ts`) and the stand-in
* (`localMachine`) both build, so the rules below hold on both and A3 tests
* them once.
*
* - **The fence.** Read by the caller once per attach (inside the
* `sandbox.attach` fact's body) and kept frozen as `machine.fence`. While it
* is missing or `fenced: false` (or the caller's `mutable` says the token
* has narrowed since), the machine refuses `files.upload` (`FILES`),
* `files.wipe` (`WIPE`) and `spawn` (`SPAWN`): the relay can't tell a
* mutating spawn from a read, so every spawn counts as mutating. The
* workspace (`RemoteMachine`, `env.ts`) refuses a mutating `ENV_CALL` the
* same way; arming a fresh VM is A3's.
* - **The env.** Every `spawn`'s `env` passes `checkSpawnEnv` first (§3.1 and
* the `process.env` equality rule): a `TypeError` naming the key. The model
* key's name (`PLACEHOLDER_NAMES`) passes only with this attach's key.
* - **Loss.** `signal` is the link's: aborted once the link is lost. A
* `spawn`'s own `signal` aborting kills the session's processes.
* - **Frozen state.** The brand freezes the machine, so everything that
* changes (the link, its loss) is read through closures and getters, never
* stored in a property.
*/
import type { CacheDir, CacheFile, FenceToken, MachineSpawn, MachineTail, SessionMachine } from 'harness-world-process';
import { checkSpawnEnv } from './env-check.ts';
import { RemoteMachine, fencedToken, type RemoteMachineOptions } from './env.ts';
import type { RelayLink } from './relay/dial.ts';
import { ustar } from './tar.ts';
export interface MachineParts {
link: RelayLink;
sessionId: string;
/** The token the relay was armed with, read once per attach. */
fence: FenceToken | undefined;
/** `/workspace`. */
root: string;
dirs: Readonly<Record<CacheDir, string>>;
/**
* The workspace's command limit, invocation clamp and flush mode
* (`RemoteMachineOptions`). The workspace itself is always a `RemoteMachine`
* over `link` holding `fence`, never one the caller supplies, so the fence
* gate on mutating `ENV_CALL`s can't be swapped out.
*/
workspaceOptions?: Pick<RemoteMachineOptions, 'timeoutMs' | 'timeLeft' | 'flush' | 'callTimeoutMs'>;
/** The model port in the VM, as the CLI's base URL. */
modelUrl: string;
/** The attach's model key `P` (§5.5): the relay admits a model request only with it. */
modelKey: string;
/** What the model must be told about this attach (a lost Drive). */
notes?: readonly string[];
/** What `notes` describe (the new Drive's id), for the acknowledgement. */
notesKey?: string;
/**
* Whether the attach may still mutate the VM, asked at every `spawn`,
* `files.upload` and `files.wipe` on top of `fence` (the session factory's:
* the invocation's token as later acquires narrowed it, so a machine handed
* out before the drive's `fenced` turned false refuses too). Default: `fence`
* alone.
*/
mutable?: () => boolean;
}
export { fencedToken };
function unfenced(op: string): Error {
return new Error(`harness-sandbox: ${op} refused: this attach holds no fenced token (docs/workspaces.md §5.4: no WIPE, FILES or SPAWN without one)`);
}
/** Build the unbranded `SessionMachine` (the caller brands it through `session.ts`). */
export function sessionMachine(parts: MachineParts): Omit<SessionMachine, 'brand'> {
const { link } = parts;
const fence = parts.fence ? Object.freeze({ count: parts.fence.count, fenced: parts.fence.fenced }) : undefined;
const fenced = fencedToken(fence);
const still = parts.mutable;
const mutable = () => fenced && (still ? still() : true);
return {
sessionId: parts.sessionId,
fence,
root: parts.root,
workspace: new RemoteMachine({ link, root: parts.root, fence, ...parts.workspaceOptions, ...(still ? { mutable: still } : {}) }),
dirs: Object.freeze({ ...parts.dirs }),
signal: link.signal,
modelUrl: parts.modelUrl,
modelKey: parts.modelKey,
notes: Object.freeze([...(parts.notes ?? [])]),
...(parts.notes?.length && parts.notesKey !== undefined ? { notesKey: parts.notesKey } : {}),
async spawn(options: MachineSpawn) {
if (!mutable()) throw unfenced('spawn');
checkSpawnEnv(options.env, process.env, parts.modelKey);
if (options.signal?.aborted) throw options.signal.reason ?? new Error('harness-sandbox: spawn aborted');
const proc = await link.spawn({ command: options.command, args: options.args, cwd: options.cwd ?? parts.root, env: options.env, ...(options.isolatedCommands ? { isolatedCommands: true } : {}) });
const signal = options.signal;
if (signal) {
const onAbort = () => link.killSession('SIGKILL');
if (signal.aborted) onAbort();
else {
signal.addEventListener('abort', onAbort, { once: true });
void proc.exited.then(() => signal.removeEventListener('abort', onAbort));
}
}
return proc;
},
files: {
async upload(dir: CacheDir, files: readonly CacheFile[]) {
if (!mutable()) throw unfenced('files.upload');
await link.files(dir, ustar(files));
},
async wipe() {
if (!mutable()) throw unfenced('files.wipe');
await link.wipe();
},
},
async tail(dir: CacheDir, path: string, options?: { offset?: number }): Promise<MachineTail> {
const t = link.tail(dir, path, options);
return {
get offset() {
return t.offset;
},
read: () => t.read(),
sync: () => t.sync(),
close: () => t.close(),
};
},
fsync: () => link.fsync(),
async close() {
link.killSession('SIGKILL');
link.close();
},
};
}