@promptbook/cli 0.114.0-13 → 0.114.0-18

package/esm/scripts/run-agent-messages/git/commitAgentProjectChanges.d.ts

@@ -0,0 +1,15 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * Commits everything one answered message changed inside one agent project.
+ *
+ * The project is turned into a git repository first when it is not one yet, so the work of every
+ * answer stays recoverable and reviewable as a normal commit history.
+ *
+ * @param options - Project identity and the commit message describing the answered message.
+ * @returns What was committed, or `null` when the project changed nothing or cannot be committed.
+ */
+export declare function commitAgentProjectChanges(options: {
+    readonly projectPath: string;
+    readonly projectName: string;
+    readonly commitMessage: string;
+}): Promise<AgentMessageProjectChange | null>;

package/esm/scripts/run-agent-messages/git/commitAnsweredMessageProjectChanges.d.ts

@@ -0,0 +1,24 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * Commits what one answered message changed in every project of one agent.
+ *
+ * Every project of an agent is its own git repository, so each answer which modified one becomes a
+ * commit there. The projects are committed one after another because they share the git executable
+ * and because an agent works with a handful of projects at most.
+ *
+ * Committing is best-effort bookkeeping around an answer the agent already produced: a project
+ * whose commit fails is reported to the console and skipped instead of failing the message.
+ *
+ * @param options - Agent folder and the commit message describing the answered message.
+ * @returns What was committed, one entry per project the message really changed.
+ */
+export declare function commitAnsweredMessageProjectChanges(options: {
+    /**
+     * Absolute path of the local agent folder owning the projects.
+     */
+    readonly agentFolderPath: string;
+    /**
+     * Commit message shared by every project commit of this message.
+     */
+    readonly commitMessage: string;
+}): Promise<ReadonlyArray<AgentMessageProjectChange>>;

package/esm/scripts/run-agent-messages/git/ensureAgentProjectGitRepository.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How one agent project directory relates to git.
+ *
+ * -   `own-repository` is a project whose own history the runner can commit into.
+ * -   `tracked-elsewhere` is a project belonging to a repository around the agent folder, whose
+ *     history is already kept by whoever owns that repository.
+ * -   `unavailable` is a project which cannot be committed, for example because git is missing.
+ */
+export type AgentProjectGitRepositoryState = 'own-repository' | 'tracked-elsewhere' | 'unavailable';
+/**
+ * Makes sure one agent project is a git repository of its own.
+ *
+ * A project which is already tracked by a repository around the agent folder is deliberately left
+ * alone: initializing a repository inside it would turn it into an embedded repository and break
+ * the history that already covers it.
+ *
+ * @param projectPath - Absolute path of the project directory.
+ * @returns How the project relates to git after this call.
+ */
+export declare function ensureAgentProjectGitRepository(projectPath: string): Promise<AgentProjectGitRepositoryState>;

package/esm/scripts/run-agent-messages/git/readAgentProjectCommitChange.d.ts

@@ -0,0 +1,11 @@
+import type { AgentMessageProjectChange } from '../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+/**
+ * Describes the latest commit of one agent project repository.
+ *
+ * @param options - Project directory and the project name the description is reported under.
+ * @returns Description of the commit, or `null` when git could not describe it.
+ */
+export declare function readAgentProjectCommitChange(options: {
+    readonly projectPath: string;
+    readonly projectName: string;
+}): Promise<AgentMessageProjectChange | null>;

package/esm/scripts/run-agent-messages/git/runAgentProjectGitCommand.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Result of one git command executed inside one agent project.
+ */
+export type AgentProjectGitCommandResult = {
+    /**
+     * Whether git reported success.
+     */
+    readonly isSuccessful: boolean;
+    /**
+     * Standard output of the command, with the trailing newline removed.
+     */
+    readonly output: string;
+};
+/**
+ * Runs one git command inside one agent project directory.
+ *
+ * Commands are executed without a shell and with an explicit argument list, so a project name or
+ * a file path can never be interpreted as a shell fragment. A failing command is reported through
+ * `isSuccessful` instead of throwing, because git uses the exit code to answer questions such as
+ * "is there anything staged" and because auto-committing a project must never fail an answer the
+ * agent already produced.
+ *
+ * @param options - Project directory and the git arguments to run there.
+ * @returns Outcome of the command.
+ */
+export declare function runAgentProjectGitCommand(options: {
+    readonly projectPath: string;
+    readonly args: ReadonlyArray<string>;
+}): Promise<AgentProjectGitCommandResult>;

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

@@ -16,9 +16,9 @@ export type AgentPlannedMessagesPromptSidecar = {
  * 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
- * 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.
+ * wake-up is planned, and each of them keeps repeating until its schedule is over or it is 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.

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

@@ -0,0 +1,7 @@
+/**
+ * Lists the direct project directories of one agent folder.
+ *
+ * @param agentFolderPath - Absolute path of the local agent folder.
+ * @returns Project directory names, or an empty list when the agent has no projects folder.
+ */
+export declare function listAgentProjectDirectoryNames(agentFolderPath: string): Promise<ReadonlyArray<string>>;

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

@@ -0,0 +1,29 @@
+import type { AgentMessageTouchedExternalSource } from '../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+/**
+ * Everything one answered message worked with, both inside and outside the agent.
+ */
+export type AnsweredMessageTouches = {
+    /**
+     * Directory names of the agent projects the answer viewed or edited.
+     */
+    readonly touchedProjectNames: ReadonlyArray<string>;
+    /**
+     * Sources outside the agent the answer reached.
+     */
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
+};
+/**
+ * Resolves which agent projects and which external sources one answered message touched.
+ *
+ * The runtime log is deleted as soon as the harness run finishes, so this must be called while
+ * the log still exists — the Agents Server later shows everything reported here as chips below
+ * the answer. Reporting touches is best-effort telemetry: an unreadable log or projects folder
+ * simply yields nothing instead of failing the already answered message.
+ *
+ * @param options - Agent folder path and the live runtime log path of the answered message.
+ * @returns Touched projects and external sources, ordered by first appearance in the run.
+ */
+export declare function resolveAnsweredMessageTouches(options: {
+    readonly projectPath: string;
+    readonly runtimeLogPath: string;
+}): Promise<AnsweredMessageTouches>;

package/esm/scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically.d.ts

@@ -0,0 +1,22 @@
+import type { PingCoderHarnessOptions } from './pingCoderHarness';
+/**
+ * Options for the endless `ptbk coder ping --period <duration>` loop.
+ */
+export type PingCoderHarnessPeriodicallyOptions = PingCoderHarnessOptions & {
+    /**
+     * How long one ping period lasts, in milliseconds.
+     *
+     * The period is measured from the start of one ping to the start of the next one, so the pings
+     * really happen once per period instead of once per period plus the duration of the ping itself.
+     */
+    readonly periodMs: number;
+};
+/**
+ * Pings the selected harness and model once per period until the process is stopped.
+ *
+ * This keeps the quota window of the harness refreshing without any real work, so the window is
+ * always open by the time you need it. The loop never ends on its own — it is stopped with `CTRL+C`
+ * or by killing the process — therefore a failing ping is reported and the next period is started
+ * instead of tearing the whole loop down.
+ */
+export declare function pingCoderHarnessPeriodically(options: PingCoderHarnessPeriodicallyOptions): Promise<never>;

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;