@bbigbang/agent-command 0.1.0

package/dist/client/agentApiClient.d.ts

@@ -0,0 +1,28 @@
+import type { AgentCommandContext } from '../context/runtimeContext.js';
+export type AgentCommandHttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+export type AgentApiRetryMode = 'auto' | 'never' | 'safe';
+export interface AgentApiResponse<T = unknown> {
+    ok: boolean;
+    status: number;
+    data: T | null;
+    error?: string;
+    errorCode?: string;
+    suggestedNextAction?: string;
+}
+export interface AgentApiClientOptions {
+    fetch?: typeof fetch;
+    env?: Record<string, string | undefined>;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface AgentApiRequestOptions {
+    retry?: AgentApiRetryMode;
+}
+export declare class AgentApiClient {
+    private readonly context;
+    private readonly fetchImpl;
+    private readonly env;
+    private readonly sleep;
+    constructor(context: Pick<AgentCommandContext, 'serverUrl' | 'token' | 'runId' | 'turnId' | 'traceId'>, options?: AgentApiClientOptions);
+    request<T = unknown>(method: AgentCommandHttpMethod, path: string, body?: unknown, options?: AgentApiRequestOptions): Promise<AgentApiResponse<T>>;
+    private fetchOnce;
+}

package/dist/client/agentApiClient.js

@@ -0,0 +1,148 @@
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError } from '../errors.js';
+function joinUrl(baseUrl, path) {
+    const normalizedBase = baseUrl.replace(/\/+$/, '');
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${normalizedBase}${normalizedPath}`;
+}
+function extractString(record, ...keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}
+function extractSuggestedNextAction(record) {
+    const direct = extractString(record, 'suggestedNextAction', 'suggested_next_action', 'required_action');
+    if (direct)
+        return direct;
+    const details = record.details;
+    if (details && typeof details === 'object') {
+        return extractString(details, 'recommendedAction', 'recommended_action', 'suggestedNextAction', 'suggested_next_action');
+    }
+    return undefined;
+}
+export class AgentApiClient {
+    context;
+    fetchImpl;
+    env;
+    sleep;
+    constructor(context, options = {}) {
+        this.context = context;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.env = options.env ?? process.env;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    async request(method, path, body, options = {}) {
+        const url = joinUrl(this.context.serverUrl, path);
+        const retryBudget = resolveRetryBudget(this.env, method, options.retry);
+        let lastNetworkError;
+        for (let attempt = 0; attempt <= retryBudget; attempt += 1) {
+            try {
+                const response = await this.fetchOnce(method, path, url, body);
+                if (!shouldRetryAgentApiResponse(response) || attempt >= retryBudget) {
+                    return response;
+                }
+            }
+            catch (error) {
+                lastNetworkError = error;
+                if (!isNetworkAgentCommandError(error) || attempt >= retryBudget) {
+                    throw error;
+                }
+            }
+            await this.sleep(retryDelayMs(attempt));
+        }
+        throw lastNetworkError instanceof Error
+            ? lastNetworkError
+            : new AgentCommandError(AGENT_COMMAND_ERROR_CODES.NETWORK_ERROR, 'Request to Bigbang core failed.');
+    }
+    async fetchOnce(method, path, url, body) {
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.context.token}`,
+                    'X-Bigbang-Agent-Surface': 'bigbang',
+                    ...(this.context.runId ? { 'X-Bigbang-Run-Id': this.context.runId } : {}),
+                    ...(this.context.turnId ? { 'X-Bigbang-Turn-Id': this.context.turnId } : {}),
+                    ...(this.context.traceId ? { 'X-Bigbang-Trace-Id': this.context.traceId } : {}),
+                    ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+        }
+        catch (error) {
+            throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.NETWORK_ERROR, `Request to Bigbang core failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error, suggestedNextAction: 'Check that the core server is reachable from this agent runtime.' });
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        let data = null;
+        if (contentType.includes('application/json')) {
+            try {
+                data = await response.json();
+            }
+            catch (error) {
+                throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_JSON_RESPONSE, `Core returned invalid JSON for ${method} ${path}.`, { status: response.status, cause: error });
+            }
+        }
+        else {
+            const text = await response.text();
+            return {
+                ok: false,
+                status: response.status,
+                data: null,
+                error: `Expected JSON response from core but received ${contentType || 'unknown content type'}${text.trim() ? `: ${text.slice(0, 200)}` : '.'}`,
+                errorCode: AGENT_COMMAND_ERROR_CODES.NON_JSON_RESPONSE,
+            };
+        }
+        if (response.ok) {
+            return { ok: true, status: response.status, data: data };
+        }
+        if (data && typeof data === 'object') {
+            const record = data;
+            const failureClass = extractString(record, 'failure_class', 'failureClass');
+            const errorCode = extractString(record, 'error_code', 'errorCode', 'code') ?? failureClass;
+            return {
+                ok: false,
+                status: response.status,
+                data: data,
+                error: extractString(record, 'error', 'message') ?? failureClass ?? `HTTP ${response.status}`,
+                errorCode,
+                suggestedNextAction: extractSuggestedNextAction(record),
+            };
+        }
+        return {
+            ok: false,
+            status: response.status,
+            data: null,
+            error: `HTTP ${response.status}`,
+        };
+    }
+}
+function resolveRetryBudget(env, method, retryMode = 'auto') {
+    if (retryMode === 'never')
+        return 0;
+    if (retryMode === 'auto' && method !== 'GET')
+        return 0;
+    const raw = env.BIGBANG_CLI_MAX_RETRIES?.trim();
+    if (raw !== undefined && raw !== '') {
+        const parsed = Number(raw);
+        if (Number.isInteger(parsed) && parsed >= 0)
+            return Math.min(parsed, 5);
+    }
+    return 2;
+}
+function retryDelayMs(attempt) {
+    return attempt === 0 ? 200 : 800;
+}
+function shouldRetryResponse(status) {
+    return status === 502 || status === 503 || status === 504;
+}
+function shouldRetryAgentApiResponse(response) {
+    if (response.errorCode === AGENT_COMMAND_ERROR_CODES.NON_JSON_RESPONSE)
+        return false;
+    return shouldRetryResponse(response.status);
+}
+function isNetworkAgentCommandError(error) {
+    return error instanceof AgentCommandError && error.code === AGENT_COMMAND_ERROR_CODES.NETWORK_ERROR;
+}

package/dist/commands/stdin.d.ts

@@ -0,0 +1,7 @@
+export interface StdinLike extends AsyncIterable<Buffer | string> {
+    isTTY?: boolean;
+    setEncoding?: (encoding: BufferEncoding) => void;
+}
+export declare function readRequiredStdin(stream: StdinLike, label?: string): Promise<string>;
+export declare function readOptionalStdin(stream: StdinLike): Promise<string | undefined>;
+export declare function readRequiredJsonStdin<T = unknown>(stream: StdinLike, label?: string): Promise<T>;

package/dist/commands/stdin.js

@@ -0,0 +1,34 @@
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError } from '../errors.js';
+async function readStream(stream) {
+    stream.setEncoding?.('utf8');
+    let content = '';
+    for await (const chunk of stream) {
+        content += String(chunk);
+    }
+    return content;
+}
+export async function readRequiredStdin(stream, label = 'content') {
+    if (stream.isTTY) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_STDIN, `No ${label} received on stdin.`, { suggestedNextAction: `Pipe ${label} into this command or use a heredoc.` });
+    }
+    const content = await readStream(stream);
+    if (!content.trim()) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_STDIN, `No ${label} received on stdin.`, { suggestedNextAction: `Pipe ${label} into this command or use a heredoc.` });
+    }
+    return content;
+}
+export async function readOptionalStdin(stream) {
+    if (stream.isTTY)
+        return undefined;
+    const content = await readStream(stream);
+    return content.trim() ? content : undefined;
+}
+export async function readRequiredJsonStdin(stream, label = 'JSON payload') {
+    const content = await readRequiredStdin(stream, label);
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.INVALID_JSON_STDIN, `stdin did not contain valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error, suggestedNextAction: 'Validate the payload with jq or node before retrying.' });
+    }
+}

