@promptbook/node 0.114.0-12 → 0.114.0-13

package/esm/scripts/run-agent-messages/messages/buildAgentGoalChatPromptSection.d.ts

@@ -1,8 +1,26 @@
-import type { AgentServerRuntimePromptApi } from './AgentServerRuntimePromptApi';
+import type { AgentPlannedMessageSnapshot } from '../../../src/book-3.0/AgentPlannedMessagesSidecar';
+/**
+ * Planned-message sidecar information made visible to one coding-harness prompt.
+ */
+export type AgentPlannedMessagesPromptSidecar = {
+    /**
+     * Portable path of the sidecar inside the agent folder.
+     */
+    readonly relativeSidecarPath: string;
+    /**
+     * Planned messages that are already waiting to wake the agent.
+     */
+    readonly currentPlannedMessages: ReadonlyArray<AgentPlannedMessageSnapshot>;
+};
 /**
  * Builds the planned-message instructions available to an Agents Server-managed coding agent.
  *
- * Planned messages always target the agent's singleton goal chat, regardless of the chat in which
- * the command is invoked.
+ * Planned messages always target the agent's singleton goal chat, regardless of the chat in which the
+ * wake-up is planned, and they repeat like `setInterval` until they are cancelled. The sidecar file is
+ * the only channel that changes them, so an answer that merely claims a follow-up was planned changes
+ * nothing — and an answer that changes nothing keeps the current plan running.
+ *
+ * @param sidecar - Sidecar prepared by the Agents Server for the answered message.
+ * @returns Prompt section, or an empty string outside Agents Server-managed runs.
  */
-export declare function buildAgentGoalChatPromptSection(runtimeApi: AgentServerRuntimePromptApi | undefined): string;
+export declare function buildAgentGoalChatPromptSection(sidecar: AgentPlannedMessagesPromptSidecar | undefined): string;

package/esm/scripts/run-agent-messages/messages/buildAgentMessagePrompt.d.ts

@@ -1,5 +1,5 @@
-import type { AgentServerRuntimePromptApi } from './AgentServerRuntimePromptApi';
 import { type AgentProjectsPromptSectionOptions } from './buildAgentProjectsPromptSection';
+import { type AgentPlannedMessagesPromptSidecar } from './buildAgentGoalChatPromptSection';
 import { type AgentTeamPromptWorkspace } from './buildAgentTeamPromptSection';
 /**
  * Options adjusting the generated agent message prompt.
@@ -10,9 +10,9 @@ export type BuildAgentMessagePromptOptions = AgentProjectsPromptSectionOptions &
      */
     teamWorkspace?: AgentTeamPromptWorkspace;
     /**
-     * Internal API details used to manage planned messages in the agent's singleton goal chat.
+     * Planned-message sidecar prepared by the Agents Server for the agent's singleton goal chat.
      */
-    goalChatRuntimeApi?: AgentServerRuntimePromptApi;
+    plannedMessagesSidecar?: AgentPlannedMessagesPromptSidecar;
 };
 /**
  * Builds the prompt sent to the selected coding runner for one queued user-thread book.

package/esm/src/book-3.0/AgentMessageRunReport.d.ts

@@ -9,6 +9,23 @@ import type { CodexLoginMethod } from './codexLoginMethod';
  * @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.
  *
@@ -44,6 +61,17 @@ export type AgentMessageRunReport = {
      * 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>;
 };
 /**
  * Builds the run-report sidecar path for one message book path.

package/esm/src/book-3.0/AgentPlannedMessagesSidecar.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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", "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 repeats like `setInterval`, so `intervalMs` is what the agent compares with its
+ * goal, while `dueAt` only says when the nearest repetition 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 wakes the agent only once.
+     */
+    readonly intervalMs: number | null;
+};
+/**
+ * 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.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessageCommand = {
+    readonly action: AgentPlannedMessageCommandAction;
+    readonly milliseconds?: 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;

package/esm/src/book-3.0/AgentPlannedMessagesSidecar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/book-3.0/createAgentMessageSidecarBaseName.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Creates the stable file-system safe base name that belongs to one queued `.book` message.
+ *
+ * Every sidecar the Agents Server prepares next to a queued message (TEAM workspaces, planned-message
+ * files, ...) derives its own name from this one normalization, so a sidecar can always be found again
+ * from the message file name alone.
+ *
+ * @param messageFileName - File name of the queued message, with or without directories.
+ * @returns Normalized base name usable as a directory or file name.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export declare function createAgentMessageSidecarBaseName(messageFileName: string): string;

package/esm/src/book-components/Chat/utils/agentProjectToolCall.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Synthetic tool name used for agent-project chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per project an answer viewed or edited, so the chat
+ * shows which projects the agent worked with below the message that touched them.
+ *
+ * @private internal chat-ui marker for touched agent projects
+ */
+export declare const AGENT_PROJECT_TOOL_CALL_NAME = "agent_project_touched";
+/**
+ * Safe, user-facing metadata shown in agent-project chips.
+ *
+ * @private internal chat-ui type for touched agent projects
+ */
+export type AgentProjectToolCallResult = {
+    /**
+     * Directory name of the project.
+     */
+    readonly projectName: string;
+    /**
+     * Human-readable project name shown in the chip.
+     */
+    readonly displayName?: string;
+    /**
+     * Link to the project page, when the chat knows where the project lives.
+     */
+    readonly projectHref?: string;
+};
+/**
+ * Parses the project-chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed project metadata, or `null` when the result describes no project.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function parseAgentProjectToolCallResult(result: unknown): AgentProjectToolCallResult | null;
+/**
+ * Resolves the chip label of one touched agent project.
+ *
+ * @param projectResult - Parsed project metadata.
+ * @returns Human-readable project name.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveAgentProjectToolCallLabel(projectResult: AgentProjectToolCallResult): string;

package/esm/src/book-components/Chat/utils/timeoutToolCallPresentation.d.ts

@@ -1,4 +1,16 @@
 import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const SET_TIMEOUT_TOOL_CALL_NAME = "set_timeout";
+/**
+ * Tool name of one cancelled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const CANCEL_TIMEOUT_TOOL_CALL_NAME = "cancel_timeout";
 /**
  * Action performed by timeout tools.
  *
@@ -140,4 +152,16 @@ export declare function buildTimeoutToolPrimarySentence(presentation: TimeoutToo
  * @private internal utility of `<Chat/>`
  */
 export declare function buildTimeoutToolScheduleSentence(presentation: TimeoutToolCallPresentation, translations?: TimeoutToolCallTranslations): string | null;
