@vantran-se/openchamber-web 1.24.4 → 2.0.1

package/server/lib/spaces/space-server.test.js

@@ -0,0 +1,335 @@
+import { describe, expect, it } from 'vitest';
+
+import { SpaceError } from './errors.js';
+import { createSpaceServerChannel, createSpaceToken } from './space-server.js';
+
+const ID = 'a1b2c3d4e5f6';
+const http = (status, body, headers = []) => `HTTP/1.1 ${status} OK\r\n${['Content-Type: application/json', ...headers].join('\r\n')}\r\n\r\n${body}`;
+const ok = (stdout = '') => ({ code: 0, stdout, stderr: '' });
+
+/**
+ * A channel on a recording `exec`. `answers` are returned in turn, the last one repeats.
+ * Nothing sleeps: the clock moves by the pause in `wait`, and by `secondsPerAttempt` for every exec.
+ */
+const channelWith = (...answers) => channelTaking(0, ...answers);
+
+const channelTaking = (secondsPerAttempt, ...answers) => {
+  const calls = [];
+  let waits = 0;
+  let clock = 1_000_000;
+  const exec = async (spaceId, argv, options) => {
+    calls.push({ spaceId, argv, options });
+    clock += secondsPerAttempt * 1000;
+    const answer = answers.length > 1 ? answers.shift() : answers[0];
+    if (answer instanceof Error) throw answer;
+    return answer;
+  };
+  const wait = async (milliseconds) => { waits += 1; clock += milliseconds; };
+  return { channel: createSpaceServerChannel({ exec, wait, now: () => clock }), calls, waits: () => waits };
+};
+
+describe('createSpaceToken', () => {
+  it('is 32 random bytes in a form that needs no quoting', () => {
+    expect(createSpaceToken()).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(createSpaceToken()).not.toBe(createSpaceToken());
+  });
+});
+
+describe('space server channel: token', () => {
+  it('sends the token on stdin to a fixed script, through a temporary name, readable by the space user only', async () => {
+    const { channel, calls } = channelWith(ok());
+    await channel.writeToken(ID, 'the-token');
+
+    expect(calls).toEqual([{
+      spaceId: ID,
+      argv: ['/bin/sh', '-c', 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; umask 077; mkdir -p /home/space/.openchamber-space && chmod 700 /home/space/.openchamber-space && cat > /home/space/.openchamber-space/token.new && mv /home/space/.openchamber-space/token.new /home/space/.openchamber-space/token'],
+      options: { stdin: 'the-token' },
+    }]);
+  });
+
+  it('reads the token back from the space, with a short time limit', async () => {
+    const token = createSpaceToken();
+    const { channel, calls } = channelWith(ok(`${token}\n`));
+
+    expect(await channel.readToken(ID)).toBe(token);
+    expect(calls[0].argv).toEqual(['/bin/cat', '/home/space/.openchamber-space/token']);
+    expect(calls[0].options.timeoutMs).toBe(10_000);
+  });
+
+  // The agent owns the token file.
+  it.each([
+    ['an empty file', ok('\n'), /is empty/],
+    ['a file that holds something else', ok('not a token: $(reboot)\n'), /does not hold a token/],
+    ['a token that is too short', ok('abc\n'), /does not hold a token/],
+    ['a token that is too long', ok(`${'a'.repeat(129)}\n`), /does not hold a token/],
+    ['a huge file', Object.assign(new Error('too much'), { code: 'command_output_too_large' }), /far too large/],
+    ['a FIFO that never ends', Object.assign(new Error('too slow'), { code: 'command_timeout' }), /in time/],
+  ])('rejects %s with a code of its own', async (title, answer, message) => {
+    const { channel } = channelWith(answer);
+
+    const error = await channel.readToken(ID).catch((caught) => caught);
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error.code).toBe('space_token_unreadable');
+    expect(error.message).toMatch(message);
+  });
+
+  it('says when the token file cannot be read at all', async () => {
+    const { channel } = channelWith({ code: 1, stdout: '', stderr: 'cat: /home/space/.openchamber-space/token: No such file or directory\n' });
+    await expect(channel.readToken(ID)).rejects.toMatchObject({ code: 'space_setup_failed', message: expect.stringContaining('No such file') });
+  });
+
+  it('says what failed inside the space', async () => {
+    const { channel } = channelWith({ code: 1, stdout: '', stderr: 'cat: write error: No space left on device\n' });
+    await expect(channel.writeToken(ID, 'x')).rejects.toMatchObject({ code: 'space_setup_failed', message: expect.stringContaining('No space left on device') });
+  });
+});
+
+describe('space server channel: plugin link', () => {
+  it('links only the plugin package, above every project of the space', async () => {
+    const { channel, calls } = channelWith(ok());
+    await channel.linkPlugin(ID);
+
+    expect(calls[0].argv).toEqual([
+      '/bin/sh', '-c', 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; mkdir -p "$1/node_modules/@opencode" && ln -sfn "$2" "$1/node_modules/@opencode/plugin"',
+      'sh', `/spaces/${ID}`, '/opt/openchamber-tools/node_modules/@opencode/plugin',
+    ]);
+  });
+});
+
+describe('space server channel: request', () => {
+  it('puts the whole request into a curl config on stdin, so nothing of it is in an argument', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '{"authenticated":true}', ['Set-Cookie: a=1; Path=/', 'Set-Cookie: b=2'])));
+    const body = JSON.stringify({ password: 'quote " backslash \\ newline \n tab \t end' });
+    const answer = await channel.request(ID, { method: 'POST', path: '/auth/session', headers: { 'Content-Type': 'application/json', Cookie: 'oc=secret' }, body });
+
+    expect(answer).toEqual({
+      status: 200,
+      headers: { 'content-type': ['application/json'], 'set-cookie': ['a=1; Path=/', 'b=2'] },
+      body: '{"authenticated":true}',
+    });
+    expect(calls[0].argv).toEqual(['/usr/bin/curl', '--disable', '--noproxy', '*', '--silent', '--show-error', '--include', '--max-time', '20', '--config', '-']);
+    expect(calls[0].options.stdin).toBe([
+      'url = "http://127.0.0.1:27600/auth/session"',
+      'request = "POST"',
+      'header = "Expect:"',
+      'header = "Content-Type: application/json"',
+      'header = "Cookie: oc=secret"',
+      'data-raw = "{\\"password\\":\\"quote \\\\\\" backslash \\\\\\\\ newline \\\\n tab \\\\t end\\"}"',
+      '',
+    ].join('\n'));
+    expect(calls[0].options.timeoutMs).toBeGreaterThan(20_000);
+  });
+
+  it('puts --disable first and --noproxy on every request, whatever the space environment says', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '')));
+    await channel.request(ID, { path: '/health' });
+    await channel.waitUntilReady(ID).catch(() => {});
+
+    // curl honours --disable only as its first argument. Without --noproxy the space's own
+    // proxy variables send this request to the corridor: measured, the answer was
+    // `curl: (1) Received HTTP/0.9 when not allowed`.
+    for (const call of calls) expect(call.argv.slice(0, 4)).toEqual(['/usr/bin/curl', '--disable', '--noproxy', '*']);
+  });
+
+  it('sends a body that starts with @ as text, not as the content of a file', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '')));
+    await channel.request(ID, { method: 'POST', path: '/x', body: '@/home/space/.openchamber-space/token' });
+
+    const lines = calls[0].options.stdin.split('\n');
+    expect(lines).toContain('data-raw = "@/home/space/.openchamber-space/token"');
+    expect(lines.some((line) => line.startsWith('data-binary') || line.startsWith('data ='))).toBe(false);
+  });
+
+  it('resolves any status, and keeps a body that holds a blank line', async () => {
+    const { channel } = channelWith(ok(http(401, 'first\r\n\r\nsecond')));
+    expect(await channel.request(ID, { path: '/api/session' })).toMatchObject({ status: 401, body: 'first\r\n\r\nsecond' });
+  });
+
+  it('keeps a line break inside a header value from becoming a second config line', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '')));
+    await channel.request(ID, { path: '/health', headers: { 'X-Test': 'a\nurl = "http://elsewhere"' } });
+    expect(calls[0].options.stdin.split('\n')).toHaveLength(5);
+  });
+
+  it('rejects a NUL character, which a curl config cannot carry', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '')));
+    await expect(channel.request(ID, { path: '/health', body: 'a\0b' })).rejects.toMatchObject({ code: 'invalid_request' });
+    expect(calls).toEqual([]);
+  });
+
+  it('says when nothing answers, with the curl exit code', async () => {
+    const { channel } = channelWith({ code: 7, stdout: '', stderr: 'curl: (7) Failed to connect to 127.0.0.1 port 27600\n' });
+    await expect(channel.request(ID, { path: '/health' })).rejects.toMatchObject({ code: 'space_server_unreachable', details: { curlExitCode: 7 } });
+  });
+
+  it('rejects an answer that is not HTTP', async () => {
+    const { channel } = channelWith(ok('garbage'));
+    await expect(channel.request(ID, { path: '/health' })).rejects.toMatchObject({ code: 'space_server_answer_unreadable' });
+  });
+
+  it('takes header names such as __proto__ and constructor as plain names', async () => {
+    const { channel } = channelWith(ok(http(200, '{}', ['__proto__: polluted', 'constructor: x', 'toString: y', 'no colon here', ': empty name'])));
+    const answer = await channel.request(ID, { path: '/health' });
+
+    expect(answer.headers.__proto__).toEqual(['polluted']);
+    expect(answer.headers.constructor).toEqual(['x']);
+    expect(answer.headers.tostring).toEqual(['y']);
+    expect(Object.keys(answer.headers)).toEqual(['content-type', '__proto__', 'constructor', 'tostring']);
+    expect({}.polluted).toBeUndefined();
+  });
+
+  it('parses tens of thousands of repeated header lines in linear time, and refuses them by the cap', async () => {
+    // The old code copied an array per line and blocked the event loop for seconds on an answer like this.
+    // Now the cap on the header block refuses it before any line is looked at.
+    const lines = Array.from({ length: 50_000 }, () => 'x: 1');
+    const { channel } = channelWith(ok(http(200, '{}', lines)));
+
+    const started = performance.now();
+    const error = await channel.request(ID, { path: '/health' }).catch((caught) => caught);
+    expect(performance.now() - started).toBeLessThan(1_000);
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error.code).toBe('space_server_answer_unreadable');
+  });
+
+  it('accepts 200 header lines, also of one repeated name, and refuses 201', async () => {
+    const accepted = channelWith(ok(http(200, '{}', Array.from({ length: 199 }, (unused, index) => `Set-Cookie: c${index}=1`))));
+    const answer = await accepted.channel.request(ID, { path: '/health' });
+    expect(answer.headers['set-cookie']).toHaveLength(199);
+    expect(answer.headers['set-cookie'][198]).toBe('c198=1');
+
+    const refused = channelWith(ok(http(200, '{}', Array.from({ length: 200 }, () => 'x: 1'))));
+    await expect(refused.channel.request(ID, { path: '/health' })).rejects.toMatchObject({ code: 'space_server_answer_unreadable', message: expect.stringContaining('200 header lines') });
+  });
+
+  it('refuses a header block of more than 64 KiB before it looks at its lines', async () => {
+    const { channel } = channelWith(ok(http(200, '{}', [`x: ${'a'.repeat(70_000)}`])));
+    await expect(channel.request(ID, { path: '/health' })).rejects.toMatchObject({ code: 'space_server_answer_unreadable', message: expect.stringContaining('65536 bytes of headers') });
+  });
+
+  it('maps a request whose exec timed out or was killed to "unreachable", never to an interrupted Docker step', async () => {
+    for (const code of ['command_timeout', 'command_killed']) {
+      const { channel } = channelWith(Object.assign(new Error('docker exec did not finish'), { code }));
+      const error = await channel.request(ID, { path: '/health' }).catch((caught) => caught);
+      expect(error).toBeInstanceOf(SpaceError);
+      expect(error.code).toBe('space_server_unreachable');
+    }
+  });
+
+  it('maps more output than the host accepts to an unreadable answer, never to an interrupted Docker step', async () => {
+    const tooLarge = Object.assign(new Error('docker exec printed more than 4194304 bytes and was stopped'), { code: 'command_output_too_large' });
+    const { channel } = channelWith(tooLarge);
+
+    const error = await channel.request(ID, { path: '/health' }).catch((caught) => caught);
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error.code).toBe('space_server_answer_unreadable');
+  });
+
+  it('cuts the text from inside the space in an error message to 2,000 characters', async () => {
+    const { channel } = channelWith({ code: 22, stdout: '', stderr: 'x'.repeat(50_000) });
+    const error = await channel.request(ID, { path: '/health' }).catch((caught) => caught);
+    expect(error.message.length).toBeLessThan(2_100);
+
+    const failing = channelWith({ code: 1, stdout: '', stderr: 'y'.repeat(50_000) });
+    const setupError = await failing.channel.writeToken(ID, 'x').catch((caught) => caught);
+    expect(setupError.message.length).toBeLessThan(2_100);
+  });
+});
+
+describe('space server channel: waitUntilReady', () => {
+  const refused = { code: 7, stdout: '', stderr: 'curl: (7) Failed to connect' };
+
+  it('waits through "nothing listens yet" and "OpenCode not ready", then resolves', async () => {
+    const { channel, calls, waits } = channelWith(refused, refused, ok(http(200, '{"isOpenCodeReady":false}')), ok(http(200, '{"isOpenCodeReady":true}')));
+    await channel.waitUntilReady(ID);
+
+    expect(calls).toHaveLength(4);
+    expect(waits()).toBe(3);
+  });
+
+  it('gives up at the deadline and says what it saw last', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '{"isOpenCodeReady":false}')));
+
+    const error = await channel.waitUntilReady(ID).catch((caught) => caught);
+    expect(error.code).toBe('space_server_not_ready');
+    expect(error.message).toMatch(/within 120 seconds \(the answer does not report OpenCode ready\)/);
+    expect(calls).toHaveLength(240);
+  });
+
+  it('asks /health with a short time limit, so a listener that never answers costs little', async () => {
+    const { channel, calls } = channelWith(ok(http(200, '{"isOpenCodeReady":true}')));
+    await channel.waitUntilReady(ID);
+
+    expect(calls[0].argv).toEqual(['/usr/bin/curl', '--disable', '--noproxy', '*', '--silent', '--show-error', '--include', '--max-time', '3', '--config', '-']);
+    expect(calls[0].options.timeoutMs).toBe(13_000);
+  });
+
+  it('ends at the wall-clock deadline when something on the port accepts and never answers', async () => {
+    // Every attempt runs into the time limit of curl: three seconds each, exit code 28.
+    const { channel, calls } = channelTaking(3, { code: 28, stdout: '', stderr: 'curl: (28) Operation timed out' });
+
+    const error = await channel.waitUntilReady(ID).catch((caught) => caught);
+    expect(error.code).toBe('space_server_not_ready');
+    // 120 seconds of deadline, in steps of 3.5 seconds. The old count of 240 attempts would have been 14 minutes here.
+    expect(calls.length).toBeLessThanOrEqual(35);
+    expect(error.message).toMatch(/within 12\d seconds/);
+  });
+
+  it('still ends when the clock of the caller stands still', async () => {
+    const calls = [];
+    const exec = async (spaceId, argv) => { calls.push(argv); return { code: 7, stdout: '', stderr: '' }; };
+    const channel = createSpaceServerChannel({ exec, wait: async () => {}, now: () => 5 });
+
+    await expect(channel.waitUntilReady(ID)).rejects.toMatchObject({ code: 'space_server_not_ready' });
+    expect(calls).toHaveLength(1_000);
+  });
+
+  it.each([
+    ['a body of null', ok(http(200, 'null'))],
+    ['a body that is a number', ok(http(200, '5'))],
+    ['a body that is not JSON', ok(http(200, '<html>'))],
+    ['an empty body', ok(http(200, ''))],
+    ['a ready answer with another status', ok(http(503, '{"isOpenCodeReady":true}'))],
+    ['a truthy value that is not true', ok(http(200, '{"isOpenCodeReady":"yes"}'))],
+    // Ready, but far larger than a health answer. The host does not spend time parsing it.
+    ['a ready body of more than 64 KiB', ok(http(200, `{"isOpenCodeReady":true,"padding":"${'x'.repeat(70 * 1024)}"}`))],
+    // Measured with curl 7.88.1 against a listener that answers `hello`: exit code 1, the code that a failed `docker exec` uses too.
+    ['a listener that does not speak HTTP', { code: 1, stdout: '', stderr: 'curl: (1) Received HTTP/0.9 when not allowed\n' }],
+    ['a request whose exec timed out', Object.assign(new Error('docker exec did not finish'), { code: 'command_timeout' })],
+    ['more header lines than the host parses', ok(http(200, '{"isOpenCodeReady":true}', Array.from({ length: 5_000 }, () => 'x: 1')))],
+    ['a header named __proto__', ok(http(200, '{}', ['__proto__: x']))],
+    ['curl exit code 56, a reset connection', { code: 56, stdout: '', stderr: 'curl: (56) Recv failure' }],
+    ['curl exit code 8, a weird server reply', { code: 8, stdout: '', stderr: 'curl: (8) Weird server reply' }],
+    ['more output than the host accepts', Object.assign(new Error('too much'), { code: 'command_output_too_large' })],
+  ])('counts %s from inside as "not ready yet", and throws nothing but a SpaceError at the end', async (title, hostile) => {
+    const { channel, calls } = channelWith(hostile);
+
+    const error = await channel.waitUntilReady(ID).catch((caught) => caught);
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error.code).toBe('space_server_not_ready');
+    expect(calls.length).toBeGreaterThan(1);
+  });
+
+  it('becomes ready after hostile answers, when the real server takes the port', async () => {
+    const { channel } = channelWith(ok(http(200, 'null')), { code: 1, stdout: '', stderr: 'curl: (1) Received HTTP/0.9 when not allowed' }, { code: 52, stdout: '', stderr: '' }, ok(http(200, '{"isOpenCodeReady":true}')));
+    await channel.waitUntilReady(ID);
+  });
+
+  it('stops at once when the container is gone, instead of waiting for the whole time', async () => {
+    const { channel, calls } = channelWith({ code: 1, stdout: '', stderr: 'Error response from daemon: container abc is not running' });
+
+    await expect(channel.waitUntilReady(ID)).rejects.toMatchObject({ code: 'space_server_unreachable', message: expect.stringContaining('is not running') });
+    expect(calls).toHaveLength(1);
+  });
+
+  it.each([1, 125, 126, 127])('stops at once for exit code %i without a curl message, because then docker exec itself failed', async (code) => {
+    const { channel, calls } = channelWith({ code, stdout: '', stderr: 'OCI runtime exec failed: exec failed: unable to start container process' });
+    await expect(channel.waitUntilReady(ID)).rejects.toMatchObject({ code: 'space_server_unreachable', details: { execFailed: true } });
+    expect(calls).toHaveLength(1);
+  });
+
+  it('lets a failure of the place through', async () => {
+    const failure = Object.assign(new Error('spawn docker ENOENT'), { code: 'command_spawn_failed' });
+    const { channel } = channelWith(failure);
+    await expect(channel.waitUntilReady(ID)).rejects.toBe(failure);
+  });
+});

