@promptbook/cli 0.114.0-12 → 0.114.0-13

package/src/book-3.0/AgentPlannedMessagesSidecar.ts

@@ -0,0 +1,229 @@
+import { join } from 'path';
+import { AGENT_MESSAGES_DIRECTORY_PATH } from './agentFolderPaths';
+import { createAgentMessageSidecarBaseName } from './createAgentMessageSidecarBaseName';
+
+// Note: [💞] This file defines the shared planned-message sidecar convention rather than one standalone entity.
+
+/**
+ * Relative directory holding the planned-message sidecar of each queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'planned');
+
+/**
+ * Command actions an agent can request from its planned-message sidecar.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS = ['set', 'cancel'] as const;
+
+/**
+ * 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 function createAgentPlannedMessagesSidecarPath(messageFileName: string): string {
+    return join(AGENT_PLANNED_MESSAGES_DIRECTORY_PATH, `${createAgentMessageSidecarBaseName(messageFileName)}.json`);
+}
+
+/**
+ * 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 function createAgentPlannedMessagesSidecarContent(sidecar: AgentPlannedMessagesSidecar): string {
+    return `${JSON.stringify(sidecar, null, 2)}\n`;
+}
+
+/**
+ * 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 function parseAgentPlannedMessagesSidecar(sidecarContent: string): AgentPlannedMessagesSidecar | null {
+    let parsedSidecar: unknown;
+
+    try {
+        parsedSidecar = JSON.parse(sidecarContent);
+    } catch {
+        return null;
+    }
+
+    if (!parsedSidecar || typeof parsedSidecar !== 'object' || Array.isArray(parsedSidecar)) {
+        return null;
+    }
+
+    const sidecar = parsedSidecar as Partial<AgentPlannedMessagesSidecar>;
+
+    if (sidecar.version !== 1 || typeof sidecar.agentPermanentId !== 'string') {
+        return null;
+    }
+
+    return {
+        version: 1,
+        agentPermanentId: sidecar.agentPermanentId,
+        currentPlannedMessages: normalizeAgentPlannedMessageSnapshots(sidecar.currentPlannedMessages),
+        commands: normalizeAgentPlannedMessageCommands(sidecar.commands),
+    };
+}
+
+/**
+ * Keeps only the commands whose action is understood by the planned-message actions.
+ *
+ * @param rawCommands - Untrusted `commands` value read from one sidecar.
+ * @returns Commands that can be dispatched, in their original order.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessageCommands(rawCommands: unknown): Array<AgentPlannedMessageCommand> {
+    if (!Array.isArray(rawCommands)) {
+        return [];
+    }
+
+    return rawCommands.filter(isAgentPlannedMessageCommand);
+}
+
+/**
+ * Checks whether one untrusted sidecar entry names a supported planned-message action.
+ *
+ * @param value - Untrusted command entry.
+ * @returns `true` when the entry can be dispatched.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function isAgentPlannedMessageCommand(value: unknown): value is AgentPlannedMessageCommand {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+
+    const action = (value as AgentPlannedMessageCommand).action;
+
+    return (
+        typeof action === 'string' &&
+        AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS.includes(action as AgentPlannedMessageCommandAction)
+    );
+}
+
+/**
+ * Keeps only the already planned messages that can be shown to the agent.
+ *
+ * @param rawSnapshots - Untrusted `currentPlannedMessages` value read from one sidecar.
+ * @returns Planned-message snapshots with the fields required for display and cancellation.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessageSnapshots(rawSnapshots: unknown): Array<AgentPlannedMessageSnapshot> {
+    if (!Array.isArray(rawSnapshots)) {
+        return [];
+    }
+
+    return rawSnapshots.filter(isAgentPlannedMessageSnapshot).map(createNormalizedAgentPlannedMessageSnapshot);
+}
+
+/**
+ * Normalizes the optional fields of one already planned message.
+ *
+ * @param snapshot - Planned-message entry with the required identity fields.
+ * @returns Snapshot with a usable repeat interval and message.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function createNormalizedAgentPlannedMessageSnapshot(
+    snapshot: AgentPlannedMessageSnapshot,
+): AgentPlannedMessageSnapshot {
+    const intervalMs = Number(snapshot.intervalMs);
+
+    return {
+        timeoutId: snapshot.timeoutId,
+        dueAt: snapshot.dueAt,
+        message: typeof snapshot.message === 'string' ? snapshot.message : null,
+        intervalMs: Number.isFinite(intervalMs) && intervalMs > 0 ? Math.floor(intervalMs) : null,
+    };
+}
+
+/**
+ * Checks whether one untrusted sidecar entry describes an already planned message.
+ *
+ * @param value - Untrusted planned-message entry.
+ * @returns `true` when the entry can be shown and cancelled.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function isAgentPlannedMessageSnapshot(value: unknown): value is AgentPlannedMessageSnapshot {
+    return Boolean(
+        value &&
+            typeof value === 'object' &&
+            typeof (value as AgentPlannedMessageSnapshot).timeoutId === 'string' &&
+            typeof (value as AgentPlannedMessageSnapshot).dueAt === 'string',
+    );
+}

package/src/book-3.0/AgentTeamConversationWorkspace.ts

@@ -1,5 +1,6 @@
-import { basename, join } from 'path';
+import { join } from 'path';
 import { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH } from './agentFolderPaths';
+import { createAgentMessageSidecarBaseName } from './createAgentMessageSidecarBaseName';
 
 // Note: [💞] This file defines the shared TEAM workspace convention rather than one standalone entity.
 
@@ -71,10 +72,7 @@ export type AgentTeamConversationWorkspaceManifest = {
  * @private internal convention shared by the Agents Server and agent-folder runner
  */
 export function createAgentTeamConversationWorkspaceDirectoryName(messageFileName: string): string {
-    const rawBaseName = basename(messageFileName).replace(/\.book$/iu, '');
-    const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
-
-    return normalizedBaseName || 'message';
+    return createAgentMessageSidecarBaseName(messageFileName);
 }
 
 /**

package/src/book-3.0/createAgentMessageSidecarBaseName.ts

@@ -0,0 +1,20 @@
+import { basename } from 'path';
+
+/**
+ * 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 function createAgentMessageSidecarBaseName(messageFileName: string): string {
+    const rawBaseName = basename(messageFileName).replace(/\.book$/iu, '');
+    const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
+
+    return normalizedBaseName || 'message';
+}

package/src/book-components/Chat/Chat/Chat.module.css

@@ -735,7 +735,12 @@
     border-radius: 999px;
     box-shadow: 0 2px 8px rgba(15, 23, 42, 0.12);
     color: inherit;
-    font-family: 'OpenMojiColor', 'OpenMojiBlack', Arial, Helvetica, sans-serif;
+    /*
+     * OpenMoji includes ASCII digits for keycap emoji sequences. Keeping it first in this stack
+     * makes time labels such as `10:28 AM` use its non-text digit glyphs, so chips must inherit
+     * the chat typography and use OpenMoji only as its existing emoji fallback.
+     */
+    font-family: inherit;
     cursor: pointer;
     transition: all 0.2s ease;
     backdrop-filter: blur(8px);

