@playcraft/cli 0.0.57 → 0.0.59

package/dist/workspace-runtime/codex/loopback.js

@@ -0,0 +1,59 @@
+import { nativeEvent } from './native-adapter.js';
+/** In-process Codex stand-in. Not the App Server; used to prove the operation/event loop. */
+export function createLoopbackNativeAdapter() {
+    const threads = new Map();
+    const approvals = new Set();
+    return {
+        name: 'loopback',
+        ready: () => true,
+        async startThread(input) {
+            const threadId = `thread_${input.sessionId}`;
+            threads.set(threadId, input.sessionId);
+            return { threadId };
+        },
+        async startTurn(input) {
+            if (threads.get(input.threadId) !== input.sessionId) {
+                return {
+                    outcome: 'failed',
+                    events: [nativeEvent('turn.failed', { reason: 'unknown_thread' })],
+                };
+            }
+            if (input.simulateLostReceipt) {
+                return { outcome: 'uncertain', events: [] };
+            }
+            const turnId = `turn_${input.clientRequestId}`;
+            const events = [
+                nativeEvent('item/agentMessage/delta', { text: `loopback:${input.text}` }),
+                nativeEvent('turn.completed', { turnId, threadId: input.threadId }),
+            ];
+            if (input.text.includes('[approval]')) {
+                const approvalId = `approval_${input.clientRequestId}`;
+                approvals.add(JSON.stringify([input.sessionId, approvalId]));
+                events.splice(1, 0, nativeEvent('item/tool/requestUserInput', { approvalId }));
+                return { outcome: 'completed', turnId, approvalId, events };
+            }
+            return { outcome: 'completed', turnId, events };
+        },
+        async interrupt(input) {
+            if (threads.get(input.threadId) !== input.sessionId) {
+                return { outcome: 'uncertain', events: [] };
+            }
+            return {
+                outcome: 'interrupted',
+                events: [nativeEvent('turn.interrupted', { threadId: input.threadId })],
+            };
+        },
+        async respondApproval(input) {
+            if (!approvals.has(JSON.stringify([input.sessionId, input.approvalId]))) {
+                return { outcome: 'failed', events: [nativeEvent('approval.unknown', { approvalId: input.approvalId })] };
+            }
+            approvals.delete(JSON.stringify([input.sessionId, input.approvalId]));
+            const result = {
+                outcome: 'completed',
+                approvalId: input.approvalId,
+                events: [nativeEvent('approval.resolved', { approvalId: input.approvalId, accepted: input.accepted })],
+            };
+            return result;
+        },
+    };
+}

package/dist/workspace-runtime/codex/native-adapter.js

@@ -0,0 +1,3 @@
+export function nativeEvent(type, payload) {
+    return { type, payload, occurredAt: new Date().toISOString() };
+}

package/dist/workspace-runtime/main.js

@@ -0,0 +1,10 @@
+import { runWorkspaceRuntimeServe } from '../commands/workspace-runtime.js';
+const flag = process.argv.indexOf('--config');
+const configPath = flag >= 0 ? process.argv[flag + 1] : undefined;
+if (!configPath) {
+    console.error('workspace-runtime: missing --config');
+    process.exitCode = 2;
+}
+else {
+    await runWorkspaceRuntimeServe(configPath);
+}

package/dist/workspace-runtime/persistence/journal.js

