synomem 0.1.0

package/dist/cli.js

@@ -0,0 +1,1040 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command, CommanderError, Option } from 'commander';
+import { configuredServiceFactory, readSynomemConfig, writeSynomemBackend } from './backend.js';
+import { credentialReference, OsCredentialStore } from './credentials.js';
+import { asSynomemError, SynomemError } from './errors.js';
+import { atomicWriteFile } from './fs-utils.js';
+import { startMcpServer } from './mcp/index.js';
+import { loginWithOAuth, StoredCredentialProvider } from './oauth.js';
+import { RemoteSynomemService } from './remote.js';
+import { createLocalImportBundle, RemoteImportClient, } from './import.js';
+import { formatSkillResult, installSkill, skillRuntimeNames, skillStatus, uninstallSkill, } from './skill-install.js';
+import { packageVersion } from './version.js';
+const defaultIo = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+};
+const cliExitCodes = new WeakMap();
+function collect(value, previous) {
+    return [...previous, value];
+}
+function skillRuntimes(values) {
+    const normalized = values.map((value) => (value === 'grokbot' ? 'grok' : value));
+    const invalid = normalized.find((value) => value !== 'all' && !skillRuntimeNames.some((runtime) => runtime === value));
+    if (invalid) {
+        throw new SynomemError('INVALID_INPUT', `Unsupported skill runtime: ${invalid}.`);
+    }
+    if (!normalized.length || normalized.includes('all'))
+        return undefined;
+    return normalized;
+}
+const skillRuntimeHelp = `${skillRuntimeNames.join(', ')}, grokbot (alias for grok), or all`;
+function parseEvidence(value) {
+    const separator = value.indexOf(':');
+    if (separator < 1 || separator === value.length - 1) {
+        throw new SynomemError('INVALID_INPUT', 'Evidence must use kind:value syntax.');
+    }
+    return {
+        kind: value.slice(0, separator),
+        value: value.slice(separator + 1),
+    };
+}
+function actor(kind, id, displayName) {
+    return {
+        kind: kind,
+        id,
+        ...(displayName ? { displayName } : {}),
+    };
+}
+function todoDue(options) {
+    if (options.dueDate && options.dueAt)
+        throw new SynomemError('INVALID_INPUT', 'Use due-date or due-at, not both.');
+    if (options.dueDate)
+        return { kind: 'date', date: options.dueDate };
+    if (options.dueAt) {
+        if (!options.timeZone)
+            throw new SynomemError('INVALID_INPUT', '--time-zone is required with --due-at.');
+        return { kind: 'datetime', datetime: options.dueAt, timeZone: options.timeZone };
+    }
+    return undefined;
+}
+function exitCode(code) {
+    if (code.endsWith('_NOT_FOUND'))
+        return 3;
+    if (code.endsWith('_FORBIDDEN') ||
+        code === 'READ_ONLY' ||
+        code === 'AUTH_REQUIRED' ||
+        code === 'AUTH_FORBIDDEN')
+        return 4;
+    if (code.startsWith('DATABASE_') || code === 'UNSUPPORTED_SCHEMA' || code === 'UNSUPPORTED_EVENT')
+        return 5;
+    if (code.startsWith('REMOTE_') || code === 'RATE_LIMITED')
+        return 5;
+    if (code === 'INTERNAL_ERROR')
+        return 1;
+    return 2;
+}
+function lineForSummary(record) {
+    const state = record.revocationStatus === 'revoked'
+        ? 'revoked'
+        : record.status === 'acknowledged'
+            ? 'acknowledged'
+            : 'new';
+    return `${record.id}  ${record.createdAt.slice(0, 10)}  ${record.recipientAgentId}  [${state}]  ${record.title}`;
+}
+function lineForItem(item) {
+    return `${item.id}  ${item.createdAt.slice(0, 10)}  ${item.kind.padEnd(5)}  [${item.status}]  ${item.title}`;
+}
+function itemListInput(options) {
+    return {
+        ...(Array.isArray(options.kind) && options.kind.length
+            ? { kinds: options.kind }
+            : {}),
+        ...(typeof options.participant === 'string' ? { participantAgentId: options.participant } : {}),
+        ...(typeof options.actor === 'string' ? { actorId: options.actor } : {}),
+        ...(typeof options.status === 'string' ? { status: options.status } : {}),
+        ...(typeof options.tag === 'string' ? { tag: options.tag } : {}),
+        ...(typeof options.visibility === 'string'
+            ? { visibility: options.visibility }
+            : {}),
+        ...(typeof options.cursor === 'string' ? { cursor: options.cursor } : {}),
+        limit: Number(options.limit ?? 10),
+        offset: Number(options.offset ?? 0),
+    };
+}
+function showRecord(record) {
+    const event = record.event;
+    const evidence = event.evidence?.map((item) => `  - ${item.kind}: ${item.value}`).join('\n');
+    return [
+        event.title,
+        `ID: ${event.id}`,
+        `Recipient: ${event.recipientDisplayName} (${event.recipientAgentId})`,
+        `From: ${event.actor.displayName ?? event.actor.id} (${event.actor.kind}:${event.actor.id})`,
+        `Date: ${event.createdAt}`,
+        `Visibility: ${event.visibility}`,
+        `Status: ${record.status}`,
+        `Revocation: ${record.revocationStatus}`,
+        event.tags?.length ? `Tags: ${event.tags.join(', ')}` : undefined,
+        '',
+        event.reason,
+        evidence ? `\nEvidence:\n${evidence}` : undefined,
+        record.acknowledgment?.note ? `\nAcknowledgment: ${record.acknowledgment.note}` : undefined,
+        record.revocation ? `\nRevoked: ${record.revocation.reason}` : undefined,
+    ]
+        .filter((value) => value !== undefined)
+        .join('\n');
+}
+function output(io, json, value, human) {
+    io.stdout(json ? `${JSON.stringify(value, null, 2)}\n` : `${human}\n`);
+}
+function globals(command) {
+    return command.optsWithGlobals();
+}
+async function withService(serviceFactory, home, configuredActor, operation) {
+    const client = serviceFactory({ ...(home ? { home } : {}), actor: configuredActor });
+    await client.init();
+    try {
+        return await operation(client);
+    }
+    finally {
+        await client.close();
+    }
+}
+function addListOptions(command) {
+    return command
+        .option('--recipient <agent>')
+        .option('--actor <id>')
+        .option('--actor-kind <kind>', 'human, agent, or system')
+        .option('--tag <tag>')
+        .option('--status <status>', 'acknowledged or unacknowledged')
+        .option('--visibility <visibility>', 'private, local, or public')
+        .addOption(new Option('--revoked <state>').choices(['include', 'only', 'exclude']).default('include'))
+        .option('--from-date <iso>')
+        .option('--to-date <iso>')
+        .option('--limit <number>', 'maximum results (default 10, maximum 50)', '10')
+        .option('--cursor <cursor>', 'opaque cursor returned by the previous page')
+        .option('--offset <number>', 'pagination offset', '0');
+}
+function listInput(options) {
+    return {
+        ...(options.recipient ? { recipientAgentId: options.recipient } : {}),
+        ...(options.actor ? { actorId: options.actor } : {}),
+        ...(options.actorKind ? { actorKind: options.actorKind } : {}),
+        ...(options.tag ? { tag: options.tag } : {}),
+        ...(options.status ? { status: options.status } : {}),
+        ...(options.visibility
+            ? { visibility: options.visibility }
+            : {}),
+        ...(options.revoked === 'only' ? { revoked: true } : {}),
+        ...(options.revoked === 'exclude' ? { revoked: false } : {}),
+        ...(options.fromDate ? { from: options.fromDate } : {}),
+        ...(options.toDate ? { to: options.toDate } : {}),
+        ...(options.cursor ? { cursor: options.cursor } : {}),
+        limit: Number(options.limit),
+        offset: Number(options.offset),
+    };
+}
+export function createCli(io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}) {
+    const env = dependencies.env ?? process.env;
+    const credentialStore = dependencies.credentialStore ?? new OsCredentialStore();
+    const oauthLogin = dependencies.oauthLogin ?? loginWithOAuth;
+    const verifyRemoteCredential = dependencies.verifyRemoteCredential ??
+        (async (options) => {
+            const remote = new RemoteSynomemService({
+                baseUrl: options.baseUrl,
+                workspaceId: options.workspaceId,
+                expectedActor: options.actor,
+                credentialProvider: new StoredCredentialProvider(options.reference, options.credentialStore, {}),
+            });
+            try {
+                await remote.init();
+            }
+            finally {
+                await remote.close();
+            }
+        });
+    const program = new Command();
+    const withClient = (home, configuredActor, operation) => withService(serviceFactory, home, configuredActor, operation);
+    cliExitCodes.set(program, 0);
+    program
+        .name('synomem')
+        .description('Local-first communication, memory, recognition, and task infrastructure for agents')
+        .version(packageVersion())
+        .option('--home <path>', 'storage root (defaults to SYNOMEM_HOME or ~/.agents)')
+        .option('--json', 'emit stable machine-readable JSON', false)
+        .showSuggestionAfterError()
+        .configureOutput({ writeOut: io.stdout, writeErr: io.stderr });
+    const remoteCommand = program.command('remote').description('Administer a remote workspace');
+    remoteCommand
+        .command('import')
+        .description('Preview or confirm a one-way import from a local Synomem home')
+        .requiredOption('--from-home <path>', 'source local Synomem home')
+        .requiredOption('--actor-id <id>', 'bound human administrator actor ID')
+        .option('--actor-name <name>', 'expected administrator display name')
+        .option('--preview', 'validate and return a short-lived import plan')
+        .option('--confirm <plan-id>', 'commit the exact bundle authorized by a preview')
+        .action(async (options, command) => {
+        const global = globals(command);
+        if (Boolean(options.preview) === Boolean(options.confirm)) {
+            throw new SynomemError('INVALID_INPUT', 'Choose exactly one of --preview or --confirm.');
+        }
+        const config = readSynomemConfig(global.home, env);
+        if (config?.backend.kind !== 'remote') {
+            throw new SynomemError('INVALID_INPUT', 'Select a remote backend before importing.');
+        }
+        const backend = config.backend;
+        const administrator = actor('human', options.actorId, options.actorName);
+        const bundle = await (dependencies.createImportBundle ?? createLocalImportBundle)(options.fromHome);
+        const result = dependencies.remoteImport
+            ? await dependencies.remoteImport({
+                baseUrl: backend.baseUrl,
+                workspaceId: backend.workspaceId,
+                actor: administrator,
+                bundle,
+                ...(options.confirm ? { planId: options.confirm } : {}),
+            })
+            : await (async () => {
+                const credentialProvider = env.SYNOMEM_ACCESS_TOKEN
+                    ? { getAccessToken: async () => env.SYNOMEM_ACCESS_TOKEN }
+                    : new StoredCredentialProvider(credentialReference(backend.baseUrl, backend.workspaceId, administrator), credentialStore, env);
+                const importer = new RemoteImportClient({
+                    baseUrl: backend.baseUrl,
+                    workspaceId: backend.workspaceId,
+                    credentialProvider,
+                });
+                return options.confirm
+                    ? await importer.confirm(bundle, options.confirm)
+                    : await importer.preview(bundle);
+            })();
+        const human = 'planId' in result
+            ? [
+                `Import preview: ${result.events} events and ${result.profiles} agent profiles.`,
+                `Source: ${result.sourceWorkspaceId}`,
+                `Target: ${result.targetWorkspaceId}`,
+                `Checksum: ${result.checksum}`,
+                `Plan expires: ${result.expiresAt}`,
+                `Plan ID: ${result.planId}`,
+                'Nothing was imported. Re-run with --confirm <plan-id> to commit this exact snapshot.',
+            ].join('\n')
+            : `Imported ${result.events} events and ${result.profiles} agent profiles into ${result.targetWorkspaceId}.`;
+        output(io, global.json, result, human);
+    });
+    program
+        .command('init')
+        .description('Initialize the local Synomem database')
+        .action(async (_options, command) => {
+        const options = globals(command);
+        const persisted = readSynomemConfig(options.home);
+        if (persisted?.backend.kind === 'remote') {
+            throw new SynomemError('INVALID_INPUT', 'The init command requires a local backend.');
+        }
+        await withClient(options.home, actor('system', 'cli'), async (client) => {
+            const info = await client.info();
+            if (info.backend !== 'local') {
+                throw new SynomemError('INVALID_INPUT', 'The init command requires a local backend.');
+            }
+            output(io, options.json, { home: info.home, database: info.databasePath }, `Initialized Synomem at ${info.home}`);
+        });
+    });
+    const backendCommand = program
+        .command('backend')
+        .description('Inspect or select the canonical backend');
+    backendCommand
+        .command('show')
+        .description('Show backend selection without connecting')
+        .action((_options, command) => {
+        const global = globals(command);
+        const config = readSynomemConfig(global.home);
+        const backend = config?.backend ?? { kind: 'local' };
+        const human = backend.kind === 'local'
+            ? `Backend: local${config ? `\nWorkspace: ${config.workspaceId}` : ' (not initialized)'}`
+            : `Backend: remote\nURL: ${backend.baseUrl}\nWorkspace: ${backend.workspaceId}`;
+        output(io, global.json, { backend, initialized: config !== undefined }, human);
+    });
+    backendCommand
+        .command('use')
+        .description('Select local or remote canonical state')
+        .argument('<kind>', 'local or remote')
+        .option('--url <url>', 'remote HTTPS origin')
+        .option('--workspace <id>', 'remote workspace ID')
+        .action((kind, options, command) => {
+        const global = globals(command);
+        if (kind !== 'local' && kind !== 'remote') {
+            throw new SynomemError('INVALID_INPUT', 'Backend kind must be local or remote.');
+        }
+        if (kind === 'remote' && (!options.url || !options.workspace)) {
+            throw new SynomemError('INVALID_INPUT', 'Remote backend selection requires --url and --workspace.');
+        }
+        const config = writeSynomemBackend(kind === 'local'
+            ? { kind: 'local' }
+            : { kind: 'remote', baseUrl: options.url, workspaceId: options.workspace }, global.home);
+        output(io, global.json, { backend: config.backend }, `Selected ${config.backend.kind} Synomem backend.`);
+    });
+    const authCommand = program.command('auth').description('Inspect remote authentication');
+    authCommand
+        .command('status')
+        .description('Report token availability without printing it')
+        .option('--actor-id <id>', 'bound actor ID (or SYNOMEM_ACTOR_ID)')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .action(async (options, command) => {
+        const global = globals(command);
+        if (env.SYNOMEM_ACCESS_TOKEN) {
+            output(io, global.json, { authenticated: true, source: 'environment' }, 'Remote authentication token is available from SYNOMEM_ACCESS_TOKEN.');
+            return;
+        }
+        const config = readSynomemConfig(global.home, env);
+        if (config?.backend.kind !== 'remote') {
+            throw new SynomemError('INVALID_INPUT', 'Select a remote backend before checking authentication.');
+        }
+        const actorId = options.actorId ?? env.SYNOMEM_ACTOR_ID;
+        if (!actorId)
+            throw new SynomemError('INVALID_INPUT', 'Specify --actor-id.');
+        const reference = credentialReference(config.backend.baseUrl, config.backend.workspaceId, actor(options.actorKind, actorId));
+        const available = Boolean(await credentialStore.get(reference));
+        output(io, global.json, { authenticated: available, source: available ? 'os-credential-store' : undefined }, available
+            ? 'A remote credential is available in the operating-system credential store.'
+            : 'Remote authentication is not configured.');
+    });
+    authCommand
+        .command('login')
+        .description('Authorize this actor with OAuth 2.1 authorization code and PKCE')
+        .requiredOption('--actor-id <id>', 'bound actor ID')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .option('--actor-name <name>', 'expected actor display name')
+        .option('--client-id <id>', 'registered public OAuth client ID (or SYNOMEM_OAUTH_CLIENT_ID)')
+        .option('--scope <scope>', 'requested OAuth scopes')
+        .option('--callback-port <port>', 'loopback callback port', '43817')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const config = readSynomemConfig(global.home, env);
+        if (config?.backend.kind !== 'remote') {
+            throw new SynomemError('INVALID_INPUT', 'Select a remote backend before login.');
+        }
+        const configuredActor = actor(options.actorKind, options.actorId, options.actorName);
+        const clientId = options.clientId ?? env.SYNOMEM_OAUTH_CLIENT_ID;
+        if (!clientId)
+            throw new SynomemError('INVALID_INPUT', 'Specify --client-id.');
+        const callbackPort = Number(options.callbackPort);
+        if (!Number.isSafeInteger(callbackPort) || callbackPort < 1 || callbackPort > 65_535) {
+            throw new SynomemError('INVALID_INPUT', '--callback-port must be from 1 through 65535.');
+        }
+        const reference = credentialReference(config.backend.baseUrl, config.backend.workspaceId, configuredActor);
+        await oauthLogin({
+            baseUrl: config.backend.baseUrl,
+            clientId,
+            credentialReference: reference,
+            credentialStore,
+            callbackPort,
+            ...(options.scope ? { scope: options.scope } : {}),
+        });
+        try {
+            await verifyRemoteCredential({
+                baseUrl: config.backend.baseUrl,
+                workspaceId: config.backend.workspaceId,
+                actor: configuredActor,
+                reference,
+                credentialStore,
+            });
+        }
+        catch (error) {
+            await credentialStore.delete(reference);
+            throw error;
+        }
+        output(io, global.json, { authenticated: true, source: 'os-credential-store', actor: configuredActor }, `Authorized ${configuredActor.kind}:${configuredActor.id}; the credential is stored by the operating system.`);
+    });
+    authCommand
+        .command('logout')
+        .description('Remove the stored OAuth credential for one actor')
+        .requiredOption('--actor-id <id>', 'bound actor ID')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const config = readSynomemConfig(global.home, env);
+        if (config?.backend.kind !== 'remote') {
+            throw new SynomemError('INVALID_INPUT', 'Select a remote backend before logout.');
+        }
+        const configuredActor = actor(options.actorKind, options.actorId);
+        const removed = await credentialStore.delete(credentialReference(config.backend.baseUrl, config.backend.workspaceId, configuredActor));
+        output(io, global.json, { authenticated: false, removed }, removed
+            ? 'Removed the stored Synomem credential.'
+            : 'No stored Synomem credential existed.');
+    });
+    const agentCommand = program
+        .command('agent')
+        .description('Create and inspect stable agent identities');
+    agentCommand
+        .command('create <id>')
+        .description('Create a stable agent profile')
+        .requiredOption('--name <display-name>', 'display name')
+        .option('--alias <id>', 'alias (repeatable)', collect, [])
+        .option('--description <text>')
+        .action(async (id, options, command) => {
+        const global = globals(command);
+        const profile = await withClient(global.home, actor('system', 'cli'), (client) => client.agents.create({
+            id,
+            displayName: options.name,
+            ...(options.alias.length ? { aliases: options.alias } : {}),
+            ...(options.description ? { description: options.description } : {}),
+        }));
+        output(io, global.json, profile, `Created ${profile.displayName} (${profile.id})`);
+    });
+    const skillCommand = program
+        .command('skill')
+        .description('Install and maintain the packaged agent skill');
+    skillCommand
+        .command('install')
+        .description('Plan or install the skill for detected agent runtimes')
+        .option('--runtime <runtime>', `${skillRuntimeHelp} (repeatable)`, collect, [])
+        .option('--yes', 'apply the displayed plan', false)
+        .option('--force', 'replace a conflicting synomem directory', false)
+        .option('--link', 'symlink to the packaged skill instead of copying it', false)
+        .option('--actor-id <id>', 'print actor-bound MCP registration commands')
+        .option('--actor-name <name>', 'display name used in MCP registration commands')
+        .action((options, command) => {
+        const global = globals(command);
+        const result = installSkill({
+            runtimes: skillRuntimes(options.runtime),
+            apply: options.yes,
+            force: options.force,
+            link: options.link,
+            actorId: options.actorId,
+            actorName: options.actorName,
+        });
+        output(io, global.json, result, formatSkillResult(result, 'install'));
+    });
+    skillCommand
+        .command('status')
+        .description('Show installed, stale, missing, or conflicting skill copies')
+        .option('--runtime <runtime>', `${skillRuntimeHelp} (repeatable)`, collect, [])
+        .option('--actor-id <id>', 'print actor-bound MCP registration commands')
+        .option('--actor-name <name>', 'display name used in MCP registration commands')
+        .action((options, command) => {
+        const global = globals(command);
+        const result = skillStatus({
+            runtimes: skillRuntimes(options.runtime),
+            actorId: options.actorId,
+            actorName: options.actorName,
+        });
+        output(io, global.json, result, formatSkillResult(result, 'status'));
+    });
+    skillCommand
+        .command('uninstall')
+        .description('Plan or remove Synomem-owned skill installations')
+        .option('--runtime <runtime>', `${skillRuntimeHelp} (repeatable)`, collect, [])
+        .option('--yes', 'apply the displayed plan', false)
+        .option('--force', 'remove a conflicting synomem directory', false)
+        .action((options, command) => {
+        const global = globals(command);
+        const result = uninstallSkill({
+            runtimes: skillRuntimes(options.runtime),
+            apply: options.yes,
+            force: options.force,
+        });
+        output(io, global.json, result, formatSkillResult(result, 'uninstall'));
+    });
+    agentCommand
+        .command('list')
+        .description('List known agent identities')
+        .action(async (_options, command) => {
+        const global = globals(command);
+        const agents = await withClient(global.home, actor('system', 'cli'), (client) => client.agents.list());
+        const human = agents.length
+            ? agents
+                .map((profile) => `${profile.id}  ${profile.displayName}${profile.aliases?.length ? `  aliases: ${profile.aliases.join(', ')}` : ''}`)
+                .join('\n')
+            : 'No agents configured.';
+        output(io, global.json, { agents }, human);
+    });
+    agentCommand
+        .command('show <id>')
+        .description('Show one agent profile, resolving aliases')
+        .action(async (id, _options, command) => {
+        const global = globals(command);
+        const profile = await withClient(global.home, actor('system', 'cli'), (client) => client.agents.get(id));
+        output(io, global.json, profile, `${profile.displayName} (${profile.id})\n${profile.description ?? 'No description.'}`);
+    });
+    agentCommand
+        .command('update <id>')
+        .description('Update an agent profile without rewriting history')
+        .option('--name <display-name>')
+        .option('--alias <id>', 'replace aliases (repeatable)', collect, [])
+        .option('--clear-aliases', 'remove every alias', false)
+        .option('--description <text>')
+        .action(async (id, options, command) => {
+        const global = globals(command);
+        const hasAliases = options.clearAliases || options.alias.length > 0;
+        const profile = await withClient(global.home, actor('system', 'cli'), (client) => client.agents.update(id, {
+            ...(options.name ? { displayName: options.name } : {}),
+            ...(hasAliases ? { aliases: options.clearAliases ? [] : options.alias } : {}),
+            ...(options.description !== undefined ? { description: options.description } : {}),
+        }));
+        output(io, global.json, profile, `Updated ${profile.displayName} (${profile.id})`);
+    });
+    const kudosCommand = program.command('kudos').description('Give and manage agent recognition');
+    kudosCommand
+        .command('give <recipient>')
+        .description('Give specific, evidence-based kudos to an agent')
+        .requiredOption('--from <actor-id>', 'stable ID of the giver')
+        .requiredOption('--actor-kind <kind>', 'human, agent, or system')
+        .option('--actor-name <display-name>')
+        .requiredOption('--title <title>')
+        .requiredOption('--reason <reason>')
+        .option('--tag <tag>', 'tag (repeatable)', collect, [])
+        .option('--evidence <kind:value>', 'sanitized evidence (repeatable)', collect, [])
+        .option('--visibility <visibility>', 'private, local, or public', 'workspace')
+        .option('--idempotency-key <key>')
+        .action(async (recipient, options, command) => {
+        const global = globals(command);
+        const result = await withClient(global.home, actor(options.actorKind, options.from, options.actorName), (client) => client.kudos.give({
+            recipientAgentId: recipient,
+            title: options.title,
+            reason: options.reason,
+            visibility: options.visibility,
+            ...(options.tag.length ? { tags: options.tag } : {}),
+            ...(options.evidence.length ? { evidence: options.evidence.map(parseEvidence) } : {}),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        const event = result.record.event;
+        output(io, global.json, result, `${result.deduplicated ? 'Found existing' : 'Created'} kudos for ${event.recipientDisplayName}\nTitle: ${event.title}\nDate: ${event.createdAt}\nID: ${event.id}`);
+    });
+    program
+        .command('inbox [agent]')
+        .description('Show pending kudos, memos, and todos for an agent')
+        .option('--as <agent-id>', 'defaults to the positional agent')
+        .option('--limit <number>', 'maximum results (default 10, maximum 50)', '10')
+        .option('--cursor <cursor>', 'opaque cursor returned by the previous page')
+        .action(async (agentId, options, command) => {
+        const global = globals(command);
+        const recipient = agentId ?? options.as;
+        if (!recipient)
+            throw new SynomemError('INVALID_INPUT', 'Specify an agent inbox.');
+        const page = await withClient(global.home, actor('agent', options.as ?? recipient), (client) => client.items.list({
+            participantAgentId: recipient,
+            pending: true,
+            limit: Number(options.limit),
+            ...(options.cursor ? { cursor: options.cursor } : {}),
+        }));
+        output(io, global.json, page, page.items.length
+            ? `${page.items.map(lineForItem).join('\n')}${page.hasMore ? `\nNext cursor: ${page.nextCursor}` : ''}`
+            : 'Inbox is clear.');
+    });
+    addListOptions(kudosCommand.command('list').description('List and filter kudos')).action(async (options, command) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor('human', 'local-cli'), (client) => client.kudos.list(listInput(options)));
+        output(io, global.json, page, page.items.length
+            ? `${page.items.map(lineForSummary).join('\n')}${page.hasMore ? `\nNext cursor: ${page.nextCursor}` : ''}`
+            : 'No kudos found.');
+    });
+    program
+        .command('list')
+        .description('List compact summaries across all record types')
+        .option('--kind <kind>', 'kudos, memo, note, or todo (repeatable)', collect, [])
+        .option('--participant <agent>')
+        .option('--actor <id>')
+        .option('--tag <tag>')
+        .option('--status <status>')
+        .option('--visibility <visibility>', 'private, workspace, or public')
+        .option('--limit <number>', 'maximum results (default 10, maximum 50)', '10')
+        .option('--cursor <cursor>')
+        .option('--offset <number>', 'deprecated offset', '0')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor('human', 'local-cli'), (client) => client.items.list(itemListInput(options)));
+        output(io, global.json, page, page.items.length
+            ? `${page.items.map(lineForItem).join('\n')}${page.hasMore ? `\nNext cursor: ${page.nextCursor}` : ''}`
+            : 'No items found.');
+    });
+    program
+        .command('changes')
+        .description('List compact changes across all record types after an opaque watermark')
+        .option('--kind <kind>', 'filter by kind (repeatable)', collect, [])
+        .option('--after <watermark>', 'watermark or change cursor from a previous response')
+        .option('--limit <number>', 'maximum changes (default 20, maximum 100)', '20')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor('human', 'local-cli'), (client) => client.items.changes({
+            limit: Number(options.limit),
+            ...(options.kind.length ? { kinds: options.kind } : {}),
+            ...(options.after ? { after: options.after } : {}),
+        }));
+        const human = page.items.length
+            ? `${page.items
+                .map((change) => `${change.sequence}  ${change.createdAt}  ${change.type}  ${change.itemId ?? '-'}`)
+                .join('\n')}\nWatermark: ${page.nextCursor}`
+            : `No new changes. Watermark: ${page.watermark}`;
+        output(io, global.json, page, human);
+    });
+    const memoCommand = program.command('memo').description('Send and manage durable messages');
+    memoCommand
+        .command('send <recipient>')
+        .requiredOption('--from <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .option('--actor-name <name>')
+        .requiredOption('--subject <subject>')
+        .requiredOption('--body <body>')
+        .option('--tag <tag>', 'tag (repeatable)', collect, [])
+        .option('--visibility <visibility>', 'private, workspace, or public', 'workspace')
+        .option('--idempotency-key <key>')
+        .action(async (recipient, options, command) => {
+        const global = globals(command);
+        const result = await withClient(global.home, actor(options.actorKind, options.from, options.actorName), (client) => client.memos.send({
+            recipientAgentId: recipient,
+            subject: options.subject,
+            body: options.body,
+            visibility: options.visibility,
+            ...(options.tag.length ? { tags: options.tag } : {}),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, global.json, result, `${result.deduplicated ? 'Found existing' : 'Sent'} memo to ${result.record.event.recipientDisplayName}\nSubject: ${result.record.event.subject}\nID: ${result.record.event.id}`);
+    });
+    memoCommand
+        .command('list')
+        .option('--participant <agent>')
+        .option('--status <status>')
+        .option('--limit <number>', 'maximum results', '10')
+        .option('--cursor <cursor>')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor('human', 'local-cli'), (client) => client.memos.list({
+            ...(options.participant ? { participantAgentId: options.participant } : {}),
+            ...(options.status ? { status: options.status } : {}),
+            limit: Number(options.limit),
+            ...(options.cursor ? { cursor: options.cursor } : {}),
+        }));
+        output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No memos found.');
+    });
+    memoCommand.command('show <memo-id>').action(async (id, _options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor('human', 'local-cli'), (client) => client.memos.get(id));
+        output(io, global.json, record, `${record.event.subject}\nID: ${record.event.id}\nStatus: ${record.status}\n\n${record.event.body}`);
+    });
+    for (const operation of ['read', 'archive']) {
+        memoCommand
+            .command(`${operation} <memo-id>`)
+            .requiredOption('--as <agent-id>')
+            .option('--actor-kind <kind>', 'agent or human', 'agent')
+            .option('--idempotency-key <key>')
+            .action(async (id, options, command) => {
+            const global = globals(command);
+            const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.memos[operation]({
+                memoId: id,
+                ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+            }));
+            output(io, global.json, record, `Memo ${id} is ${record.status}.`);
+        });
+    }
+    const noteCommand = program
+        .command('note')
+        .description('Retain and revise agent-owned knowledge');
+    noteCommand
+        .command('create')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'agent or human', 'agent')
+        .option('--owner <agent-id>')
+        .requiredOption('--title <title>')
+        .requiredOption('--body <body>')
+        .option('--tag <tag>', 'tag (repeatable)', collect, [])
+        .option('--idempotency-key <key>')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const result = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.notes.create({
+            ...(options.owner ? { ownerAgentId: options.owner } : {}),
+            title: options.title,
+            body: options.body,
+            ...(options.tag.length ? { tags: options.tag } : {}),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, global.json, result, `${result.deduplicated ? 'Found existing' : 'Created'} note\nTitle: ${result.record.current.title}\nID: ${result.record.event.id}`);
+    });
+    noteCommand
+        .command('list')
+        .option('--owner <agent>')
+        .option('--status <status>')
+        .option('--limit <number>', 'maximum results', '10')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor('human', 'local-cli'), (client) => client.notes.list({
+            ...(options.owner ? { participantAgentId: options.owner } : {}),
+            ...(options.status ? { status: options.status } : {}),
+            limit: Number(options.limit),
+        }));
+        output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No notes found.');
+    });
+    noteCommand.command('show <note-id>').action(async (id, _options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor('human', 'local-cli'), (client) => client.notes.get(id));
+        output(io, global.json, record, `${record.current.title}\nID: ${record.event.id}\nVersion: ${record.current.version}\n\n${record.current.body}`);
+    });
+    noteCommand
+        .command('revise <note-id>')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'agent or human', 'agent')
+        .requiredOption('--expected-version <number>')
+        .option('--title <title>')
+        .option('--body <body>')
+        .option('--tag <tag>', 'replace tags', collect, [])
+        .option('--idempotency-key <key>')
+        .action(async (id, options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.notes.revise({
+            noteId: id,
+            expectedVersion: Number(options.expectedVersion),
+            ...(options.title ? { title: options.title } : {}),
+            ...(options.body ? { body: options.body } : {}),
+            ...(options.tag.length ? { tags: options.tag } : {}),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, global.json, record, `Revised note ${id} to version ${record.current.version}.`);
+    });
+    noteCommand
+        .command('archive <note-id>')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'agent or human', 'agent')
+        .option('--idempotency-key <key>')
+        .action(async (id, options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.notes.archive({
+            noteId: id,
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, global.json, record, `Archived note ${id}.`);
+    });
+    const todoCommand = program.command('todo').description('Create and manage agent todos');
+    todoCommand
+        .command('create <assignee>')
+        .requiredOption('--from <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'agent')
+        .requiredOption('--title <title>')
+        .option('--description <text>')
+        .option('--priority <number>', '1 highest, 4 lowest', '3')
+        .option('--due-date <date>')
+        .option('--due-at <datetime>')
+        .option('--time-zone <iana-zone>')
+        .option('--tag <tag>', 'tag (repeatable)', collect, [])
+        .option('--visibility <visibility>', 'private, workspace, or public', 'workspace')
+        .option('--idempotency-key <key>')
+        .action(async (assignee, options, command) => {
+        const global = globals(command);
+        const result = await withClient(global.home, actor(options.actorKind, options.from), (client) => client.todos.create({
+            assigneeAgentId: assignee,
+            title: options.title,
+            ...(options.description ? { description: options.description } : {}),
+            priority: Number(options.priority),
+            ...((due) => (due ? { due } : {}))(todoDue(options)),
+            ...(options.tag.length ? { tags: options.tag } : {}),
+            visibility: options.visibility,
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, global.json, result, `${result.deduplicated ? 'Found existing' : 'Created'} todo for ${result.record.event.assigneeDisplayName}\nTitle: ${result.record.current.title}\nID: ${result.record.event.id}`);
+    });
+    todoCommand
+        .command('list')
+        .option('--assignee <agent>')
+        .option('--status <status>')
+        .option('--limit <number>', 'maximum results', '10')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const page = await withClient(global.home, actor('human', 'local-cli'), (client) => client.todos.list({
+            ...(options.assignee ? { participantAgentId: options.assignee } : {}),
+            ...(options.status ? { status: options.status } : {}),
+            limit: Number(options.limit),
+        }));
+        output(io, global.json, page, page.items.map(lineForItem).join('\n') || 'No todos found.');
+    });
+    todoCommand.command('show <todo-id>').action(async (id, _options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor('human', 'local-cli'), (client) => client.todos.get(id));
+        output(io, global.json, record, `${record.current.title}\nID: ${record.event.id}\nStatus: ${record.status}\nVersion: ${record.current.version}`);
+    });
+    todoCommand
+        .command('update <todo-id>')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'agent or human', 'agent')
+        .requiredOption('--expected-version <number>')
+        .option('--title <title>')
+        .option('--description <text>')
+        .option('--priority <number>')
+        .option('--due-date <date>')
+        .option('--due-at <datetime>')
+        .option('--time-zone <iana-zone>')
+        .option('--clear-due')
+        .option('--visibility <visibility>')
+        .option('--idempotency-key <key>')
+        .action(async (id, options, command) => {
+        const global = globals(command);
+        const parsedDue = todoDue(options);
+        const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.todos.update({
+            todoId: id,
+            expectedVersion: Number(options.expectedVersion),
+            ...(options.title ? { title: options.title } : {}),
+            ...(options.description !== undefined ? { description: options.description } : {}),
+            ...(options.priority ? { priority: Number(options.priority) } : {}),
+            ...(options.clearDue ? { due: null } : parsedDue ? { due: parsedDue } : {}),
+            ...(options.visibility ? { visibility: options.visibility } : {}),
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        }));
+        output(io, global.json, record, `Updated todo ${id} to version ${record.current.version}.`);
+    });
+    for (const operation of ['accept', 'reject', 'complete', 'reopen', 'cancel']) {
+        todoCommand
+            .command(`${operation} <todo-id>`)
+            .requiredOption('--as <actor-id>')
+            .option('--actor-kind <kind>', 'agent or human', 'agent')
+            .option('--note <text>')
+            .option('--reason <text>')
+            .option('--idempotency-key <key>')
+            .action(async (id, options, command) => {
+            const global = globals(command);
+            const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => operation === 'accept'
+                ? client.todos.accept({
+                    todoId: id,
+                    ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                })
+                : operation === 'reject'
+                    ? client.todos.reject({
+                        todoId: id,
+                        ...(options.reason ? { reason: options.reason } : {}),
+                        ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+                    })
+                    : operation === 'complete'
+                        ? client.todos.complete({
+                            todoId: id,
+                            ...(options.note ? { note: options.note } : {}),
+                            ...(options.idempotencyKey
+                                ? { idempotencyKey: options.idempotencyKey }
+                                : {}),
+                        })
+                        : operation === 'cancel'
+                            ? client.todos.cancel({
+                                todoId: id,
+                                ...(options.reason ? { reason: options.reason } : {}),
+                                ...(options.idempotencyKey
+                                    ? { idempotencyKey: options.idempotencyKey }
+                                    : {}),
+                            })
+                            : client.todos.reopen({
+                                todoId: id,
+                                ...(options.idempotencyKey
+                                    ? { idempotencyKey: options.idempotencyKey }
+                                    : {}),
+                            }));
+            output(io, global.json, record, `Todo ${id} is ${record.status}.`);
+        });
+    }
+    kudosCommand
+        .command('show <kudos-id>')
+        .description('Show one kudos item and its current state')
+        .action(async (id, _options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor('system', 'cli'), (client) => client.kudos.get(id));
+        output(io, global.json, record, showRecord(record));
+    });
+    kudosCommand
+        .command('acknowledge <kudos-id>')
+        .description('Record that a recipient reviewed kudos')
+        .requiredOption('--as <agent-id>', 'recipient agent identity')
+        .option('--actor-kind <kind>', 'agent, human, or system', 'agent')
+        .option('--name <display-name>')
+        .option('--note <text>')
+        .action(async (id, options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor(options.actorKind, options.as, options.name), (client) => client.kudos.acknowledge({
+            kudosId: id,
+            ...(options.note ? { note: options.note } : {}),
+        }));
+        output(io, global.json, record, `Acknowledged ${id} as ${options.as}.`);
+    });
+    kudosCommand
+        .command('revoke <kudos-id>')
+        .description('Record a revocation while preserving history')
+        .requiredOption('--as <actor-id>')
+        .option('--actor-kind <kind>', 'human, agent, or system', 'human')
+        .requiredOption('--reason <reason>')
+        .option('--administrative', 'mark as an administrative revocation', false)
+        .action(async (id, options, command) => {
+        const global = globals(command);
+        const record = await withClient(global.home, actor(options.actorKind, options.as), (client) => client.kudos.revoke({
+            kudosId: id,
+            reason: options.reason,
+            administrative: options.administrative,
+        }));
+        output(io, global.json, record, `Revoked ${id}; the audit trail was preserved.`);
+    });
+    kudosCommand
+        .command('wins [agent]')
+        .description('Print the generated WINS.md path or content')
+        .option('--open', 'open WINS.md in the system GUI', false)
+        .option('--print', 'print Markdown content', false)
+        .action(async (agentId, options, command) => {
+        const global = globals(command);
+        if (!agentId)
+            throw new SynomemError('INVALID_INPUT', 'Specify an agent.');
+        const details = await withClient(global.home, actor('system', 'cli'), async (client) => {
+            const profile = await client.agents.get(agentId);
+            const info = await client.info();
+            if (info.backend !== 'local') {
+                throw new SynomemError('INVALID_INPUT', 'Generated WINS.md files are available only with the local backend.');
+            }
+            const capabilities = await client.capabilities();
+            const path = join(info.home, profile.id, 'WINS.md');
+            if (!existsSync(path)) {
+                const hint = capabilities.projections.writeWinsMarkdown
+                    ? 'Run `synomem rebuild` to generate it.'
+                    : 'Enable projection.writeWinsMarkdown and run `synomem rebuild`.';
+                throw new SynomemError('INVALID_INPUT', `No generated WINS.md exists for ${profile.id}. ${hint}`);
+            }
+            return { profile, path, content: readFileSync(path, 'utf8') };
+        });
+        if (options.open) {
+            const commandName = process.platform === 'darwin'
+                ? 'open'
+                : process.platform === 'win32'
+                    ? 'cmd'
+                    : 'xdg-open';
+            const args = process.platform === 'win32' ? ['/c', 'start', '', details.path] : [details.path];
+            spawn(commandName, args, { detached: true, stdio: 'ignore' }).unref();
+        }
+        output(io, global.json, details, options.print ? details.content.trimEnd() : details.path);
+    });
+    addListOptions(kudosCommand.command('stats').description('Show aggregate kudos statistics')).action(async (options, command) => {
+        const global = globals(command);
+        const stats = await withClient(global.home, actor('system', 'cli'), (client) => client.stats(listInput(options)));
+        output(io, global.json, stats, `Total: ${stats.total}\nActive: ${stats.active}\nAcknowledged: ${stats.acknowledged}\nRevoked: ${stats.revoked}`);
+    });
+    program
+        .command('rebuild')
+        .description('Regenerate current-state and filesystem projections from canonical events')
+        .action(async (_options, command) => {
+        const global = globals(command);
+        const result = await withClient(global.home, actor('system', 'cli'), (client) => client.rebuild());
+        output(io, global.json, result, `Rebuilt ${result.generated.length} file(s); removed ${result.removed.length} stale file(s).`);
+    });
+    program
+        .command('backup <destination>')
+        .description('Create a transactionally consistent SQLite backup')
+        .action(async (destination, _options, command) => {
+        const global = globals(command);
+        const path = await withClient(global.home, actor('system', 'cli'), (client) => {
+            if (!client.backup) {
+                throw new SynomemError('INVALID_INPUT', 'Filesystem backup is available only with the local backend.');
+            }
+            return client.backup(destination);
+        });
+        output(io, global.json, { path }, `Created backup at ${path}`);
+    });
+    program
+        .command('export')
+        .description('Export canonical events for portability')
+        .addOption(new Option('--format <format>').choices(['json', 'jsonl', 'markdown']).default('json'))
+        .option('--output <path>', 'write to an explicit destination instead of stdout')
+        .action(async (options, command) => {
+        const global = globals(command);
+        const content = await withClient(global.home, actor('system', 'cli'), (client) => client.export(options.format));
+        if (options.output) {
+            const destination = resolve(options.output);
+            atomicWriteFile(destination, content, 0o600);
+            output(io, global.json, { path: destination, format: options.format }, `Exported ${options.format} to ${destination}`);
+        }
+        else {
+            io.stdout(content);
+        }
+    });
+    program
+        .command('doctor')
+        .description('Run safe diagnostics')
+        .action(async (_options, command) => {
+        const global = globals(command);
+        const result = await withClient(global.home, actor('system', 'cli'), (client) => client.doctor());
+        const human = result.diagnostics
+            .map((item) => `${item.level.toUpperCase().padEnd(7)} ${item.code}: ${item.message}`)
+            .join('\n');
+        output(io, global.json, result, human);
+        if (!result.healthy)
+            cliExitCodes.set(program, 5);
+    });
+    program
+        .command('mcp')
+        .description('Run the actor-bound MCP server over stdio')
+        .requiredOption('--actor-id <id>')
+        .requiredOption('--actor-kind <kind>', 'human, agent, or system')
+        .option('--actor-name <display-name>')
+        .action(async (options, command) => {
+        const global = globals(command);
+        await startMcpServer({
+            ...(global.home ? { home: global.home } : {}),
+            actor: actor(options.actorKind, options.actorId, options.actorName),
+        });
+    });
+    return program;
+}
+export async function runCli(argv = process.argv, io = defaultIo, serviceFactory = configuredServiceFactory, dependencies = {}) {
+    const program = createCli(io, serviceFactory, dependencies);
+    program.exitOverride();
+    try {
+        await program.parseAsync(argv);
+        return cliExitCodes.get(program) ?? 0;
+    }
+    catch (error) {
+        if (error instanceof CommanderError && error.exitCode === 0)
+            return 0;
+        if (error instanceof CommanderError) {
+            if (!error.message.startsWith('error:'))
+                io.stderr(`${error.message}\n`);
+            return 2;
+        }
+        const kudosError = asSynomemError(error);
+        const json = argv.includes('--json');
+        io.stderr(json
+            ? `${JSON.stringify({ ok: false, error: { code: kudosError.code, message: kudosError.message } })}\n`
+            : `Error [${kudosError.code}]: ${kudosError.message}\n`);
+        return exitCode(kudosError.code);
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    process.exitCode = await runCli();
+}
+//# sourceMappingURL=cli.js.map