package/dist/context/runtimeContext.d.ts

@@ -0,0 +1,25 @@
+export type AgentCommandEnv = Record<string, string | undefined>;
+export type AgentCommandTokenSource = 'bigbang-token-file' | 'bigbang-token-env' | 'channel-bridge-token-env';
+export interface AgentCommandContext {
+    agentId: string;
+    serverUrl: string;
+    token: string;
+    tokenSource: AgentCommandTokenSource;
+    conversationId?: string;
+    runId?: string;
+    turnId?: string;
+    traceId?: string;
+    runContextPath?: string;
+}
+export interface LoadAgentCommandContextOptions {
+    env?: AgentCommandEnv;
+    readFile?: (path: string) => string;
+}
+export interface AgentRunContext {
+    runId?: string;
+    turnId?: string;
+    traceId?: string;
+}
+export declare function loadAgentCommandContext(options?: LoadAgentCommandContextOptions): AgentCommandContext;
+export declare function resolveCurrentRunId(context: Pick<AgentCommandContext, 'runId' | 'runContextPath'>, readFile?: (path: string) => string): string | undefined;
+export declare function resolveCurrentRunContext(context: Pick<AgentCommandContext, 'runId' | 'turnId' | 'traceId' | 'runContextPath'>, readFile?: (path: string) => string): AgentRunContext;

