@promptbook/google/umd/src/book-3.0/AgentMessageRunReport.d.ts

Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action

import type { Usage } from '../execution/Usage';
import type { AgentMessageProjectChange } from '../utils/agent-message-runtime/AgentMessageProjectChange';
import type { AgentMessageTouchedExternalSource } from '../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
import type { CodexLoginMethod } from './codexLoginMethod';
/**
 * File suffix appended to one answered message book to store its run report sidecar.
 *
 * For example `messages/finished/2026-07-16-thread.book` is reported in
 * `messages/finished/2026-07-16-thread.book.report.json`.
 *
 * @private internal constant of the agent folder convention
 */
export declare const AGENT_MESSAGE_RUN_REPORT_FILE_SUFFIX = ".report.json";
/**
 * Exact wall-clock interval during which one harness processed an agent message.
 *
 * Note: [🚉] This is fully serializable as JSON
 *
 * @private internal type of the agent folder convention
 */
export type AgentMessageRunExecutionTiming = {
    /**
     * ISO 8601 timestamp captured immediately before the harness begins the message.
     */
    readonly startedAt: string;
    /**
     * ISO 8601 timestamp captured when the harness finishes the message.
     */
    readonly finishedAt: string;
};
/**
 * Report describing how one queued agent message was answered by a CLI harness runner.
 *
 * The agent runner writes it next to the answered message book so consumers
 * (for example the Agents Server task details) can show which runner, authentication
 * method and usage one answer cost without re-parsing the runner output.
 *
 * Note: [🚉] This is fully serializable as JSON
 *
 * @private internal type of the agent folder convention
 */
export type AgentMessageRunReport = {
    /**
     * Report schema version for forward compatibility.
     */
    readonly version: 1;
    /**
     * Name of the harness runner which answered the message, for example `codex` or `claude-code`.
     */
    readonly runnerName: string;
    /**
     * Model identifier used by the runner, when known.
     */
    readonly modelName?: string;
    /**
     * Authentication method the runner used, when it can be determined.
     *
     * Currently only the OpenAI Codex runner reports this (its ChatGPT account vs. `OPENAI_API_KEY`);
     * other runners leave it `undefined`.
     */
    readonly loginMethod?: CodexLoginMethod;
    /**
     * Usage statistics of the run (price, token counts, duration).
     */
    readonly usage: Usage;
    /**
     * Measured wall-clock timing of the actual harness execution, excluding time spent waiting in the queue.
     */
    readonly executionTiming?: AgentMessageRunExecutionTiming;
    /**
     * Directory names of the agent projects the harness worked with while answering the message.
     *
     * Reported by the runner from its live runtime log, which is deleted once the message is
     * answered, so this is the only trace of the projects one answer viewed or edited.
     */
    readonly touchedProjectNames?: ReadonlyArray<string>;
    /**
     * Sources outside the agent — integrations, websites and web searches — the harness reached
     * while answering the message.
     *
     * Reported from the same live runtime log as `touchedProjectNames`, so this is the only trace
     * of what one answer touched beyond the agent itself.
     */
    readonly touchedExternalSources?: ReadonlyArray<AgentMessageTouchedExternalSource>;
    /**
     * Changes the harness made to the agent projects while answering the message.
     *
     * Every agent project is a git repository and the runner commits each answer into it, so one
     * entry describes exactly what one message did to one project — including the diff of the
     * commit it created.
     */
    readonly projectChanges?: ReadonlyArray<AgentMessageProjectChange>;
};
/**
 * Builds the run-report sidecar path for one message book path.
 *
 * Works for absolute and relative paths because the suffix is simply appended.
 *
 * @private internal utility of the agent folder convention
 */
export declare function buildAgentMessageRunReportPath(messageFilePath: string): string;
/**
 * Serializes one run report into the stable JSON format persisted next to the answered message book.
 *
 * @private internal utility of the agent folder convention
 */
export declare function serializeAgentMessageRunReport(report: AgentMessageRunReport): string;
/**
 * Validates one already-parsed JSON value as a run report.
 *
 * @returns The typed report, or `null` when the value does not match the expected shape,
 * so consumers can silently skip malformed or foreign sidecar files.
 *
 * @private internal utility of the agent folder convention
 */
export declare function normalizeAgentMessageRunReport(value: unknown): AgentMessageRunReport | null;
/**
 * Parses one run-report sidecar file content.
 *
 * @returns The typed report, or `null` when the content is not valid JSON or does not match the expected shape.
 *
 * @private internal utility of the agent folder convention
 */
export declare function parseAgentMessageRunReport(reportFileContent: string): AgentMessageRunReport | null;