threadroom-pi 0.1.0-beta.0

package/node_modules/threadroom-service/lib/ensure.js

@@ -0,0 +1,157 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { request } from 'node:http';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { threadroomDatabasePath } from './paths.js';
+
+const cli = fileURLToPath(new URL('../bin/threadroom-service.js', import.meta.url));
+const stderrLimit = 4000;
+const storageIdentity = (database) => createHash('sha256').update(database).digest('hex').slice(0, 24);
+
+function endpoint(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost'].includes(url.hostname) ||
+      url.username || url.password || (url.pathname !== '/' && url.pathname !== '') || url.search || url.hash) {
+    throw Object.assign(new Error('Automatic Threadroom startup only owns an uncredentialed loopback HTTP origin.'), { code: 'unmanaged_endpoint' });
+  }
+  return url;
+}
+
+function probe(baseUrl, expectedStorageId, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const url = new URL('/api/health', baseUrl);
+    let settled = false;
+    const finish = (value) => { if (settled) return; settled = true; clearTimeout(timer); resolve(value); };
+    const call = request(url, { method: 'GET', family: 4, agent: false, headers: { Accept: 'application/json' } }, (response) => {
+      const chunks = []; let bytes = 0;
+      response.on('data', (chunk) => {
+        bytes += chunk.length;
+        if (bytes > 64 * 1024) { response.destroy(); finish({ status: 'incompatible', reason: 'health response exceeded 64 KiB' }); }
+        else chunks.push(chunk);
+      });
+      response.on('error', () => finish({ status: 'unavailable' }));
+      response.on('end', () => {
+        let body;
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+        catch { return finish({ status: 'incompatible', reason: 'health response was not JSON' }); }
+        if (response.statusCode === 200 && body?.ok === true && body.service === 'threadroom' && body.apiVersion === 2 &&
+            body.website === true && body.storageId === expectedStorageId) return finish({ status: 'healthy', health: body });
+        const reason = body?.service === 'threadroom' && body?.apiVersion !== 2
+          ? `API version ${body?.apiVersion ?? 'missing'} is incompatible; restart the detached Threadroom service for API version 2`
+          : 'service identity, API version, website, or storage does not match';
+        finish({ status: 'incompatible', reason, health: body });
+      });
+    });
+    call.on('error', () => finish({ status: 'unavailable' }));
+    call.end();
+    const timer = setTimeout(() => { call.destroy(); finish({ status: 'unavailable' }); }, timeoutMs);
+    timer.unref?.();
+  });
+}
+
+function startupError(message, stderr, cause) {
+  const diagnostic = stderr.trim();
+  const text = diagnostic ? `${message}\nThreadroom service stderr:\n${diagnostic}` : message;
+  return Object.assign(cause === undefined ? new Error(text) : new Error(text, { cause }), { code: 'service_start_failed' });
+}
+
+/** Idempotently ensure one compatible detached local API + website process.
+ * The returned boundary performs no write retry; callers invoke it before each
+ * request so an ambiguous mutation remains ambiguous. */
+export function createThreadroomServiceEnsurer({
+  baseUrl = 'http://127.0.0.1:4310', database = threadroomDatabasePath(), timeoutMs = 5000,
+  env = process.env, spawnProcess = spawn,
+} = {}) {
+  const url = endpoint(baseUrl);
+  if (url.port === '0') throw Object.assign(new Error('Automatic Threadroom startup needs a stable nonzero port.'), { code: 'unmanaged_endpoint' });
+  if (!isAbsolute(database)) throw new Error('Automatic Threadroom startup needs an absolute database path.');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 100) throw new Error('Threadroom startup timeout must be at least 100 ms.');
+  const databasePath = resolve(database), storageId = storageIdentity(databasePath);
+  const dataDir = dirname(databasePath);
+  const lock = join(dataDir, `.startup-${createHash('sha256').update(url.origin).digest('hex').slice(0, 12)}`);
+  let inflight;
+  async function ensureOnce() {
+    const initial = await probe(url, storageId);
+    if (initial.status === 'healthy') return initial.health;
+    if (initial.status === 'incompatible') throw Object.assign(new Error(`Threadroom endpoint ${url.origin} is already occupied by an incompatible runtime (${initial.reason}).`), { code: 'incompatible_service' });
+
+    mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+    let owned = false, ownerToken;
+    const claim = () => {
+      mkdirSync(lock, { mode: 0o700 });
+      ownerToken = randomUUID(); writeFileSync(join(lock, 'owner'), ownerToken, { mode: 0o600 }); owned = true;
+    };
+    try {
+      try { claim(); }
+      catch (error) {
+        if (error?.code !== 'EEXIST') throw error;
+        // Never delete a lease we do not own. If its starter disappeared, the
+        // bounded wait below falls back to the HTTP port's atomic bind; extra
+        // contenders may launch, but only one compatible service can listen.
+      }
+      if (!owned) {
+        const deadline = Date.now() + Math.max(100, Math.floor(timeoutMs / 2));
+        while (Date.now() < deadline) {
+          const observed = await probe(url, storageId);
+          if (observed.status === 'healthy') return observed.health;
+          if (observed.status === 'incompatible') throw Object.assign(new Error(`Threadroom endpoint ${url.origin} became occupied by an incompatible runtime (${observed.reason}).`), { code: 'incompatible_service' });
+          await delay(100);
+        }
+        // The lease may be orphaned. Continue without mutating it; the port is
+        // the final cross-process ownership claim and losers exit on EADDRINUSE.
+      }
+
+      const afterLock = await probe(url, storageId);
+      if (afterLock.status === 'healthy') return afterLock.health;
+      if (afterLock.status === 'incompatible') throw Object.assign(new Error(`Threadroom endpoint ${url.origin} is occupied by an incompatible runtime (${afterLock.reason}).`), { code: 'incompatible_service' });
+
+      const port = url.port || '80';
+      const child = spawnProcess(process.execPath, [cli, 'serve', '--database', databasePath, '--port', port], {
+        cwd: dataDir, detached: true, windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'],
+        env: { ...env, THREADROOM_DB: databasePath, THREADROOM_SEED_DEMO: '0' },
+      });
+      let stderr = '', launchFailure, exit, ready = false;
+      const remember = (chunk) => { stderr = `${stderr}${chunk}`.slice(-stderrLimit); };
+      child.stderr?.on('data', remember);
+      child.stderr?.unref?.(); child.unref();
+      child.once('error', (error) => { launchFailure = error; });
+      child.once('exit', (code, signal) => { exit = { code, signal }; });
+      try {
+        let deadline = Date.now() + timeoutMs, raceGrace = false;
+        while (Date.now() < deadline) {
+          const observed = await probe(url, storageId);
+          if (observed.status === 'healthy') { ready = true; return observed.health; }
+          if (observed.status === 'incompatible') throw Object.assign(new Error(`Threadroom endpoint ${url.origin} became occupied by an incompatible runtime (${observed.reason}).`), { code: 'incompatible_service' });
+          // A fallback contender can lose the port or an early SQLite race while
+          // another compatible starter is still becoming ready. Preserve its
+          // diagnostic, but let health—not child lifetime—decide. A failed lease
+          // owner grants one bounded window for its waiters to take the port.
+          if (owned && !raceGrace && (launchFailure || exit)) { deadline += timeoutMs; raceGrace = true; }
+          await delay(100);
+        }
+        try { child.kill(); } catch {}
+        if (launchFailure) throw startupError(`Failed to launch Threadroom: ${launchFailure.message}`, stderr, launchFailure);
+        if (exit) throw startupError(`Threadroom exited before readiness${exit.signal ? ` with signal ${exit.signal}` : ` with code ${exit.code ?? 'unknown'}`}.`, stderr);
+        throw startupError('Threadroom did not become healthy before the startup deadline.', stderr);
+      } finally {
+        if (!ready && child.exitCode === null) { try { child.kill(); } catch {} }
+        child.stderr?.off('data', remember); child.stderr?.resume(); child.stderr?.unref?.();
+      }
+    } finally {
+      if (owned) {
+        try { if (readFileSync(join(lock, 'owner'), 'utf8') === ownerToken) rmSync(lock, { recursive: true, force: true }); }
+        catch (error) { if (error?.code !== 'ENOENT') throw error; }
+      }
+    }
+  }
+  return {
+    baseUrl: url.origin, database: databasePath, storageId,
+    ensure() {
+      if (!inflight) inflight = ensureOnce().finally(() => { inflight = undefined; });
+      return inflight;
+    },
+  };
+}