package/dist/context/runtimeContext.js

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs';
+import { AGENT_COMMAND_ERROR_CODES, AgentCommandError } from '../errors.js';
+function optionalEnvString(value) {
+    const trimmed = value?.trim();
+    return trimmed || undefined;
+}
+function buildContextBase(params) {
+    return {
+        agentId: params.agentId,
+        serverUrl: params.serverUrl,
+        token: params.token,
+        tokenSource: params.tokenSource,
+        conversationId: optionalEnvString(params.env.BIGBANG_CONVERSATION_ID),
+        runId: optionalEnvString(params.env.BIGBANG_RUN_ID),
+        turnId: optionalEnvString(params.env.BIGBANG_TURN_ID),
+        traceId: optionalEnvString(params.env.BIGBANG_TRACE_ID),
+        runContextPath: optionalEnvString(params.env.BIGBANG_RUN_CONTEXT_PATH),
+    };
+}
+function readTrimmedTokenFile(path, readFile) {
+    let raw;
+    try {
+        raw = readFile(path);
+    }
+    catch (error) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.TOKEN_FILE_UNREADABLE, `BIGBANG_AUTH_TOKEN_FILE=${path} could not be read.`, {
+            cause: error,
+            suggestedNextAction: 'Restart the agent runtime so the platform can inject a readable agent auth token file.',
+        });
+    }
+    const token = raw.trim();
+    if (!token) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.TOKEN_FILE_EMPTY, `BIGBANG_AUTH_TOKEN_FILE=${path} is empty.`, { suggestedNextAction: 'Restart the agent runtime so the platform can inject a fresh agent auth token.' });
+    }
+    return token;
+}
+export function loadAgentCommandContext(options = {}) {
+    const env = options.env ?? process.env;
+    const readFile = options.readFile ?? ((path) => readFileSync(path, 'utf8'));
+    const agentId = env.BIGBANG_AGENT_ID?.trim();
+    if (!agentId) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_AGENT_ID, 'BIGBANG_AGENT_ID is required.', { suggestedNextAction: 'Run this command from an Bigbang managed agent runtime.' });
+    }
+    const serverUrl = env.BIGBANG_SERVER_URL?.trim();
+    if (!serverUrl) {
+        throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_SERVER_URL, 'BIGBANG_SERVER_URL is required.', { suggestedNextAction: 'Run this command from an Bigbang managed agent runtime.' });
+    }
+    const tokenFile = env.BIGBANG_AUTH_TOKEN_FILE?.trim();
+    if (tokenFile) {
+        return buildContextBase({
+            agentId,
+            serverUrl,
+            token: readTrimmedTokenFile(tokenFile, readFile),
+            tokenSource: 'bigbang-token-file',
+            env,
+        });
+    }
+    const bigbangToken = env.BIGBANG_AUTH_TOKEN?.trim();
+    if (bigbangToken) {
+        return buildContextBase({
+            agentId,
+            serverUrl,
+            token: bigbangToken,
+            tokenSource: 'bigbang-token-env',
+            env,
+        });
+    }
+    const bridgeToken = env.CHANNEL_BRIDGE_AUTH_TOKEN?.trim();
+    if (bridgeToken) {
+        return buildContextBase({
+            agentId,
+            serverUrl,
+            token: bridgeToken,
+            tokenSource: 'channel-bridge-token-env',
+            env,
+        });
+    }
+    throw new AgentCommandError(AGENT_COMMAND_ERROR_CODES.MISSING_TOKEN, 'BIGBANG_AUTH_TOKEN_FILE, BIGBANG_AUTH_TOKEN, or CHANNEL_BRIDGE_AUTH_TOKEN is required.', { suggestedNextAction: 'Restart the agent runtime so the platform can inject an agent auth token.' });
+}
+export function resolveCurrentRunId(context, readFile = (path) => readFileSync(path, 'utf8')) {
+    return resolveCurrentRunContext(context, readFile).runId;
+}
+export function resolveCurrentRunContext(context, readFile = (path) => readFileSync(path, 'utf8')) {
+    const fallback = {
+        runId: optionalEnvString(context.runId),
+        turnId: optionalEnvString(context.turnId),
+        traceId: optionalEnvString(context.traceId),
+    };
+    if (context.runContextPath) {
+        try {
+            const parsed = JSON.parse(readFile(context.runContextPath));
+            const runId = typeof parsed.runId === 'string' ? parsed.runId.trim() : '';
+            const turnId = typeof parsed.turnId === 'string' ? parsed.turnId.trim() : '';
+            const traceId = typeof parsed.traceId === 'string' ? parsed.traceId.trim() : '';
+            return {
+                runId: runId || fallback.runId,
+                turnId: turnId || fallback.turnId,
+                traceId: traceId || fallback.traceId,
+            };
+        }
+        catch {
+            // Runtime context files can be absent before the first dispatch writes them.
+        }
+    }
+    return fallback;
+}

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+export declare const AGENT_COMMAND_ERROR_CODES: {
+    readonly FILE_TOO_LARGE: "FILE_TOO_LARGE";
+    readonly FILE_UNREADABLE: "FILE_UNREADABLE";
+    readonly INVALID_ARG: "INVALID_ARG";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly INVALID_JSON_RESPONSE: "INVALID_JSON_RESPONSE";
+    readonly INVALID_JSON_STDIN: "INVALID_JSON_STDIN";
+    readonly INVALID_PANEL_PAYLOAD: "INVALID_PANEL_PAYLOAD";
+    readonly INVALID_TASK_STATUS: "INVALID_TASK_STATUS";
+    readonly MESSAGE_NOT_RESOLVED: "MESSAGE_NOT_RESOLVED";
+    readonly MISSING_AGENT_ID: "MISSING_AGENT_ID";
+    readonly MISSING_ATTACHMENT_SCOPE: "MISSING_ATTACHMENT_SCOPE";
+    readonly MISSING_CONVERSATION_ID: "MISSING_CONVERSATION_ID";
+    readonly MISSING_MESSAGE_ID: "MISSING_MESSAGE_ID";
+    readonly MISSING_SERVER_URL: "MISSING_SERVER_URL";
+    readonly MISSING_STDIN: "MISSING_STDIN";
+    readonly MISSING_TOKEN: "MISSING_TOKEN";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly NON_JSON_RESPONSE: "NON_JSON_RESPONSE";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly REQUEST_FAILED: "REQUEST_FAILED";
+    readonly SERVER_5XX: "SERVER_5XX";
+    readonly TOKEN_FILE_EMPTY: "TOKEN_FILE_EMPTY";
+    readonly TOKEN_FILE_UNREADABLE: "TOKEN_FILE_UNREADABLE";
+    readonly UNEXPECTED_ERROR: "UNEXPECTED_ERROR";
+};
+export type AgentCommandErrorCode = (typeof AGENT_COMMAND_ERROR_CODES)[keyof typeof AGENT_COMMAND_ERROR_CODES];
+export declare function normalizeAgentCommandErrorCode(code: AgentCommandErrorCode | string): string;
+export declare class AgentCommandError extends Error {
+    readonly code: string;
+    readonly suggestedNextAction?: string;
+    readonly status?: number;
+    constructor(code: AgentCommandErrorCode | string, message: string, options?: {
+        suggestedNextAction?: string;
+        status?: number;
+        cause?: unknown;
+    });
+}
+export declare function toAgentCommandError(error: unknown): AgentCommandError;