package/src/book-components/Chat/Chat/renderToolCallDetails.tsx

@@ -7,6 +7,7 @@ import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
 import { getToolCallChipletInfo, TOOL_TITLES } from '../utils/getToolCallChipletInfo';
 import { resolveToolCallState } from '../utils/resolveToolCallState';
+import { isTimeoutToolCallName } from '../utils/timeoutToolCallPresentation';
 import { getToolCallTimestamp } from '../utils/toolCallParsing/getToolCallTimestamp';
 import { parseToolCallArguments } from '../utils/toolCallParsing/parseToolCallArguments';
 import { parseToolCallResult } from '../utils/toolCallParsing/parseToolCallResult';
@@ -375,18 +376,6 @@ function isTimeToolCallName(toolName: string): boolean {
     return toolName === 'get_current_time' || toolName === 'useTime';
 }
 
-/**
- * Checks whether a tool name should use the timeout renderer.
- *
- * @param toolName - Raw tool name.
- * @returns `true` when the tool is a timeout-like tool.
- *
- * @private function of ChatToolCallModal
- */
-function isTimeoutToolCallName(toolName: string): boolean {
-    return toolName === 'set_timeout' || toolName === 'cancel_timeout';
-}
-
 /**
  * Checks whether a tool name should use the email renderer.
  *

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

@@ -0,0 +1,74 @@
+/**
+ * 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 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 function parseAgentProjectToolCallResult(result: unknown): AgentProjectToolCallResult | null {
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        return null;
+    }
+
+    const candidate = result as Partial<AgentProjectToolCallResult>;
+    if (typeof candidate.projectName !== 'string' || candidate.projectName.trim().length === 0) {
+        return null;
+    }
+
+    return {
+        projectName: candidate.projectName.trim(),
+        ...(typeof candidate.displayName === 'string' && candidate.displayName.trim().length > 0
+            ? { displayName: candidate.displayName.trim() }
+            : {}),
+        ...(typeof candidate.projectHref === 'string' && candidate.projectHref.trim().length > 0
+            ? { projectHref: candidate.projectHref.trim() }
+            : {}),
+    };
+}
+
+/**
+ * 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 function resolveAgentProjectToolCallLabel(projectResult: AgentProjectToolCallResult): string {
+    return projectResult.displayName || projectResult.projectName;
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/book-components/Chat/utils/getToolCallChipletInfo.ts

@@ -1,6 +1,11 @@
 import type { ToolCall } from '../../../types/ToolCall';
 import { ASSISTANT_PREPARATION_TOOL_CALL_NAME } from '../../../types/ToolCall';
 import type { AgentChipData } from '../AgentChip/AgentChip';
+import {
+    AGENT_PROJECT_TOOL_CALL_NAME,
+    parseAgentProjectToolCallResult,
+    resolveAgentProjectToolCallLabel,
+} from './agentProjectToolCall';
 import { formatToolCallLocalTime } from './formatToolCallLocalTime';
 import { formatToolCallTranslationTemplate } from './formatToolCallTranslationTemplate';
 import {
@@ -112,6 +117,7 @@ type ToolCallChipletResolver = (context: ToolCallChipletContext) => ToolCallChip
  */
 const SPECIALIZED_TOOL_CALL_CHIPLET_RESOLVERS: ReadonlyArray<ToolCallChipletResolver> = [
     resolveWalletCredentialChipletInfo,
+    resolveAgentProjectToolCallChipletInfo,
     resolveTeamToolCallChipletInfo,
     resolveTimeToolCallChipletInfo,
     resolveEmailToolCallChipletInfo,
@@ -140,6 +146,7 @@ export function buildToolCallChipText(chipletInfo: ToolCallChipletInfo): string
 export const TOOL_TITLES: Record<string, { title: string; emoji: string }> = {
     [ASSISTANT_PREPARATION_TOOL_CALL_NAME]: { title: 'Preparing agent', emoji: '✨' },
     [WALLET_CREDENTIAL_TOOL_CALL_NAME]: { title: 'Credential used', emoji: '🔐' },
+    [AGENT_PROJECT_TOOL_CALL_NAME]: { title: 'Project', emoji: '📁' },
     'self-learning': { title: 'self-learning', emoji: '🧠' },
     retrieve_user_memory: { title: 'Reading memory', emoji: '🧠' },
     store_user_memory: { title: 'Storing memory', emoji: '🧠' },
@@ -320,6 +327,27 @@ function resolveWalletCredentialChipletInfo(context: ToolCallChipletContext): To
     return createEmojiToolCallChipletInfo(context, walletCredentialResult.credentialName);
 }
 
+/**
+ * Resolves the project-name chip label for touched agent projects.
+ *
+ * @param context - Shared chiplet resolution context.
+ * @returns Chiplet info when the tool call marks a touched project, otherwise `null`.
+ *
+ * @private utility of `<Chat/>`
+ */
+function resolveAgentProjectToolCallChipletInfo(context: ToolCallChipletContext): ToolCallChipletInfo | null {
+    if (context.toolCall.name !== AGENT_PROJECT_TOOL_CALL_NAME) {
+        return null;
+    }
+
+    const projectResult = parseAgentProjectToolCallResult(context.resultRaw);
+    if (!projectResult) {
+        return null;
+    }
+
+    return createEmojiToolCallChipletInfo(context, resolveAgentProjectToolCallLabel(projectResult));
+}
+
 /**
  * Resolves a chip label and agent metadata for TEAM tool calls.
  *

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

@@ -2,12 +2,26 @@ import type { TODO_any } from '../../../utils/organization/TODO_any';
 import { formatToolCallDateTime } from './formatToolCallDateTime';
 import { formatToolCallTranslationTemplate } from './formatToolCallTranslationTemplate';
 
+/**
+ * Tool name of one scheduled wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export 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 const CANCEL_TIMEOUT_TOOL_CALL_NAME = 'cancel_timeout';
+
 /**
  * Tool names handled by timeout-specific chat presentation.
  *
  * @private internal timeout-chat constant
  */
-const TIMEOUT_TOOL_NAMES = ['set_timeout', 'cancel_timeout'] as const;
+const TIMEOUT_TOOL_NAMES = [SET_TIMEOUT_TOOL_CALL_NAME, CANCEL_TIMEOUT_TOOL_CALL_NAME] as const;
 
 /**
  * Milliseconds in one second.
@@ -412,9 +426,15 @@ function formatTimeoutDurationCompact(milliseconds: number): string {
 /**
  * Converts timeout duration into natural language sentence fragments.
  *
- * @private internal timeout-chat helper
+ * 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
  */
-function formatTimeoutDurationHuman(milliseconds: number): string {
+export function formatTimeoutDurationHuman(milliseconds: number): string {
     const normalizedMilliseconds = Math.max(0, Math.floor(milliseconds));
     const totalSeconds = Math.max(1, Math.floor(normalizedMilliseconds / SECOND_IN_MILLISECONDS));