@@ -0,0 +1,350 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { workspaceRegistrationSchema, checkpointRecordSchema, operationRecordSchema, pendingSourceEventSchema, sourceEventKey, sourceEventReceiptSchema, terminalRecordSchema, } from '@playcraft/common/cloud-workspace/runtime';
+export class RuntimeJournal {
+    filePath;
+    writes = Promise.resolve();
+    locks = new Map();
+    async exclusive(key, action) {
+        const previous = this.locks.get(key) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.locks.set(key, current);
+        await previous;
+        try {
+            return await action();
+        }
+        finally {
+            release();
+            if (this.locks.get(key) === current)
+                this.locks.delete(key);
+        }
+    }
+    snapshot = {
+        workspaces: {},
+        workspaceFileRevisions: {},
+        operations: {},
+        receipts: {},
+        events: {},
+        sessions: {},
+        terminals: {},
+        checkpoints: {},
+        fileRevisions: {},
+        approvals: {},
+        managedWrites: {},
+        executionGroup: { stopConfirmed: false, replaced: false },
+        lastSourceSequence: 0,
+        acceptedLeaseFence: 0,
+        destroyed: false,
+    };
+    constructor(stateDir) {
+        this.filePath = join(stateDir, 'journal.json');
+    }
+    async load() {
+        try {
+            const parsed = JSON.parse(await readFile(this.filePath, 'utf8'));
+            this.snapshot = {
+                workspaces: Object.fromEntries(Object.entries(parsed.workspaces ?? {}).map(([key, value]) => [key, workspaceRegistrationSchema.parse(value)])),
+                workspaceFileRevisions: parsed.workspaceFileRevisions ?? {},
+                operations: Object.fromEntries(Object.entries(parsed.operations ?? {}).map(([key, value]) => [
+                    key,
+                    operationRecordSchema.parse(value),
+                ])),
+                receipts: Object.fromEntries(Object.entries(parsed.receipts ?? {}).map(([key, value]) => [
+                    key,
+                    sourceEventReceiptSchema.parse(value),
+                ])),
+                events: Object.fromEntries(Object.entries(parsed.events ?? {}).map(([key, value]) => [
+                    key,
+                    pendingSourceEventSchema.parse(value),
+                ])),
+                sessions: Object.fromEntries(Object.entries(parsed.sessions ?? {}).map(([key, value]) => [
+                    key,
+                    {
+                        ...value,
+                        recoverability: value.recoverability === 'history_only' ? 'history_only' : 'native',
+                    },
+                ])),
+                terminals: Object.fromEntries(Object.entries(parsed.terminals ?? {}).map(([key, value]) => [
+                    key,
+                    terminalRecordSchema.parse(value),
+                ])),
+                checkpoints: Object.fromEntries(Object.entries(parsed.checkpoints ?? {}).map(([key, value]) => [
+                    key,
+                    checkpointRecordSchema.parse(value),
+                ])),
+                fileRevisions: parsed.fileRevisions ?? {},
+                managedWrites: sanitizeManagedWrites(parsed.managedWrites),
+                fileCheckpointId: typeof parsed.fileCheckpointId === 'string' ? parsed.fileCheckpointId : undefined,
+                consistentCheckpointId: typeof parsed.consistentCheckpointId === 'string' ? parsed.consistentCheckpointId : undefined,
+                approvals: Object.fromEntries(Object.entries(parsed.approvals ?? {})
+                    .filter(([, value]) => isStoredApproval(value))
+                    .map(([key, value]) => [key, value])),
+                executionGroup: {
+                    pid: integerOrUndefined(parsed.executionGroup?.pid),
+                    startedAt: typeof parsed.executionGroup?.startedAt === 'string'
+                        ? parsed.executionGroup.startedAt
+                        : undefined,
+                    previousPid: integerOrUndefined(parsed.executionGroup?.previousPid),
+                    stopConfirmed: parsed.executionGroup?.stopConfirmed === true,
+                    replaced: parsed.executionGroup?.replaced === true,
+                },
+                runtimeEpoch: integerOrUndefined(parsed.runtimeEpoch),
+                lastSourceSequence: parsed.lastSourceSequence ?? 0,
+                acceptedLeaseFence: parsed.acceptedLeaseFence ?? highestFence(parsed.operations ?? {}),
+                destroyed: parsed.destroyed === true,
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    getWorkspace(workspaceId) {
+        return this.snapshot.workspaces[workspaceId];
+    }
+    async putWorkspace(binding) {
+        this.snapshot.workspaces[binding.workspaceId] = workspaceRegistrationSchema.parse(binding);
+        await this.flush();
+    }
+    findSessionCreation(sessionId) {
+        return Object.values(this.snapshot.operations).find((item) => item.kind === 'session.create' && item.sessionId === sessionId);
+    }
+    findTerminalCreation(terminalId) {
+        return Object.values(this.snapshot.operations).find((item) => item.kind === 'terminal.create' && item.terminalId === terminalId);
+    }
+    getOperation(scopeKey) {
+        return this.snapshot.operations[scopeKey];
+    }
+    getOperationById(operationId) {
+        return Object.values(this.snapshot.operations).find((operation) => operation.operationId === operationId);
+    }
+    getReceipt(key) {
+        return this.snapshot.receipts[key];
+    }
+    getSession(sessionId) {
+        return this.snapshot.sessions[sessionId];
+    }
+    listSessions() {
+        return Object.values(this.snapshot.sessions);
+    }
+    getTerminal(terminalId) {
+        return this.snapshot.terminals[terminalId];
+    }
+    listTerminals(workspaceId) {
+        return Object.values(this.snapshot.terminals).filter((item) => !workspaceId || item.workspaceId === workspaceId);
+    }
+    getCheckpoint(checkpointId) {
+        return this.snapshot.checkpoints[checkpointId];
+    }
+    fileCheckpointId() {
+        return this.snapshot.fileCheckpointId;
+    }
+    consistentCheckpointId() {
+        return this.snapshot.consistentCheckpointId;
+    }
+    async setFileCheckpointId(checkpointId) {
+        this.snapshot.fileCheckpointId = checkpointId;
+        await this.flush();
+    }
+    async setConsistentCheckpointId(checkpointId) {
+        this.snapshot.consistentCheckpointId = checkpointId;
+        await this.flush();
+    }
+    listManagedWrites(workspaceId) {
+        return Object.values(this.snapshot.managedWrites).filter((item) => !workspaceId || item.workspaceId === workspaceId);
+    }
+    getManagedWrite(writeId) {
+        return this.snapshot.managedWrites[writeId];
+    }
+    async putManagedWrite(record) {
+        this.snapshot.managedWrites[record.writeId] = record;
+        await this.flush();
+    }
+    fileRevisions(workspaceId) {
+        return { ...(workspaceId ? this.snapshot.workspaceFileRevisions[workspaceId] ?? {} : this.snapshot.fileRevisions) };
+    }
+    fileRevision(path, workspaceId) {
+        return this.fileRevisions(workspaceId)[path]?.revision ?? 0;
+    }
+    destroyed() {
+        return this.snapshot.destroyed;
+    }
+    lastSourceSequence() {
+        return this.snapshot.lastSourceSequence;
+    }
+    acceptedLeaseFence() {
+        return this.snapshot.acceptedLeaseFence;
+    }
+    storedRuntimeEpoch() {
+        return this.snapshot.runtimeEpoch;
+    }
+    executionGroup() {
+        return { ...this.snapshot.executionGroup };
+    }
+    getApproval(sessionId, approvalId) {
+        return this.snapshot.approvals[approvalKey(sessionId, approvalId)];
+    }
+    listApprovals() {
+        return Object.values(this.snapshot.approvals);
+    }
+    async putApproval(approval) {
+        this.snapshot.approvals[approvalKey(approval.sessionId, approval.approvalId)] = approval;
+        await this.flush();
+    }
+    async noteExecutionGroup(group) {
+        this.snapshot.executionGroup = {
+            ...this.snapshot.executionGroup,
+            pid: group.pid,
+            startedAt: group.startedAt,
+        };
+        await this.flush();
+    }
+    async writeExecutionEpoch(input) {
+        this.snapshot.runtimeEpoch = input.runtimeEpoch;
+        this.snapshot.executionGroup = {
+            pid: input.pid,
+            startedAt: input.startedAt,
+            previousPid: input.previousPid,
+            stopConfirmed: input.stopConfirmed,
+            replaced: true,
+        };
+        for (const [key, approval] of Object.entries(this.snapshot.approvals)) {
+            if (approval.status === 'pending') {
+                this.snapshot.approvals[key] = { ...approval, status: 'expired' };
+            }
+        }
+        await this.flush();
+    }
+    async setExecutionStopConfirmed(stopConfirmed) {
+        this.snapshot.executionGroup = { ...this.snapshot.executionGroup, stopConfirmed };
+        await this.flush();
+    }
+    listEvents(afterSequence = 0) {
+        return Object.values(this.snapshot.events)
+            .filter((event) => event.source.sourceSequence > afterSequence)
+            .sort((left, right) => left.source.sourceSequence - right.source.sourceSequence);
+    }
+    async putOperation(scopeKey, operation) {
+        this.snapshot.operations[scopeKey] = operationRecordSchema.parse(operation);
+        await this.flush();
+        return this.snapshot.operations[scopeKey];
+    }
+    async putSession(binding) {
+        this.snapshot.sessions[binding.sessionId] = binding;
+        await this.flush();
+    }
+    async putTerminal(record) {
+        const parsed = terminalRecordSchema.parse(record);
+        this.snapshot.terminals[parsed.terminalId] = parsed;
+        await this.flush();
+        return parsed;
+    }
+    async putCheckpoint(checkpoint) {
+        const parsed = checkpointRecordSchema.parse(checkpoint);
+        this.snapshot.checkpoints[parsed.checkpointId] = parsed;
+        await this.flush();
+        return parsed;
+    }
+    async putFileRevision(path, record, workspaceId) {
+        if (workspaceId) {
+            (this.snapshot.workspaceFileRevisions[workspaceId] ??= {})[path] = record;
+        }
+        else {
+            this.snapshot.fileRevisions[path] = record;
+        }
+        await this.flush();
+    }
+    async replaceFileRevisions(records, workspaceId) {
+        if (workspaceId)
+            this.snapshot.workspaceFileRevisions[workspaceId] = { ...records };
+        else
+            this.snapshot.fileRevisions = { ...records };
+        await this.flush();
+    }
+    async markDestroyed() {
+        this.snapshot.destroyed = true;
+        await this.flush();
+    }
+    async replaceSessions(sessions) {
+        this.snapshot.sessions = Object.fromEntries(sessions.map((item) => [item.sessionId, item]));
+        await this.flush();
+    }
+    async setAcceptedLeaseFence(value) {
+        this.snapshot.acceptedLeaseFence = Math.max(this.snapshot.acceptedLeaseFence, value);
+        await this.flush();
+    }
+    async putReceipt(receipt, sourceSequence) {
+        this.snapshot.receipts[sourceEventKey(receipt.source)] =
+            sourceEventReceiptSchema.parse(receipt);
+        this.snapshot.lastSourceSequence = Math.max(this.snapshot.lastSourceSequence, sourceSequence);
+        await this.flush();
+    }
+    async appendEvent(event) {
+        const parsed = pendingSourceEventSchema.parse(event);
+        this.snapshot.events[sourceEventKey(parsed.source)] = parsed;
+        this.snapshot.lastSourceSequence = Math.max(this.snapshot.lastSourceSequence, parsed.source.sourceSequence);
+        await this.flush();
+        return parsed;
+    }
+    async flush() {
+        const snapshot = `${JSON.stringify(this.snapshot)}\n`;
+        const write = this.writes.then(async () => {
+            await mkdir(dirname(this.filePath), { recursive: true, mode: 0o700 });
+            const tempPath = `${this.filePath}.${process.pid}.tmp`;
+            await writeFile(tempPath, snapshot, { mode: 0o600 });
+            await rename(tempPath, this.filePath);
+        });
+        this.writes = write.catch(() => undefined);
+        await write;
+    }
+}
+function sanitizeManagedWrites(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    const records = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const record = item;
+        if (record.writeId !== key || typeof record.workspaceId !== 'string' || typeof record.startedAt !== 'string') {
+            continue;
+        }
+        if (record.source !== 'manual' && record.source !== 'agent' && record.source !== 'background')
+            continue;
+        records[key] = {
+            writeId: key,
+            workspaceId: record.workspaceId,
+            source: record.source,
+            startedAt: record.startedAt,
+            pid: integerOrUndefined(record.pid),
+            stoppedAt: typeof record.stoppedAt === 'string' ? record.stoppedAt : undefined,
+        };
+    }
+    return records;
+}
+function approvalKey(sessionId, approvalId) {
+    return `${sessionId}:${approvalId}`;
+}
+function integerOrUndefined(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+function isStoredApproval(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (typeof record.approvalId === 'string' &&
+        typeof record.sessionId === 'string' &&
+        typeof record.runtimeEpoch === 'number' &&
+        typeof record.nativeRequestId === 'string' &&
+        (record.status === 'pending' ||
+            record.status === 'approved' ||
+            record.status === 'rejected' ||
+            record.status === 'expired'));
+}
+function highestFence(operations) {
+    return Object.values(operations).reduce((highest, operation) => Math.max(highest, operation.leaseFence ?? 0), 0);
+}

package/dist/workspace-runtime/processes/managed-writes.js

@@ -0,0 +1,69 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+export const MANAGED_WRITE_SOURCES = ['manual', 'agent', 'background'];
+const BACKGROUND_WRITER = `
+const fs = require('node:fs');
+const file = process.argv[1];
+if (!file) process.exit(1);
+fs.appendFileSync(file, 'background\\n');
+const timer = setInterval(() => {
+  try { fs.appendFileSync(file, 'x'); }
+  catch { clearInterval(timer); process.exit(0); }
+}, 200);
+`;
+/** `true` alive, `false` confirmed exited, `undefined` when the probe cannot tell. */
+export function probeProcess(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ESRCH')
+            return false;
+        return undefined;
+    }
+}
+export function spawnBackgroundWriter(absolutePath) {
+    const child = spawn(process.execPath, ['-e', BACKGROUND_WRITER, absolutePath], {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    if (!child.pid)
+        throw new Error('background_write_failed');
+    return child.pid;
+}
+export async function stopBackgroundWriter(pid) {
+    signal(pid, 'SIGTERM');
+    if (await waitUntilStopped(pid, 2_000))
+        return true;
+    signal(pid, 'SIGKILL');
+    return waitUntilStopped(pid, 2_000);
+}
+function signal(pid, name) {
+    try {
+        process.kill(-pid, name);
+    }
+    catch (error) {
+        if (error.code !== 'ESRCH')
+            return;
+        try {
+            process.kill(pid, name);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+async function waitUntilStopped(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const alive = probeProcess(pid);
+        if (alive === false)
+            return true;
+        if (alive === undefined)
+            return false;
+        await delay(50);
+    }
+    return probeProcess(pid) === false;
+}

package/dist/workspace-runtime/serve.js

@@ -0,0 +1,111 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { INCOMPATIBLE_EXIT_CODE, negotiateProtocol, } from '@playcraft/common/cloud-workspace/runtime';
+import { RuntimeJournal } from './persistence/journal.js';
+import { createCodexAppServerAdapter } from './codex/app-server.js';
+import { createLoopbackNativeAdapter } from './codex/loopback.js';
+import { handleRuntimeRequest } from './server/http.js';
+import { handleExecutionGroupCrash } from './server/execution-group.js';
+import { RuntimeProcessLock } from './server/lock.js';
+import { probeGitBinary } from './workspaces/git.js';
+export async function startWorkspaceRuntime(config, options = {}) {
+    process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
+    const negotiated = negotiateProtocol(config);
+    if (!negotiated.ok) {
+        const error = Object.assign(new Error('protocol_incompatible'), {
+            code: 'protocol_incompatible',
+            exitCode: INCOMPATIBLE_EXIT_CODE,
+        });
+        throw error;
+    }
+    const lock = new RuntimeProcessLock(config.stateDir);
+    lock.acquire();
+    try {
+        const journal = new RuntimeJournal(config.stateDir);
+        await journal.load();
+        await mkdir(config.workspaceRoot, { recursive: true, mode: 0o700 });
+        const native = options.nativeAdapter ?? defaultNativeAdapter(config);
+        const state = {
+            config: { ...config, protocolMinor: negotiated.protocolMinor },
+            journal,
+            acceptedLeaseFence: journal.acceptedLeaseFence(),
+            gitAvailable: await probeGitBinary(),
+            native,
+            runtimeEpoch: Math.max(config.runtimeEpoch, journal.storedRuntimeEpoch() ?? 0),
+            executionQueue: Promise.resolve(),
+            instanceToken: randomUUID(),
+        };
+        native?.onUnexpectedExit?.((event) => {
+            void handleExecutionGroupCrash(state, event.pid);
+        });
+        try {
+            await native?.start?.();
+            const group = native?.executionProcess?.();
+            if (group)
+                await journal.noteExecutionGroup(group);
+        }
+        catch {
+            /* conversation stays adapter_not_started until Codex handshake succeeds */
+        }
+        const server = createServer((request, response) => {
+            void handleRuntimeRequest(state, request, response);
+        });
+        const port = await listenOn(server, config.listen.host, config.listen.port);
+        return {
+            config: state.config,
+            state,
+            url: `http://${formatHost(config.listen.host)}:${port}`,
+            async close() {
+                await closeServer(server);
+                try {
+                    await native?.close?.();
+                }
+                catch {
+                    /* adapter shutdown is best-effort */
+                }
+                lock.release();
+            },
+        };
+    }
+    catch (error) {
+        lock.release();
+        throw error;
+    }
+}
+function listenOn(server, host, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => reject(error);
+        server.once('error', onError);
+        server.listen(port, host, () => {
+            server.removeListener('error', onError);
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new Error('listen_failed'));
+                return;
+            }
+            resolve(address.port);
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
+function formatHost(host) {
+    return host.includes(':') ? `[${host}]` : host;
+}
+function defaultNativeAdapter(config) {
+    if (process.env.PLAYCRAFT_NATIVE_ADAPTER === 'loopback')
+        return createLoopbackNativeAdapter();
+    if (process.env.PLAYCRAFT_NATIVE_ADAPTER === 'codex') {
+        return createCodexAppServerAdapter({ config });
+    }
+    return undefined;
+}

package/dist/workspace-runtime/server/auth.js

@@ -0,0 +1,21 @@
+import { timingSafeEqual } from 'node:crypto';
+export function extractControlToken(headers) {
+    const authorization = headerValue(headers.authorization);
+    if (authorization?.startsWith('Bearer ')) {
+        return authorization.slice('Bearer '.length).trim() || null;
+    }
+    const dedicated = headerValue(headers['x-playcraft-control-token']);
+    return dedicated?.trim() || null;
+}
+export function controlTokenMatches(expected, actual) {
+    if (!actual)
+        return false;
+    const left = Buffer.from(expected);
+    const right = Buffer.from(actual);
+    if (left.length !== right.length)
+        return false;
+    return timingSafeEqual(left, right);
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}