fuli-context 0.2.0

package/src/setup/graph-runtime.js

@@ -0,0 +1,360 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+import {
+  ensureContainerRuntime,
+  runDockerCompose
+} from './container-runtime.js';
+import { readJsonFile, writeJsonFileAtomic } from '../storage/json-file.js';
+
+export {
+  dockerInfoIndicatesDaemon,
+  selectDockerEnvironment
+} from './container-runtime.js';
+
+const PERSONAL_PROVIDER_URL = 'http://127.0.0.1:8787';
+const WORKSPACE_PROVIDER_URL = 'http://127.0.0.1:8788';
+
+export const MANAGED_PERSONAL_PROVIDER_URL = PERSONAL_PROVIDER_URL;
+export const MANAGED_WORKSPACE_PROVIDER_URL = WORKSPACE_PROVIDER_URL;
+
+export async function ensureGraphRuntime(input, dependencies = {}) {
+  const deps = graphDependencies(dependencies);
+  const containerRuntime = await deps.ensureContainerRuntime({
+    env: input.env ?? process.env,
+    onProgress: input.onProgress
+  });
+  deps.ensureDirectory(input.paths.dataDir);
+  const secrets = ensureProviderSecrets(input.paths.graphEnvPath, deps);
+  deps.startProviders(input.paths, input.paths.graphEnvPath, {
+    personalOnly: input.personalOnly === true,
+    containerRuntime,
+    ...(input.buildProviders === false ? { build: false } : {})
+  });
+  await waitForProvider(PERSONAL_PROVIDER_URL, deps.fetch);
+  if (!input.personalOnly) await waitForProvider(WORKSPACE_PROVIDER_URL, deps.fetch);
+
+  let config = deps.readConfig(input.paths.graphRuntimeConfigPath);
+  if (!config) {
+    config = await bootstrapGraph({
+      personalSpaceName: input.personalSpaceName,
+      secrets,
+      personalOnly: input.personalOnly === true,
+      fetchImpl: deps.fetch
+    });
+    deps.writeConfig(input.paths.graphRuntimeConfigPath, config);
+    deps.secureFile(input.paths.graphRuntimeConfigPath);
+  }
+  stopOwnedLegacyRuntime(input.paths, deps);
+
+  if (input.noStart) return { status: 'initialized', url: null, pid: null };
+  const existing = deps.readState(input.paths.graphRuntimeStatePath);
+  if (isGraphRuntimeState(existing) && deps.isProcessAlive(existing.pid)) {
+    const healthy = await deps.webHealth(existing.url, existing.pid, existing.version);
+    if (healthy && existing.port === input.port) {
+      return { status: 'running', url: existing.url, pid: existing.pid };
+    }
+    if (!healthy) throw new Error('Recorded Fuli Graphiti runtime is not healthy');
+    deps.stopProcess(existing.pid);
+  }
+  const child = deps.spawnWebRuntime({
+    paths: input.paths,
+    nodePath: process.execPath,
+    port: input.port
+  });
+  const url = `http://127.0.0.1:${input.port}`;
+  if (!Number.isInteger(child.pid) || !await waitForWeb(url, child.pid, deps)) {
+    if (Number.isInteger(child.pid)) deps.stopProcess(child.pid);
+    throw new Error('Fuli Graphiti console could not start');
+  }
+  deps.writeState(input.paths.graphRuntimeStatePath, {
+    version: 3,
+    pid: child.pid,
+    url,
+    port: input.port,
+    managedProviders: input.personalOnly
+      ? ['personal']
+      : ['personal', 'development-workspace'],
+    startedAt: new Date().toISOString()
+  });
+  return { status: 'started', url, pid: child.pid };
+}
+
+function ensureProviderSecrets(path, deps) {
+  if (deps.fileExists(path)) return parseEnv(deps.readText(path));
+  const values = {
+    FULI_PERSONAL_NEO4J_PASSWORD: secret(),
+    FULI_WORKSPACE_NEO4J_PASSWORD: secret(),
+    FULI_PERSONAL_BOOTSTRAP_TOKEN: secret(),
+    FULI_WORKSPACE_BOOTSTRAP_TOKEN: secret()
+  };
+  const body = Object.entries(values).map(([key, value]) => `${key}=${value}`).join('\n') + '\n';
+  deps.writeText(path, body);
+  deps.secureFile(path);
+  return values;
+}
+
+async function bootstrapGraph({ personalSpaceName, secrets, personalOnly, fetchImpl }) {
+  const personalIdentity = await bootstrapProvider(
+    PERSONAL_PROVIDER_URL,
+    secrets.FULI_PERSONAL_BOOTSTRAP_TOKEN,
+    personalSpaceName,
+    fetchImpl
+  );
+  const personalSpace = await findOrCreateSpace(PERSONAL_PROVIDER_URL, {
+    token: personalIdentity.access_token,
+    name: personalSpaceName,
+    kind: 'personal',
+    fetchImpl
+  });
+  const config = {
+    version: 1,
+    personal: {
+      providerUrl: PERSONAL_PROVIDER_URL,
+      accessToken: personalIdentity.access_token,
+      principalId: personalIdentity.principal_id,
+      spaceId: personalSpace.id
+    },
+    workspaces: []
+  };
+  if (personalOnly) return config;
+
+  const workspaceIdentity = await bootstrapProvider(
+    WORKSPACE_PROVIDER_URL,
+    secrets.FULI_WORKSPACE_BOOTSTRAP_TOKEN,
+    personalSpaceName,
+    fetchImpl
+  );
+  const project = await findOrCreateSpace(WORKSPACE_PROVIDER_URL, {
+    token: workspaceIdentity.access_token,
+    name: '工作',
+    kind: 'project',
+    fetchImpl
+  });
+  await providerRequest(PERSONAL_PROVIDER_URL, '/v1/subscriptions', {
+    token: personalIdentity.access_token,
+    body: {
+      personal_space_id: personalSpace.id,
+      project_id: project.id,
+      provider_url: WORKSPACE_PROVIDER_URL,
+      project_name: project.name
+    },
+    fetchImpl
+  });
+  config.workspaces.push({
+      providerUrl: WORKSPACE_PROVIDER_URL,
+      accessToken: workspaceIdentity.access_token,
+      principalId: workspaceIdentity.principal_id
+  });
+  return config;
+}
+
+async function bootstrapProvider(url, bootstrapToken, principalName, fetchImpl) {
+  const response = await fetchImpl(`${url}/v1/bootstrap`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-fuli-bootstrap-token': bootstrapToken
+    },
+    body: JSON.stringify({ principal_name: principalName })
+  });
+  if (!response.ok) throw new Error(`Could not bootstrap ${url}`);
+  return response.json();
+}
+
+async function providerRequest(baseUrl, path, { token, body, fetchImpl }) {
+  const response = await fetchImpl(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${token}`,
+      'content-type': 'application/json'
+    },
+    body: JSON.stringify(body)
+  });
+  if (!response.ok) throw new Error(`Provider setup failed at ${path}`);
+  return response.json();
+}
+
+async function findOrCreateSpace(baseUrl, { token, name, kind, fetchImpl }) {
+  const response = await fetchImpl(`${baseUrl}/v1/spaces`, {
+    headers: { authorization: `Bearer ${token}` }
+  });
+  if (!response.ok) throw new Error('Could not list Provider spaces during setup');
+  const existing = (await response.json()).find(
+    (space) => space.kind === kind && space.name === name
+  );
+  if (existing) return existing;
+  return providerRequest(baseUrl, '/v1/spaces', {
+    token,
+    body: { name, kind },
+    fetchImpl
+  });
+}
+
+async function waitForProvider(url, fetchImpl) {
+  for (let attempt = 0; attempt < 120; attempt += 1) {
+    try {
+      const response = await fetchImpl(`${url}/health`);
+      if (response.ok) return;
+    } catch {
+      // Containers and Graphiti indices may still be starting.
+    }
+    await delay(1000);
+  }
+  throw new Error(`Graphiti provider did not become ready: ${url}`);
+}
+
+async function waitForWeb(url, pid, deps) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (!deps.isProcessAlive(pid)) return false;
+    if (await deps.webHealth(url, pid, 3)) return true;
+    await delay(100);
+  }
+  return false;
+}
+
+export function startGraphProviders(paths, envPath, options = {}) {
+  const args = [
+    'compose',
+    '--env-file', envPath,
+    '-f', paths.graphComposePath,
+    'up', '-d'
+  ];
+  if (options.build !== false) args.push('--build');
+  if (options.personalOnly) args.push('personal-neo4j', 'personal-provider');
+  runDockerCompose(args, options.containerRuntime);
+}
+
+export function stopGraphProviders(paths, envPath, options = {}) {
+  const args = [
+    'compose',
+    '--env-file', envPath,
+    '-f', paths.graphComposePath,
+    'stop'
+  ];
+  if (options.personalOnly) args.push('personal-provider', 'personal-neo4j');
+  runDockerCompose(args);
+}
+
+function spawnWebRuntime(input) {
+  mkdirSync(dirname(input.paths.logPath), { recursive: true });
+  const log = openSync(input.paths.logPath, 'a');
+  try {
+    const child = spawn(input.nodePath, [
+      input.paths.serverPath,
+      '--runtime-config', input.paths.graphRuntimeConfigPath,
+      '--port', String(input.port)
+    ], {
+      detached: true,
+      windowsHide: true,
+      stdio: ['ignore', log, log]
+    });
+    child.unref();
+    return child;
+  } finally {
+    closeSync(log);
+  }
+}
+
+function stopOwnedLegacyRuntime(paths, deps) {
+  deps.stopLegacyService();
+  const state = deps.readState(paths.statePath);
+  if (state?.version !== 1 || state.dbPath !== paths.dbPath || !Number.isInteger(state.pid)) return;
+  if (deps.isProcessAlive(state.pid)) deps.stopProcess(state.pid);
+}
+
+function graphDependencies(overrides) {
+  return {
+    fetch: globalThis.fetch,
+    fileExists: existsSync,
+    readText: (path) => readFileSync(path, 'utf8'),
+    writeText: (path, value) => writeFileSync(path, value, { mode: 0o600 }),
+    secureFile: (path) => chmodSync(path, 0o600),
+    ensureDirectory: (path) => mkdirSync(path, { recursive: true }),
+    readConfig: (path) => readJsonFile(path, null),
+    writeConfig: writeJsonFileAtomic,
+    readState: (path) => readJsonFile(path, null),
+    writeState: writeJsonFileAtomic,
+    ensureContainerRuntime,
+    startProviders: startGraphProviders,
+    spawnWebRuntime,
+    isProcessAlive,
+    stopProcess,
+    stopLegacyService,
+    webHealth: checkLocalConsoleHealth,
+    ...overrides
+  };
+}
+
+export async function checkLocalConsoleHealth(url, expectedPid, stateVersion = 3) {
+  try {
+    const response = await fetch(`${url}/api/health`, {
+      signal: AbortSignal.timeout(2500)
+    });
+    if (response.ok) {
+      const body = await response.json();
+      return body?.service === 'fuli-local-console' &&
+        (!Number.isInteger(expectedPid) || body.pid === expectedPid);
+    }
+    if (response.status !== 404 || stateVersion !== 2) return false;
+  } catch {
+    return false;
+  }
+
+  try {
+    return (await fetch(`${url}/api/state`, { signal: AbortSignal.timeout(2500) })).ok;
+  } catch {
+    return false;
+  }
+}
+
+function isGraphRuntimeState(state) {
+  return (state?.version === 2 || state?.version === 3) &&
+    Number.isInteger(state.pid) && typeof state.url === 'string';
+}
+
+function stopLegacyService() {
+  if (process.platform !== 'darwin') return;
+  spawnSync('launchctl', ['remove', 'dev.jevonscode.fuli.local'], {
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: 'ignore'
+  });
+}
+
+function parseEnv(body) {
+  return Object.fromEntries(body.split(/\r?\n/).filter(Boolean).map((line) => {
+    const index = line.indexOf('=');
+    return [line.slice(0, index), line.slice(index + 1)];
+  }));
+}
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function secret() {
+  return randomBytes(32).toString('base64url');
+}
+
+function isProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function stopProcess(pid) {
+  try { process.kill(pid, 'SIGTERM'); } catch { /* already stopped */ }
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/setup/node-runtime.js

@@ -0,0 +1,24 @@
+const MINIMUM_NODE_VERSION = Object.freeze([24, 12, 0]);
+
+export function assertSupportedNodeVersion(version = process.versions.node) {
+  const parsed = parseNodeVersion(version);
+  if (compareVersions(parsed, MINIMUM_NODE_VERSION) >= 0) return;
+  throw new Error(
+    `fl setup 需要 Node.js 24.12 或更高版本；当前为 ${version}。` +
+    `请升级 Node.js 后重新运行 fl setup。`
+  );
+}
+
+function parseNodeVersion(value) {
+  const match = String(value).match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!match) throw new Error(`无法识别 Node.js 版本：${value}`);
+  return match.slice(1).map(Number);
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < right.length; index += 1) {
+    const difference = left[index] - right[index];
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}

package/src/setup/options.js

@@ -0,0 +1,91 @@
+import { DEFAULT_FULI_PORT } from '../defaults.js';
+
+const VALUE_OPTIONS = Object.freeze({
+  '--data-dir': 'dataDir',
+  '--personal-space': 'personalSpaceName',
+  '--port': 'port'
+});
+
+const BOOLEAN_OPTIONS = Object.freeze({
+  '--yes': 'yes',
+  '--codex-only': 'codexOnly',
+  '--skip-agents': 'skipAgents',
+  '--no-start': 'noStart'
+});
+
+const PROVIDER_MODE_OPTIONS = new Set(['--personal-only', '--with-dev-public']);
+
+export function parseSetupOptions(args = []) {
+  const result = {
+    dataDir: null,
+    personalSpaceName: '我',
+    port: DEFAULT_FULI_PORT,
+    yes: false,
+    codexOnly: false,
+    skipAgents: false,
+    personalOnly: true,
+    noStart: false
+  };
+  const seen = new Set();
+
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index];
+    if (seen.has(flag)) throw new TypeError(`Duplicate ${flag}`);
+    if (PROVIDER_MODE_OPTIONS.has(flag)) {
+      const conflicting = flag === '--personal-only' ? '--with-dev-public' : '--personal-only';
+      if (seen.has(conflicting)) {
+        throw new TypeError('--personal-only and --with-dev-public cannot be combined');
+      }
+      result.personalOnly = flag !== '--with-dev-public';
+      seen.add(flag);
+      continue;
+    }
+    const booleanKey = BOOLEAN_OPTIONS[flag];
+    if (booleanKey) {
+      result[booleanKey] = true;
+      seen.add(flag);
+      continue;
+    }
+    const valueKey = VALUE_OPTIONS[flag];
+    if (!valueKey) throw new TypeError(`Unknown setup option: ${flag}`);
+    const value = args[index + 1];
+    if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new TypeError(`Missing value for ${flag}`);
+    }
+    result[valueKey] = valueKey === 'port' ? parsePort(value) : value.trim();
+    seen.add(flag);
+    index += 1;
+  }
+  return result;
+}
+
+export function parseUninstallOptions(args = []) {
+  const result = { dataDir: null, yes: false };
+  const seen = new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index];
+    if (seen.has(flag)) throw new TypeError(`Duplicate ${flag}`);
+    if (flag === '--yes') {
+      result.yes = true;
+      seen.add(flag);
+      continue;
+    }
+    if (flag !== '--data-dir') throw new TypeError(`Unknown uninstall option: ${flag}`);
+    const value = args[index + 1];
+    if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new TypeError('Missing value for --data-dir');
+    }
+    result.dataDir = value.trim();
+    seen.add(flag);
+    index += 1;
+  }
+  return result;
+}
+
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new TypeError('--port must be between 1 and 65535');
+  }
+  return port;
+}

package/src/setup/paths.js

@@ -0,0 +1,47 @@
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+export function resolveSetupPaths({
+  dataDir = null,
+  cwd = process.cwd(),
+  platform = process.platform,
+  env = process.env,
+  homeDir = homedir(),
+  packageRoot = DEFAULT_PACKAGE_ROOT
+} = {}) {
+  const resolvedDataDir = resolve(cwd, dataDir ?? defaultDataDir({ platform, env, homeDir }));
+  const root = resolve(packageRoot);
+  return {
+    dataDir: resolvedDataDir,
+    dbPath: join(resolvedDataDir, 'context.db'),
+    graphEnvPath: join(resolvedDataDir, 'graph-provider.env'),
+    graphRuntimeConfigPath: join(resolvedDataDir, 'graph-runtime.json'),
+    graphRuntimeStatePath: join(resolvedDataDir, 'graph-runtime-state.json'),
+    backupDir: join(resolvedDataDir, 'backups', 'agents'),
+    logPath: join(resolvedDataDir, 'logs', 'runtime.log'),
+    statePath: join(resolvedDataDir, 'runtime.json'),
+    serverPath: join(root, 'src', 'server.js'),
+    mcpServerPath: join(root, 'src', 'mcp-server.js'),
+    graphSetupPath: join(root, 'src', 'graphiti', 'setup.js'),
+    graphComposePath: join(root, 'compose.graphiti.yml'),
+    sessionSkillPath: join(root, 'skills', 'capturing-session-knowledge'),
+    projectSkillPath: join(root, 'skills', 'grilling-project')
+  };
+}
+
+function defaultDataDir({ platform, env, homeDir }) {
+  if (platform === 'win32') {
+    return join(nonEmpty(env.LOCALAPPDATA) ?? join(homeDir, 'AppData', 'Local'), 'Fuli');
+  }
+  if (platform === 'darwin') {
+    return join(homeDir, 'Library', 'Application Support', 'Fuli');
+  }
+  return join(nonEmpty(env.XDG_DATA_HOME) ?? join(homeDir, '.local', 'share'), 'fuli');
+}
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim() ? value : null;
+}

package/src/setup/session-skill.js

@@ -0,0 +1,91 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync
+} from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+export function installSessionSkill(agent, {
+  sourcePath,
+  backupDir,
+  clock = () => new Date()
+}) {
+  if (!agent.skillPath) throw new TypeError(`Missing Skill path for ${agent.label}`);
+  const sourceEntry = join(sourcePath, 'SKILL.md');
+  if (!existsSync(sourceEntry)) throw new Error('Fuli session Skill source is missing');
+
+  if (isSessionSkillCurrent(sourcePath, agent.skillPath)) {
+    return { status: 'current', path: agent.skillPath, backupPath: null };
+  }
+
+  mkdirSync(dirname(agent.skillPath), { recursive: true });
+  let backupPath = null;
+  if (existsSync(agent.skillPath)) {
+    const stamp = clock().toISOString().replaceAll(/[:.]/g, '-');
+    backupPath = join(backupDir, 'skills', `${agent.id}-${stamp}`, basename(agent.skillPath));
+    mkdirSync(dirname(backupPath), { recursive: true });
+    renameSync(agent.skillPath, backupPath);
+  }
+
+  const stagingPath = `${agent.skillPath}.fuli-installing`;
+  rmSync(stagingPath, { recursive: true, force: true });
+  try {
+    cpSync(sourcePath, stagingPath, { recursive: true, errorOnExist: true });
+    renameSync(stagingPath, agent.skillPath);
+  } catch (error) {
+    rmSync(stagingPath, { recursive: true, force: true });
+    if (backupPath && !existsSync(agent.skillPath)) renameSync(backupPath, agent.skillPath);
+    throw error;
+  }
+
+  return { status: 'installed', path: agent.skillPath, backupPath };
+}
+
+export function isSessionSkillCurrent(sourcePath, targetPath) {
+  const sourceEntry = join(sourcePath, 'SKILL.md');
+  const targetEntry = join(targetPath, 'SKILL.md');
+  if (!existsSync(sourceEntry) || !existsSync(targetEntry)) return false;
+  try {
+    const sourceFiles = listFiles(sourcePath);
+    const targetFiles = listFiles(targetPath);
+    if (
+      sourceFiles.length !== targetFiles.length ||
+      sourceFiles.some((file, index) => file !== targetFiles[index])
+    ) {
+      return false;
+    }
+    return sourceFiles.every((file) => (
+      readFileSync(join(sourcePath, file)).equals(readFileSync(join(targetPath, file)))
+    ));
+  } catch {
+    return false;
+  }
+}
+
+export function removeBundledSkill(agent, {
+  sourcePath,
+  fileExists = existsSync,
+  remove = rmSync
+}) {
+  if (!agent.skillPath || !fileExists(agent.skillPath)) {
+    return { status: 'not_installed', path: agent.skillPath ?? null };
+  }
+  if (!isSessionSkillCurrent(sourcePath, agent.skillPath)) {
+    return { status: 'preserved_modified', path: agent.skillPath };
+  }
+  remove(agent.skillPath, { recursive: true, force: false });
+  return { status: 'removed', path: agent.skillPath };
+}
+
+function listFiles(root, directory = '') {
+  return readdirSync(join(root, directory), { withFileTypes: true })
+    .flatMap((entry) => {
+      const relativePath = join(directory, entry.name);
+      return entry.isDirectory() ? listFiles(root, relativePath) : [relativePath];
+    })
+    .sort();
+}

package/src/setup/setup.js

@@ -0,0 +1,85 @@
+import { backupAgentConfig } from './config-backup.js';
+import { inspectAgentInstallations } from './agent-installation-status.js';
+import { connectAgent, discoverAgents } from './agents.js';
+import { resolveSetupPaths } from './paths.js';
+import { ensureGraphRuntime } from './graph-runtime.js';
+import { installSessionSkill } from './session-skill.js';
+
+export function planLocalSetup(options, {
+  env = process.env,
+  resolvePaths = resolveSetupPaths,
+  discover = discoverAgents,
+  inspectInstallations = inspectAgentInstallations,
+  nodePath = process.execPath
+} = {}) {
+  const paths = resolvePaths({ dataDir: options.dataDir, env });
+  const discovered = options.skipAgents ? [] : discover({ env });
+  const agents = options.codexOnly
+    ? discovered.filter(({ id }) => id === 'codex')
+    : discovered;
+  return {
+    paths,
+    agents: inspectInstallations(agents, {
+      nodePath,
+      mcpServerPath: paths.mcpServerPath,
+      runtimeConfigPath: paths.graphRuntimeConfigPath,
+      sessionSkillPath: paths.sessionSkillPath,
+      projectSkillPath: paths.projectSkillPath
+    })
+  };
+}
+
+export async function applyLocalSetup(plan, options, dependencies = {}) {
+  const ensureRuntime = dependencies.ensureRuntime ?? ensureGraphRuntime;
+  const backupConfig = dependencies.backupConfig ?? backupAgentConfig;
+  const connect = dependencies.connect ?? connectAgent;
+  const installSkill = dependencies.installSkill ?? installSessionSkill;
+  const runtime = await ensureRuntime({
+    paths: plan.paths,
+    personalSpaceName: options.personalSpaceName,
+    port: options.port,
+    personalOnly: options.personalOnly,
+    noStart: options.noStart,
+    env: dependencies.env ?? process.env,
+    onProgress: dependencies.onProgress
+  });
+  const context = {
+    nodePath: dependencies.nodePath ?? process.execPath,
+    mcpServerPath: plan.paths.mcpServerPath,
+    runtimeConfigPath: plan.paths.graphRuntimeConfigPath
+  };
+  const agents = [];
+
+  for (const agent of plan.agents.filter(
+    ({ available, selected }) => available && selected !== false
+  )) {
+    try {
+      const backupPath = backupConfig(agent, { backupDir: plan.paths.backupDir });
+      const connected = connect(agent, context);
+      const skills = [
+        installSkill(agent, {
+          sourcePath: plan.paths.sessionSkillPath,
+          backupDir: plan.paths.backupDir
+        }),
+        installSkill({ ...agent, skillPath: agent.projectSkillPath }, {
+          sourcePath: plan.paths.projectSkillPath,
+          backupDir: plan.paths.backupDir
+        })
+      ];
+      agents.push({ ...connected, backupPath, skills });
+    } catch (error) {
+      agents.push({
+        id: agent.id,
+        label: agent.label,
+        status: 'failed',
+        message: error instanceof Error ? error.message : 'Agent connection failed'
+      });
+    }
+  }
+
+  return {
+    status: agents.some(({ status }) => status === 'failed') ? 'partial' : 'ready',
+    runtime,
+    agents
+  };
+}