@inixiative/archive 0.3.0 → 0.4.0

package/README.md

@@ -45,20 +45,41 @@ Use `--source claude-code` for Claude histories. Collection matches the exact wo
 
 Deploy the included Dockerfile with a persistent volume mounted at `/data`, HTTPS, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters. Compose bind-mounts `./data` (or `ARCHIVE_DATA_DIR`) at `/data`, so the store survives rebuilds, `down -v` and volume prunes, and binds only to loopback on port 4411 (or `ARCHIVE_PORT`); put an HTTPS reverse proxy in front for remote use. Railway needs a `/data` volume. The Render blueprint provisions a dedicated disk and generated token.
 
-Place the destination's token in an environment variable, then run:
+Place the destination's token in a private file (`chmod 600`, owned by you) or an environment variable, then run:
 
 ```sh
-bun run archive connect --url https://your-archive.example --project-id inixiative --token-env INIXIATIVE_ARCHIVE_TOKEN
+bun run archive connect --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/credentials/inixiative.token
 bun run archive routes
 bun run archive sync
 bun run archive sync --watch
 bun run archive search --remote --query 'migration'
 ```
 
-`setup` is an alias for `connect`. Setup verifies access before saving configuration and does not upload. The URL locates the server; the token grants access. Configuration stores only the environment variable name. Secrets must be available in the collector/sync process environment. Redirects are refused; only HTTPS or loopback HTTP is allowed.
+`setup` is an alias for `connect`. Setup verifies access before saving configuration and does not upload. The URL locates the server; the token grants access. Configuration stores only the token file path (`tokenFile`) or environment variable name (`--token-env`, `tokenEnv`), never the token. A token file is read on every request, so rotating it needs no restart; symlinks and files readable by group or others are refused. An environment variable must be set in the sync process environment. Redirects are refused; only HTTPS or loopback HTTP is allowed.
 
 `--home PATH`, `--store FILE` and `--config FILE` support custom paths. Keep the database with its source UUID when moving machines. Back up the entire database; a new store creates a new source identity.
 
+## Always-on local archiving
+
+`archive agents` declares long-running agents in `~/.local/share/archive/agents.json` and installs them as launchd agents (macOS) or systemd user units (Linux):
+
+```sh
+archive init
+archive connect --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/credentials/inixiative.token
+archive agents add-collector --name claude-code.inixiative --source claude-code --project-id inixiative --project-root ~/code/inixiative --worktrees
+archive agents add-collector --name codex.inixiative --source codex --project-id inixiative --project-root ~/code/inixiative --worktrees
+archive agents serve on
+archive agents sync on
+archive agents install
+archive agents status
+```
+
+`add-collector` upserts by `--name` (lowercase letters, digits, `.` and `-`); `--directory` defaults to `~/.claude/projects` or `~/.codex/sessions`, and `--project-root`, `--worktrees` and `--atlas` behave as for `collect`. `remove-collector --name N`, `serve on|off [--port P]` and `sync on|off` edit the same file. `install` writes one unit per agent: `com.inixiative.archive.local` (serve), `com.inixiative.archive.sync` (`sync --watch`) and `com.inixiative.archive.collect.<name>`. Each runs the current Bun with this package's own `src/cli.ts`, restarts on exit (30 second throttle), works in the archive home and logs to `logs/<label>.{out,err}.log` there. Re-running `install` reloads only changed or stopped units and removes Archive units no longer declared; other launchd agents are untouched. `uninstall` removes every Archive unit; `status` reports each unit's load state, PID and last log entry. One archive home per user account: units are named by agent, not by home. Sync reads destination token files itself, so no wrapper script is needed. Re-run `install` after upgrading the package if its install path changes.
+
+Docker Compose is the alternative for the server: `docker compose up -d` bind-mounts `./data` (or `ARCHIVE_DATA_DIR`) at `/data` and binds loopback port 4411. It is a separate store, so connect it as a destination and let the `sync` agent publish to it; do not bind-mount the store the host agents are writing, since SQLite locking across the Docker VM boundary is unreliable. Collectors run on the host, where the session histories are.
+
+`@inixiative/archive/agents` exports the pure pieces for integrations: `agentsConfigSchema`, `agentUnits`, `renderPlist`, `renderSystemdUnit` and `planAgents`, plus `installAgents`, `uninstallAgents` and `agentStatus` with an injectable command runner and supervisor directory.
+
 ## Connect through Kingdom
 
 Pair a runtime with Kingdom (Foundry: Settings → Kingdom) and expose its `kastle_runtime_` credential in an environment variable, then either let Kingdom store the archives:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/archive",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -14,7 +14,8 @@
     "./cli": "./src/cli.ts",
     "./collector": "./src/collector.ts",
     "./chatgpt": "./src/chatgpt.ts",