package/dist/errors.js

@@ -0,0 +1,49 @@
+export const AGENT_COMMAND_ERROR_CODES = {
+    FILE_TOO_LARGE: 'FILE_TOO_LARGE',
+    FILE_UNREADABLE: 'FILE_UNREADABLE',
+    INVALID_ARG: 'INVALID_ARG',
+    INVALID_INPUT: 'INVALID_INPUT',
+    INVALID_JSON_RESPONSE: 'INVALID_JSON_RESPONSE',
+    INVALID_JSON_STDIN: 'INVALID_JSON_STDIN',
+    INVALID_PANEL_PAYLOAD: 'INVALID_PANEL_PAYLOAD',
+    INVALID_TASK_STATUS: 'INVALID_TASK_STATUS',
+    MESSAGE_NOT_RESOLVED: 'MESSAGE_NOT_RESOLVED',
+    MISSING_AGENT_ID: 'MISSING_AGENT_ID',
+    MISSING_ATTACHMENT_SCOPE: 'MISSING_ATTACHMENT_SCOPE',
+    MISSING_CONVERSATION_ID: 'MISSING_CONVERSATION_ID',
+    MISSING_MESSAGE_ID: 'MISSING_MESSAGE_ID',
+    MISSING_SERVER_URL: 'MISSING_SERVER_URL',
+    MISSING_STDIN: 'MISSING_STDIN',
+    MISSING_TOKEN: 'MISSING_TOKEN',
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    NON_JSON_RESPONSE: 'NON_JSON_RESPONSE',
+    NOT_FOUND: 'NOT_FOUND',
+    REQUEST_FAILED: 'REQUEST_FAILED',
+    SERVER_5XX: 'SERVER_5XX',
+    TOKEN_FILE_EMPTY: 'TOKEN_FILE_EMPTY',
+    TOKEN_FILE_UNREADABLE: 'TOKEN_FILE_UNREADABLE',
+    UNEXPECTED_ERROR: 'UNEXPECTED_ERROR',
+};
+// Keep this as a passthrough: core-owned business error codes must remain exact.
+export function normalizeAgentCommandErrorCode(code) {
+    return code;
+}
+export class AgentCommandError extends Error {
+    code;
+    suggestedNextAction;
+    status;
+    constructor(code, message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'AgentCommandError';
+        this.code = normalizeAgentCommandErrorCode(code);
+        this.suggestedNextAction = options.suggestedNextAction;
+        this.status = options.status;
+    }
+}
+export function toAgentCommandError(error) {
+    if (error instanceof AgentCommandError)
+        return error;
+    if (error instanceof Error)
+        return new AgentCommandError(AGENT_COMMAND_ERROR_CODES.UNEXPECTED_ERROR, error.message, { cause: error });
+    return new AgentCommandError(AGENT_COMMAND_ERROR_CODES.UNEXPECTED_ERROR, String(error));
+}

