@promptbook/utils/esm/src/book-3.0/AgentPlannedMessagesSidecar.d.ts

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

/**
 * Relative directory holding the planned-message sidecar of each queued message.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export declare const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH: string;
/**
 * Command actions an agent can request from its planned-message sidecar.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export declare const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS: readonly ["set", "update", "cancel"];
/**
 * One planned-message command action.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export type AgentPlannedMessageCommandAction = (typeof AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS)[number];
/**
 * One planned message that is already waiting to wake the agent.
 *
 * A planned message can repeat like `setInterval`, run a bounded number of times, or wake the agent
 * only once, so the whole schedule is what the agent compares with its goal, while `dueAt` only says
 * when the nearest wake-up happens.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export type AgentPlannedMessageSnapshot = {
    readonly timeoutId: string;
    readonly dueAt: string;
    readonly message: string | null;
    /**
     * Repeat interval in milliseconds, or `null` for a planned message that does not repeat at a fixed
     * interval.
     */
    readonly intervalMs: number | null;
    /**
     * Five-field cron expression driving the repetitions, or `null` when the planned message does not
     * follow a cron.
     */
    readonly cronExpression: string | null;
    /**
     * Moment before which the planned message never wakes the agent, or `null` when it has no starting
     * date.
     */
    readonly startsAt: string | null;
    /**
     * Moment after which the planned message never wakes the agent again, or `null` when it has no
     * ending date.
     */
    readonly endsAt: string | null;
    /**
     * Total number of wake-ups the planned message performs, or `null` when it repeats until it is
     * cancelled.
     */
    readonly maxRunCount: number | null;
    /**
     * Number of times the planned message already woke the agent.
     */
    readonly runCount: number;
};
/**
 * One command written by the coding harness into its planned-message sidecar.
 *
 * The payload stays untyped on purpose: it is untrusted harness output and is validated by the very
 * same shared planned-message actions that back the model tools and the internal runtime API.
 *
 * For a `set` command, `milliseconds` is the repeat interval of the planned message, not a one-shot
 * delay, and `cronExpression`, `startsAt`, `endsAt`, and `maxRunCount` bound how it repeats. An
 * `update` command changes the very same fields of the planned message named by `timeoutId`, where a
 * field that is left out stays as it is and an explicit `null` removes the bound.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export type AgentPlannedMessageCommand = {
    readonly action: AgentPlannedMessageCommandAction;
    readonly milliseconds?: unknown;
    readonly cronExpression?: unknown;
    readonly startsAt?: unknown;
    readonly endsAt?: unknown;
    readonly maxRunCount?: unknown;
    readonly message?: unknown;
    readonly timeoutId?: unknown;
};
/**
 * Planned-message sidecar prepared for one queued message.
 *
 * `currentPlannedMessages` is written by the Agents Server and is read-only for the agent, while
 * `commands` is the only channel through which a coding harness can plan or cancel a wake-up.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export type AgentPlannedMessagesSidecar = {
    readonly version: 1;
    readonly agentPermanentId: string;
    readonly currentPlannedMessages: ReadonlyArray<AgentPlannedMessageSnapshot>;
    readonly commands: ReadonlyArray<AgentPlannedMessageCommand>;
};
/**
 * Creates the relative planned-message sidecar path of one queued message.
 *
 * @param messageFileName - File name of the queued `.book` message.
 * @returns Relative path of the sidecar inside the agent folder.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export declare function createAgentPlannedMessagesSidecarPath(messageFileName: string): string;
/**
 * Serializes one planned-message sidecar into its stored representation.
 *
 * @param sidecar - Sidecar prepared for one queued message.
 * @returns Pretty-printed JSON the coding harness can edit by hand.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export declare function createAgentPlannedMessagesSidecarContent(sidecar: AgentPlannedMessagesSidecar): string;
/**
 * Parses one untrusted planned-message sidecar written back by a coding harness.
 *
 * A malformed sidecar never fails the already answered chat, so this returns `null` instead of throwing.
 *
 * @param sidecarContent - Raw file content read from the agent folder.
 * @returns Normalized sidecar, or `null` when it cannot be used.
 *
 * @private internal convention shared by the Agents Server and agent-folder runner
 */
export declare function parseAgentPlannedMessagesSidecar(sidecarContent: string): AgentPlannedMessagesSidecar | null;