fuli-context 0.7.5 → 0.7.7

package/src/cli/remote-mcp-command.js

@@ -0,0 +1,282 @@
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  openSync,
+  readFileSync
+} from 'node:fs';
+import { resolve } from 'node:path';
+
+import {
+  bindRuntimeLeaseAgentTools,
+  createRuntimeLeaseClient
+} from '../adaptive-runtime/lease-client.js';
+import { openFederatedGraphApplication } from '../graphiti/federated-application.js';
+import { resolveGraphRuntimeOptions } from '../graphiti/runtime-config.js';
+import { createRemoteMcpHttpServer } from '../mcp/remote-http-server.js';
+import { normalizeMcpSourceApplication } from '../mcp/session-id.js';
+
+const DEFAULT_REMOTE_MCP_PORT = 2728;
+const DEFAULT_REMOTE_MCP_MAX_SESSIONS = 8;
+const DEFAULT_REMOTE_MCP_SESSION_IDLE_TTL_SECONDS = 15 * 60;
+const REMOTE_MCP_OPTIONS = new Set([
+  '--personal-project-id', '--bearer-token-file', '--data-dir', '--host', '--port',
+  '--source-application', '--allowed-origin', '--allowed-host', '--max-sessions',
+  '--session-idle-ttl-seconds'
+]);
+
+export function parseRemoteMcpOptions(args) {
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    if (!REMOTE_MCP_OPTIONS.has(flag)) {
+      throw new TypeError(`Unknown remote MCP option: ${flag}`);
+    }
+    const value = args[index + 1];
+    if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+      throw new TypeError(`Missing value for ${flag}`);
+    }
+  }
+  const personalProjectId = requiredOption(args, '--personal-project-id');
+  const bearerTokenFile = requiredOption(args, '--bearer-token-file');
+  const dataDir = optionalOption(args, '--data-dir');
+  const host = optionalOption(args, '--host') ?? '127.0.0.1';
+  if (!['127.0.0.1', '::1', 'localhost'].includes(host)) {
+    throw new TypeError('Remote MCP must bind to a loopback host behind an authenticated HTTPS proxy');
+  }
+  const port = numberOption(args, '--port', DEFAULT_REMOTE_MCP_PORT);
+  const sourceApplication = normalizeMcpSourceApplication(
+    optionalOption(args, '--source-application') ?? 'claude'
+  );
+  const allowedOrigin = optionalOption(args, '--allowed-origin');
+  const allowedHost = optionalOption(args, '--allowed-host');
+  const maxSessions = boundedIntegerOption(
+    args, '--max-sessions', DEFAULT_REMOTE_MCP_MAX_SESSIONS, 1, 64
+  );
+  const sessionIdleTtlSeconds = boundedIntegerOption(
+    args,
+    '--session-idle-ttl-seconds',
+    DEFAULT_REMOTE_MCP_SESSION_IDLE_TTL_SECONDS,
+    10,
+    24 * 60 * 60
+  );
+  return {
+    personalProjectId,
+    bearerTokenFile,
+    dataDir,
+    port,
+    host,
+    sourceApplication,
+    allowedOrigin,
+    allowedHost,
+    maxSessions,
+    sessionIdleTtlSeconds
+  };
+}
+
+export async function runRemoteMcpCommand(args, dependencies = {}) {
+  const options = parseRemoteMcpOptions(args);
+  const env = dependencies.env ?? process.env;
+  const runtimeConfigPath = resolveGraphRuntimeOptions([], env, {
+    setupPaths: { dataDir: options.dataDir ?? undefined }
+  }).runtimeConfigPath;
+  const readToken = dependencies.readBearerToken ?? readBearerToken;
+  const bearerToken = readToken(options.bearerTokenFile);
+  const openApplication = dependencies.openApplication ?? openFederatedGraphApplication;
+  const createLeaseClient = dependencies.createLeaseClient ?? createRuntimeLeaseClient;
+  const bindLeaseTools = dependencies.bindRuntimeLeaseAgentTools
+    ?? bindRuntimeLeaseAgentTools;
+  let app;
+  let leaseClient;
+  let remote;
+  try {
+    app = openApplication({ runtimeConfigPath });
+    leaseClient = createLeaseClient({ runtimeConfigPath });
+    bindLeaseTools(app, leaseClient);
+    await leaseClient.withGraphLease(
+      'remote-mcp-project-preflight',
+      () => assertPersonalProjectExists(
+        app,
+        app.config.personal.spaceId,
+        options.personalProjectId
+      )
+    );
+    remote = await (dependencies.createRemoteServer ?? createRemoteMcpHttpServer)({
+      app,
+      bearerToken,
+      personalProjectId: options.personalProjectId,
+      personalSpaceId: app.config.personal.spaceId,
+      sourceApplication: options.sourceApplication,
+      host: options.host,
+      port: options.port,
+      allowedOrigins: options.allowedOrigin ? [options.allowedOrigin] : [],
+      allowedHosts: options.allowedHost ? [options.allowedHost] : [],
+      maxSessions: options.maxSessions,
+      sessionIdleTtlMs: options.sessionIdleTtlSeconds * 1000,
+      withRuntimeLease: (owner, operation) => leaseClient.withGraphLease(owner, operation)
+    });
+  } catch (error) {
+    await Promise.allSettled([
+      Promise.resolve().then(() => leaseClient?.close?.()),
+      Promise.resolve().then(() => app?.close?.())
+    ]);
+    throw error;
+  }
+
+  const signalTarget = dependencies.signalTarget ?? process;
+  const writeError = dependencies.writeError ?? ((value) => process.stderr.write(value));
+  const reportError = dependencies.reportError ?? ((error) => {
+    writeError(`Fuli remote MCP shutdown failed: ${describeError(error)}\n`);
+  });
+  const setExitCode = dependencies.setExitCode ?? ((code) => { process.exitCode = code; });
+  const handlers = new Map();
+  let closing;
+  const close = () => {
+    if (closing) return closing;
+    closing = Promise.resolve().then(async () => {
+      const failures = [];
+      for (const resource of [remote, leaseClient, app]) {
+        try {
+          await resource.close();
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      if (failures.length === 1) throw failures[0];
+      if (failures.length > 1) {
+        throw new AggregateError(failures, 'Fuli remote MCP shutdown failed');
+      }
+    }).finally(() => {
+      for (const [signal, handler] of handlers) signalTarget.off(signal, handler);
+    });
+    return closing;
+  };
+  const write = dependencies.write ?? ((value) => process.stdout.write(`${value}\n`));
+  try {
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      const handler = () => {
+        void close().catch((error) => {
+          setExitCode(1);
+          reportError(error);
+        });
+      };
+      handlers.set(signal, handler);
+      signalTarget.once(signal, handler);
+    }
+    write([
+      `Fuli remote MCP listening on ${remote.url}/mcp`,
+      `Bound project: ${options.personalProjectId}`,
+      'This listener is loopback-only. Publish it only through an authenticated HTTPS OAuth proxy; never expose the local Provider or Neo4j ports.'
+    ].join('\n'));
+  } catch (error) {
+    try {
+      await close();
+    } catch (cleanupError) {
+      const cleanupFailures = cleanupError instanceof AggregateError
+        ? cleanupError.errors
+        : [cleanupError];
+      throw new AggregateError(
+        [error, ...cleanupFailures],
+        'Fuli remote MCP startup finalization failed'
+      );
+    }
+    throw error;
+  }
+  return { status: 'running', url: `${remote.url}/mcp`, close, server: remote.server };
+}
+
+function describeError(error) {
+  if (error instanceof AggregateError) {
+    return error.errors.map(describeError).join('; ');
+  }
+  return error?.message ?? String(error);
+}
+
+async function assertPersonalProjectExists(app, personalSpaceId, personalProjectId) {
+  const projects = await app.listPersonalProjects({ personalSpaceId });
+  if (!Array.isArray(projects) || !projects.some(project => [
+    project?.project_id,
+    project?.projectId,
+    project?.personal_project_id,
+    project?.personalProjectId
+  ].includes(personalProjectId))) {
+    throw new TypeError(
+      `Remote MCP project ${personalProjectId} does not exist in the configured personal space`
+    );
+  }
+}
+
+export function readBearerToken(path, fileSystem = {}) {
+  const open = fileSystem.openSync ?? openSync;
+  const fstat = fileSystem.fstatSync ?? fstatSync;
+  const readFile = fileSystem.readFileSync ?? readFileSync;
+  const close = fileSystem.closeSync ?? closeSync;
+  const constants = fileSystem.constants ?? fsConstants;
+  const absolute = resolve(path);
+  let descriptor;
+  try {
+    descriptor = open(
+      absolute,
+      constants.O_RDONLY
+        | (constants.O_NOFOLLOW ?? 0)
+        | (constants.O_NONBLOCK ?? 0)
+    );
+  } catch (error) {
+    if (error?.code === 'ELOOP' || error?.code === 'EMLINK') {
+      throw new TypeError('Remote MCP bearer token path must not be a symbolic link');
+    }
+    throw error;
+  }
+  try {
+    const metadata = fstat(descriptor);
+    if (!metadata.isFile()) throw new TypeError('Remote MCP bearer token path must be a regular file');
+    if (metadata.size > 4096) {
+      throw new TypeError('Remote MCP bearer token file must not exceed 4096 bytes');
+    }
+    if (process.platform !== 'win32' && (metadata.mode & 0o077) !== 0) {
+      throw new TypeError('Remote MCP bearer token file must be readable only by its owner (chmod 600)');
+    }
+    const token = readFile(descriptor, 'utf8').trim();
+    if (!/^[\x21-\x7E]{24,512}$/.test(token)) {
+      throw new TypeError(
+        'Remote MCP bearer token must contain 24 to 512 visible ASCII characters without spaces'
+      );
+    }
+    return token;
+  } finally {
+    close(descriptor);
+  }
+}
+
+function requiredOption(args, flag) {
+  const value = optionalOption(args, flag);
+  if (!value) throw new TypeError(`Missing ${flag}`);
+  return value;
+}
+
+function optionalOption(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return null;
+  if (args.indexOf(flag, index + 1) !== -1) throw new TypeError(`Duplicate ${flag}`);
+  const value = args[index + 1];
+  if (typeof value !== 'string' || !value.trim() || value.startsWith('--')) {
+    throw new TypeError(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
+function numberOption(args, flag, fallback) {
+  return boundedIntegerOption(args, flag, fallback, 0, 65_535);
+}
+
+function boundedIntegerOption(args, flag, fallback, minimum, maximum) {
+  const value = optionalOption(args, flag);
+  if (value === null) return fallback;
+  if (!/^\d+$/.test(value)) {
+    throw new TypeError(`${flag} must be an integer from ${minimum} to ${maximum}`);
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+    throw new TypeError(`${flag} must be an integer from ${minimum} to ${maximum}`);
+  }
+  return parsed;
+}

package/src/cli/setup-command.js

@@ -96,6 +96,10 @@ export function formatSetupResult(result, plan) {
   }
   lines.push('Knowledge storage: Graphiti / Neo4j');
   for (const agent of result.agents) {
+    if (agent.status === 'partial') {
+      lines.push(`${agent.label}: partially configured; retry setup to finish installation`);
+      continue;
+    }
     if (agent.status !== 'connected') {
       lines.push(`${agent.label}: connection failed; retry setup later`);
       continue;
@@ -103,6 +107,7 @@ export function formatSetupResult(result, plan) {
     lines.push(agent.newTaskRequired
       ? `${agent.label}: connected; create or reopen a task to load the new configuration`
       : `${agent.label}: connected`);
+    for (const step of agent.nextSteps ?? []) lines.push(`${agent.label}: ${step}`);
   }
   return lines.join('\n');
 }

package/src/cli.js

@@ -7,7 +7,9 @@ import {
   printHelp
 } from './cli/command-registry.js';
 import { runLocalRuntimeCommand } from './cli/local-runtime-command.js';
+import { runRemoteMcpCommand } from './cli/remote-mcp-command.js';
 import { runGraphDataCommand } from './cli/graph-data-command.js';
+import { runEmployeeCommand } from './cli/employee-command.js';
 import { runSetupCommand } from './cli/setup-command.js';
 import { runUninstallCommand } from './cli/uninstall-command.js';
 import { runUpdateCommand } from './cli/update-command.js';
@@ -35,10 +37,18 @@ export async function main(argv = process.argv.slice(2), env = process.env) {
     const [action, ...graphArgs] = commandArgs;
     return runGraphDataCommand(action, graphArgs, { env });
   }
+  if (command === 'employee') {
+    assertSupportedNodeVersion();
+    return runEmployeeCommand(commandArgs, { env });
+  }
   if (command === 'connect-workspace') {
     assertSupportedNodeVersion();
     return runWorkspaceConnectionCommand(commandArgs, { env });
   }
+  if (command === 'remote-mcp') {
+    assertSupportedNodeVersion();
+    return runRemoteMcpCommand(commandArgs, { env });
+  }
   if (command === 'uninstall') {
     await runUninstallCommand(commandArgs, { env });
     return;

package/src/employees/catalog/jefa.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "id": "jefa",
+  "version": "1.0.0",
+  "name": "Jefa",
+  "role": "项目经理",
+  "description": "把目标拆成任务，整理看板与进展，留待你确认。",
+  "occupationEmoji": "🧭",
+  "defaultProjectScope": "all",
+  "taskEntry": { "boardTool": "read_board", "titleTool": "prepare_session_title" },
+  "capabilities": ["项目规划", "任务拆解", "看板读写", "迭代复盘"],
+  "workKinds": ["project_management", "planning", "review"],
+  "initialPreferences": [
+    "先读取当前项目的看板，再创建或修改任务；避免重复事项。",
+    "修改任务时携带读取到的 updatedAt 版本；冲突后先重新读取。",
+    "Agent 认为完成时只移入待确认，最终完成由用户决定。",
+    "不推测未上报的模型、token 或执行耗时，不自动扩大项目权限。"
+  ],
+  "permissions": ["board.read", "board.write", "session.title"],
+  "runtime": { "apiVersion": 1, "entry": "runtime/index.mjs", "webRoot": "web" }
+}

package/src/employees/install-package.js

@@ -0,0 +1,77 @@
+import {
+  cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync,
+  readFileSync, readdirSync, renameSync, rmSync, writeFileSync
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { EmployeeError, parseEmployeeManifest } from './manifest.js';
+import { confinedPath, employeeDirectories } from './package-registry.js';
+
+// Installation is an explicit local CLI action. The HTTP/MCP catalog never
+// downloads code, follows a user-supplied executable URL, or executes installers.
+export function installEmployeePackage({ sourceDirectory, runtimeConfigPath, replace = false }) {
+  const source = resolve(sourceDirectory);
+  const digest = packageDigest(source);
+  const manifest = parseEmployeeManifest(JSON.parse(readFileSync(join(source, 'employee.json'), 'utf8')));
+  if (manifest.runtime) {
+    confinedPath(source, manifest.runtime.entry);
+    confinedPath(source, `${manifest.runtime.webRoot}/index.html`);
+  }
+  const { packageDirectory } = employeeDirectories(runtimeConfigPath);
+  mkdirSync(packageDirectory, { recursive: true });
+  const target = join(packageDirectory, manifest.id);
+  if (existsSync(target)) {
+    // Verify the actual installed files, not an old receipt that may outlive an edit.
+    let installedDigest;
+    try { installedDigest = packageDigest(target); } catch { /* Explicit replacement is required for a damaged package. */ }
+    if (installedDigest === digest) {
+      return { id: manifest.id, version: manifest.version, idempotent: true, backupCreated: false };
+    }
+    if (!replace) throw new EmployeeError('Employee package already exists; use --replace to keep a backup and update it', 409, 'package_exists');
+  }
+  const staging = mkdtempSync(join(packageDirectory, '.install-'));
+  let backup;
+  try {
+    cpSync(source, join(staging, 'package'), { recursive: true, dereference: false });
+    if (packageDigest(join(staging, 'package')) !== digest) throw new TypeError('Employee package changed while installing');
+    writeFileSync(join(staging, 'package', '.installation.json'), JSON.stringify({
+      schemaVersion: 1, digest, installedAt: new Date().toISOString()
+    }));
+    if (existsSync(target)) {
+      backup = `${target}.backup-${createHash('sha256').update(staging).digest('hex').slice(0, 12)}`;
+      renameSync(target, backup);
+    }
+    try { renameSync(join(staging, 'package'), target); }
+    catch (error) { if (backup) renameSync(backup, target); throw error; }
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+  return { id: manifest.id, version: manifest.version, idempotent: false, backupCreated: Boolean(backup) };
+}
+
+function packageDigest(root) {
+  let bytes = 0;
+  let files = 0;
+  const hash = createHash('sha256');
+  function walk(directory, prefix = '') {
+    if (lstatSync(directory).isSymbolicLink()) throw new TypeError('Employee packages may not contain symlinks');
+    for (const name of readdirSync(directory).sort()) {
+      if (name === '.env' || name.startsWith('.env.') || ['.git', 'node_modules'].includes(name)) {
+        throw new TypeError('Employee packages must contain only built artifacts, not environments or repositories');
+      }
+      const file = join(directory, name);
+      const stat = lstatSync(file);
+      if (stat.isSymbolicLink()) throw new TypeError('Employee packages may not contain symlinks');
+      // Only the generated root receipt is metadata; nested names are package content.
+      if (name === '.installation.json' && prefix === '' && stat.isFile()) continue;
+      if (stat.isDirectory()) { walk(file, `${prefix}${name}/`); continue; }
+      if (!stat.isFile()) throw new TypeError('Unsupported employee package entry');
+      bytes += stat.size;
+      files += 1;
+      if (bytes > 64 * 1024 * 1024 || files > 4096) throw new TypeError('Employee package exceeds the installation budget');
+      hash.update(`${prefix}${name}\0`).update(readFileSync(file)).update('\0');
+    }
+  }
+  walk(root);
+  return hash.digest('hex');
+}

package/src/employees/management-policy.js

@@ -0,0 +1,88 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { z } from 'zod';
+import { EmployeeError } from './manifest.js';
+
+const projectId = z.string().min(1).max(256);
+export const employeeManagementSchema = z.object({
+  mode: z.enum(['selected', 'all']),
+  projectIds: z.array(projectId).max(500).default([]),
+  excludedProjectIds: z.array(projectId).max(500).default([]),
+  titleMode: z.enum(['off', 'suggest', 'auto']).default('suggest'),
+  titleStyle: z.enum(['text', 'emoji']).default('emoji'),
+}).strict().superRefine((value, context) => {
+  if ((value.mode === 'all' && value.projectIds.length) ||
+    (value.mode === 'selected' && value.excludedProjectIds.length)) {
+    context.addIssue({ code: 'custom', message: 'Use selected project IDs OR all projects with exclusions.' });
+  }
+});
+
+export function parseEmployeeManagement(value) {
+  const result = employeeManagementSchema.safeParse(value);
+  if (!result.success) throw new TypeError('Invalid employee management policy');
+  return { ...result.data, projectIds: [...new Set(result.data.projectIds)].sort(),
+    excludedProjectIds: [...new Set(result.data.excludedProjectIds)].sort() };
+}
+
+// Employee policy is local host configuration, not a public project fact or a
+// Provider model/executor policy. SQLite CAS also protects independent MCP hosts.
+export class EmployeeManagementStore {
+  constructor(path = ':memory:') {
+    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true });
+    this.database = new DatabaseSync(path);
+    this.database.exec(`PRAGMA busy_timeout = 5000;
+      CREATE TABLE IF NOT EXISTS employee_management (
+        space_id TEXT NOT NULL, template_id TEXT NOT NULL,
+        revision INTEGER NOT NULL, policy TEXT NOT NULL,
+        PRIMARY KEY (space_id, template_id)
+      )`);
+  }
+  read(spaceId, templateId) {
+    const row = this.database.prepare('SELECT revision, policy FROM employee_management WHERE space_id = ? AND template_id = ?').get(spaceId, templateId);
+    return row ? { revision: row.revision, ...parseEmployeeManagement(JSON.parse(row.policy)) } : null;
+  }
+  write(spaceId, templateId, policy, expectedRevision) {
+    const parsed = parseEmployeeManagement(policy);
+    this.database.exec('BEGIN IMMEDIATE');
+    try {
+      const current = this.read(spaceId, templateId);
+      if ((current?.revision ?? 0) !== expectedRevision) {
+        throw new EmployeeError('Employee policy changed; reload before saving', 409, 'assignment_scope_conflict');
+      }
+      const revision = expectedRevision + 1;
+      this.database.prepare(`INSERT INTO employee_management (space_id, template_id, revision, policy) VALUES (?, ?, ?, ?)
+        ON CONFLICT(space_id, template_id) DO UPDATE SET revision = excluded.revision, policy = excluded.policy`)
+        .run(spaceId, templateId, revision, JSON.stringify(parsed));
+      this.database.exec('COMMIT');
+      return { ...parsed, revision };
+    } catch (error) { this.database.exec('ROLLBACK'); throw error; }
+  }
+  close() { if (!this.closed) { this.closed = true; this.database.close(); } }
+}
+
+export function managementFor(manifest, agent, stored) {
+  if (stored) {
+    if (stored.mode !== 'all') return stored;
+    // Ending the last assignment is an explicit prohibition too. Keep that
+    // veto until a scope edit explicitly reselects/reassigns the project.
+    const history = agent?.assignments ?? [];
+    const activeIds = new Set(history.filter(a => a.status === 'active').map(a => a.personalProjectId));
+    const endedIds = history.filter(a => a.status === 'ended' && !activeIds.has(a.personalProjectId)).map(a => a.personalProjectId);
+    return { ...stored, excludedProjectIds: [...new Set([...stored.excludedProjectIds, ...endedIds])].sort() };
+  }
+  // Upgrades preserve existing authorization. Only a new recruitment uses the
+  // template default; an existing employee opts in by saving the new all rule.
+  return { revision: 0, mode: agent ? 'selected' : manifest.defaultProjectScope ?? 'selected',
+    projectIds: [...new Set((agent?.assignments ?? []).filter(a => a.status === 'active').map(a => a.personalProjectId))],
+    excludedProjectIds: [], titleMode: manifest.taskEntry ? 'auto' : 'suggest', titleStyle: 'emoji' };
+}
+
+export function policyAllowsProject(policy, id) {
+  return policy.mode === 'all' ? !policy.excludedProjectIds.includes(id) : policy.projectIds.includes(id);
+}
+
+export function managementWithoutRevision(policy) {
+  const { revision: _revision, ...value } = policy;
+  return parseEmployeeManagement(value);
+}

package/src/employees/manifest.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { ApplicationError } from '../app/application-error.js';
+
+const identifier = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
+const toolIdentifier = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/);
+const relativeFile = z.string().min(1).max(160).refine(
+  (value) => !value.startsWith('/') && !value.includes('\\') &&
+    !value.split('/').some((part) => !part || part === '.' || part === '..') &&
+    !value.includes(':'),
+  'Employee package paths must stay inside the package'
+);
+
+export const employeeManifestSchema = z.object({
+  schemaVersion: z.literal(1),
+  id: identifier,
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  name: z.string().trim().min(1).max(100),
+  role: z.string().trim().min(1).max(100),
+  description: z.string().trim().min(1).max(1000),
+  occupationEmoji: z.string().min(1).max(32),
+  capabilities: z.array(z.string().min(1).max(180)).max(24),
+  workKinds: z.array(z.string().min(1).max(180)).max(24),
+  initialPreferences: z.array(z.string().min(1).max(512)).max(24),
+  permissions: z.array(z.string().regex(/^[a-z][a-z0-9_-]*(?:\.[a-z0-9_-]+)+$/)).max(24),
+  defaultProjectScope: z.enum(['selected', 'all']).optional(),
+  taskEntry: z.object({
+    boardTool: toolIdentifier,
+    titleTool: toolIdentifier.optional(),
+  }).strict().optional(),
+  runtime: z.object({
+    apiVersion: z.literal(1),
+    entry: relativeFile,
+    webRoot: relativeFile
+  }).strict().nullable()
+}).strict();
+
+export function parseEmployeeManifest(value) {
+  const parsed = employeeManifestSchema.safeParse(value);
+  if (!parsed.success) throw new TypeError('Invalid employee package manifest');
+  return parsed.data;
+}
+
+export const employeeAgentId = (id) => `employee.${identifier.parse(id)}`;
+export const employeeCapability = (id) => `fuli.employee:${identifier.parse(id)}`;
+
+export class EmployeeError extends ApplicationError {
+  constructor(message, status = 400, code = 'employee_error') {
+    super(code, message);
+    this.name = 'EmployeeError';
+    this.status = status;
+    this.code = code;
+  }
+}

package/src/employees/package-registry.js

@@ -0,0 +1,107 @@
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { EmployeeError, parseEmployeeManifest } from './manifest.js';
+
+const builtinRoot = fileURLToPath(new URL('./catalog/', import.meta.url));
+
+export function createEmployeePackageRegistry({ packageDirectory, dataDirectory, catalogDirectory = builtinRoot }) {
+  const runtimes = new Map();
+  let closed = false;
+
+  function catalog() {
+    const entries = new Map();
+    for (const file of readdirSync(catalogDirectory).filter((name) => name.endsWith('.json'))) {
+      const manifest = readManifest(join(catalogDirectory, file));
+      entries.set(manifest.id, { manifest, root: null, runtimeStatus: manifest.runtime ? 'install_required' : 'not_required' });
+    }
+    if (packageDirectory && existsSync(packageDirectory)) {
+      for (const name of readdirSync(packageDirectory)) {
+        if (!/^[a-z][a-z0-9-]{0,63}$/.test(name)) continue;
+        const root = join(packageDirectory, name);
+        try {
+          if (!statSync(root).isDirectory()) continue;
+          confinedPath(packageDirectory, name);
+          const manifest = readManifest(confinedPath(root, 'employee.json'));
+          if (manifest.id !== name) continue;
+          if (manifest.runtime) {
+            confinedPath(root, manifest.runtime.entry);
+            confinedPath(root, `${manifest.runtime.webRoot}/index.html`);
+          }
+          entries.set(name, { manifest, root, runtimeStatus: manifest.runtime ? 'ready' : 'not_required' });
+        } catch {
+          const previous = entries.get(name);
+          if (previous) entries.set(name, { ...previous, runtimeStatus: 'unavailable' });
+        }
+      }
+    }
+    return [...entries.values()];
+  }
+
+  function get(id) {
+    const entry = catalog().find(({ manifest }) => manifest.id === id);
+    if (!entry) throw new EmployeeError('Employee template not found', 404, 'template_not_found');
+    return entry;
+  }
+
+  async function runtime(id) {
+    if (closed) throw new EmployeeError('Employee runtime is closed', 503, 'runtime_closed');
+    const entry = get(id);
+    if (entry.runtimeStatus !== 'ready' || !entry.manifest.runtime) {
+      throw new EmployeeError('Employee workbench package is not installed or unavailable', 503, 'runtime_unavailable');
+    }
+    if (!runtimes.has(id)) {
+      const loading = (async () => {
+        const module = await import(pathToFileURL(confinedPath(entry.root, entry.manifest.runtime.entry)).href);
+        if (typeof module.createEmployeeRuntime !== 'function') throw new TypeError('Invalid employee runtime export');
+        const instance = await module.createEmployeeRuntime({
+          dataDirectory: resolve(dataDirectory, id),
+          packageDirectory: entry.root,
+          manifest: entry.manifest
+        });
+        if (!instance || !['handleHttp', 'callTool', 'describeTools', 'close'].every(
+          (name) => typeof instance[name] === 'function'
+        )) {
+          instance?.close?.();
+          throw new TypeError('Employee runtime does not implement API version 1');
+        }
+        if (closed) { await instance.close(); throw new Error('Employee runtime is closed'); }
+        return instance;
+      })().catch(() => {
+        runtimes.delete(id);
+        throw new EmployeeError('Employee runtime could not be loaded', 503, 'runtime_unavailable');
+      });
+      runtimes.set(id, loading);
+    }
+    return runtimes.get(id);
+  }
+
+  return {
+    catalog, get, runtime,
+    async close() {
+      closed = true;
+      await Promise.allSettled([...runtimes.values()].map(async (entry) => (await entry).close()));
+      runtimes.clear();
+    }
+  };
+}
+
+export function confinedPath(root, file) {
+  const resolvedRoot = realpathSync(root);
+  const resolvedFile = realpathSync(resolve(root, file));
+  const local = relative(resolvedRoot, resolvedFile);
+  if (local === '..' || local.startsWith(`..${sep}`) || isAbsolute(local)) {
+    throw new TypeError('Employee package path escapes its installation');
+  }
+  return resolvedFile;
+}
+
+function readManifest(file) {
+  if (statSync(file).size > 32_768) throw new TypeError('Employee manifest is too large');
+  return parseEmployeeManifest(JSON.parse(readFileSync(file, 'utf8')));
+}
+
+export function employeeDirectories(runtimeConfigPath) {
+  const root = join(dirname(runtimeConfigPath), 'employees');
+  return { packageDirectory: join(root, 'packages'), dataDirectory: join(root, 'data') };
+}