@bbigbang/cli 0.1.0

package/dist/commands/contextCommands.js

@@ -0,0 +1,253 @@
+import { joinServer, runBridge } from '@bbigbang/server-ops';
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError, appendCommonBody, createRuntime, parseNonNegativeInteger, parsePositiveInteger, readRequiredJsonStdin, responseError, summarizeContextBundle, summarizeConversationList, summarizeConversationSummary, summarizeHeldMessageDrafts, summarizeHandoffCreate, summarizeHandoffStatus, summarizeInboxCheck, summarizeInboxWait, summarizeRuntimePresence, summarizeSelfState, summarizeServerDirectory, writeOutput } from '../cliSupport.js';
+export function registerContextCommands(program, options) {
+    const server = program.command('server').description('Server and runtime summary');
+    server.command('info')
+        .description('Print server directory (channels, agents, humans)')
+        .action(async () => {
+        const runtime = createRuntime(program, options);
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/server`);
+        if (!response.ok)
+            throw responseError(response, 'server info failed');
+        writeOutput(runtime, summarizeServerDirectory(response.data), response.data);
+    });
+    server.command('join')
+        .description('Install this machine as a Bigbang server connected to a public Hub')
+        .requiredOption('--hub-url <url>', 'Public Hub URL')
+        .requiredOption('--token <token>', 'One-time Hub registration token')
+        .requiredOption('--server-id <id>', 'Issued server id')
+        .requiredOption('--server-slug <slug>', 'Issued server slug')
+        .requiredOption('--server-name <name>', 'Issued server name')
+        .requiredOption('--version <semver>', 'Package version issued by the Hub')
+        .option('--install-packages <packages>', 'Comma-separated npm package specs to install for core/node/CLI')
+        .option('--port <n>', 'Local core port', '3100')
+        .option('--service <kind>', 'systemd, tmux, or none', 'systemd')
+        .option('--dry-run', 'Print planned actions without writing files or starting services')
+        .action(async (opts) => {
+        await joinServer({
+            hubUrl: opts.hubUrl,
+            token: opts.token,
+            serverId: opts.serverId,
+            serverSlug: opts.serverSlug,
+            serverName: opts.serverName,
+            version: opts.version,
+            installPackages: parseInstallPackagesOption(opts.installPackages),
+            port: Number(opts.port),
+            service: opts.service,
+            dryRun: opts.dryRun === true,
+        });
+    });
+    server.command('bridge')
+        .description('Run the outbound bridge that connects a local server to a public Hub')
+        .option('--hub-url <url>', 'Public Hub URL')
+        .option('--token <token>', 'Hub registration or persisted bridge token')
+        .option('--credential-path <path>', 'Path for persisted bridge credentials')
+        .option('--server-id <id>', 'Server id')
+        .option('--server-slug <slug>', 'Server slug')
+        .option('--server-name <name>', 'Server name')
+        .option('--version <semver>', 'Running package version')
+        .option('--core-url <url>', 'Local core HTTP URL')
+        .action(async (opts) => {
+        await runBridge({
+            hubUrl: opts.hubUrl,
+            token: opts.token,
+            credentialPath: opts.credentialPath,
+            serverId: opts.serverId,
+            serverSlug: opts.serverSlug,
+            serverName: opts.serverName,
+            version: opts.version,
+            coreUrl: opts.coreUrl,
+        });
+    });
+    const inbox = program.command('inbox').description('Inbox peek helpers');
+    inbox.command('check')
+        .description('Peek pending inbox surfaces without advancing read checkpoints')
+        .option('--channel <target>', 'Optional channel, DM, or thread target filter')
+        .option('--limit <n>', 'Max surfaces to list')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        const channel = typeof opts.channel === 'string' ? opts.channel.trim() : '';
+        if (channel)
+            params.set('channel', channel);
+        const limit = parsePositiveInteger('limit', opts.limit);
+        if (limit !== undefined)
+            params.set('limit', String(Math.min(limit, 100)));
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/inbox${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'inbox check failed');
+        writeOutput(runtime, summarizeInboxCheck(response.data), response.data);
+    });
+    inbox.command('wait')
+        .description('Wait once for pending inbox surfaces without advancing read checkpoints')
+        .option('--channel <target>', 'Optional channel, DM, or thread target filter')
+        .option('--limit <n>', 'Max surfaces to list')
+        .option('--timeout <s>', 'Max seconds to wait before exiting', '30')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        const channel = typeof opts.channel === 'string' ? opts.channel.trim() : '';
+        if (channel)
+            params.set('channel', channel);
+        const limit = parsePositiveInteger('limit', opts.limit);
+        if (limit !== undefined)
+            params.set('limit', String(Math.min(limit, 100)));
+        const timeoutSeconds = parseNonNegativeInteger('timeout', opts.timeout) ?? 30;
+        params.set('timeout_ms', String(Math.min(timeoutSeconds * 1000, 60000)));
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/inbox/wait${qs ? `?${qs}` : ''}`, undefined, { retry: 'never' });
+        if (!response.ok)
+            throw responseError(response, 'inbox wait failed');
+        writeOutput(runtime, summarizeInboxWait(response.data), response.data);
+    });
+    const self = program.command('self').description('Current agent self-state helpers');
+    self.command('state')
+        .description('Print self-state report for the current conversation')
+        .action(async () => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        if (runtime.context.conversationId)
+            params.set('conversationId', runtime.context.conversationId);
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/self-state${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'self state failed');
+        writeOutput(runtime, summarizeSelfState(response.data), response.data);
+    });
+    const runtimeCommand = program.command('runtime').description('Runtime presence helpers');
+    runtimeCommand.command('presence')
+        .description('Print runtime presence report for the current conversation')
+        .action(async () => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        if (runtime.context.conversationId)
+            params.set('conversationId', runtime.context.conversationId);
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/runtime-presence${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'runtime presence failed');
+        writeOutput(runtime, summarizeRuntimePresence(response.data), response.data);
+    });
+    const conversation = program.command('conversation').description('Conversation discovery and summary helpers');
+    conversation.command('list')
+        .description('List conversations visible to the current agent')
+        .option('--status <status>', 'Filter by status: all, idle, queued, active, recovering, awaiting_approval, failed', 'all')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const status = typeof opts.status === 'string' ? opts.status.trim() : 'all';
+        const params = new URLSearchParams();
+        if (status !== 'all')
+            params.set('status', status);
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/my-conversations${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'list conversations failed');
+        writeOutput(runtime, summarizeConversationList(response.data), response.data);
+    });
+    conversation.command('summary')
+        .description('Fetch a summary for a target or conversation id')
+        .option('--target <target>', 'Conversation target such as #general, dm:@name, or thread target')
+        .option('--conversation-id <id>', 'Conversation id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const target = typeof opts.target === 'string' ? opts.target.trim() : '';
+        const conversationId = typeof opts.conversationId === 'string' ? opts.conversationId.trim() : '';
+        if (!target && !conversationId) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_ARG, 'conversation summary requires --target or --conversation-id.', { suggestedNextAction: 'Pass a target such as --target #general or --conversation-id conv-123.' });
+        }
+        const params = new URLSearchParams();
+        if (target)
+            params.set('target', target);
+        if (conversationId)
+            params.set('conversation_id', conversationId);
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/conversation-summary?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'conversation summary failed');
+        writeOutput(runtime, summarizeConversationSummary(response.data), response.data);
+    });
+    const context = program.command('context').description('Context bundle helpers');
+    context.command('bundle')
+        .description('Build a context bundle for the current conversation')
+        .option('--max-surfaces <n>', 'Max neighboring surfaces to include')
+        .option('--max-tasks <n>', 'Max related tasks to include')
+        .option('--max-handoffs <n>', 'Max related handoffs to include')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const conversationId = runtime.context.conversationId?.trim();
+        if (!conversationId) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_CONVERSATION_ID, 'context bundle requires BIGBANG_CONVERSATION_ID.', { suggestedNextAction: 'Run this command from an Bigbang managed conversation runtime.' });
+        }
+        const body = { conversationId };
+        const maxSurfaces = parsePositiveInteger('max-surfaces', opts.maxSurfaces);
+        if (maxSurfaces !== undefined)
+            body.maxSurfaces = maxSurfaces;
+        const maxTasks = parsePositiveInteger('max-tasks', opts.maxTasks);
+        if (maxTasks !== undefined)
+            body.maxTasks = maxTasks;
+        const maxHandoffs = parsePositiveInteger('max-handoffs', opts.maxHandoffs);
+        if (maxHandoffs !== undefined)
+            body.maxHandoffs = maxHandoffs;
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/context-bundle`, body);
+        if (!response.ok)
+            throw responseError(response, 'context bundle failed');
+        writeOutput(runtime, summarizeContextBundle(response.data), response.data);
+    });
+    const draft = program.command('draft').description('Draft message helpers');
+    const draftHeld = draft.command('held').description('Held message draft operations');
+    draftHeld.command('list')
+        .description('List held message drafts for the current agent')
+        .option('--status <status>', 'Draft status filter')
+        .option('--limit <n>', 'Max drafts to return')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        const status = typeof opts.status === 'string' ? opts.status.trim() : '';
+        if (status)
+            params.set('status', status);
+        const limit = parsePositiveInteger('limit', opts.limit);
+        if (limit !== undefined)
+            params.set('limit', String(Math.min(limit, 100)));
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/held-message-drafts${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'list held message drafts failed');
+        writeOutput(runtime, summarizeHeldMessageDrafts(response.data), response.data);
+    });
+    const handoff = program.command('handoff').description('Conversation handoff operations');
+    handoff.command('create')
+        .description('Create a handoff from stdin JSON (target, mode, goal, optional context)')
+        .action(async () => {
+        const runtime = createRuntime(program, options);
+        const stdin = await readRequiredJsonStdin(runtime.io.stdin, 'handoff create JSON payload');
+        if (!stdin || typeof stdin !== 'object' || Array.isArray(stdin)) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_JSON_STDIN, 'handoff create JSON payload must be an object.', { suggestedNextAction: 'Pipe an object such as {"target":"#review","mode":"delegate_only","goal":"Review the plan."}' });
+        }
+        const body = appendCommonBody(runtime, {
+            ...stdin,
+            conversationId: typeof stdin.conversationId === 'string' ? stdin.conversationId.trim() : runtime.context.conversationId,
+        });
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/handoff`, body);
+        if (!response.ok)
+            throw responseError(response, 'handoff create failed');
+        writeOutput(runtime, summarizeHandoffCreate(response.data), response.data);
+    });
+    handoff.command('status')
+        .description('Read the status of a handoff by id')
+        .argument('<handoff-id>', 'Handoff id')
+        .action(async (handoffId) => {
+        const runtime = createRuntime(program, options);
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/handoffs/${encodeURIComponent(handoffId)}`);
+        if (!response.ok)
+            throw responseError(response, 'handoff status failed');
+        writeOutput(runtime, summarizeHandoffStatus(response.data), response.data);
+    });
+}
+function parseInstallPackagesOption(value) {
+    if (typeof value !== 'string' || !value.trim())
+        return [];
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+}

package/dist/commands/memoryCommands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import type { BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerMemoryCommands(program: Command, options: BuildBigbangProgramOptions): void;

package/dist/commands/memoryCommands.js

@@ -0,0 +1,154 @@
+import { appendCommonBody, createRuntime, parseNumber, parsePositiveInteger, parseRequiredNumber, requireString, responseError, writeOutput, } from '../cliSupport.js';
+function summarizeMemoryNode(node) {
+    const topic = typeof node.topic === 'string' ? node.topic : '(untitled)';
+    const status = typeof node.status === 'string' ? node.status : 'unknown';
+    const category = typeof node.category === 'string' ? node.category : 'unknown';
+    const importance = typeof node.importance === 'number' ? node.importance.toFixed(2) : '?';
+    const nodeId = typeof node.nodeId === 'string' ? node.nodeId : '';
+    return `${nodeId} [${status}/${category}] ${topic} (importance ${importance})`;
+}
+function summarizeMemoryEdge(edge) {
+    const edgeId = typeof edge.edgeId === 'string' ? edge.edgeId : '';
+    const relation = typeof edge.relation === 'string' ? edge.relation : 'related_to';
+    const source = typeof edge.sourceNodeId === 'string' ? edge.sourceNodeId : '';
+    const target = typeof edge.targetNodeId === 'string' ? edge.targetNodeId : '';
+    return `${edgeId} ${source} -${relation}-> ${target}`;
+}
+export function registerMemoryCommands(program, options) {
+    const memory = program.command('memory').description('Memory network operations');
+    const node = memory.command('node').description('Memory node operations');
+    const edge = memory.command('edge').description('Memory edge operations');
+    node.command('create')
+        .description('Create a memory node')
+        .requiredOption('--topic <topic>', 'Memory topic')
+        .requiredOption('--summary <summary>', 'Memory summary')
+        .requiredOption('--category <category>', 'Memory category')
+        .option('--importance <value>', 'Importance 0-1', parseNumber)
+        .option('--source-message-id <id>', 'Source message id')
+        .option('--source-snippet <snippet>', 'Source message snippet')
+        .option('--status <status>', 'Node status (draft/confirmed/retired)', 'draft')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const body = appendCommonBody(runtime, {
+            topic: requireString(opts.topic, '--topic'),
+            summary: requireString(opts.summary, '--summary'),
+            category: requireString(opts.category, '--category'),
+            ...(opts.importance != null ? { importance: opts.importance } : {}),
+            ...(opts.sourceMessageId ? { sourceMessageId: opts.sourceMessageId } : {}),
+            ...(opts.sourceSnippet ? { sourceSnippet: opts.sourceSnippet } : {}),
+            status: opts.status ?? 'draft',
+        });
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/memory/nodes`, body);
+        if (!response.ok)
+            throw responseError(response, 'memory node create');
+        const created = response.data;
+        writeOutput(runtime, summarizeMemoryNode(created), created);
+    });
+    node.command('list')
+        .description('List memory nodes')
+        .option('--category <category>', 'Filter by category')
+        .option('--status <status>', 'Filter by status')
+        .option('--since <timestamp>', 'Filter by updated_at >= timestamp', parsePositiveInteger)
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        if (opts.category)
+            params.set('category', opts.category);
+        if (opts.status)
+            params.set('status', opts.status);
+        if (opts.since != null)
+            params.set('since', String(opts.since));
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/memory/nodes${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'memory node list');
+        const payload = response.data;
+        const nodes = payload.nodes ?? [];
+        writeOutput(runtime, nodes.map(summarizeMemoryNode).join('\n') || 'No memory nodes.', payload);
+    });
+    node.command('update')
+        .description('Update a memory node')
+        .argument('<node_id>', 'Memory node id')
+        .option('--reinforce', 'Reinforce memory')
+        .option('--retire', 'Retire memory')
+        .option('--confirm', 'Confirm draft memory')
+        .option('--topic <topic>', 'Update topic')
+        .option('--summary <summary>', 'Update summary')
+        .option('--importance <value>', 'Update importance', parseNumber)
+        .action(async (nodeId, opts) => {
+        const runtime = createRuntime(program, options);
+        const body = appendCommonBody(runtime, {
+            ...(opts.reinforce ? { reinforce: true } : {}),
+            ...(opts.retire ? { retire: true } : {}),
+            ...(opts.confirm ? { confirm: true } : {}),
+            ...(opts.topic ? { topic: opts.topic } : {}),
+            ...(opts.summary ? { summary: opts.summary } : {}),
+            ...(opts.importance != null ? { importance: opts.importance } : {}),
+        });
+        const response = await runtime.client.request('PATCH', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/memory/nodes/${encodeURIComponent(nodeId)}`, body);
+        if (!response.ok)
+            throw responseError(response, 'memory node update');
+        const updated = response.data;
+        writeOutput(runtime, summarizeMemoryNode(updated), updated);
+    });
+    node.command('search')
+        .description('Search memory nodes')
+        .requiredOption('--query <query>', 'Search query')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams({ query: requireString(opts.query, '--query') });
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/memory/nodes?${params.toString()}`);
+        if (!response.ok)
+            throw responseError(response, 'memory node search');
+        const payload = response.data;
+        const nodes = payload.nodes ?? [];
+        writeOutput(runtime, nodes.map(summarizeMemoryNode).join('\n') || 'No matching memory nodes.', payload);
+    });
+    edge.command('create')
+        .description('Create a memory edge')
+        .requiredOption('--source <node_id>', 'Source node id')
+        .requiredOption('--target <node_id>', 'Target node id')
+        .requiredOption('--relation <relation>', 'Edge relation')
+        .option('--strength <value>', 'Edge strength 0-1', parseNumber)
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const body = appendCommonBody(runtime, {
+            sourceNodeId: requireString(opts.source, '--source'),
+            targetNodeId: requireString(opts.target, '--target'),
+            relation: requireString(opts.relation, '--relation'),
+            ...(opts.strength != null ? { strength: opts.strength } : {}),
+        });
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/memory/edges`, body);
+        if (!response.ok)
+            throw responseError(response, 'memory edge create');
+        const created = response.data;
+        writeOutput(runtime, summarizeMemoryEdge(created), created);
+    });
+    edge.command('list')
+        .description('List memory edges')
+        .option('--node <node_id>', 'Filter by node id')
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const params = new URLSearchParams();
+        if (opts.node)
+            params.set('node', opts.node);
+        const qs = params.toString();
+        const response = await runtime.client.request('GET', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/memory/edges${qs ? `?${qs}` : ''}`);
+        if (!response.ok)
+            throw responseError(response, 'memory edge list');
+        const payload = response.data;
+        const edges = payload.edges ?? [];
+        writeOutput(runtime, edges.map(summarizeMemoryEdge).join('\n') || 'No memory edges.', payload);
+    });
+    memory.command('dream-watermark')
+        .description('Report dream processing watermark')
+        .requiredOption('--seq <message_seq>', 'Last processed message seq', (value) => parseRequiredNumber('seq', value))
+        .action(async (opts) => {
+        const runtime = createRuntime(program, options);
+        const body = appendCommonBody(runtime, { seq: opts.seq });
+        const response = await runtime.client.request('POST', `/api/internal/agent/${encodeURIComponent(runtime.context.agentId)}/memory/dream-watermark`, body);
+        if (!response.ok)
+            throw responseError(response, 'memory dream-watermark');
+        writeOutput(runtime, `watermark seq=${opts.seq}`, response.data);
+    });
+}

package/dist/commands/messageCommands.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from 'commander';
+import type { BuildBigbangProgramOptions } from '../cliSupport.js';
+export declare function registerMessageCommands(program: Command, options: BuildBigbangProgramOptions): void;