-    "./tags": "./src/tags.ts"
+    "./tags": "./src/tags.ts",
+    "./agents": "./src/agents.ts"
   },
   "files": [
     "src"
@@ -35,7 +36,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.36",
+    "@inixiative/config": "^0.5.37",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/agents.ts

@@ -0,0 +1,386 @@
+import { randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+
+export const defaultHome = () => join(homedir(), '.local/share/archive');
+export const AGENT_LABEL_PREFIX = 'com.inixiative.archive.';
+/** History each provider writes by default. */
+export const defaultHistoryDirectory = (source: 'claude-code' | 'codex') =>
+  join(homedir(), source === 'codex' ? '.codex/sessions' : '.claude/projects');
+
+const absolute = z.string().max(4096).refine(isAbsolute, 'Path must be absolute');
+export const collectorAgentSchema = z.strictObject({
+  name: z
+    .string()
+    .max(64)
+    .regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/),
+  source: z.enum(['claude-code', 'codex']),
+  directory: absolute,
+  projectId: z.string().min(1).max(256),
+  projectRoots: z.array(absolute).min(1).max(100),
+  worktrees: z.boolean().optional(),
+  atlas: z.boolean().optional(),
+});
+export const agentsConfigSchema = z
+  .strictObject({
+    serve: z.strictObject({ port: z.number().int().min(1).max(65535).optional() }).optional(),
+    sync: z.boolean().optional(),
+    collectors: z.array(collectorAgentSchema).max(100),
+  })
+  .refine(
+    (c) => new Set(c.collectors.map((x) => x.name)).size === c.collectors.length,
+    'Collector names must be unique',
+  );
+export type AgentsConfig = z.infer<typeof agentsConfigSchema>;
+export type CollectorAgent = z.infer<typeof collectorAgentSchema>;
+
+export const readAgents = (file: string): AgentsConfig | undefined =>
+  existsSync(file) ? agentsConfigSchema.parse(JSON.parse(readFileSync(file, 'utf8'))) : undefined;
+export function writeAgents(file: string, input: AgentsConfig) {
+  const config = agentsConfigSchema.parse(input);
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  renameSync(temp, file);
+  chmodSync(file, 0o600);
+  return config;
+}
+export function upsertCollector(config: AgentsConfig | undefined, collector: CollectorAgent) {
+  const collectors = (config?.collectors ?? []).filter((c) => c.name !== collector.name);
+  return { ...config, collectors: [...collectors, collectorAgentSchema.parse(collector)] };
+}
+
+export interface AgentUnit {
+  label: string;
+  /** Full argv: runtime, CLI entrypoint, command. */
+  args: string[];
+  workingDirectory: string;
+  stdout: string;
+  stderr: string;
+}
+export interface AgentUnitOptions {
+  home: string;
+  execPath?: string;
+  /** Defaults to this package's own CLI, wherever it is installed. */
+  cliPath?: string;
+}
+export const packageCliPath = () => fileURLToPath(new URL('./cli.ts', import.meta.url));
+
+export function collectorArgs(c: CollectorAgent) {
+  return [
+    'collect',
+    '--directory',
+    c.directory,
+    '--source',
+    c.source,
+    ...c.projectRoots.flatMap((root) => ['--project-root', root]),
+    ...(c.worktrees ? ['--worktrees'] : []),
+    ...(c.atlas ? ['--atlas'] : []),
+    '--project-id',
+    c.projectId,
+    '--watch',
+  ];
+}
+
+/** One supervised unit per declared agent. */
+export function agentUnits(config: AgentsConfig, options: AgentUnitOptions): AgentUnit[] {
+  const home = resolve(options.home);
+  const base = [options.execPath ?? process.execPath, options.cliPath ?? packageCliPath()];
+  const homeArgs = home === resolve(defaultHome()) ? [] : ['--home', home];
+  const unit = (suffix: string, command: string[]): AgentUnit => {
+    const label = AGENT_LABEL_PREFIX + suffix;
+    return {
+      label,
+      args: [...base, ...command, ...homeArgs],
+      workingDirectory: home,
+      stdout: join(home, 'logs', `${label}.out.log`),
+      stderr: join(home, 'logs', `${label}.err.log`),
+    };
+  };
+  return [
+    ...(config.serve
+      ? [
+          unit('local', [
+            'serve',
+            ...(config.serve.port ? ['--port', String(config.serve.port)] : []),
+          ]),
+        ]
+      : []),
+    ...(config.sync ? [unit('sync', ['sync', '--watch'])] : []),
+    ...config.collectors.map((c) => unit(`collect.${c.name}`, collectorArgs(c))),
+  ];
+}
+
+const xml = (value: string) =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export function renderPlist(unit: AgentUnit) {
+  const string = (value: string) => `<string>${xml(value)}</string>`;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  ${string(unit.label)}
+  <key>ProgramArguments</key>
+  <array>
+${unit.args.map((arg) => `    ${string(arg)}`).join('\n')}
+  </array>
+  <key>WorkingDirectory</key>
+  ${string(unit.workingDirectory)}
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  ${string(unit.stdout)}
+  <key>StandardErrorPath</key>
+  ${string(unit.stderr)}
+</dict>
+</plist>
+`;
+}
+
+// systemd expands % specifiers and $ variables even inside quotes.
+const systemdEscape = (value: string) => value.replace(/%/g, '%%').replace(/\$/g, '$$$$');
+const systemdQuote = (arg: string) =>
+  `"${systemdEscape(arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"'))}"`;
+export function renderSystemdUnit(unit: AgentUnit) {
+  return `[Unit]
+Description=Archive ${unit.label.slice(AGENT_LABEL_PREFIX.length)}
+
+[Service]
+ExecStart=${unit.args.map(systemdQuote).join(' ')}
+WorkingDirectory=${systemdEscape(unit.workingDirectory)}
+Restart=always
+RestartSec=30
+StandardOutput=append:${systemdEscape(unit.stdout)}
+StandardError=append:${systemdEscape(unit.stderr)}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export type AgentPlatform = 'darwin' | 'linux';
+export const unitFileName = (label: string, platform: AgentPlatform) =>
+  label + (platform === 'darwin' ? '.plist' : '.service');
+const ownedLabel = (label: string) =>
+  label === `${AGENT_LABEL_PREFIX}local` ||
+  label === `${AGENT_LABEL_PREFIX}sync` ||
+  label.startsWith(`${AGENT_LABEL_PREFIX}collect.`);
+/** Labels of Archive units present in a supervisor directory. */
+export function installedLabels(dir: string, platform: AgentPlatform) {
+  const extension = unitFileName('', platform);
+  return existsSync(dir)
+    ? readdirSync(dir)
+        .filter((file) => file.endsWith(extension))
+        .map((file) => file.slice(0, -extension.length))
+        .filter(ownedLabel)
+        .sort()
+    : [];
+}
+
+export interface AgentPlan {
+  write: { label: string; file: string; content: string }[];
+  unchanged: string[];
+  remove: string[];
+}
+/** Pure: which unit files to write, keep, or remove, given what is on disk. */
+export function planAgents(
+  units: AgentUnit[],
+  installed: { label: string; content?: string }[],
+  platform: AgentPlatform,
+  dir: string,
+): AgentPlan {
+  const current = new Map(installed.map((i) => [i.label, i.content]));
+  const render = platform === 'darwin' ? renderPlist : renderSystemdUnit;
+  const plan: AgentPlan = { write: [], unchanged: [], remove: [] };
+  for (const unit of units) {
+    const content = render(unit);
+    if (current.get(unit.label) === content) plan.unchanged.push(unit.label);
+    else
+      plan.write.push({
+        label: unit.label,
+        file: join(dir, unitFileName(unit.label, platform)),
+        content,
+      });
+  }
+  const wanted = new Set(units.map((u) => u.label));
+  plan.remove = installed.map((i) => i.label).filter((l) => ownedLabel(l) && !wanted.has(l));
+  return plan;
+}
+
+export type AgentRunner = (argv: string[]) => { code: number; stdout: string; stderr: string };
+const spawnRunner: AgentRunner = (argv) => {
+  const run = Bun.spawnSync(argv, { stdout: 'pipe', stderr: 'pipe' });
+  return { code: run.exitCode ?? 1, stdout: run.stdout.toString(), stderr: run.stderr.toString() };
+};
+export interface AgentHostOptions {
+  home?: string;
+  platform?: AgentPlatform;
+  /** Supervisor directory; defaults to ~/Library/LaunchAgents or ~/.config/systemd/user. */
+  dir?: string;
+  run?: AgentRunner;
+  uid?: number;
+  sleep?: (ms: number) => void;
+  execPath?: string;
+  cliPath?: string;
+}
+function host(options: AgentHostOptions) {
+  const platform =
+    options.platform ??
+    (process.platform === 'darwin' || process.platform === 'linux'
+      ? process.platform
+      : (() => {
+          throw new Error('Agents support macOS launchd and Linux systemd only');
+        })());
+  const home = resolve(options.home ?? defaultHome());
+  const dir =
+    options.dir ??
+    join(homedir(), platform === 'darwin' ? 'Library/LaunchAgents' : '.config/systemd/user');
+  const run = options.run ?? spawnRunner;
+  const domain = `gui/${options.uid ?? process.getuid?.()}`;
+  const sleep = options.sleep ?? Bun.sleepSync;
+  const file = (label: string) => join(dir, unitFileName(label, platform));
+  const systemctl = (...args: string[]) => run(['systemctl', '--user', ...args]);
+  const unload = (label: string) => {
+    if (platform === 'darwin') run(['launchctl', 'bootout', `${domain}/${label}`]);
+    else systemctl('disable', '--now', `${label}.service`);
+  };
+  const load = (label: string) => {
+    if (platform === 'linux') {
+      const enabled = systemctl('enable', `${label}.service`);
+      const started = systemctl('restart', `${label}.service`);
+      if (enabled.code || started.code) throw new Error(`systemctl failed for ${label}`);
+      return;
+    }
+    run(['launchctl', 'bootout', `${domain}/${label}`]);
+    // bootout returns before launchd finishes tearing down; bootstrap then fails with I/O error 5.
+    for (let attempt = 1; ; attempt++) {
+      const result = run(['launchctl', 'bootstrap', domain, file(label)]);
+      if (!result.code) return;
+      if (attempt >= 5 || (result.code !== 5 && !/Input\/output error/.test(result.stderr)))
+        throw new Error(`launchctl bootstrap failed for ${label}: ${result.stderr.trim()}`);
+      sleep(1000);
+    }
+  };
+  const loaded = (label: string) => {
+    if (platform === 'darwin') {
+      const result = run(['launchctl', 'print', `${domain}/${label}`]);
+      if (result.code) return { loaded: false };
+      const pid = /\bpid = (\d+)/.exec(result.stdout)?.[1];
+      return { loaded: true, pid: pid ? Number(pid) : undefined };
+    }
+    const result = systemctl('show', `${label}.service`, '--property=ActiveState,MainPID');
+    const state = /ActiveState=(\w+)/.exec(result.stdout)?.[1];
+    const pid = Number(/MainPID=(\d+)/.exec(result.stdout)?.[1] ?? 0);
+    return { loaded: state === 'active' || state === 'activating', pid: pid || undefined };
+  };
+  const remove = (labels: string[]) => {
+    for (const label of labels) {
+      unload(label);
+      rmSync(file(label), { force: true });
+    }
+    if (platform === 'linux' && labels.length) systemctl('daemon-reload');
+  };
+  return { platform, home, dir, file, load, loaded, remove, systemctl };
+}
+
+/** Writes and (re)loads declared agents; removes Archive units no longer declared. */
+export function installAgents(config: AgentsConfig, options: AgentHostOptions = {}) {
+  const h = host(options);
+  const units = agentUnits(config, {
+    home: h.home,
+    execPath: options.execPath,
+    cliPath: options.cliPath,
+  });
+  mkdirSync(join(h.home, 'logs'), { recursive: true, mode: 0o700 });
+  mkdirSync(h.dir, { recursive: true });
+  const installed = installedLabels(h.dir, h.platform).map((label) => ({
+    label,
+    content: readFileSync(h.file(label), 'utf8'),
+  }));
+  const plan = planAgents(units, installed, h.platform, h.dir);
+  h.remove(plan.remove);
+  for (const { file, content } of plan.write) {
+    const temp = `${file}.${randomUUID()}.tmp`;
+    writeFileSync(temp, content, { mode: 0o644, flag: 'wx' });
+    renameSync(temp, file);
+  }
+  if (h.platform === 'linux' && plan.write.length) h.systemctl('daemon-reload');
+  // Unchanged units that are not running are loaded again.
+  const reload = [
+    ...plan.write.map((w) => w.label),
+    ...plan.unchanged.filter((label) => !h.loaded(label).loaded),
+  ];
+  for (const label of reload) h.load(label);
+  return {
+    platform: h.platform,
+    dir: h.dir,
+    loaded: reload,
+    unchanged: plan.unchanged.filter((l) => !reload.includes(l)),
+    removed: plan.remove,
+  };
+}
+
+export function uninstallAgents(options: AgentHostOptions = {}) {
+  const h = host(options);
+  const labels = installedLabels(h.dir, h.platform);
+  h.remove(labels);
+  return { platform: h.platform, dir: h.dir, removed: labels };
+}
+
+/** Last log entry: CLI output is pretty JSON, so the last top-level value, compacted; else the last line. */
+function lastEntry(file: string) {
+  if (!existsSync(file)) return undefined;
+  const fd = openSync(file, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    const buffer = Buffer.alloc(Math.min(size, 65_536));
+    readSync(fd, buffer, 0, buffer.length, size - buffer.length);
+    const lines = buffer.toString('utf8').trimEnd().split('\n');
+    const start = lines.findLastIndex((line) => line === '{' || line === '[');
+    if (start >= 0)
+      try {
+        return JSON.stringify(JSON.parse(lines.slice(start).join('\n'))).slice(0, 500);
+      } catch {}
+    return lines.at(-1) || undefined;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function agentStatus(config: AgentsConfig | undefined, options: AgentHostOptions = {}) {
+  const h = host(options);
+  const units = config
+    ? agentUnits(config, { home: h.home, execPath: options.execPath, cliPath: options.cliPath })
+    : [];
+  const declared = new Set(units.map((u) => u.label));
+  const labels = [...new Set([...declared, ...installedLabels(h.dir, h.platform)])].sort();
+  return labels.map((label) => ({
+    label,
+    declared: declared.has(label),
+    installed: existsSync(h.file(label)),
+    ...h.loaded(label),
+    lastOut: lastEntry(join(h.home, 'logs', `${label}.out.log`)),
+    lastErr: lastEntry(join(h.home, 'logs', `${label}.err.log`)),
+  }));
+}

package/src/cli.ts

@@ -1,9 +1,18 @@
 #!/usr/bin/env bun
 import { randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
+import {
+  agentStatus,
+  defaultHistoryDirectory,
+  defaultHome,
+  installAgents,
+  readAgents,
+  uninstallAgents,
+  upsertCollector,
+  writeAgents,
+} from './agents';
 import { importChatGPTThread } from './chatgpt';
 import {
   archiveRequest,
@@ -26,7 +35,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
     args,
     allowPositionals: true,
     options: {
-      home: { type: 'string', default: join(homedir(), '.local/share/archive') },
+      home: { type: 'string', default: defaultHome() },
       store: { type: 'string' },
       config: { type: 'string' },
       url: { type: 'string' },
@@ -36,7 +45,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
       'owner-model': { type: 'string' },
       'organization-id': { type: 'string' },
       'space-id': { type: 'string' },
-      'token-env': { type: 'string', default: 'ARCHIVE_TOKEN' },
+      'token-env': { type: 'string' },
       'token-file': { type: 'string' },
       file: { type: 'string' },
       directory: { type: 'string' },
@@ -50,7 +59,8 @@ export async function runCli(args = Bun.argv.slice(2)) {
       atlas: { type: 'boolean', default: false },
       tag: { type: 'string', multiple: true },
       limit: { type: 'string', default: '100' },
-      port: { type: 'string', default: process.env.PORT ?? '4411' },
+      port: { type: 'string' },
+      name: { type: 'string' },
       hostname: { type: 'string', default: '127.0.0.1' },
       watch: { type: 'boolean', default: false },
       remote: { type: 'boolean', default: false },
@@ -65,12 +75,14 @@ export async function runCli(args = Bun.argv.slice(2)) {
   const command = positionals[0];
   if (v.help || !command) {
     console.log(
-      'Archive: init | serve | connect (setup) | preview | import | collect | list | export | tag | routes | sync | search\n' +
-        'connect --url HTTPS_URL --project-id ID --token-env ENV [--kind kingdom [--connection-id ID] [--owner-model M --organization-id UUID --space-id UUID]]\n' +
+      'Archive: init | serve | connect (setup) | preview | import | collect | list | export | tag | routes | sync | search | agents\n' +
+        'connect --url HTTPS_URL --project-id ID (--token-env ENV | --token-file PATH) [--kind kingdom [--connection-id ID] [--owner-model M --organization-id UUID --space-id UUID]]\n' +
         'import --file PATH --source codex|claude-code --project-id ID [--tag TAG]\n' +
         'collect --directory HISTORY --source codex|claude-code --project-root EXACT_CWD [--project-root ...] [--worktrees] [--atlas] --project-id ID [--watch]\n' +
         'sync [--watch] | routes | search --query TEXT [--remote]\n' +
         'serve --home PATH [--port 4411 --hostname 127.0.0.1]\n' +
+        'agents add-collector --name N --source codex|claude-code --project-id ID --project-root DIR [--project-root ...] [--directory HISTORY] [--worktrees] [--atlas]\n' +
+        'agents remove-collector --name N | serve on|off [--port P] | sync on|off | install | uninstall | status\n' +
         'All commands accept --home PATH; integrations may use --store FILE --config FILE.',
     );
     return;
@@ -94,7 +106,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
     const instance = startArchiveServer({
       store: storePath,
       token,
-      port: Number(v.port),
+      port: Number(v.port ?? process.env.PORT ?? 4411),
       hostname: v.hostname,
     });
     output({ listening: instance.server.url.href, store: storePath });
@@ -107,10 +119,12 @@ export async function runCli(args = Bun.argv.slice(2)) {
     return;
   }
   if (command === 'connect' || command === 'setup') {
+    const tokenFile = v['token-file'] && resolve(v['token-file']);
     const destination = archiveDestinationSchema.parse({
       projectId: v['project-id'],
       url: v.url,
-      tokenEnv: v['token-env'],
+      tokenEnv: v['token-env'] ?? (tokenFile ? undefined : 'ARCHIVE_TOKEN'),
+      tokenFile,
       kind: v.kind,
       ...(v.kind === 'kingdom'
         ? {
@@ -135,6 +149,58 @@ export async function runCli(args = Bun.argv.slice(2)) {
     output(connectDestination(config, destination));
     return;
   }
+  if (command === 'agents') {
+    const file = join(home, 'agents.json');
+    const current = readAgents(file);
+    const [action, state] = positionals.slice(1);
+    const toggle = () => {
+      if (state !== 'on' && state !== 'off') throw new Error(`agents ${action} requires on|off`);
+      return state === 'on';
+    };
+    const base = { collectors: [], ...current };
+    if (action === 'add-collector') {
+      if (!v.name || !v['project-id'] || !v['project-root'] || !v.source)
+        throw new Error('add-collector requires --name, --source, --project-id and --project-root');
+      const source = v.source as 'codex' | 'claude-code';
+      output(
+        writeAgents(
+          file,
+          upsertCollector(current, {
+            name: v.name,
+            source,
+            directory: resolve(v.directory ?? defaultHistoryDirectory(source)),
+            projectId: v['project-id'],
+            projectRoots: v['project-root'].map((root) => resolve(root)),
+            ...(v.worktrees ? { worktrees: true } : {}),
+            ...(v.atlas ? { atlas: true } : {}),
+          }),
+        ),
+      );
+    } else if (action === 'remove-collector') {
+      if (!v.name) throw new Error('remove-collector requires --name');
+      output(
+        writeAgents(file, {
+          ...base,
+          collectors: base.collectors.filter((c) => c.name !== v.name),
+        }),
+      );
+    } else if (action === 'serve') {
+      const { serve: _, ...rest } = base;
+      output(
+        writeAgents(
+          file,
+          toggle() ? { ...rest, serve: v.port ? { port: Number(v.port) } : {} } : rest,
+        ),
+      );
+    } else if (action === 'sync') output(writeAgents(file, { ...base, sync: toggle() }));
+    else if (action === 'install') {
+      if (!current) throw new Error('No agents.json; declare agents first');
+      output(installAgents(current, { home }));
+    } else if (action === 'uninstall') output(uninstallAgents({ home }));
+    else if (action === 'status') output(agentStatus(current, { home }));
+    else throw new Error('Unknown agents command; use --help');
+    return;
+  }
   if (command === 'preview') {
     if (
       Boolean(v.file) === Boolean(v.directory) ||

package/src/client.ts

@@ -2,6 +2,7 @@ import {
   type ArchiveDestination,
   archiveDestinationSchema,
   destinationIdentity,
+  destinationToken,
   destinationUrl,
 } from './config';
 import type { LocalArchiveStore } from './local';
@@ -26,7 +27,7 @@ export async function archiveRequest(
   transport: typeof fetch = fetch,
 ) {
   const url = destinationUrl(destination.url);
-  const token = process.env[destination.tokenEnv];
+  const token = destinationToken(destination);
   if (!token || (destination.kind === 'kingdom' && !token.startsWith('kastle_runtime_')))
     throw new Error('Archive runtime credential unavailable');
   const path =

package/src/config.ts

@@ -1,12 +1,27 @@
 import { randomUUID } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute } from 'node:path';
 import { z } from 'zod';
 
 const common = {
   projectId: z.string().min(1).max(256),
   url: z.url(),
-  tokenEnv: z.string().regex(/^[A-Z][A-Z0-9_]+$/),
+  tokenEnv: z
+    .string()
+    .regex(/^[A-Z][A-Z0-9_]+$/)
+    .optional(),
+  tokenFile: z.string().max(4096).refine(isAbsolute, 'tokenFile must be absolute').optional(),
 };
 /** Kingdom derives the owner from the runtime credential; these narrow it to a space or organization it manages. */
 export const kingdomOwnerFields = {
@@ -14,26 +29,46 @@ export const kingdomOwnerFields = {
   organizationId: z.uuid().optional(),
   spaceId: z.uuid().optional(),
 };
-export const archiveDestinationSchema = z.union([
-  z.strictObject({
-    ...common,
-    kind: z.literal('archive'),
-    keepIds: z.array(z.string()).max(0).optional(),
-  }),
-  z.strictObject({
-    ...common,
-    kind: z.literal('kingdom'),
-    /** A hosted Archive that Kingdom forwards to; omitted, Kingdom stores the archive itself. */
-    connectionId: z
-      .string()
-      .regex(/^[a-z0-9-]+$/)
-      .max(120)
-      .optional(),
-    ...kingdomOwnerFields,
-  }),
-]);
+export const archiveDestinationSchema = z
+  .union([
+    z.strictObject({
+      ...common,
+      kind: z.literal('archive'),
+      keepIds: z.array(z.string()).max(0).optional(),
+    }),
+    z.strictObject({
+      ...common,
+      kind: z.literal('kingdom'),
+      /** A hosted Archive that Kingdom forwards to; omitted, Kingdom stores the archive itself. */
+      connectionId: z
+        .string()
+        .regex(/^[a-z0-9-]+$/)
+        .max(120)
+        .optional(),
+      ...kingdomOwnerFields,
+    }),
+  ])
+  .refine(
+    (d) => Boolean(d.tokenEnv) !== Boolean(d.tokenFile),
+    'Set exactly one of tokenEnv or tokenFile',
+  );
 export type ArchiveDestination = z.infer<typeof archiveDestinationSchema>;
 
+/** Private regular file owned by this user; a symlink or group/world access is refused. */
+export function readTokenFile(path: string) {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.mode & 0o077)
+      throw new Error('Token file must be a regular file owned by you with mode 0600');
+    return readFileSync(fd, 'utf8').trim();
+  } finally {
+    closeSync(fd);
+  }
+}
+export const destinationToken = (destination: ArchiveDestination) =>
+  destination.tokenFile ? readTokenFile(destination.tokenFile) : process.env[destination.tokenEnv!];
+
 export function destinationUrl(input: string) {
   const url = new URL(input);
   if (
@@ -93,6 +128,8 @@ export function connectDestination(file: string, input: unknown) {
     kind: destination.kind,
     projectId: destination.projectId,
     url: destination.url,
-    tokenEnv: destination.tokenEnv,
+    ...(destination.tokenFile
+      ? { tokenFile: destination.tokenFile }
+      : { tokenEnv: destination.tokenEnv }),
   };
 }