package/server/lib/spaces/tools-filler.js

@@ -0,0 +1,82 @@
+// The program of the one-shot container that fills a tools volume, and the input it reads.
+//
+// The program is fixed. Only its input varies: one JSON header line with the key and the
+// name and byte length of each file, then the bytes of the files, one after another.
+// The input travels over stdin, because there is no tar library here and none may be added.
+
+import { SpaceError } from './errors.js';
+import { requireToolsKey } from './labels.js';
+
+const FILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const PACKAGE_JSON_NAME = 'package.json';
+
+// Joined with spaces into one line. Docker Desktop on Windows was verified with many
+// special characters in an argument, but never with a newline. So every line here is a
+// whole statement, and there are no `//` comments inside.
+//
+// Arguments: the tools directory and a staging directory under /tmp.
+// `package.json` goes to the tools directory, every other file to the staging directory.
+// The marker vouches for everything npm wrote, and npm flushes nothing. So `sync` runs first, and
+// only then is the marker written: through a temporary name, with the file and its directory
+// flushed before and after the rename. A marker on disk without the content it vouches for would
+// be a broken volume that nothing repairs. A Docker machine that crashes right after a fill can
+// still lose the marker or leave it empty, and the place then removes the volume and fills again.
+// @opencode/cli is the one package whose install script runs: it links the OpenCode binary
+// for this CPU and C library to the path its launcher starts. Without it `opencode` only prints an error.
+const PROGRAM_LINES = [
+  "const fs = require('node:fs');",
+  "const path = require('node:path');",
+  "const { spawnSync } = require('node:child_process');",
+  'const [toolsDirectory, stagingDirectory] = process.argv.slice(1);',
+  "const fail = (message) => { console.error('fill failed: ' + message); process.exit(1); };",
+  "const run = (file, args, cwd) => { const result = spawnSync(file, args, { cwd, stdio: ['ignore', 'inherit', 'inherit'] }); if (result.status !== 0) fail(file + ' ' + args[0] + ' ended with ' + (result.status === null ? result.signal || result.error : result.status)); };",
+  'const chunks = [];',
+  "process.stdin.on('data', (chunk) => chunks.push(chunk));",
+  "process.stdin.on('end', () => {",
+  '  const input = Buffer.concat(chunks);',
+  '  const headerEnd = input.indexOf(10);',
+  "  if (headerEnd < 0) fail('the input has no header line');",
+  '  let header = null;',
+  "  try { header = JSON.parse(input.subarray(0, headerEnd).toString('utf8')); } catch (error) { fail('the header is not JSON'); }",
+  "  if (!header || !/^[0-9a-f]{16}$/.test(header.key) || !Array.isArray(header.files)) fail('the header needs a key and a file list');",
+  '  fs.mkdirSync(stagingDirectory, { recursive: true });',
+  '  let offset = headerEnd + 1;',
+  '  for (const file of header.files) {',
+  "    if (!file || typeof file.name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(file.name)) fail('a file name must be a plain name');",
+  "    if (!Number.isSafeInteger(file.bytes) || file.bytes < 0 || offset + file.bytes > input.length) fail('the length of ' + file.name + ' does not fit the input');",
+  "    fs.writeFileSync(path.join(file.name === 'package.json' ? toolsDirectory : stagingDirectory, file.name), input.subarray(offset, offset + file.bytes));",
+  '    offset += file.bytes;',
+  '  }',
+  "  if (offset !== input.length) fail('the input is longer than the header says');",
+  "  run('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--cache', path.join(stagingDirectory, 'npm-cache')], toolsDirectory);",
+  "  run(process.execPath, ['postinstall.mjs'], path.join(toolsDirectory, 'node_modules', '@opencode/cli'));",
+  "  for (const needed of ['node_modules/.bin/openchamber', 'node_modules/.bin/opencode', 'node_modules/@opencode/plugin/package.json']) {",
+  "    if (!fs.existsSync(path.join(toolsDirectory, needed))) fail(needed + ' is missing after the install');",
+  '  }',
+  "  run('/bin/sync', [], toolsDirectory);",
+  "  const flush = (target, flags) => { const descriptor = fs.openSync(target, flags); try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); } };",
+  "  const marker = path.join(toolsDirectory, '.filled');",
+  "  fs.writeFileSync(marker + '.new', header.key);",
+  "  flush(marker + '.new', 'r+');",
+  "  flush(toolsDirectory, 'r');",
+  "  fs.renameSync(marker + '.new', marker);",
+  "  flush(toolsDirectory, 'r');",
+  '});',
+];
+
+export const FILLER_PROGRAM = PROGRAM_LINES.map((line) => line.trim()).join(' ');
+
+/**
+ * The stdin of the filler for one tools source: the header line, then the bytes.
+ * `files` are the tarballs of a packed source as `{ name, bytes }`, empty for a registry source.
+ */
+export function buildFillInput({ key, packageJson, files = [] }) {
+  const entries = [{ name: PACKAGE_JSON_NAME, bytes: Buffer.from(packageJson, 'utf8') }, ...files];
+  for (const entry of entries) {
+    if (!FILE_NAME_PATTERN.test(entry.name) || !Buffer.isBuffer(entry.bytes)) {
+      throw new SpaceError('invalid_tools_file', 'A tools file needs a plain name without slashes and its bytes as a Buffer');
+    }
+  }
+  const header = { key: requireToolsKey(key), files: entries.map((entry) => ({ name: entry.name, bytes: entry.bytes.length })) };
+  return Buffer.concat([Buffer.from(`${JSON.stringify(header)}\n`, 'utf8'), ...entries.map((entry) => entry.bytes)]);
+}