package/dist/formatters/message.d.ts

@@ -0,0 +1,11 @@
+export interface HeldMessageResponse {
+    held?: boolean;
+    stale?: boolean;
+    message?: string;
+    draftId?: string;
+    seenUpToSeq?: number;
+    blockedSeqRange?: string;
+    latestMessages?: Array<Record<string, unknown>>;
+    readHistory?: string;
+}
+export declare function formatMessageHeld(target: string, data: HeldMessageResponse): string;

package/dist/formatters/message.js

@@ -0,0 +1,40 @@
+function formatLatestMessage(item) {
+    const seq = typeof item.seq === 'number' ? item.seq : String(item.seq ?? '?');
+    const sender = typeof item.senderName === 'string'
+        ? item.senderName
+        : typeof item.sender_name === 'string'
+            ? item.sender_name
+            : String(item.senderId ?? item.sender_id ?? 'unknown');
+    const content = typeof item.content === 'string' ? item.content : '';
+    return `seq=${seq} ${sender}: ${content}`;
+}
+export function formatMessageHeld(target, data) {
+    const platformMessage = typeof data.message === 'string' && data.message.trim()
+        ? data.message.trim()
+        : 'Your draft was not sent because newer messages exist on this surface.';
+    const blockedSeqRange = typeof data.blockedSeqRange === 'string' && data.blockedSeqRange.trim()
+        ? data.blockedSeqRange.trim()
+        : 'unknown';
+    const latestMessages = Array.isArray(data.latestMessages)
+        ? data.latestMessages
+            .map((item) => (item && typeof item === 'object' ? formatLatestMessage(item) : ''))
+            .filter(Boolean)
+        : [];
+    const lines = [
+        platformMessage,
+        '',
+        `Draft held for ${target}; nothing was posted.`,
+        `Newer seq range: ${blockedSeqRange}.`,
+    ];
+    if (data.draftId)
+        lines.push(`Draft ID: ${data.draftId}`);
+    if (typeof data.seenUpToSeq === 'number')
+        lines.push(`Seen up to seq: ${data.seenUpToSeq}`);
+    if (latestMessages.length > 0) {
+        lines.push('', 'Latest messages:', ...latestMessages);
+    }
+    if (data.readHistory)
+        lines.push(`Catch-up hint: ${data.readHistory}`);
+    lines.push('', 'Next: review the newer messages, then send a revised message or stop.');
+    return `${lines.join('\n')}\n`;
+}

