@promptbook/types 0.114.0-13 → 0.114.0-18

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

@@ -1,4 +1,6 @@
 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.
@@ -72,6 +74,22 @@ export type AgentMessageRunReport = {
      * 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.

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

@@ -9,7 +9,7 @@ export declare const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH: string;
  *
  * @private internal convention shared by the Agents Server and agent-folder runner
  */
-export declare const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS: readonly ["set", "cancel"];
+export declare const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS: readonly ["set", "update", "cancel"];
 /**
  * One planned-message command action.
  *
@@ -19,8 +19,9 @@ export type AgentPlannedMessageCommandAction = (typeof AGENT_PLANNED_MESSAGE_COM
 /**
  * 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.
+ * 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
  */
@@ -29,9 +30,34 @@ export type AgentPlannedMessageSnapshot = {
     readonly dueAt: string;
     readonly message: string | null;
     /**
-     * Repeat interval in milliseconds, or `null` for a planned message that wakes the agent only once.
+     * 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.
@@ -39,13 +65,20 @@ export type AgentPlannedMessageSnapshot = {
  * 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.
+ * 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;
 };

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

@@ -0,0 +1,31 @@
+/**
+ * Schedule of one planned message as it is described to an agent.
+ *
+ * The fields match `AgentPlannedMessageSnapshot`, so one snapshot, one scheduling result, and one
+ * stored planned message are all described by the very same sentence.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessageScheduleDescription = {
+    readonly intervalMs?: number | null;
+    readonly cronExpression?: string | null;
+    readonly startsAt?: string | null;
+    readonly endsAt?: string | null;
+    readonly maxRunCount?: number | null;
+    readonly runCount?: number | null;
+    readonly dueAt?: string | null;
+};
+/**
+ * Describes one planned-message schedule in a single sentence fragment.
+ *
+ * A planned message can repeat forever, repeat a bounded number of times, run inside a date window, or
+ * wake the agent only once. Every surface showing a planned message — the wake-up itself, the goal-chat
+ * notes, the planned-message prompt section, and the model tools — describes it with this one helper,
+ * so an agent never has to reconcile two different wordings of the same plan.
+ *
+ * @param schedule - Schedule of the planned message.
+ * @returns Fragment such as `repeats every 5 minutes (2 of 10 runs done)`.
+ *
+ * @private internal utility of the Agents Server planned messages
+ */
+export declare function describeAgentPlannedMessageSchedule(schedule: AgentPlannedMessageScheduleDescription): string;

package/esm/src/book-components/BookEditor/createDeprecatedCommitmentDiagnostics.browser.d.ts

@@ -1,9 +1 @@
-/**
- * Browser-compatible stub for `createDeprecatedCommitmentDiagnostics`.
- *
- * In the browser build the full Node.js implementation is not available,
- * so this stub always returns an empty array to keep the editor functional.
- *
- * @private internal utility of `BookEditorMonaco`
- */
-export declare function createDeprecatedCommitmentDiagnostics(_agentSource?: string): [];
+export { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics';

package/esm/src/book-components/BookEditor/createDuplicateFromCommitmentDiagnostics.d.ts

@@ -0,0 +1,28 @@
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+/**
+ * Monaco diagnostic shown when a Book source declares its parent agent more than once.
+ *
+ * @private internal type of `BookEditorMonaco`
+ */
+type DuplicateFromCommitmentDiagnostic = {
+    readonly startLineNumber: number;
+    readonly startColumn: number;
+    readonly endLineNumber: number;
+    readonly endColumn: number;
+    readonly message: string;
+    readonly source: string;
+    readonly severity: 'warning';
+};
+/**
+ * Creates Book editor diagnostics for a parent agent declared by more than one `FROM` commitment.
+ *
+ * Repeating `FROM` stays valid — the last one wins and overrides every earlier one — but an author who writes it
+ * twice usually means only one of them, so every `FROM` keyword is marked to show which one actually applies.
+ *
+ * @param agentSource - Current editor content.
+ * @returns Warning markers for every `FROM` keyword, empty when the book declares at most one parent.
+ *
+ * @private internal utility of `BookEditorMonaco`
+ */
+export declare function createDuplicateFromCommitmentDiagnostics(agentSource?: string_book): ReadonlyArray<DuplicateFromCommitmentDiagnostic>;
+export {};

package/esm/src/book-components/BookEditor/createDuplicateFromCommitmentDiagnostics.test.d.ts

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

package/esm/src/book-components/Chat/Chat/renderAgentProjectDiff.d.ts

@@ -0,0 +1,13 @@
+import { type ReactElement } from 'react';
+/**
+ * Renders one unified diff with added, removed and context lines told apart.
+ *
+ * @param options - Diff text and whether it holds only the beginning of the real diff.
+ * @returns Readable diff block.
+ *
+ * @private function of ChatToolCallModal
+ */
+export declare function renderAgentProjectDiff(options: {
+    readonly diff: string;
+    readonly isDiffTruncated: boolean;
+}): ReactElement;

package/esm/src/book-components/Chat/Chat/renderAgentProjectToolCallDetails.d.ts

@@ -0,0 +1,16 @@
+import { type ReactElement } from 'react';
+import type { AgentProjectToolCallResult } from '../utils/agentProjectToolCall';
+/**
+ * Renders the detail view of one project the answer worked with.
+ *
+ * The card answers the two questions a project chip raises: what this project is right now — its
+ * runtime state and where to open it — and what this very message did to it.
+ *
+ * @param options - Parsed project chip payload.
+ * @returns Project details section for the tool modal.
+ *
+ * @private function of ChatToolCallModal
+ */
+export declare function renderAgentProjectToolCallDetails(options: {
+    readonly project: AgentProjectToolCallResult;
+}): ReactElement;

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

@@ -1,3 +1,4 @@
+import type { AgentMessageProjectChange } from '../../../utils/agent-message-runtime/AgentMessageProjectChange';
 /**
  * Synthetic tool name used for agent-project chips in chat UI.
  *
@@ -10,6 +11,9 @@ export declare const AGENT_PROJECT_TOOL_CALL_NAME = "agent_project_touched";
 /**
  * Safe, user-facing metadata shown in agent-project chips.
  *
+ * Everything besides the project name is optional, because a chip written by an older server — or
+ * one whose project has meanwhile been deleted — still has to render.
+ *
  * @private internal chat-ui type for touched agent projects
  */
 export type AgentProjectToolCallResult = {
@@ -21,10 +25,45 @@ export type AgentProjectToolCallResult = {
      * Human-readable project name shown in the chip.
      */
     readonly displayName?: string;
+    /**
+     * Short project description, resolved the same way as on the project page.
+     */
+    readonly description?: string;
     /**
      * Link to the project page, when the chat knows where the project lives.
      */
     readonly projectHref?: string;
+    /**
+     * Address the running project itself is served on, when it has one.
+     */
+    readonly projectUrl?: string;
+    /**
+     * Whether the project was running when the answer finished.
+     */
+    readonly isRunning?: boolean;
+    /**
+     * Runtime status label, the same one the project page shows.
+     */
+    readonly runtimeStatusLabel?: string;
+    /**
+     * Total size of the project, already formatted for display.
+     */
+    readonly sizeLabel?: string;
+    /**
+     * Count of files inside the project.
+     */
+    readonly fileCount?: number;
+    /**
+     * Whether the project folder is a git repository.
+     */
+    readonly isGitRepository?: boolean;
+    /**
+     * What this very message changed in the project, when it changed anything.
+     *
+     * Its `projectName` repeats the one above because the change is reported by the agent runner
+     * in exactly this shape, and reusing it keeps the two descriptions from drifting apart.
+     */
+    readonly change?: AgentMessageProjectChange;
 };
 /**
  * Parses the project-chip payload from one tool result.

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

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

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

@@ -0,0 +1,38 @@
+import type { AgentMessageTouchedExternalSource } from '../../../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+/**
+ * Synthetic tool name used for external-source chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per source outside the agent an answer viewed or
+ * edited, so the chat shows which services, websites and searches the agent really reached below
+ * the message that touched them. Work the agent does inside itself emits nothing.
+ *
+ * @private internal chat-ui marker for touched external sources
+ */
+export declare const EXTERNAL_SOURCE_TOOL_CALL_NAME = "external_source_touched";
+/**
+ * Parses the external-source chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed source metadata, or `null` when the result describes no external source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function parseExternalSourceToolCallResult(result: unknown): AgentMessageTouchedExternalSource | null;
+/**
+ * Resolves the chip label of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns User-facing name of the source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallLabel(externalSource: AgentMessageTouchedExternalSource): string;
+/**
+ * Resolves the chip emoji of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns Emoji telling apart an integration, a website and a search.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallEmoji(externalSource: AgentMessageTouchedExternalSource): string;

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

@@ -5,6 +5,12 @@ import type { TODO_any } from '../../../utils/organization/TODO_any';
  * @private internal timeout-chat constant
  */
 export declare const SET_TIMEOUT_TOOL_CALL_NAME = "set_timeout";
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const UPDATE_TIMEOUT_TOOL_CALL_NAME = "update_timeout";
 /**
  * Tool name of one cancelled wake-up, used by every producer of timeout chips.
  *

package/esm/src/cli/cli-commands/coder/waitOptions.d.ts

@@ -12,3 +12,15 @@ export declare const DEFAULT_WAIT_AFTER_ERROR_MS: number;
  * @private internal utility of `ptbk coder` wait handling
  */
 export declare function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number;
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined;

package/esm/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -84,8 +84,23 @@ export declare class AgentCollectionInSupabase {
     private mapAgentBasicInformationRow;
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
+     *
+     * An agent that still exists always wins over a soft-deleted one, so a name that was deleted and
+     * later created again resolves to the agent that is live now instead of to the recycle-bin leftover.
+     * Soft-deleted agents stay resolvable as a fallback because the recycle bin restores them by name
+     * or permanent id.
      */
     getAgentPermanentId(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<string_agent_permanent_id>;
+    /**
+     * Looks up the permanent id of the oldest agent matching one name or permanent id.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+     * @param options - Whether soft-deleted agents may be matched as well.
+     * @returns Permanent id of the matched agent, or `null` when nothing matches.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private findAgentPermanentId;
     /**
      * Retrieves the source code of an agent by its name or permanent ID.
      */

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

@@ -0,0 +1,76 @@
+/**
+ * One file an answered agent message created, edited or deleted inside one project.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChangedFile = {
+    /**
+     * Path of the file relative to the project root, using `/` separators.
+     */
+    readonly path: string;
+    /**
+     * Count of lines added to the file.
+     */
+    readonly insertionCount: number;
+    /**
+     * Count of lines removed from the file.
+     */
+    readonly deletionCount: number;
+};
+/**
+ * Everything answering one single message changed inside one agent project.
+ *
+ * Each agent project is a git repository and every answer which modifies it is committed there
+ * automatically, so this describes exactly one such commit — the trace of what one message really
+ * did to one project, which a chat can show below the answer that did it.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChange = {
+    /**
+     * Directory name of the changed project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+    /**
+     * Full hash of the commit holding the changes of this message.
+     */
+    readonly commitHash: string;
+    /**
+     * ISO 8601 timestamp when the changes were committed.
+     */
+    readonly committedAt: string;
+    /**
+     * Files the message changed, ordered as git reports them.
+     */
+    readonly changedFiles: ReadonlyArray<AgentMessageProjectChangedFile>;
+    /**
+     * Count of lines added across all changed files.
+     */
+    readonly insertionCount: number;
+    /**
+     * Count of lines removed across all changed files.
+     */
+    readonly deletionCount: number;
+    /**
+     * Unified diff of the commit, shortened when the change is too large to carry into a chat.
+     */
+    readonly diff: string;
+    /**
+     * Whether `diff` holds only the beginning of the real diff.
+     */
+    readonly isDiffTruncated: boolean;
+};
+/**
+ * Validates one already-parsed JSON value as a project change.
+ *
+ * @param value - Raw serialized project change.
+ * @returns The typed project change, or `null` when the value does not match the expected shape,
+ * so consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export declare function normalizeAgentMessageProjectChange(value: unknown): AgentMessageProjectChange | null;

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

@@ -0,0 +1,45 @@
+/**
+ * Category of one external source an answered agent message touched.
+ *
+ * -   `integration` is a third-party service reached through an integration, for example Gmail.
+ * -   `website` is a concrete web address the agent fetched or browsed.
+ * -   `search` is a lookup the agent ran against a web search engine.
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSourceKind = 'integration' | 'website' | 'search';
+/**
+ * One source outside the agent itself which answering a single message viewed or edited.
+ *
+ * Everything the agent does inside its own folder stays internal and is never described here;
+ * this records only the reach beyond it, so a chat can tell which outside services and websites
+ * one answer really involved.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSource = {
+    /**
+     * Category of the touched source.
+     */
+    readonly kind: AgentMessageTouchedExternalSourceKind;
+    /**
+     * User-facing name of the source, for example `Gmail`, `example.com` or the search query.
+     */
+    readonly name: string;
+    /**
+     * Address of the source, when the touch names a concrete one.
+     */
+    readonly url?: string;
+};
+/**
+ * Validates one already-parsed JSON value as a touched external source.
+ *
+ * @param value - Raw serialized source.
+ * @returns The typed source, or `null` when the value does not match the expected shape, so
+ * consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export declare function normalizeAgentMessageTouchedExternalSource(value: unknown): AgentMessageTouchedExternalSource | null;

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

@@ -42,6 +42,9 @@ export type AgentMessageRuntimeLogEvent = {
         readonly command?: string;
         readonly exit_code?: number | null;
         readonly changes?: ReadonlyArray<AgentMessageRuntimeLogFileChange>;
+        readonly server?: string;
+        readonly tool?: string;
+        readonly query?: string;
     };
 };
 /**

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

@@ -0,0 +1,18 @@
+import type { AgentMessageTouchedExternalSource } from './AgentMessageTouchedExternalSource';
+/**
+ * Resolves which sources outside the agent one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a source counts as touched when the
+ * harness reached it in a tool invocation — calling an integration, fetching a web address,
+ * searching the web, or running a network client in the shell. Only tool payloads are inspected:
+ * tool results and assistant narration are ignored so a service merely mentioned in the
+ * conversation is never reported, and addresses of the machine the agent runs on are dropped
+ * because they are internal.
+ *
+ * @param options - Raw runtime log content of one answered message.
+ * @returns Touched external sources without duplicates, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedExternalSources(options: {
+    readonly logText: string | null | undefined;
+}): ReadonlyArray<AgentMessageTouchedExternalSource>;

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

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

package/esm/src/utils/random/$generateBookBoilerplate.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-12`).
+ * It follows semantic versioning (e.g., `0.114.0-17`).
  *
  * @generated
  */

package/package.json

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

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

@@ -1,4 +1,6 @@
 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.
@@ -72,6 +74,22 @@ export type AgentMessageRunReport = {
      * 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.

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

@@ -9,7 +9,7 @@ export declare const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH: string;
  *
  * @private internal convention shared by the Agents Server and agent-folder runner
  */
-export declare const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS: readonly ["set", "cancel"];
+export declare const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS: readonly ["set", "update", "cancel"];
 /**
  * One planned-message command action.
  *
@@ -19,8 +19,9 @@ export type AgentPlannedMessageCommandAction = (typeof AGENT_PLANNED_MESSAGE_COM
 /**
  * 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.
+ * 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
  */
@@ -29,9 +30,34 @@ export type AgentPlannedMessageSnapshot = {
     readonly dueAt: string;
     readonly message: string | null;
     /**
-     * Repeat interval in milliseconds, or `null` for a planned message that wakes the agent only once.
+     * 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.
@@ -39,13 +65,20 @@ export type AgentPlannedMessageSnapshot = {
  * 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.
+ * 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;
 };

package/umd/src/book-3.0/describeAgentPlannedMessageSchedule.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Schedule of one planned message as it is described to an agent.
+ *
+ * The fields match `AgentPlannedMessageSnapshot`, so one snapshot, one scheduling result, and one
+ * stored planned message are all described by the very same sentence.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessageScheduleDescription = {
+    readonly intervalMs?: number | null;
+    readonly cronExpression?: string | null;
+    readonly startsAt?: string | null;
+    readonly endsAt?: string | null;
+    readonly maxRunCount?: number | null;
+    readonly runCount?: number | null;
+    readonly dueAt?: string | null;
+};
+/**
+ * Describes one planned-message schedule in a single sentence fragment.
+ *
+ * A planned message can repeat forever, repeat a bounded number of times, run inside a date window, or
+ * wake the agent only once. Every surface showing a planned message — the wake-up itself, the goal-chat
+ * notes, the planned-message prompt section, and the model tools — describes it with this one helper,
+ * so an agent never has to reconcile two different wordings of the same plan.
+ *
+ * @param schedule - Schedule of the planned message.
+ * @returns Fragment such as `repeats every 5 minutes (2 of 10 runs done)`.
+ *
+ * @private internal utility of the Agents Server planned messages
+ */
+export declare function describeAgentPlannedMessageSchedule(schedule: AgentPlannedMessageScheduleDescription): string;

package/umd/src/book-components/BookEditor/createDeprecatedCommitmentDiagnostics.browser.d.ts

@@ -1,9 +1 @@
-/**
- * Browser-compatible stub for `createDeprecatedCommitmentDiagnostics`.
- *
- * In the browser build the full Node.js implementation is not available,
- * so this stub always returns an empty array to keep the editor functional.
- *
- * @private internal utility of `BookEditorMonaco`
- */
-export declare function createDeprecatedCommitmentDiagnostics(_agentSource?: string): [];
+export { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics';

package/umd/src/book-components/BookEditor/createDuplicateFromCommitmentDiagnostics.d.ts

@@ -0,0 +1,28 @@
+import type { string_book } from '../../book-2.0/agent-source/string_book';
+/**
+ * Monaco diagnostic shown when a Book source declares its parent agent more than once.
+ *
+ * @private internal type of `BookEditorMonaco`
+ */
+type DuplicateFromCommitmentDiagnostic = {
+    readonly startLineNumber: number;
+    readonly startColumn: number;
+    readonly endLineNumber: number;
+    readonly endColumn: number;
+    readonly message: string;
+    readonly source: string;
+    readonly severity: 'warning';
+};
+/**
+ * Creates Book editor diagnostics for a parent agent declared by more than one `FROM` commitment.
+ *
+ * Repeating `FROM` stays valid — the last one wins and overrides every earlier one — but an author who writes it
+ * twice usually means only one of them, so every `FROM` keyword is marked to show which one actually applies.
+ *
+ * @param agentSource - Current editor content.
+ * @returns Warning markers for every `FROM` keyword, empty when the book declares at most one parent.
+ *
+ * @private internal utility of `BookEditorMonaco`
+ */
+export declare function createDuplicateFromCommitmentDiagnostics(agentSource?: string_book): ReadonlyArray<DuplicateFromCommitmentDiagnostic>;
+export {};

package/umd/src/book-components/BookEditor/createDuplicateFromCommitmentDiagnostics.test.d.ts

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

package/umd/src/book-components/Chat/Chat/renderAgentProjectDiff.d.ts

@@ -0,0 +1,13 @@
+import { type ReactElement } from 'react';
+/**
+ * Renders one unified diff with added, removed and context lines told apart.
+ *
+ * @param options - Diff text and whether it holds only the beginning of the real diff.
+ * @returns Readable diff block.
+ *
+ * @private function of ChatToolCallModal
+ */
+export declare function renderAgentProjectDiff(options: {
+    readonly diff: string;
+    readonly isDiffTruncated: boolean;
+}): ReactElement;

package/umd/src/book-components/Chat/Chat/renderAgentProjectToolCallDetails.d.ts

@@ -0,0 +1,16 @@
+import { type ReactElement } from 'react';
+import type { AgentProjectToolCallResult } from '../utils/agentProjectToolCall';
+/**
+ * Renders the detail view of one project the answer worked with.
+ *
+ * The card answers the two questions a project chip raises: what this project is right now — its
+ * runtime state and where to open it — and what this very message did to it.
+ *
+ * @param options - Parsed project chip payload.
+ * @returns Project details section for the tool modal.
+ *
+ * @private function of ChatToolCallModal
+ */
+export declare function renderAgentProjectToolCallDetails(options: {
+    readonly project: AgentProjectToolCallResult;
+}): ReactElement;

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

@@ -1,3 +1,4 @@
+import type { AgentMessageProjectChange } from '../../../utils/agent-message-runtime/AgentMessageProjectChange';
 /**
  * Synthetic tool name used for agent-project chips in chat UI.
  *
@@ -10,6 +11,9 @@ export declare const AGENT_PROJECT_TOOL_CALL_NAME = "agent_project_touched";
 /**
  * Safe, user-facing metadata shown in agent-project chips.
  *
+ * Everything besides the project name is optional, because a chip written by an older server — or
+ * one whose project has meanwhile been deleted — still has to render.
+ *
  * @private internal chat-ui type for touched agent projects
  */
 export type AgentProjectToolCallResult = {
@@ -21,10 +25,45 @@ export type AgentProjectToolCallResult = {
      * Human-readable project name shown in the chip.
      */
     readonly displayName?: string;
+    /**
+     * Short project description, resolved the same way as on the project page.
+     */
+    readonly description?: string;
     /**
      * Link to the project page, when the chat knows where the project lives.
      */
     readonly projectHref?: string;
+    /**
+     * Address the running project itself is served on, when it has one.
+     */
+    readonly projectUrl?: string;
+    /**
+     * Whether the project was running when the answer finished.
+     */
+    readonly isRunning?: boolean;
+    /**
+     * Runtime status label, the same one the project page shows.
+     */
+    readonly runtimeStatusLabel?: string;
+    /**
+     * Total size of the project, already formatted for display.
+     */
+    readonly sizeLabel?: string;
+    /**
+     * Count of files inside the project.
+     */
+    readonly fileCount?: number;
+    /**
+     * Whether the project folder is a git repository.
+     */
+    readonly isGitRepository?: boolean;
+    /**
+     * What this very message changed in the project, when it changed anything.
+     *
+     * Its `projectName` repeats the one above because the change is reported by the agent runner
+     * in exactly this shape, and reusing it keeps the two descriptions from drifting apart.
+     */
+    readonly change?: AgentMessageProjectChange;
 };
 /**
  * Parses the project-chip payload from one tool result.

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

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

package/umd/src/book-components/Chat/utils/externalSourceToolCall.d.ts

@@ -0,0 +1,38 @@
+import type { AgentMessageTouchedExternalSource } from '../../../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+/**
+ * Synthetic tool name used for external-source chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per source outside the agent an answer viewed or
+ * edited, so the chat shows which services, websites and searches the agent really reached below
+ * the message that touched them. Work the agent does inside itself emits nothing.
+ *
+ * @private internal chat-ui marker for touched external sources
+ */
+export declare const EXTERNAL_SOURCE_TOOL_CALL_NAME = "external_source_touched";
+/**
+ * Parses the external-source chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed source metadata, or `null` when the result describes no external source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function parseExternalSourceToolCallResult(result: unknown): AgentMessageTouchedExternalSource | null;
+/**
+ * Resolves the chip label of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns User-facing name of the source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallLabel(externalSource: AgentMessageTouchedExternalSource): string;
+/**
+ * Resolves the chip emoji of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns Emoji telling apart an integration, a website and a search.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export declare function resolveExternalSourceToolCallEmoji(externalSource: AgentMessageTouchedExternalSource): string;

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

@@ -5,6 +5,12 @@ import type { TODO_any } from '../../../utils/organization/TODO_any';
  * @private internal timeout-chat constant
  */
 export declare const SET_TIMEOUT_TOOL_CALL_NAME = "set_timeout";
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export declare const UPDATE_TIMEOUT_TOOL_CALL_NAME = "update_timeout";
 /**
  * Tool name of one cancelled wake-up, used by every producer of timeout chips.
  *

package/umd/src/cli/cli-commands/coder/waitOptions.d.ts

@@ -12,3 +12,15 @@ export declare const DEFAULT_WAIT_AFTER_ERROR_MS: number;
  * @private internal utility of `ptbk coder` wait handling
  */
 export declare function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number;
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined;

package/umd/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentCollectionInSupabase.d.ts

@@ -84,8 +84,23 @@ export declare class AgentCollectionInSupabase {
     private mapAgentBasicInformationRow;
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
+     *
+     * An agent that still exists always wins over a soft-deleted one, so a name that was deleted and
+     * later created again resolves to the agent that is live now instead of to the recycle-bin leftover.
+     * Soft-deleted agents stay resolvable as a fallback because the recycle bin restores them by name
+     * or permanent id.
      */
     getAgentPermanentId(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<string_agent_permanent_id>;
+    /**
+     * Looks up the permanent id of the oldest agent matching one name or permanent id.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+     * @param options - Whether soft-deleted agents may be matched as well.
+     * @returns Permanent id of the matched agent, or `null` when nothing matches.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private findAgentPermanentId;
     /**
      * Retrieves the source code of an agent by its name or permanent ID.
      */

package/umd/src/utils/agent-message-runtime/AgentMessageProjectChange.d.ts

@@ -0,0 +1,76 @@
+/**
+ * One file an answered agent message created, edited or deleted inside one project.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChangedFile = {
+    /**
+     * Path of the file relative to the project root, using `/` separators.
+     */
+    readonly path: string;
+    /**
+     * Count of lines added to the file.
+     */
+    readonly insertionCount: number;
+    /**
+     * Count of lines removed from the file.
+     */
+    readonly deletionCount: number;
+};
+/**
+ * Everything answering one single message changed inside one agent project.
+ *
+ * Each agent project is a git repository and every answer which modifies it is committed there
+ * automatically, so this describes exactly one such commit — the trace of what one message really
+ * did to one project, which a chat can show below the answer that did it.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageProjectChange = {
+    /**
+     * Directory name of the changed project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+    /**
+     * Full hash of the commit holding the changes of this message.
+     */
+    readonly commitHash: string;
+    /**
+     * ISO 8601 timestamp when the changes were committed.
+     */
+    readonly committedAt: string;
+    /**
+     * Files the message changed, ordered as git reports them.
+     */
+    readonly changedFiles: ReadonlyArray<AgentMessageProjectChangedFile>;
+    /**
+     * Count of lines added across all changed files.
+     */
+    readonly insertionCount: number;
+    /**
+     * Count of lines removed across all changed files.
+     */
+    readonly deletionCount: number;
+    /**
+     * Unified diff of the commit, shortened when the change is too large to carry into a chat.
+     */
+    readonly diff: string;
+    /**
+     * Whether `diff` holds only the beginning of the real diff.
+     */
+    readonly isDiffTruncated: boolean;
+};
+/**
+ * Validates one already-parsed JSON value as a project change.
+ *
+ * @param value - Raw serialized project change.
+ * @returns The typed project change, or `null` when the value does not match the expected shape,
+ * so consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export declare function normalizeAgentMessageProjectChange(value: unknown): AgentMessageProjectChange | null;

package/umd/src/utils/agent-message-runtime/AgentMessageTouchedExternalSource.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Category of one external source an answered agent message touched.
+ *
+ * -   `integration` is a third-party service reached through an integration, for example Gmail.
+ * -   `website` is a concrete web address the agent fetched or browsed.
+ * -   `search` is a lookup the agent ran against a web search engine.
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSourceKind = 'integration' | 'website' | 'search';
+/**
+ * One source outside the agent itself which answering a single message viewed or edited.
+ *
+ * Everything the agent does inside its own folder stays internal and is never described here;
+ * this records only the reach beyond it, so a chat can tell which outside services and websites
+ * one answer really involved.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent-message runtime
+ */
+export type AgentMessageTouchedExternalSource = {
+    /**
+     * Category of the touched source.
+     */
+    readonly kind: AgentMessageTouchedExternalSourceKind;
+    /**
+     * User-facing name of the source, for example `Gmail`, `example.com` or the search query.
+     */
+    readonly name: string;
+    /**
+     * Address of the source, when the touch names a concrete one.
+     */
+    readonly url?: string;
+};
+/**
+ * Validates one already-parsed JSON value as a touched external source.
+ *
+ * @param value - Raw serialized source.
+ * @returns The typed source, or `null` when the value does not match the expected shape, so
+ * consumers can silently skip foreign or malformed entries.
+ *
+ * @private internal utility of the agent-message runtime
+ */
+export declare function normalizeAgentMessageTouchedExternalSource(value: unknown): AgentMessageTouchedExternalSource | null;

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

@@ -42,6 +42,9 @@ export type AgentMessageRuntimeLogEvent = {
         readonly command?: string;
         readonly exit_code?: number | null;
         readonly changes?: ReadonlyArray<AgentMessageRuntimeLogFileChange>;
+        readonly server?: string;
+        readonly tool?: string;
+        readonly query?: string;
     };
 };
 /**

package/umd/src/utils/agent-message-runtime/resolveAgentMessageTouchedExternalSources.d.ts

@@ -0,0 +1,18 @@
+import type { AgentMessageTouchedExternalSource } from './AgentMessageTouchedExternalSource';
+/**
+ * Resolves which sources outside the agent one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a source counts as touched when the
+ * harness reached it in a tool invocation — calling an integration, fetching a web address,
+ * searching the web, or running a network client in the shell. Only tool payloads are inspected:
+ * tool results and assistant narration are ignored so a service merely mentioned in the
+ * conversation is never reported, and addresses of the machine the agent runs on are dropped
+ * because they are internal.
+ *
+ * @param options - Raw runtime log content of one answered message.
+ * @returns Touched external sources without duplicates, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedExternalSources(options: {
+    readonly logText: string | null | undefined;
+}): ReadonlyArray<AgentMessageTouchedExternalSource>;

package/umd/src/utils/agent-message-runtime/resolveAgentMessageTouchedExternalSources.test.d.ts

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

package/umd/src/utils/random/$generateBookBoilerplate.test.d.ts

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

package/umd/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-12`).
+ * It follows semantic versioning (e.g., `0.114.0-17`).
  *
  * @generated
  */