package/node_modules/threadroom-service/lib/paths.js

@@ -0,0 +1,19 @@
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+
+/** Stable per-user service data; never relative to a checkout or plugin install. */
+export function threadroomDataDirectory(env = process.env, home = homedir(), platform = process.platform) {
+  if (platform === 'darwin') return join(home, 'Library', 'Application Support', 'Threadroom');
+  if (platform === 'win32') {
+    const local = env.LOCALAPPDATA;
+    return join(local && isAbsolute(local) ? local : join(home, 'AppData', 'Local'), 'Threadroom');
+  }
+  const xdg = env.XDG_DATA_HOME;
+  return join(xdg && isAbsolute(xdg) ? xdg : join(home, '.local', 'share'), 'threadroom');
+}
+
+/** Resolve an explicit environment value before a launcher changes cwd. */
+export function threadroomDatabasePath({ value = process.env.THREADROOM_DB, cwd = process.cwd(), env = process.env,
+  home = homedir(), platform = process.platform } = {}) {
+  return value ? resolve(cwd, value) : join(threadroomDataDirectory(env, home, platform), 'threadroom.sqlite');
+}

package/node_modules/threadroom-service/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "threadroom-service",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Independent local Threadroom API and website service",
+  "type": "module",
+  "engines": { "node": ">=24" },
+  "bin": { "threadroom-service": "bin/threadroom-service.js" },
+  "exports": {
+    "./ensure": "./lib/ensure.js",
+    "./paths": "./lib/paths.js"
+  },
+  "files": ["bin/", "lib/", "dist/", "README.md"],
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepack": "npm run build",
+    "test": "node --test test/*.test.js"
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "threadroom-pi",
+  "version": "0.1.0-beta.0",
+  "private": false,
+  "type": "module",
+  "description": "Private blocking or nonblocking questions and optional durable Threadroom discussions for Pi",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "ask-user-question",
+    "questionnaire",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "Scott Meyer <17101862+Scott-Meyer@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Scott-Meyer/threadroom.git",
+    "directory": "packages/pi-extension"
+  },
+  "homepage": "https://github.com/Scott-Meyer/threadroom/tree/main/packages/pi-extension#readme",
+  "bugs": {
+    "url": "https://github.com/Scott-Meyer/threadroom/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["extensions/", "src/", "scripts/", "README.md", "LICENSE"],
+  "engines": { "node": ">=24" },
+  "dependencies": {
+    "threadroom-service": "0.1.0"
+  },
+  "bundleDependencies": ["threadroom-service"],
+  "scripts": {
+    "prepublishOnly": "node scripts/verify-release.js",
+    "prepack": "node scripts/stage-service.js stage",
+    "postpack": "node scripts/stage-service.js clean"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": ["./extensions/index.ts"],
+    "skills": [],
+    "prompts": [],
+    "themes": []
+  }
+}