package/dist/formatters/panel.d.ts

@@ -0,0 +1,22 @@
+export interface PanelVersionConflictResponse {
+    error?: string;
+    error_code?: string;
+    failure_class?: string;
+    details?: {
+        panelId?: string;
+        panel_id?: string;
+        currentVersion?: number;
+        current_version?: number;
+        expectedVersion?: number;
+        expected_version?: number;
+        recommendedAction?: string;
+        recommended_action?: string;
+    };
+    panelId?: string;
+    panel_id?: string;
+    currentVersion?: number;
+    current_version?: number;
+    expectedVersion?: number;
+    expected_version?: number;
+}
+export declare function formatPanelVersionConflict(data: PanelVersionConflictResponse): string;

package/dist/formatters/panel.js

@@ -0,0 +1,19 @@
+export function formatPanelVersionConflict(data) {
+    const details = data.details ?? {};
+    const panelId = data.panelId ?? data.panel_id ?? details.panelId ?? details.panel_id ?? 'panel';
+    const currentVersion = data.currentVersion ?? data.current_version ?? details.currentVersion ?? details.current_version;
+    const expectedVersion = data.expectedVersion ?? data.expected_version ?? details.expectedVersion ?? details.expected_version;
+    const recommendedAction = details.recommendedAction ?? details.recommended_action;
+    const lines = [
+        `Panel update conflicted for ${panelId}; nothing was overwritten.`,
+        '',
+    ];
+    if (expectedVersion !== undefined)
+        lines.push(`Expected version: ${expectedVersion}`);
+    if (currentVersion !== undefined)
+        lines.push(`Current version: ${currentVersion}`);
+    if (recommendedAction)
+        lines.push(`Core guidance: ${recommendedAction}`);
+    lines.push('', 'Next: run bigbang panel read-events/read-rows or read the latest panel state, merge user changes, then retry with the current expected_version.', 'Do not blindly overwrite saved user state or annotations.');
+    return `${lines.join('\n')}\n`;
+}

package/dist/formatters/task.d.ts

@@ -0,0 +1,7 @@
+export interface TaskHeldResponse {
+    state?: string;
+    error?: string;
+    readHistory?: string;
+    seenUpToSeq?: number;
+}
+export declare function formatTaskHeld(action: 'claim' | 'update', target: string, data: TaskHeldResponse): string;

package/dist/formatters/task.js

