Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { describe, it, expect, vi } from 'vitest';
import { posixPath } from '../lib/testHelper.js';
import { EventEmitter } from 'events';
import { ChildProcess } from '../lib/childProcess.js';
import { mkdtemp, rm, writeFile } from 'fs/promises';
import { tmpdir } from 'os';
import { join } from 'path';
// Wrap the REAL resolveWindowsExecutable/prepareWindowsSafeSpawn in spies
// (not stubs) so every existing test below is unaffected (both are no-op
// pass-throughs on the non-win32 host running this suite) while one test
// can force a specific resolved path, or force isWin32 on the wrap, to
// prove describeImageViaCli actually spawns the result.
vi.mock('../lib/bufferedSpawn.js', async (importOriginal) => {
const actual = await importOriginal();
return {
...actual,
resolveWindowsExecutable: vi.fn(actual.resolveWindowsExecutable),
prepareWindowsSafeSpawn: vi.fn(actual.prepareWindowsSafeSpawn),
};
});
const {
decodeImageDataUrl,
buildCliVisionInvocation,
prepareCliVisionRun,
describeImageViaCli,
describeImagesFromPaths,
} = await import('./visionCli.js');
const { resolveWindowsExecutable, prepareWindowsSafeSpawn } = await import('../lib/bufferedSpawn.js');
// Windows takes killProcessTree's tree-wide `taskkill /T` branch instead, so
// `needsProcessGroup` is false there and these sites spawn attached. The policy
// itself is pinned with an injected platform in credentialBootstrap.test.js;
// these assert only that each site plumbs the decision through.
const EXPECT_GROUP = process.platform !== 'win32';
const PNG_DATA_URL = `data:image/png;base64,${Buffer.from('fake-png').toString('base64')}`;
it('refuses stopped production after vision attachments are staged without spawning', async () => {
const dir = await mkdtemp(join(tmpdir(), 'vision-admission-'));
try {
const path = join(dir, 'frame.png'); await writeFile(path, 'fake-png');
const spawnImpl = vi.fn();
await expect(describeImagesFromPaths({ provider: { id: 'codex', command: 'codex', args: [] }, imagePaths: [path], prompt: 'review',
spawnImpl, beforeExecute: () => { throw new Error('Production stopped'); } })).rejects.toThrow('Production stopped');
expect(spawnImpl).not.toHaveBeenCalled();
} finally { await rm(dir, { recursive: true, force: true }); }
});
describe('decodeImageDataUrl', () => {
it('decodes the base64 payload to bytes', () => {
expect(decodeImageDataUrl(PNG_DATA_URL).toString()).toBe('fake-png');
});
it('throws on a non-image / malformed data URL', () => {
expect(() => decodeImageDataUrl('not-a-data-url')).toThrow(/base64 image data URL/);
expect(() => decodeImageDataUrl('data:image/png;base64,')).toThrow(/no base64 payload/);
});
});
describe('buildCliVisionInvocation', () => {
it('attaches the image via -i and a positional prompt for codex', () => {
const inv = buildCliVisionInvocation(
{ id: 'codex', command: 'codex', args: [] }, 'gpt-5', '/tmp/x', 'describe',
);
expect(inv.command).toBe('codex');
expect(inv.args).toContain('-i');
expect(posixPath(inv.args)).toContain('/tmp/x/vision-input.png');
expect(inv.args).toContain('-m');
expect(inv.args).toContain('gpt-5');
expect(inv.args[inv.args.length - 1]).toBe('describe'); // prompt is positional
// Codex's startup update check is disabled so it can't stall / brew-upgrade
// under the vision timeout.
expect(inv.args).toEqual(expect.arrayContaining(['-c', 'check_for_update_on_startup=false']));
expect(inv.stdin).toBeNull();
expect(posixPath(inv.cwd)).toBe('/tmp/x');
});
it('omits -m for the codex-configured-default sentinel (falls back to config.toml)', () => {
const inv = buildCliVisionInvocation(
{ id: 'codex', command: 'codex', args: [] }, 'codex-configured-default', '/tmp/x', 'p',
);
expect(inv.args).not.toContain('-m');
expect(inv.args).not.toContain('codex-configured-default');
});
it('does not double-add exec when the provider args already pin it', () => {
const inv = buildCliVisionInvocation(
{ id: 'codex', command: 'codex', args: ['exec'] }, null, '/tmp/x', 'p',
);
expect(inv.args.filter((a) => a === 'exec')).toHaveLength(1);
});
it('uses stdin + cwd-local file reference for claude-code', () => {
const inv = buildCliVisionInvocation(
{ id: 'claude-code', command: 'claude', args: [] }, 'claude-opus-4-8', '/tmp/y', 'describe',
);
expect(inv.command).toBe('claude');
expect(inv.args).toEqual(expect.arrayContaining(['-p', '-', '--model', 'claude-opus-4-8']));
expect(inv.stdin).toContain('describe');
expect(inv.stdin).toContain('vision-input.png');
expect(posixPath(inv.cwd)).toBe('/tmp/y');
});
it('attaches every named frame and injects effort for a multi-image Codex call', () => {
const inv = buildCliVisionInvocation(
{ id: 'codex', command: 'codex', args: [] },
'gpt-5',
'/tmp/x',
'describe motion',
{ imageNames: ['vision-1.jpg', 'vision-2.jpg'], effort: 'high' },
);
const paths = inv.args.map((a) => posixPath(a));
expect(paths.filter((a) => a === '-i')).toHaveLength(2);
expect(paths).toContain('/tmp/x/vision-1.jpg');
expect(paths).toContain('/tmp/x/vision-2.jpg');
expect(inv.args).toEqual(expect.arrayContaining(['-c', 'model_reasoning_effort=high']));
});
it('lists every frame in the Claude stdin prompt and passes effort through buildCliArgs', () => {
const inv = buildCliVisionInvocation(
{ id: 'claude-code', command: 'claude', args: [] },
'claude-opus-4-8',
'/tmp/y',
'describe motion',
{ imageNames: ['vision-1.jpg', 'vision-2.jpg'], effort: 'high' },
);
expect(inv.stdin).toContain('vision-1.jpg');
expect(inv.stdin).toContain('vision-2.jpg');
expect(inv.stdin).toMatch(/chronological/i);
expect(inv.args).toEqual(expect.arrayContaining(['--effort', 'high']));
});
});
describe('prepareCliVisionRun', () => {
it('stages multiple files for the shared runner and removes them on cleanup', async () => {
const sourceDir = await mkdtemp(join(tmpdir(), 'portos-vision-source-'));
try {
const first = join(sourceDir, 'first.png');
const second = join(sourceDir, 'second.jpg');
await Promise.all([writeFile(first, 'one'), writeFile(second, 'two')]);
const prepared = await prepareCliVisionRun({
provider: { id: 'codex', command: 'codex', args: [] },
imagePaths: [first, second],
prompt: 'compare',
model: 'gpt-5',
effort: 'high',
});
expect(prepared.invocation.args.filter((arg) => arg === '-i')).toHaveLength(2);
expect(prepared.invocation.cwd).toMatch(/portos-vision-run-/);
await prepared.cleanup();
await expect(import('fs/promises').then(({ stat }) => stat(prepared.invocation.cwd))).rejects.toMatchObject({ code: 'ENOENT' });
} finally {
await rm(sourceDir, { recursive: true, force: true });
}
});
});
// A minimal child-process double: an EventEmitter with stdin/stdout/stderr.
function makeFakeChild() {
const child = new EventEmitter();
// killProcessTree tells a spawned child from a node-pty session by
// `instanceof ChildProcess` (a pty takes a different kill shape), so the fake
// has to carry the prototype the way a real spawn() result does.
Object.setPrototypeOf(child, ChildProcess.prototype);
child.killed = false;
child.kill = vi.fn(() => { child.killed = true; });
// A real ChildProcess stdin is a stream — the fake is one too, or the
// production guardChildStdin listener has nothing to attach to (#5655).
child.stdin = Object.assign(new EventEmitter(), { write: vi.fn(), end: vi.fn(), destroy: vi.fn() });
child.stdout = new EventEmitter();
child.stderr = new EventEmitter();
return child;
}
// A spawnImpl that drives `child` through `script(child)` *after* the caller's
// synchronous spawn-and-listen block has run. describeImageViaCli awaits
// mkdtemp+writeFile, then synchronously spawns and attaches its data/close/error
// listeners; deferring the script to a microtask guarantees those listeners are
// attached before any event fires. A fixed `setTimeout` instead raced those
// async file ops and dropped events on the floor (no listener yet) under CI
// load, hanging the promise until the 10s test timeout.
function spawnEmitting(child, script) {
return vi.fn(() => { queueMicrotask(() => script(child)); return child; });
}
describe('describeImageViaCli', () => {
it('returns the trimmed stdout text in the API-compatible shape on exit 0', async () => {
const child = makeFakeChild();
const spawnImpl = spawnEmitting(child, (c) => {
c.stdout.emit('data', Buffer.from(' a woman in a red cloak '));
c.emit('close', 0);
});
const promise = describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: PNG_DATA_URL,
prompt: 'caption this',
model: 'gpt-5',
spawnImpl,
});
const result = await promise;
expect(result).toEqual({
text: 'a woman in a red cloak', finishReason: null, usage: null, reasoning: '',
});
expect(spawnImpl).toHaveBeenCalledOnce();
});
it('wraps a resolved .cmd shim via cmd.exe /c, preserving the multi-word prompt as one arg (#1865)', async () => {
const resolvedPath = 'C:\\Users\\Joe\\AppData\\Roaming\\npm\\codex.cmd';
vi.mocked(resolveWindowsExecutable).mockReturnValueOnce(resolvedPath);
// Force the wrap's win32 branch (host running this suite is never win32)
// to exercise the real cmd.exe /c contract, not the identity pass-through.
const { prepareWindowsSafeSpawn: realPrepare } = await vi.importActual('../lib/bufferedSpawn.js');
vi.mocked(prepareWindowsSafeSpawn).mockImplementationOnce((cmd, args) => realPrepare(cmd, args, true));
const child = makeFakeChild();
const spawnImpl = spawnEmitting(child, (c) => {
c.stdout.emit('data', Buffer.from('caption'));
c.emit('close', 0);
});
const promise = describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: PNG_DATA_URL,
// Free-text prompt with spaces — the exact scenario that broke under
// the prior (rejected) shell:true approach: shell:true + an args array
// doesn't escape arguments, so this would have silently mis-split into
// extra shell tokens. The cmd.exe wrapper relies on Node's own correct
// non-shell argv escaping instead, which keeps it as one token.
prompt: 'describe this photo in detail',
spawnImpl,
});
await promise;
const [spawnedCommand, spawnedArgs, options] = spawnImpl.mock.calls[0];
expect(spawnedCommand).toBe('cmd.exe');
expect(spawnedArgs[0]).toBe('/c');
expect(spawnedArgs[1]).toBe(resolvedPath);
expect(spawnedArgs[spawnedArgs.length - 1]).toBe('describe this photo in detail');
// Never falls back to shell:true (DEP0190) — the cmd.exe wrapper relies
// on Node's own correct non-shell argv escaping instead.
expect(options.shell).toBeUndefined();
});
it('strips the codex session transcript down to the assistant reply', async () => {
const child = makeFakeChild();
// A realistic codex exec transcript: banner … \ncodex\n<reply>\ntokens used …
const transcript = [
'OpenAI Codex v0.141.0',
'--------',
'user',
'caption',
'codex',
'a woman in a red cloak, bust shot',
'tokens used: 1234',
].join('\n');
const spawnImpl = spawnEmitting(child, (c) => {
c.stdout.emit('data', Buffer.from(transcript));
c.emit('close', 0);
});
const promise = describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: PNG_DATA_URL,
prompt: 'caption',
model: 'gpt-5',
spawnImpl,
});
const result = await promise;
expect(result.text).toBe('a woman in a red cloak, bust shot');
});
it('extracts the assistant reply when codex emits it AFTER the tokens-used footer', async () => {
const child = makeFakeChild();
// Newer codex format: the final reply follows the `tokens used\n<count>` footer.
const transcript = [
'OpenAI Codex v0.141.0',
'codex',
'(intermediate working notes)',
'tokens used',
'1234',
'{"boxes":[{"x":0,"y":0,"w":0.5,"h":1}]}',
].join('\n');
const spawnImpl = spawnEmitting(child, (c) => {
c.stdout.emit('data', Buffer.from(transcript));
c.emit('close', 0);
});
const promise = describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: PNG_DATA_URL,
prompt: 'caption',
spawnImpl,
});
const result = await promise;
expect(result.text).toBe('{"boxes":[{"x":0,"y":0,"w":0.5,"h":1}]}');
});
it('rejects with a tail of stderr on a non-zero exit', async () => {
const child = makeFakeChild();
const spawnImpl = spawnEmitting(child, (c) => {
c.stderr.emit('data', Buffer.from('vision unavailable'));
c.emit('close', 1);
});
const promise = describeImageViaCli({
provider: { id: 'claude-code', command: 'claude', args: [] },
dataUrl: PNG_DATA_URL,
prompt: 'caption',
spawnImpl,
});
await expect(promise).rejects.toThrow(/exited 1.*vision unavailable/s);
});
it('rejects when the process fails to spawn', async () => {
const child = makeFakeChild();
const spawnImpl = spawnEmitting(child, (c) => {
c.emit('error', new Error('ENOENT'));
});
const promise = describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: PNG_DATA_URL,
prompt: 'p',
spawnImpl,
});
await expect(promise).rejects.toThrow(/Failed to spawn codex.*ENOENT/s);
});
it('rejects (and does not hang) when the child exceeds the timeout', async () => {
const child = makeFakeChild();
const spawnImpl = vi.fn(() => child);
const promise = describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: PNG_DATA_URL,
prompt: 'p',
timeout: 20,
spawnImpl,
});
// The child never emits `close` (simulates a wedged process); the timeout
// must SIGTERM it and reject on its own rather than awaiting `close`.
await expect(promise).rejects.toThrow(/timed out after 20ms/);
expect(child.kill).toHaveBeenCalledWith('SIGTERM');
});
// #7496. With a credentialBootstrap provider the direct child is the user's
// bootstrap CLI supervising the harness, not the harness itself, so the
// timeout has to signal the whole process group or a wedged vision call
// leaves a harness running past the rejection.
describe('credential-bootstrap process-group teardown', () => {
const bootstrapProvider = {
id: 'codex',
command: 'codex',
args: [],
credentialBootstrap: { command: 'token-cli', args: ['run'], argsSeparator: '--' },
};
it('spawns a bootstrap-wrapped child detached, and an unwrapped one attached', async () => {
const wrappedChild = makeFakeChild();
const wrappedSpawn = spawnEmitting(wrappedChild, (c) => { c.emit('close', 0); });
await describeImageViaCli({
provider: bootstrapProvider, dataUrl: PNG_DATA_URL, prompt: 'p', spawnImpl: wrappedSpawn,
});
expect(wrappedSpawn.mock.calls[0][0]).toBe('token-cli');
expect(wrappedSpawn.mock.calls[0][2].detached).toBe(EXPECT_GROUP);
const plainChild = makeFakeChild();
const plainSpawn = spawnEmitting(plainChild, (c) => { c.emit('close', 0); });
await describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: PNG_DATA_URL, prompt: 'p', spawnImpl: plainSpawn,
});
expect(plainSpawn.mock.calls[0][2].detached).toBe(false);
});
it.skipIf(process.platform === 'win32')('signals the whole group on timeout for a wrapped provider', async () => {
// Spy so the negative pid never reaches a real process group.
const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
const child = makeFakeChild();
child.pid = 818181;
const promise = describeImageViaCli({
provider: bootstrapProvider, dataUrl: PNG_DATA_URL, prompt: 'p', timeout: 20,
spawnImpl: vi.fn(() => child),
});
await expect(promise).rejects.toThrow(/timed out after 20ms/);
expect(killSpy).toHaveBeenCalledWith(-818181, 'SIGTERM');
// The group signal landed, so the per-pid fallback never runs — the
// harness behind the wrapper is covered by the same signal.
expect(child.kill).not.toHaveBeenCalled();
killSpy.mockRestore();
});
});
it('contains an EPIPE on stdin from a vision CLI that died before reading the prompt (#5655)', async () => {
// describeImageViaCli runs outside the Express request lifecycle, so an
// unlistened 'error' on the stdin stream would kill the server process
// instead of rejecting this promise.
const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
const child = makeFakeChild();
let listenersAtWriteTime = null;
child.stdin.write = vi.fn(() => {
listenersAtWriteTime = child.stdin.listenerCount('error');
throw Object.assign(new Error('write EPIPE'), { code: 'EPIPE' });
});
const spawnImpl = spawnEmitting(child, (c) => {
expect(() => c.stdin.emit('error', Object.assign(new Error('write EPIPE'), { code: 'EPIPE' }))).not.toThrow();
c.emit('close', 1);
});
// claude-code is the stdin-delivering vision provider (codex puts the
// prompt in argv and never writes the pipe).
await expect(describeImageViaCli({
provider: { id: 'claude-code', command: 'claude', args: [] },
dataUrl: PNG_DATA_URL,
prompt: 'caption this',
spawnImpl,
})).rejects.toThrow(/exited 1/);
expect(listenersAtWriteTime).toBe(1);
// The pipe is closed anyway, so a child still reading stdin sees EOF.
expect(child.stdin.destroy).toHaveBeenCalled();
errorSpy.mockRestore();
});
it('throws on a malformed data URL before spawning', async () => {
const spawnImpl = vi.fn();
await expect(describeImageViaCli({
provider: { id: 'codex', command: 'codex', args: [] },
dataUrl: 'garbage',
prompt: 'p',
spawnImpl,
})).rejects.toThrow(/base64 image data URL/);
expect(spawnImpl).not.toHaveBeenCalled();
});
});