package/scripts/stage-service.js

@@ -0,0 +1,32 @@
+import { access, cp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+const here = fileURLToPath(new URL('../', import.meta.url));
+const service = fileURLToPath(new URL('../../service/', import.meta.url));
+const target = join(here, 'node_modules', 'threadroom-service');
+const marker = join(here, '.threadroom-service-pack-staged');
+const action = process.argv[2];
+const exists = async (path) => access(path).then(() => true, () => false);
+
+if (action === 'clean') {
+  if (await exists(marker)) {
+    await rm(target, { recursive: true, force: true });
+    await rm(marker, { force: true });
+  }
+} else if (action === 'stage') {
+  await rm(marker, { force: true });
+  if (await exists(join(service, 'scripts', 'build.js'))) {
+    await import(new URL('../../service/scripts/build.js', import.meta.url).href);
+    await rm(target, { recursive: true, force: true });
+    await mkdir(target, { recursive: true });
+    for (const entry of ['bin', 'lib', 'dist', 'README.md', 'package.json']) {
+      await cp(join(service, entry), join(target, entry), { recursive: true });
+    }
+    await writeFile(marker, 'staged from the Threadroom source workspace\n');
+  } else if (!await exists(join(target, 'package.json'))) {
+    throw new Error('Threadroom service source and bundled package are both missing.');
+  }
+} else {
+  throw new Error('Use stage or clean.');
+}

package/scripts/verify-packed.js

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const repositoryRoot = fileURLToPath(new URL('../../../', import.meta.url));
+const sdk = process.env.THREADROOM_PI_SDK_ROOT;
+if (!sdk) throw new Error('Set THREADROOM_PI_SDK_ROOT to the supported installed Pi package before checking a release artifact.');
+
+const directory = await mkdtemp(join(tmpdir(), 'threadroom-pi-packed-'));
+const agentDir = join(directory, 'agent');
+process.env.PI_CODING_AGENT_DIR = agentDir;
+process.env.THREADROOM_API_URL = '::release-check-must-not-connect::';
+try {
+  const packed = spawnSync('npm', ['pack', '--workspace', 'threadroom-pi', '--json', '--pack-destination', directory], {
+    cwd: repositoryRoot,
+    encoding: 'utf8',
+    timeout: 120_000,
+  });
+  assert.equal(packed.status, 0, packed.stderr || packed.stdout);
+  const starts = [packed.stdout.indexOf('\n{'), packed.stdout.indexOf('\n[')].filter(index => index >= 0);
+  const jsonStart = starts.length ? Math.min(...starts) + 1 : 0;
+  const report = JSON.parse(packed.stdout.slice(jsonStart));
+  const packedPackage = Array.isArray(report) ? report[0] : report['threadroom-pi'] || Object.values(report)[0];
+  assert.ok(packedPackage);
+  const tarball = join(directory, packedPackage.filename);
+  const archive = execFileSync('tar', ['-tzf', tarball], { encoding: 'utf8' }).split('\n');
+  for (const path of [
+    'package/extensions/index.ts',
+    'package/LICENSE',
+    'package/node_modules/threadroom-service/package.json',
+    'package/node_modules/threadroom-service/bin/threadroom-service.js',
+    'package/node_modules/threadroom-service/lib/ensure.js',
+    'package/node_modules/threadroom-service/lib/paths.js',
+    'package/node_modules/threadroom-service/dist/src/main.js',
+    'package/node_modules/threadroom-service/dist/public/index.html',
+  ]) assert.ok(archive.includes(path), `Packed artifact is missing ${path}`);
+
+  const installRoot = join(directory, 'install');
+  const installed = spawnSync('npm', ['install', '--prefix', installRoot, '--ignore-scripts', '--legacy-peer-deps', '--offline', tarball], {
+    encoding: 'utf8',
+    timeout: 120_000,
+  });
+  assert.equal(installed.status, 0, installed.stderr || installed.stdout);
+  const installedRoot = join(installRoot, 'node_modules', 'threadroom-pi');
+  const installedManifest = JSON.parse(await readFile(join(installedRoot, 'package.json'), 'utf8'));
+  assert.equal(installedManifest.name, 'threadroom-pi');
+  assert.equal(installedManifest.version, packedPackage.version);
+  const bundledManifest = JSON.parse(await readFile(join(installedRoot, 'node_modules', 'threadroom-service', 'package.json'), 'utf8'));
+  assert.equal(bundledManifest.name, 'threadroom-service');
+
+  const { loadExtensions } = await import(pathToFileURL(join(sdk, 'dist/core/extensions/loader.js')).href);
+  const { SessionManager } = await import(pathToFileURL(join(sdk, 'dist/core/session-manager.js')).href);
+  const target = join(installedRoot, 'extensions', 'index.ts');
+  const loaded = await loadExtensions([target], installRoot);
+  assert.deepEqual(loaded.errors, []);
+  assert.equal(loaded.extensions.length, 1);
+  const extension = loaded.extensions[0];
+  assert.ok(extension.tools.has('ask_user_question'));
+  assert.equal(extension.tools.has('ask_user_question_async'), false);
+
+  let activeTools = [...extension.tools.keys()];
+  loaded.runtime.getActiveTools = () => [...activeTools];
+  loaded.runtime.setActiveTools = names => { activeTools = [...names]; };
+  loaded.runtime.appendEntry = () => {};
+  loaded.runtime.sendMessage = () => {};
+  const context = {
+    mode: 'print', hasUI: false, cwd: installRoot, isIdle: () => true,
+    sessionManager: SessionManager.inMemory(installRoot),
+    ui: { setStatus() {}, notify() {} },
+  };
+  for (const handler of extension.handlers.get('session_start') || []) await handler({}, context);
+  assert.deepEqual(activeTools, ['ask_user_question'], 'Shared tools must remain inactive after a clean default start.');
+  const ask = extension.tools.get('ask_user_question').definition;
+  await assert.rejects(() => ask.execute('release-print-check', { questions: [{
+    question: 'Can this clean package present a private question?', options: [{ label: 'Yes' }, { label: 'No' }],
+  }] }, undefined, undefined, context), { code: 'unsupported_host' });
+  for (const handler of extension.handlers.get('session_shutdown') || []) await handler({}, context);
+
+  console.log(`Verified ${packedPackage.filename}: clean offline install, bundled service, installed Pi load, private tool, and default-off shared lane.`);
+} finally {
+  await rm(directory, { recursive: true, force: true });
+}

package/scripts/verify-release.js

@@ -0,0 +1,79 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { readFile, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const repositoryRoot = fileURLToPath(new URL('../../../', import.meta.url));
+const manifest = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'));
+const serviceManifest = JSON.parse(await readFile(join(repositoryRoot, 'packages/service/package.json'), 'utf8'));
+const readme = await readFile(join(packageRoot, 'README.md'), 'utf8');
+const license = await readFile(join(packageRoot, 'LICENSE'), 'utf8');
+const problems = [];
+
+const expect = (condition, message) => { if (!condition) problems.push(message); };
+expect(manifest.name === 'threadroom-pi', 'Package name must remain threadroom-pi.');
+expect(/^0\.1\.0-beta\.\d+$/.test(manifest.version), 'Version must be a 0.1.0 beta prerelease.');
+expect(manifest.private === false, 'Package must explicitly set private=false.');
+expect(manifest.license === 'MIT', 'Package metadata must declare the selected MIT license.');
+expect(manifest.publishConfig?.access === 'public', 'publishConfig.access must be public.');
+if (process.env.npm_lifecycle_event === 'prepublishOnly') {
+  expect(process.env.npm_config_tag === 'beta', 'Publishing requires an explicit --tag beta; refusing npm\'s latest default.');
+}
+expect(manifest.repository?.url === 'git+https://github.com/Scott-Meyer/threadroom.git', 'Repository provenance is missing or unexpected.');
+expect(manifest.homepage && manifest.bugs?.url, 'Homepage and issue metadata are required.');
+expect(manifest.keywords?.includes('pi-package'), 'Pi package discovery keyword is missing.');
+expect(manifest.pi?.extensions?.length === 1 && manifest.pi.extensions[0] === './extensions/index.ts', 'Published Pi entry point is unexpected.');
+expect(manifest.bundleDependencies?.length === 1 && manifest.bundleDependencies[0] === 'threadroom-service', 'The local service must remain the sole bundled dependency.');
+expect(manifest.dependencies?.['threadroom-service'] === serviceManifest.version, 'Bundled service dependency must match the staged service version.');
+expect(['@earendil-works/pi-coding-agent', '@earendil-works/pi-tui', 'typebox'].every(name => manifest.peerDependencies?.[name] === '*'), 'Pi-provided imports must remain wildcard peer dependencies.');
+expect(manifest.files?.includes('LICENSE'), 'The published file list must include LICENSE.');
+expect(readme.includes('pi install npm:threadroom-pi@beta'), 'README must contain the beta Pi installation command.');
+expect(readme.includes('shared Threadroom lane is experimental, off by default'), 'README must keep the unfinished shared lane boundary visible.');
+expect(license.startsWith('MIT License\n') && license.includes('Copyright (c) 2026 Scott Meyer'), 'LICENSE does not contain the selected MIT grant and copyright.');
+
+const releaseInputs = ['packages/pi-extension', 'packages/service', 'src', 'public'];
+try {
+  const dirty = execFileSync('git', ['status', '--porcelain=v1', '--untracked-files=all', '--', ...releaseInputs], {
+    cwd: repositoryRoot,
+    encoding: 'utf8',
+  }).trim();
+  expect(!dirty, `Release inputs are not committed:\n${dirty}`);
+  execFileSync('git', ['diff', '--check', '--', ...releaseInputs], { cwd: repositoryRoot, stdio: 'pipe' });
+} catch (error) {
+  if (!problems.some(problem => problem.startsWith('Release inputs are not committed:'))) {
+    problems.push(`Git release-input verification failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+if (problems.length) {
+  console.error(`threadroom-pi release check failed:\n\n- ${problems.join('\n- ')}`);
+  process.exit(1);
+}
+
+console.log(`threadroom-pi ${manifest.version} metadata and release inputs are ready for a beta publish.`);
+if (process.argv.includes('--full')) {
+  const sdk = process.env.THREADROOM_PI_SDK_ROOT;
+  if (!sdk) throw new Error('Set THREADROOM_PI_SDK_ROOT before running the full release check.');
+  const testDirectory = join(repositoryRoot, 'packages/pi-extension/test');
+  const tests = (await readdir(testDirectory)).filter(name => name.endsWith('.test.js')).sort().map(name => join(testDirectory, name));
+  const checked = spawnSync(process.execPath, ['--test', ...tests], {
+    cwd: repositoryRoot,
+    encoding: 'utf8',
+    timeout: 300_000,
+    stdio: 'inherit',
+    env: { ...process.env, THREADROOM_PI_TUI_SMOKE: '1' },
+  });
+  if (checked.error) throw checked.error;
+  if (checked.status !== 0) throw new Error(`Pi extension tests failed with status ${checked.status}.`);
+
+  for (const [command, args] of [
+    [process.execPath, [join(packageRoot, 'scripts/verify-packed.js')]],
+    ['npm', ['publish', '--workspace', 'threadroom-pi', '--dry-run', '--tag', 'beta', '--access', 'public']],
+  ]) {
+    const result = spawnSync(command, args, { cwd: repositoryRoot, encoding: 'utf8', timeout: 300_000, stdio: 'inherit', env: process.env });
+    if (result.error) throw result.error;
+    if (result.status !== 0) throw new Error(`${command} ${args.join(' ')} failed with status ${result.status}.`);
+  }
+  console.log(`threadroom-pi ${manifest.version} passed the full beta release check; nothing was published.`);
+}

package/src/client.js

@@ -0,0 +1,135 @@
+// Rendering-independent Node transport; no Pi, website, database or fetch globals.
+import { HttpTransport } from './http-transport.js';
+export class ThreadroomError extends Error {
+  constructor(message, { status, ambiguous = false } = {}) {
+    super(message); this.name = 'ThreadroomError'; this.status = status; this.ambiguous = ambiguous;
+  }
+}
+
+function serviceUrl(value) {
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.href.includes('?') || url.href.includes('#')) {
+    throw new Error('Threadroom needs HTTP(S) addresses without embedded credentials, query strings, or fragments.');
+  }
+  return url.href.replace(/\/$/, '');
+}
+
+export class ThreadroomClient {
+  constructor(baseUrl = 'http://127.0.0.1:4310', { uiUrl = baseUrl, timeoutMs = 15000, beforeConnect } = {}) {
+    this.baseUrl = serviceUrl(baseUrl);
+    this.uiUrl = serviceUrl(uiUrl);
+    this.timeoutMs = timeoutMs;
+    this.beforeConnect = beforeConnect;
+    this.lifetime = new AbortController();
+    this.transport = new HttpTransport();
+  }
+  /** Cancel this client's requests/streams and release its sockets. Permanent,
+   * idempotent, and independent of Participation.close() and other clients. */
+  close() { this.lifetime.abort(new Error('Threadroom client is closed.')); return this.transport.close(); }
+  link(id) { return `${this.uiUrl}/threads/${encodeURIComponent(id)}`; }
+  async ready(signal) {
+    signal.throwIfAborted();
+    if (!this.beforeConnect) return;
+    const work = Promise.resolve().then(() => this.beforeConnect({ signal }));
+    await new Promise((resolve, reject) => {
+      const abort = () => reject(signal.reason);
+      signal.addEventListener('abort', abort, { once: true });
+      work.then((value) => { signal.removeEventListener('abort', abort); resolve(value); },
+        (error) => { signal.removeEventListener('abort', abort); reject(error); });
+    });
+    signal.throwIfAborted();
+  }
+  async request(path, { method = 'GET', input, key, signal } = {}) {
+    const combined = AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.timeoutMs), ...(signal ? [signal] : [])]);
+    await this.ready(combined);
+    let response;
+    try {
+      response = await this.transport.open(`${this.baseUrl}${path}`, { method, signal: combined,
+        headers: { 'Content-Type': 'application/json', ...(key ? { 'Idempotency-Key': key } : {}) },
+        ...(input !== undefined ? { body: JSON.stringify(input) } : {}) });
+      if (response.statusCode >= 300 && response.statusCode < 400) {
+        response.destroy();
+        throw new Error('Threadroom redirects are not followed.');
+      }
+      const chunks = [];
+      for await (const chunk of response) chunks.push(chunk);
+      const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+      if (response.statusCode < 200 || response.statusCode >= 300) {
+        throw new ThreadroomError(result.error || `HTTP ${response.statusCode}`, { status: response.statusCode });
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof ThreadroomError) throw error;
+      throw new ThreadroomError(`Threadroom connection failed: ${error.message}`, { ambiguous: method !== 'GET' });
+    }
+  }
+  publish(input, options = {}) { return this.request('/api/ask', { ...options, method: 'POST', input }); }
+  read(id, options) { return this.request(`/api/nodes/${encodeURIComponent(id)}`, options); }
+  respond(id, input, options = {}) { return this.request(`/api/nodes/${encodeURIComponent(id)}/respond`, { ...options, method: 'POST', input }); }
+  tree(options) { return this.request('/api/tree', options); }
+
+  // Owned Node SSE supports cancellation/replay without EventSource or fetch.
+  async *events(after, signal, onOpen = () => {}) {
+    const combined = AbortSignal.any([this.lifetime.signal, ...(signal ? [signal] : [])]);
+    await this.ready(combined);
+    const response = await this.transport.open(`${this.baseUrl}/api/stream?after=${after}`, { signal: combined,
+      headers: { Accept: 'text/event-stream' } });
+    if (response.statusCode < 200 || response.statusCode >= 300 ||
+        !response.headers['content-type']?.includes('text/event-stream')) {
+      response.destroy();
+      throw new ThreadroomError(`Threadroom stream failed (HTTP ${response.statusCode})`);
+    }
+    const decoder = new TextDecoder();
+    let buffer = '', data = [], eventType = '', frameSize = 0;
+    try {
+      onOpen();
+      for await (const value of response) {
+        buffer += decoder.decode(value, { stream: true });
+        if (buffer.length > 1024 * 1024) throw new ThreadroomError('Threadroom stream frame exceeded 1 MiB');
+        let newline;
+        while ((newline = buffer.indexOf('\n')) !== -1) {
+          const line = buffer.slice(0, newline).replace(/\r$/, '');
+          buffer = buffer.slice(newline + 1);
+          if (!line) {
+            if (data.length && eventType === 'change') yield JSON.parse(data.join('\n'));
+            data = []; eventType = ''; frameSize = 0;
+          } else {
+            frameSize += line.length;
+            if (frameSize > 1024 * 1024) throw new ThreadroomError('Threadroom stream frame exceeded 1 MiB');
+            if (line.startsWith('event:')) eventType = line.slice(6).trim();
+            else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
+          }
+        }
+      }
+      throw new ThreadroomError('Threadroom stream disconnected');
+    } finally { response.destroy(); }
+  }
+}
+
+// Readable records never require executing an old authored document. Large source,
+// image data and arbitrary values remain at their durable address, not in every turn.
+export function readable(record, client) {
+  const node = record.node;
+  const summarize = (n) => ({ id: n.id, parentId: n.parentId, title: n.title,
+    body: clip(n.body, n === node ? 8000 : 1500), expectsAnswer: n.expectsAnswer, status: n.status,
+    author: n.author, createdAt: n.createdAt, url: client.link(n.id),
+    ...(n.presentation ? { presentation: { kind: n.presentation.kind,
+      revision: n.presentation.revision, fallback: clip(n.presentation.fallback, 4000),
+      url: `${client.baseUrl}/api/nodes/${encodeURIComponent(n.id)}/presentation` } } : {}),
+    ...(n.response ? { response: { ...n.response,
+      selections: compactValues(n.response.selections, n === node ? 6000 : 1500) } } : {}) });
+  return { node: summarize(node), ancestors: (record.ancestors || []).map((ancestor) => ({
+      id: ancestor.id, parentId: ancestor.parentId, title: clip(ancestor.title, 2000),
+      expectsAnswer: ancestor.expectsAnswer, status: ancestor.status, author: ancestor.author,
+    })), counts: record.counts,
+    children: (record.children || []).slice(-10).map(summarize),
+    ...(record.children?.length > 10 ? { omittedChildren: record.children.length - 10 } : {}),
+    url: client.link(node.id), ...(record.deduplicated !== undefined ? { deduplicated: record.deduplicated } : {}) };
+}
+function clip(value, length) {
+  return typeof value === 'string' && value.length > length ? `${value.slice(0, length)}\n[Truncated; full content at the node URL]` : value;
+}
+function compactValues(values, limit) {
+  if (JSON.stringify(values || []).length <= limit) return values;
+  return { omitted: true, reason: 'Large semantic values or images; retrieve the durable node for the full selections.' };
+}

package/src/config.js

@@ -0,0 +1,57 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+function readLayer(path) {
+  let value;
+  try { value = JSON.parse(readFileSync(path, 'utf8')); }
+  catch (error) {
+    if (error?.code === 'ENOENT') return { present: false };
+    return { present: true, error: `Cannot read ${path}: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { present: true, error: `${path} must contain a JSON object.` };
+  }
+  const unknown = Object.keys(value).filter((key) => key !== 'shared');
+  if (unknown.length) return { present: true, error: `${path} has unknown setting${unknown.length === 1 ? '' : 's'}: ${unknown.join(', ')}.` };
+  if (value.shared !== undefined && typeof value.shared !== 'boolean') {
+    return { present: true, error: `${path} setting "shared" must be true or false.` };
+  }
+  return { present: true, value: value.shared };
+}
+
+/** Locate the extension-owned global default and project override. */
+export function threadroomConfigPaths({ cwd, agentDir, configDirName = '.pi' }) {
+  return Object.freeze({ globalPath: join(agentDir, 'threadroom.json'), projectPath: join(cwd, configDirName, 'threadroom.json') });
+}
+
+/** Resolve the optional shared lane. Project configuration is never read before
+ * Pi has established project trust. An invalid effective layer fails closed;
+ * an explicit trusted-project value can supersede a lower-layer warning. */
+export function resolveThreadroomConfig({ cwd, agentDir, configDirName = '.pi', projectTrusted = false }) {
+  const { globalPath, projectPath } = threadroomConfigPaths({ cwd, agentDir, configDirName });
+  let enabled = false, source = 'default';
+  const warnings = [];
+  const global = readLayer(globalPath);
+  if (global.error) { warnings.push(global.error); enabled = false; source = 'invalid'; }
+  else if (global.value !== undefined) { enabled = global.value; source = 'global'; }
+  if (projectTrusted) {
+    const project = readLayer(projectPath);
+    if (project.error) { warnings.push(project.error); enabled = false; source = 'invalid'; }
+    else if (project.value !== undefined) { enabled = project.value; source = 'project'; }
+  }
+  return Object.freeze({ enabled, source, globalPath, projectPath, warnings: Object.freeze(warnings) });
+}
+
+/** Persist the one owned setting. Undefined removes an override and inherits the
+ * lower scope (or the built-in off default). */
+export function writeThreadroomConfig({ path, shared }) {
+  if (shared === undefined) { rmSync(path, { force: true }); return; }
+  if (typeof shared !== 'boolean') throw new TypeError('Threadroom shared setting must be boolean or undefined.');
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, `${JSON.stringify({ shared }, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+  } finally { rmSync(temporary, { force: true }); }
+}