@@ -0,0 +1,13 @@
+export function formatTaskHeld(action, target, data) {
+    const lines = [
+        `Task ${action} for ${target} was held; no task mutation was applied.`,
+        '',
+        'Reason: newer task or conversation context may exist. Review it before retrying.',
+    ];
+    if (typeof data.seenUpToSeq === 'number')
+        lines.push(`Seen up to seq: ${data.seenUpToSeq}`);
+    if (data.readHistory)
+        lines.push(`Catch-up hint: ${data.readHistory}`);
+    lines.push('', 'Next: read the latest task/thread context, then rerun the command only if the update is still correct.');
+    return `${lines.join('\n')}\n`;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { AGENT_COMMAND_ERROR_CODES, AgentCommandError, normalizeAgentCommandErrorCode, toAgentCommandError, type AgentCommandErrorCode, } from './errors.js';
+export { BIGBANG_RECEIPT_PREFIX, formatBigbangReceipt, parseBigbangReceipts, type BigbangMessageSendReceipt, type BigbangMessageSendReceiptKind, type BigbangReceipt, } from './receipt.js';
+export { loadAgentCommandContext, resolveCurrentRunContext, resolveCurrentRunId, type AgentCommandContext, type AgentCommandEnv, type AgentRunContext, type AgentCommandTokenSource, type LoadAgentCommandContextOptions, } from './context/runtimeContext.js';
+export { AgentApiClient, type AgentApiClientOptions, type AgentApiResponse, type AgentApiRetryMode, type AgentCommandHttpMethod, } from './client/agentApiClient.js';
+export { readOptionalStdin, readRequiredJsonStdin, readRequiredStdin, type StdinLike, } from './commands/stdin.js';
+export { formatMessageHeld, type HeldMessageResponse } from './formatters/message.js';
+export { formatTaskHeld, type TaskHeldResponse } from './formatters/task.js';
+export { formatPanelVersionConflict, type PanelVersionConflictResponse } from './formatters/panel.js';
+export { BIGBANG_COMMAND_CATALOG, BIGBANG_COMMAND_SUMMARY_LINES, } from './bigbangCommandCatalog.generated.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+export { AGENT_COMMAND_ERROR_CODES, AgentCommandError, normalizeAgentCommandErrorCode, toAgentCommandError, } from './errors.js';
+export { BIGBANG_RECEIPT_PREFIX, formatBigbangReceipt, parseBigbangReceipts, } from './receipt.js';
+export { loadAgentCommandContext, resolveCurrentRunContext, resolveCurrentRunId, } from './context/runtimeContext.js';
+export { AgentApiClient, } from './client/agentApiClient.js';
+export { readOptionalStdin, readRequiredJsonStdin, readRequiredStdin, } from './commands/stdin.js';
+export { formatMessageHeld } from './formatters/message.js';
+export { formatTaskHeld } from './formatters/task.js';
+export { formatPanelVersionConflict } from './formatters/panel.js';
+export { BIGBANG_COMMAND_CATALOG, BIGBANG_COMMAND_SUMMARY_LINES, } from './bigbangCommandCatalog.generated.js';

package/dist/receipt.d.ts

@@ -0,0 +1,14 @@
+export declare const BIGBANG_RECEIPT_PREFIX = "@@BIGBANG_RECEIPT@@";
+export type BigbangMessageSendReceiptKind = 'progress' | 'final';
+export interface BigbangMessageSendReceipt {
+    op: 'message.send';
+    ok: true;
+    kind: BigbangMessageSendReceiptKind;
+    messageId: string;
+    target?: string;
+    runId?: string;
+    conversationId?: string;
+}
+export type BigbangReceipt = BigbangMessageSendReceipt;
+export declare function formatBigbangReceipt(receipt: BigbangReceipt): string;
+export declare function parseBigbangReceipts(text: string): BigbangReceipt[];

package/dist/receipt.js

@@ -0,0 +1,54 @@
+export const BIGBANG_RECEIPT_PREFIX = '@@BIGBANG_RECEIPT@@';
+export function formatBigbangReceipt(receipt) {
+    return `${BIGBANG_RECEIPT_PREFIX}${JSON.stringify(receipt)}`;
+}
+export function parseBigbangReceipts(text) {
+    const receipts = [];
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        const prefixIndex = line.indexOf(BIGBANG_RECEIPT_PREFIX);
+        if (prefixIndex < 0)
+            continue;
+        const jsonText = line.slice(prefixIndex + BIGBANG_RECEIPT_PREFIX.length).trim();
+        if (!jsonText)
+            continue;
+        try {
+            const parsed = JSON.parse(jsonText);
+            const receipt = normalizeBigbangReceipt(parsed);
+            if (receipt)
+                receipts.push(receipt);
+        }
+        catch {
+            // Ignore non-receipt text that happens to contain the marker.
+        }
+    }
+    return receipts;
+}
+function normalizeBigbangReceipt(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    if (record.op !== 'message.send' || record.ok !== true)
+        return null;
+    const kind = record.kind === 'final' ? 'final' : record.kind === 'progress' ? 'progress' : null;
+    if (!kind)
+        return null;
+    const messageId = stringValue(record.messageId) ?? stringValue(record.id);
+    if (!messageId)
+        return null;
+    return {
+        op: 'message.send',
+        ok: true,
+        kind,
+        messageId,
+        ...(stringValue(record.target) ? { target: stringValue(record.target) } : {}),
+        ...(stringValue(record.runId) ? { runId: stringValue(record.runId) } : {}),
+        ...(stringValue(record.conversationId) ? { conversationId: stringValue(record.conversationId) } : {}),
+    };
+}
+function stringValue(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}