package/server/lib/spaces/tools-filler.test.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+
+import { TOOLS_MARKER_PATH } from './layout.js';
+import { runCommand } from './run-command.js';
+import { FILLER_PROGRAM, buildFillInput } from './tools-filler.js';
+
+const KEY = '0123456789abcdef';
+
+describe('buildFillInput', () => {
+  it('puts a header line with names and byte lengths before the bytes', () => {
+    const input = buildFillInput({ key: KEY, packageJson: '{"a":"ä"}', files: [{ name: 'web.tgz', bytes: Buffer.from([0, 10, 255]) }] });
+
+    const headerEnd = input.indexOf(10);
+    expect(JSON.parse(input.subarray(0, headerEnd).toString('utf8'))).toEqual({
+      key: KEY,
+      files: [{ name: 'package.json', bytes: 10 }, { name: 'web.tgz', bytes: 3 }],
+    });
+    expect(input.subarray(headerEnd + 1, headerEnd + 11).toString('utf8')).toBe('{"a":"ä"}');
+    expect([...input.subarray(headerEnd + 11)]).toEqual([0, 10, 255]);
+  });
+
+  it.each(['../evil.tgz', 'a/b.tgz', '.hidden', '', 'a\\b', 'x'.repeat(101)])('rejects the file name %j', (name) => {
+    expect(() => buildFillInput({ key: KEY, packageJson: '{}', files: [{ name, bytes: Buffer.alloc(1) }] })).toThrow(expect.objectContaining({ code: 'invalid_tools_file' }));
+  });
+
+  it('rejects bytes that are not a Buffer, and a bad key', () => {
+    expect(() => buildFillInput({ key: KEY, packageJson: '{}', files: [{ name: 'a.tgz', bytes: 'text' }] })).toThrow(expect.objectContaining({ code: 'invalid_tools_file' }));
+    expect(() => buildFillInput({ key: 'nope', packageJson: '{}' })).toThrow(expect.objectContaining({ code: 'invalid_tools_key' }));
+  });
+});
+
+describe('FILLER_PROGRAM', () => {
+  it('is one line, so it is safe as one argument on every host', () => {
+    expect(FILLER_PROGRAM).not.toMatch(/[\r\n]/);
+    expect(() => new Function(FILLER_PROGRAM)).not.toThrow();
+  });
+
+  it('ignores install scripts, keeps the npm cache out of the volume, and writes the marker that the place reads', () => {
+    expect(FILLER_PROGRAM).toContain("'--ignore-scripts', '--no-audit', '--no-fund', '--cache'");
+    expect(FILLER_PROGRAM).toContain(`'${path.posix.basename(TOOLS_MARKER_PATH)}'`);
+  });
+});
+
+// The program runs here as it does in the filler, against temporary directories and a stand-in for npm.
+describe.skipIf(process.platform === 'win32')('FILLER_PROGRAM, run', () => {
+  const FAKE_NPM = `#!/bin/sh
+echo "$@" > npm-args.txt
+[ -f fail-npm ] && exit 3
+mkdir -p node_modules/.bin node_modules/@opencode/plugin node_modules/@opencode/cli
+touch node_modules/.bin/openchamber node_modules/.bin/opencode
+[ -f skip-plugin ] || echo '{}' > node_modules/@opencode/plugin/package.json
+echo "import fs from 'node:fs'; fs.writeFileSync('postinstall-ran', 'yes');" > node_modules/@opencode/cli/postinstall.mjs
+`;
+  let root;
+  let tools;
+  let staging;
+  let originalPath;
+
+  beforeAll(() => {
+    originalPath = process.env.PATH;
+  });
+
+  afterAll(() => {
+    process.env.PATH = originalPath;
+  });
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-filler-test-'));
+    tools = path.join(root, 'tools');
+    staging = path.join(root, 'staging');
+    fs.mkdirSync(tools);
+    fs.mkdirSync(path.join(root, 'bin'));
+    fs.writeFileSync(path.join(root, 'bin', 'npm'), FAKE_NPM, { mode: 0o755 });
+    process.env.PATH = `${path.join(root, 'bin')}${path.delimiter}${originalPath}`;
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  const fill = (stdin) => runCommand(process.execPath, ['-e', FILLER_PROGRAM, tools, staging], { stdin, timeoutMs: 30_000 });
+  const rawInput = (header, ...bodies) => Buffer.concat([Buffer.from(`${JSON.stringify(header)}\n`), ...bodies.map((body) => Buffer.from(body))]);
+
+  it('writes package.json to the tools directory, tarballs to staging, installs, and writes the marker last', async () => {
+    const bytes = Buffer.from([31, 139, 0, 10, 255, 0]);
+    const result = await fill(buildFillInput({ key: KEY, packageJson: '{"name":"x"}', files: [{ name: 'openchamber-web.tgz', bytes }] }));
+
+    expect(result).toMatchObject({ code: 0 });
+    expect(fs.readFileSync(path.join(tools, 'package.json'), 'utf8')).toBe('{"name":"x"}');
+    expect(fs.readFileSync(path.join(staging, 'openchamber-web.tgz'))).toEqual(bytes);
+    expect(fs.existsSync(path.join(tools, 'openchamber-web.tgz'))).toBe(false);
+    expect(fs.readFileSync(path.join(tools, 'npm-args.txt'), 'utf8').trim()).toBe(`install --ignore-scripts --no-audit --no-fund --cache ${path.join(staging, 'npm-cache')}`);
+    // The one install script that runs: the OpenCode launcher needs its binary linked.
+    expect(fs.readFileSync(path.join(tools, 'node_modules', '@opencode/cli', 'postinstall-ran'), 'utf8')).toBe('yes');
+    expect(fs.readFileSync(path.join(tools, '.filled'), 'utf8')).toBe(KEY);
+    // The marker arrives through a rename, so a marker that exists is never half written.
+    expect(fs.existsSync(path.join(tools, '.filled.new'))).toBe(false);
+  });
+
+  it('writes no marker when npm fails', async () => {
+    fs.writeFileSync(path.join(tools, 'fail-npm'), '');
+    const result = await fill(buildFillInput({ key: KEY, packageJson: '{}' }));
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain('fill failed: npm install ended with 3');
+    expect(fs.existsSync(path.join(tools, '.filled'))).toBe(false);
+  });
+
+  it('writes no marker when a needed package is missing after the install', async () => {
+    fs.writeFileSync(path.join(tools, 'skip-plugin'), '');
+    const result = await fill(buildFillInput({ key: KEY, packageJson: '{}' }));
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain('node_modules/@opencode/plugin/package.json is missing');
+    expect(fs.existsSync(path.join(tools, '.filled'))).toBe(false);
+  });
+
+  it.each(['../escaped', 'sub/file', '/etc/passwd', '.filled', ''])('refuses the file name %j and writes nothing', async (name) => {
+    const result = await fill(rawInput({ key: KEY, files: [{ name, bytes: 1 }] }, 'x'));
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain('a file name must be a plain name');
+    expect(fs.readdirSync(tools)).toEqual([]);
+    expect(fs.existsSync(path.join(root, 'escaped'))).toBe(false);
+  });
+
+  it.each([
+    ['a length past the end of the input', { key: KEY, files: [{ name: 'a.tgz', bytes: 50 }] }, 'does not fit the input'],
+    ['a negative length', { key: KEY, files: [{ name: 'a.tgz', bytes: -1 }] }, 'does not fit the input'],
+    ['bytes after the last file', { key: KEY, files: [{ name: 'a.tgz', bytes: 1 }] }, 'longer than the header says'],
+    ['a bad key', { key: '../x', files: [] }, 'needs a key and a file list'],
+  ])('refuses %s', async (title, header, message) => {
+    const result = await fill(rawInput(header, 'xyz'));
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain(message);
+    expect(fs.existsSync(path.join(tools, '.filled'))).toBe(false);
+  });
+
+  it('refuses input without a header', async () => {
+    expect((await fill('no newline here')).stderr).toContain('no header line');
+    expect((await fill('not json\n')).stderr).toContain('not JSON');
+  });
+});