+/**
+ * Converts timeout duration into natural language sentence fragments.
+ *
+ * Shared by every timeout surface: the chat chips, the goal-chat planned messages of the Agents
+ * Server, and the planned-message prompt section of the agent-folder runner.
+ *
+ * @param milliseconds - Duration or repeat interval in milliseconds.
+ * @returns Label such as `5 minutes` or `1 hour 30 minutes`.
+ *
+ * @private internal utility of `<Chat/>` and the Agents Server planned messages
+ */
+export declare function formatTimeoutDurationHuman(milliseconds: number): string;
 export {};

package/esm/src/utils/agent-message-runtime/parseAgentMessageRuntimeLogEvents.d.ts

@@ -0,0 +1,59 @@
+/**
+ * One string-keyed payload of a coding-harness tool invocation.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+type RuntimeLogToolInput = Record<string, unknown>;
+/**
+ * One content block of a Claude Code `stream-json` assistant event.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogContentBlock = {
+    readonly type?: string;
+    readonly text?: string;
+    readonly name?: string;
+    readonly input?: RuntimeLogToolInput;
+};
+/**
+ * One file path touched by a Codex `file_change` item.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogFileChange = {
+    readonly path?: string;
+};
+/**
+ * Minimal shape of one coding-harness runtime log event.
+ *
+ * The runtime log mixes two harness formats — Claude Code `stream-json` (`type`/`message`) and
+ * Codex JSONL (`type`/`item`) — so both are described by one permissive structure and every
+ * consumer reads only the fields it understands.
+ *
+ * @private internal type of agent-message runtime logs
+ */
+export type AgentMessageRuntimeLogEvent = {
+    readonly type?: string;
+    readonly message?: {
+        readonly content?: ReadonlyArray<AgentMessageRuntimeLogContentBlock>;
+    };
+    readonly item?: {
+        readonly type?: string;
+        readonly command?: string;
+        readonly exit_code?: number | null;
+        readonly changes?: ReadonlyArray<AgentMessageRuntimeLogFileChange>;
+    };
+};
+/**
+ * Parses every structured event out of one coding-harness runtime log.
+ *
+ * The local agent runner streams the answering harness output into a live runtime log file, one
+ * JSON event per line, optionally prefixed by shell noise. Lines without a usable JSON object are
+ * skipped so a partially written or interleaved log never breaks its consumers.
+ *
+ * @param logText - Raw runtime log content.
+ * @returns Structured events in the order they were streamed.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function parseAgentMessageRuntimeLogEvents(logText: string | null | undefined): ReadonlyArray<AgentMessageRuntimeLogEvent>;
+export {};

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves which projects one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a project counts as touched when the
+ * harness named it in a tool invocation — reading, searching, running, or editing files inside
+ * `projects/<project-name>/`. Only tool payloads are inspected: tool results and assistant
+ * narration are ignored so a project merely mentioned in the conversation is never reported.
+ *
+ * Every candidate is matched against the projects that really exist, which both filters prompt
+ * placeholders such as `projects/<project-name>/` and keeps the reported names canonical.
+ *
+ * @param options - Raw runtime log content and the project directory names of the agent.
+ * @returns Touched project names in the canonical spelling, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedProjectNames(options: {
+    readonly logText: string | null | undefined;
+    readonly knownProjectNames: ReadonlyArray<string>;
+}): ReadonlyArray<string>;

package/esm/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.114.0-10`).
+ * It follows semantic versioning (e.g., `0.114.0-12`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/node",
-    "version": "0.114.0-12",
+    "version": "0.114.0-13",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -97,7 +97,7 @@
     "types": "./esm/src/_packages/node.index.d.ts",
     "typings": "./esm/src/_packages/node.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.114.0-12"
+        "@promptbook/core": "0.114.0-13"
     },
     "dependencies": {
         "@openai/agents": "0.4.15",