package/server/lib/spaces/tools-pack.js

@@ -0,0 +1,49 @@
+// Packs the local `web` and `sdk` packages of a checkout into tarballs, for the tools
+// volume of a development build. Nothing from the host's node_modules travels: native
+// packages are per platform, so the filler installs every dependency itself, for Linux.
+//
+// Measured with bun 1.4.2:
+// - `bun pm pack` runs the package's `prepack` script. For `web` that builds the built-in extensions.
+// - It rewrites `workspace:*` to the version of the local package.
+// - With `--destination` it writes `<name>-<version>.tgz` there. `--filename` cannot be combined with it.
+// - With `--quiet` the last line of stdout is the path of the tarball. Script output comes before it.
+// `vite build` is not needed: a space runs the server with `--api-only`.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { SpaceError } from './errors.js';
+
+const STEP_TIMEOUT_MS = 5 * 60_000;
+
+const CHECKOUT_ROOT = fileURLToPath(new URL('../../../../../', import.meta.url));
+
+/**
+ * Resolves `{ webTarballPath, sdkTarballPath }` inside `outputDirectory`, for createPackedToolsSource.
+ * Needs the workspace dependencies installed, because the sdk is compiled first.
+ */
+export async function packLocalTools({ runCommand, bunPath = 'bun', checkoutRoot = CHECKOUT_ROOT, outputDirectory }) {
+  const step = async (what, packageName, args) => {
+    const cwd = path.join(checkoutRoot, 'packages', packageName);
+    const result = await runCommand(bunPath, args, { cwd, timeoutMs: STEP_TIMEOUT_MS });
+    if (result.code !== 0) {
+      throw new SpaceError('tools_pack_failed', `Could not ${what} in ${cwd}: ${result.stderr.trim() || `exit code ${result.code}`}. Run "bun install" in the checkout, then try again.`);
+    }
+    return result.stdout;
+  };
+
+  const pack = async (packageName) => {
+    const stdout = await step(`pack the ${packageName} package`, packageName, ['pm', 'pack', '--destination', outputDirectory, '--quiet']);
+    const tarball = stdout.split('\n').map((line) => line.trim()).filter(Boolean).pop() ?? '';
+    if (!tarball.endsWith('.tgz')) {
+      throw new SpaceError('tools_pack_failed', `bun did not say where it wrote the ${packageName} tarball`);
+    }
+    return path.resolve(outputDirectory, tarball);
+  };
+
+  // The sdk ships its compiled `dist`, and nothing in its pack step builds it.
+  await step('build the sdk package', 'sdk', ['run', 'build']);
+  const sdkTarballPath = await pack('sdk');
+  const webTarballPath = await pack('web');
+  return { webTarballPath, sdkTarballPath };
+}