@promptbook/cli 0.114.0-13 → 0.114.0-18

package/apps/agents-server/src/utils/agentGoalChat/agentGoalChatPlannedMessageActions.ts

@@ -1,11 +1,19 @@
 import { spaceTrim } from 'spacetrim';
 import { ParseError } from '../../../../../src/errors/ParseError';
-import type { UserChatTimeoutRecord, UserChatTimeoutStatus } from '../userChatTimeout';
+import type {
+    PlannedMessageScheduleInput,
+    UpdateAgentScopedUserChatTimeoutPatch,
+    UserChatTimeoutRecord,
+    UserChatTimeoutStatus,
+} from '../userChatTimeout';
 import {
     cancelScheduledUserChatTimeout,
     getAgentScopedUserChatTimeout,
     listAgentUserChatTimeouts,
+    parsePlannedMessageSchedule,
+    resolvePlannedMessageDueAt,
     scheduleThreadScopedUserChatTimeout,
+    updateScheduledUserChatTimeout,
 } from '../userChatTimeout';
 import { ensureAgentGoalChat } from './ensureAgentGoalChat';
 
@@ -24,14 +32,6 @@ const MAX_LISTED_PLANNED_MESSAGES_LIMIT = 100;
  */
 const ACTIVE_PLANNED_MESSAGE_STATUSES: ReadonlyArray<UserChatTimeoutStatus> = ['QUEUED', 'RUNNING'];
 
-/**
- * Shortest repeat interval one agent may plan for itself.
- *
- * Planned messages repeat like `setInterval`, so an interval below one minute would turn the goal
- * chat into an unattended self-invocation loop instead of a plan.
- */
-const MINIMUM_PLANNED_MESSAGE_INTERVAL_MS = 60_000;
-
 /**
  * Minimal goal-chat identity needed when scheduling a planned message.
  */
@@ -41,35 +41,76 @@ type AgentGoalChatPlannedMessageTarget = {
 };
 
 /**
- * Serializable summary of one planned goal-chat message.
+ * Serializable schedule of one planned goal-chat message.
+ *
+ * The field names match the planned-message sidecar snapshot, so one scheduling result, one listed
+ * message, and one sidecar entry all describe a schedule in exactly the same way.
  */
-export type AgentGoalChatPlannedMessageItem = {
-    readonly timeoutId: string;
-    readonly status: UserChatTimeoutStatus;
+export type AgentGoalChatPlannedMessageScheduleFields = {
     readonly dueAt: string;
-    readonly isPaused: boolean;
     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` when the planned message does not repeat at a fixed
+     * interval.
      */
     readonly intervalMs: number | null;
+
+    /**
+     * Five-field cron expression, 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`.
+     */
+    readonly startsAt: string | null;
+
+    /**
+     * Moment after which the planned message never wakes the agent again, or `null`.
+     */
+    readonly endsAt: string | null;
+
+    /**
+     * Total number of wake-ups, or `null` when the planned message repeats until it is cancelled.
+     */
+    readonly maxRunCount: number | null;
+
+    /**
+     * Number of wake-ups that already happened.
+     */
+    readonly runCount: number;
+};
+
+/**
+ * Serializable summary of one planned goal-chat message.
+ */
+export type AgentGoalChatPlannedMessageItem = AgentGoalChatPlannedMessageScheduleFields & {
+    readonly timeoutId: string;
+    readonly status: UserChatTimeoutStatus;
+    readonly isPaused: boolean;
 };
 
 /**
  * Result returned after scheduling one planned goal-chat message.
  */
-export type SetAgentGoalChatPlannedMessageResult = {
+export type SetAgentGoalChatPlannedMessageResult = AgentGoalChatPlannedMessageScheduleFields & {
     readonly action: 'set';
     readonly status: 'set';
     readonly timeoutId: string;
-    readonly dueAt: string;
-    readonly message: string | null;
+};
 
-    /**
-     * Repeat interval in milliseconds of the scheduled planned message.
-     */
-    readonly intervalMs: number | null;
+/**
+ * Result returned after changing the schedule of one planned goal-chat message.
+ *
+ * The schedule fields are absent when there was no such planned message to change. A planned message
+ * which is firing right now reports `busy` together with the schedule it still has, because its
+ * schedule is being consumed by that very firing and is therefore left untouched.
+ */
+export type UpdateAgentGoalChatPlannedMessageResult = Partial<AgentGoalChatPlannedMessageScheduleFields> & {
+    readonly action: 'update';
+    readonly status: 'updated' | 'busy' | 'not_found';
+    readonly timeoutId: string;
 };
 
 /**
@@ -92,26 +133,55 @@ export type CancelAgentGoalChatPlannedMessageResult = {
     readonly dueAt?: string;
 };
 
+/**
+ * Schedule an agent may request for one planned message.
+ *
+ * Every field is untrusted, and leaving all of them out is only allowed when updating the message text
+ * of an existing planned message.
+ */
+export type AgentGoalChatPlannedMessageScheduleRequest = {
+    readonly milliseconds?: unknown;
+    readonly cronExpression?: unknown;
+    readonly startsAt?: unknown;
+    readonly endsAt?: unknown;
+    readonly maxRunCount?: unknown;
+};
+
 /**
  * Shared operations used by both model tools and the coding-agent runtime API.
  *
- * Planned messages behave like `setInterval`: `set` starts a repeating wake-up and only `cancel`
- * stops it, so an agent that is happy with its plan does not have to do anything.
+ * A planned message can repeat like `setInterval`, wake the agent a bounded number of times, run only
+ * inside a date window, or fire just once — and it can be re-planned or cancelled at any time from any
+ * invocation of the agent.
  */
 export type AgentGoalChatPlannedMessageActions = {
     /**
-     * Starts one repeating planned message, where `milliseconds` is its repeat interval.
+     * Plans one message, where the schedule says how and how long it repeats.
      */
-    readonly set: (options: {
-        readonly agentPermanentId: string;
-        readonly milliseconds: unknown;
-        readonly message: unknown;
-    }) => Promise<SetAgentGoalChatPlannedMessageResult>;
+    readonly set: (
+        options: AgentGoalChatPlannedMessageScheduleRequest & {
+            readonly agentPermanentId: string;
+            readonly message: unknown;
+        },
+    ) => Promise<SetAgentGoalChatPlannedMessageResult>;
+
+    /**
+     * Changes the schedule or the text of one already planned message, keeping its identity.
+     */
+    readonly update: (
+        options: AgentGoalChatPlannedMessageScheduleRequest & {
+            readonly agentPermanentId: string;
+            readonly timeoutId: unknown;
+            readonly message?: unknown;
+        },
+    ) => Promise<UpdateAgentGoalChatPlannedMessageResult>;
+
     readonly list: (options: {
         readonly agentPermanentId: string;
         readonly isIncludingFinished?: unknown;
         readonly limit?: unknown;
     }) => Promise<ListAgentGoalChatPlannedMessagesResult>;
+
     readonly cancel: (options: {
         readonly agentPermanentId: string;
         readonly timeoutId: unknown;
@@ -126,6 +196,7 @@ export type AgentGoalChatPlannedMessageDependencies = {
     readonly scheduleThreadScopedUserChatTimeout: typeof scheduleThreadScopedUserChatTimeout;
     readonly listAgentUserChatTimeouts: typeof listAgentUserChatTimeouts;
     readonly getAgentScopedUserChatTimeout: typeof getAgentScopedUserChatTimeout;
+    readonly updateScheduledUserChatTimeout: typeof updateScheduledUserChatTimeout;
     readonly cancelScheduledUserChatTimeout: typeof cancelScheduledUserChatTimeout;
 };
 
@@ -137,6 +208,7 @@ const AGENT_GOAL_CHAT_PLANNED_MESSAGE_DEPENDENCIES: AgentGoalChatPlannedMessageD
     scheduleThreadScopedUserChatTimeout,
     listAgentUserChatTimeouts,
     getAgentScopedUserChatTimeout,
+    updateScheduledUserChatTimeout,
     cancelScheduledUserChatTimeout,
 };
 
@@ -144,7 +216,7 @@ const AGENT_GOAL_CHAT_PLANNED_MESSAGE_DEPENDENCIES: AgentGoalChatPlannedMessageD
  * Creates the shared planned-message operations for one agent's singleton goal chat.
  *
  * @param dependencyOverrides - Optional persistence substitutions used by focused tests.
- * @returns Scheduling, listing, and cancellation operations with normalized serializable results.
+ * @returns Scheduling, re-planning, listing, and cancellation operations with normalized serializable results.
  */
 export function createAgentGoalChatPlannedMessageActions(
     dependencyOverrides: Partial<AgentGoalChatPlannedMessageDependencies> = {},
@@ -157,16 +229,18 @@ export function createAgentGoalChatPlannedMessageActions(
     return {
         async set(options): Promise<SetAgentGoalChatPlannedMessageResult> {
             const agentPermanentId = parseRequiredText(options.agentPermanentId, 'agentPermanentId');
-            const intervalMs = parsePlannedMessageIntervalMs(options.milliseconds);
+            const schedule = parsePlannedMessageSchedule(createPlannedMessageScheduleInput(options));
             const message = parseRequiredText(options.message, 'message');
             const goalChat = await dependencies.ensureAgentGoalChat(agentPermanentId);
-            // Note: A planned message repeats like `setInterval`, so the requested delay is also its interval
             const plannedMessage = await dependencies.scheduleThreadScopedUserChatTimeout({
                 userId: goalChat.userId,
                 agentPermanentId,
                 chatId: goalChat.id,
-                durationMs: intervalMs,
-                recurrenceIntervalMs: intervalMs,
+                recurrenceIntervalMs: schedule.recurrenceIntervalMs,
+                cronExpression: schedule.cronExpression,
+                startsAt: schedule.startsAt,
+                endsAt: schedule.endsAt,
+                maxRunCount: schedule.maxRunCount,
                 message,
             });
 
@@ -174,9 +248,49 @@ export function createAgentGoalChatPlannedMessageActions(
                 action: 'set',
                 status: 'set',
                 timeoutId: plannedMessage.timeoutId,
-                dueAt: plannedMessage.dueAt,
-                message: plannedMessage.message,
-                intervalMs: plannedMessage.recurrenceIntervalMs,
+                ...createPlannedMessageScheduleFields(plannedMessage),
+            };
+        },
+
+        async update(options): Promise<UpdateAgentGoalChatPlannedMessageResult> {
+            const agentPermanentId = parseRequiredText(options.agentPermanentId, 'agentPermanentId');
+            const timeoutId = parseRequiredText(options.timeoutId, 'timeoutId');
+            const existingPlannedMessage = await dependencies.getAgentScopedUserChatTimeout({
+                agentPermanentId,
+                timeoutId,
+            });
+
+            if (!isActivePlannedMessage(existingPlannedMessage)) {
+                return { action: 'update', status: 'not_found', timeoutId };
+            }
+
+            if (existingPlannedMessage.status === 'RUNNING') {
+                // Note: A firing planned message is being re-armed from its stored schedule right now,
+                //       so changing that schedule underneath the firing would be silently overwritten
+                return {
+                    action: 'update',
+                    status: 'busy',
+                    timeoutId,
+                    ...createPlannedMessageScheduleFields(existingPlannedMessage),
+                };
+            }
+
+            const patch = createPlannedMessagePatch(existingPlannedMessage, options);
+            const updatedPlannedMessage = await dependencies.updateScheduledUserChatTimeout({
+                agentPermanentId,
+                timeoutId,
+                patch,
+            });
+
+            if (!updatedPlannedMessage) {
+                return { action: 'update', status: 'not_found', timeoutId };
+            }
+
+            return {
+                action: 'update',
+                status: 'updated',
+                timeoutId,
+                ...createPlannedMessageScheduleFields(updatedPlannedMessage),
             };
         },
 
@@ -236,26 +350,140 @@ export function createAgentGoalChatPlannedMessageActions(
 export const AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS = createAgentGoalChatPlannedMessageActions();
 
 /**
- * Parses one planned-message repeat interval.
+ * Collects the untrusted schedule fields of one planned-message request.
+ *
+ * @param request - Schedule requested by an agent.
+ * @returns Schedule input of the shared schedule parser.
+ */
+function createPlannedMessageScheduleInput(
+    request: AgentGoalChatPlannedMessageScheduleRequest,
+): PlannedMessageScheduleInput {
+    return {
+        milliseconds: request.milliseconds,
+        cronExpression: request.cronExpression,
+        startsAt: request.startsAt,
+        endsAt: request.endsAt,
+        maxRunCount: request.maxRunCount,
+    };
+}
+
+/**
+ * Builds the stored patch of one re-planned message.
  *
- * @param rawMilliseconds - Untrusted interval supplied by a model or runtime API.
- * @returns Repeat interval in whole milliseconds.
+ * Only the requested fields change: the schedule is re-validated as a whole against the fields that
+ * stay, and the next wake-up is moved to the first one the new schedule allows.
+ *
+ * @param existingPlannedMessage - Planned message being changed.
+ * @param request - Schedule and message requested by the agent.
+ * @returns Patch written to the stored planned message.
  */
-function parsePlannedMessageIntervalMs(rawMilliseconds: unknown): number {
-    const milliseconds = Number(rawMilliseconds);
+function createPlannedMessagePatch(
+    existingPlannedMessage: UserChatTimeoutRecord,
+    request: AgentGoalChatPlannedMessageScheduleRequest & { readonly message?: unknown },
+): UpdateAgentScopedUserChatTimeoutPatch {
+    const isMessageRequested = request.message !== undefined;
+    const messagePatch = isMessageRequested ? { message: parseRequiredText(request.message, 'message') } : {};
+
+    if (!isPlannedMessageScheduleRequested(request)) {
+        if (!isMessageRequested) {
+            throw new ParseError(
+                spaceTrim(`
+                    Nothing to change in this planned message.
+
+                    - Pass at least one of \`cronExpression\`, \`milliseconds\`, \`startsAt\`, \`endsAt\`, \`maxRunCount\`, or \`message\`.
+                `),
+            );
+        }
+
+        return messagePatch;
+    }
+
+    const schedule = parsePlannedMessageSchedule(
+        createMergedPlannedMessageScheduleInput(existingPlannedMessage, request),
+    );
+    const dueAtDate = resolvePlannedMessageDueAt({
+        schedule,
+        completedRunCount: existingPlannedMessage.runCount,
+        afterDate: new Date(),
+    });
 
-    if (!Number.isFinite(milliseconds) || milliseconds < MINIMUM_PLANNED_MESSAGE_INTERVAL_MS) {
+    if (dueAtDate === null) {
         throw new ParseError(
             spaceTrim(`
-                Invalid planned-message interval.
+                This change would leave the planned message without any wake-up ahead.
 
-                - A planned message **repeats** at this interval until it is cancelled.
-                - \`milliseconds\` must be a number of at least \`${MINIMUM_PLANNED_MESSAGE_INTERVAL_MS}\`.
+                - Its schedule would already be over, for example because \`endsAt\` is in the past or \`maxRunCount\` is not above the ${existingPlannedMessage.runCount} run(s) it already did.
+                - **Cancel** the planned message instead when it should stop.
             `),
         );
     }
 
-    return Math.floor(milliseconds);
+    return {
+        ...messagePatch,
+        dueAt: dueAtDate.toISOString(),
+        recurrenceIntervalMs: schedule.recurrenceIntervalMs,
+        cronExpression: schedule.cronExpression,
+        startsAt: schedule.startsAt,
+        endsAt: schedule.endsAt,
+        maxRunCount: schedule.maxRunCount,
+    };
+}
+
+/**
+ * Merges one requested schedule change into the schedule a planned message already has.
+ *
+ * Choosing a cron drops the fixed interval and choosing an interval drops the cron, because one
+ * planned message follows exactly one recurrence rule.
+ *
+ * @param existingPlannedMessage - Planned message being changed.
+ * @param request - Schedule requested by the agent.
+ * @returns Schedule input describing the planned message after the change.
+ */
+function createMergedPlannedMessageScheduleInput(
+    existingPlannedMessage: UserChatTimeoutRecord,
+    request: AgentGoalChatPlannedMessageScheduleRequest,
+): PlannedMessageScheduleInput {
+    const isCronRequested = Boolean(request.cronExpression);
+    const isIntervalRequested = request.milliseconds !== undefined && request.milliseconds !== null;
+
+    return {
+        milliseconds: isCronRequested
+            ? null
+            : resolveRequestedScheduleValue(request.milliseconds, existingPlannedMessage.recurrenceIntervalMs),
+        cronExpression: isIntervalRequested
+            ? null
+            : resolveRequestedScheduleValue(request.cronExpression, existingPlannedMessage.cronExpression),
+        startsAt: resolveRequestedScheduleValue(request.startsAt, existingPlannedMessage.startsAt),
+        endsAt: resolveRequestedScheduleValue(request.endsAt, existingPlannedMessage.endsAt),
+        maxRunCount: resolveRequestedScheduleValue(request.maxRunCount, existingPlannedMessage.maxRunCount),
+    };
+}
+
+/**
+ * Keeps the stored value of one schedule field that was not part of the request.
+ *
+ * @param requestedValue - Untrusted value from the request, where `undefined` means "not requested".
+ * @param storedValue - Value the planned message has today.
+ * @returns Value describing the field after the change.
+ */
+function resolveRequestedScheduleValue(requestedValue: unknown, storedValue: unknown): unknown {
+    return requestedValue === undefined ? storedValue : requestedValue;
+}
+
+/**
+ * Determines whether one request changes the schedule instead of only the message text.
+ *
+ * @param request - Schedule requested by the agent.
+ * @returns `true` when at least one schedule field was requested.
+ */
+function isPlannedMessageScheduleRequested(request: AgentGoalChatPlannedMessageScheduleRequest): boolean {
+    return (
+        request.milliseconds !== undefined ||
+        request.cronExpression !== undefined ||
+        request.startsAt !== undefined ||
+        request.endsAt !== undefined ||
+        request.maxRunCount !== undefined
+    );
 }
 
 /**
@@ -304,6 +532,27 @@ function parseListLimit(rawLimit: unknown): number {
     return Math.floor(limit);
 }
 
+/**
+ * Maps one durable timeout row into the schedule shared by every planned-message result.
+ *
+ * @param plannedMessage - Stored timeout row.
+ * @returns Serializable schedule of the planned message.
+ */
+function createPlannedMessageScheduleFields(
+    plannedMessage: UserChatTimeoutRecord,
+): AgentGoalChatPlannedMessageScheduleFields {
+    return {
+        dueAt: plannedMessage.dueAt,
+        message: plannedMessage.message,
+        intervalMs: plannedMessage.recurrenceIntervalMs,
+        cronExpression: plannedMessage.cronExpression,
+        startsAt: plannedMessage.startsAt,
+        endsAt: plannedMessage.endsAt,
+        maxRunCount: plannedMessage.maxRunCount,
+        runCount: plannedMessage.runCount,
+    };
+}
+
 /**
  * Maps one durable timeout row into the model-facing planned-message shape.
  *
@@ -314,15 +563,13 @@ function createPlannedMessageListItem(plannedMessage: UserChatTimeoutRecord): Ag
     return {
         timeoutId: plannedMessage.timeoutId,
         status: plannedMessage.status,
-        dueAt: plannedMessage.dueAt,
         isPaused: Boolean(plannedMessage.pausedAt),
-        message: plannedMessage.message,
-        intervalMs: plannedMessage.recurrenceIntervalMs,
+        ...createPlannedMessageScheduleFields(plannedMessage),
     };
 }
 
 /**
- * Determines whether one timeout can still be cancelled.
+ * Determines whether one timeout can still be changed or cancelled.
  *
  * @param plannedMessage - Stored timeout or a missing lookup result.
  * @returns `true` for active messages without an existing cancellation request.

package/apps/agents-server/src/utils/agentGoalChat/createAgentGoalChatNoteContent.ts

@@ -1,5 +1,8 @@
 import { spaceTrim } from 'spacetrim';
-import { formatTimeoutDurationHuman } from '../../../../../src/book-components/Chat/utils/timeoutToolCallPresentation';
+import {
+    describeAgentPlannedMessageSchedule,
+    type AgentPlannedMessageScheduleDescription,
+} from '../../../../../src/book-3.0/describeAgentPlannedMessageSchedule';
 
 /**
  * Lifecycle events of an agent that are recorded in its goal chat.
@@ -57,27 +60,54 @@ export function createAgentGoalChatLifecycleNoteContent(options: {
 }
 
 /**
- * Builds the goal-chat note left when a planned message is scheduled.
- *
- * @param options - Planned-message identity, repeat interval, due time, and optional payload message.
- * @returns Note content stored as one agent message.
+ * Planned-message details shown in one goal-chat note.
  */
-export function createAgentGoalChatPlannedMessageNoteContent(options: {
+export type AgentGoalChatPlannedMessageNoteOptions = AgentPlannedMessageScheduleDescription & {
     readonly timeoutId: string;
     readonly dueAt: string;
-    readonly intervalMs?: number | null;
     readonly message?: string | null;
-}): string {
+};
+
+/**
+ * Builds the goal-chat note left when a planned message is scheduled.
+ *
+ * @param options - Planned-message identity, its whole schedule, and optional payload message.
+ * @returns Note content stored as one agent message.
+ */
+export function createAgentGoalChatPlannedMessageNoteContent(options: AgentGoalChatPlannedMessageNoteOptions): string {
+    return createAgentGoalChatPlannedMessageScheduleNoteContent('⏳ I planned a message that', options);
+}
+
+/**
+ * Builds the goal-chat note left when the schedule of a planned message is changed.
+ *
+ * @param options - Planned-message identity, its new schedule, and optional payload message.
+ * @returns Note content stored as one agent message.
+ */
+export function createAgentGoalChatUpdatedPlannedMessageNoteContent(
+    options: AgentGoalChatPlannedMessageNoteOptions,
+): string {
+    return createAgentGoalChatPlannedMessageScheduleNoteContent('🔁 I changed a planned message, which now', options);
+}
+
+/**
+ * Builds one goal-chat note describing the current schedule of a planned message.
+ *
+ * @param headlinePrefix - Sentence opening telling apart a new plan from a changed one.
+ * @param options - Planned-message identity, its schedule, and optional payload message.
+ * @returns Note content stored as one agent message.
+ *
+ * @private function of `createAgentGoalChatNoteContent`
+ */
+function createAgentGoalChatPlannedMessageScheduleNoteContent(
+    headlinePrefix: string,
+    options: AgentGoalChatPlannedMessageNoteOptions,
+): string {
     const plannedMessage = options.message?.trim() || '';
-    const headline = options.intervalMs
-        ? `⏳ I planned a message that will wake me up every ${formatTimeoutDurationHuman(
-              options.intervalMs,
-          )}, for the first time at ${options.dueAt}.`
-        : `⏳ I planned a message that will wake me up at ${options.dueAt}.`;
 
     return spaceTrim(
         (block) => `
-            ${headline}
+            ${headlinePrefix} ${describeAgentPlannedMessageSchedule(options)}.
 
             ${plannedMessage ? block(plannedMessage) : ''}
 
@@ -92,9 +122,7 @@ export function createAgentGoalChatPlannedMessageNoteContent(options: {
  * @param options - Planned-message identity.
  * @returns Note content stored as one agent message.
  */
-export function createAgentGoalChatCancelledPlannedMessageNoteContent(options: {
-    readonly timeoutId: string;
-}): string {
+export function createAgentGoalChatCancelledPlannedMessageNoteContent(options: { readonly timeoutId: string }): string {
     return spaceTrim(`
         🚫 I cancelled the planned message \`${options.timeoutId}\`, so it will not wake me up anymore.
     `);

package/apps/agents-server/src/utils/agentGoalChat.ts

@@ -10,6 +10,7 @@ export {
     createAgentGoalChatCancelledPlannedMessageNoteContent,
     createAgentGoalChatLifecycleNoteContent,
     createAgentGoalChatPlannedMessageNoteContent,
+    createAgentGoalChatUpdatedPlannedMessageNoteContent,
 } from './agentGoalChat/createAgentGoalChatNoteContent';
 export { ensureAgentGoalChat } from './agentGoalChat/ensureAgentGoalChat';
 export {

package/apps/agents-server/src/utils/agentProjects/agentProjectIdentity.ts

@@ -0,0 +1,46 @@
+import { isSameAgentPermanentId } from '../agentIdentifier';
+
+/**
+ * Identity of one agent project, shared by every project runtime state store.
+ */
+export type AgentProjectIdentity = {
+    /**
+     * Permanent id of the agent owning the project.
+     */
+    readonly agentPermanentId: string;
+
+    /**
+     * Directory name of the project inside the agent `projects/` folder.
+     */
+    readonly projectName: string;
+};
+
+/**
+ * Creates the case-insensitive lookup key of one agent project.
+ *
+ * Agent permanent ids and project directory names are compared without letter casing everywhere,
+ * so state stores keyed by this function can never hold two entries for the same project.
+ *
+ * @param identity - Agent and project identification.
+ * @returns Lookup key usable in a `Map` or `Set`.
+ */
+export function createAgentProjectIdentityKey(identity: AgentProjectIdentity): string {
+    return `${identity.agentPermanentId.toLowerCase()}/${identity.projectName.toLowerCase()}`;
+}
+
+/**
+ * Returns whether two identities describe the same agent project.
+ *
+ * @param firstIdentity - First agent and project identification.
+ * @param secondIdentity - Second agent and project identification.
+ * @returns `true` when both identities point at the same project of the same agent.
+ */
+export function isSameAgentProjectIdentity(
+    firstIdentity: AgentProjectIdentity,
+    secondIdentity: AgentProjectIdentity,
+): boolean {
+    return (
+        isSameAgentPermanentId(firstIdentity.agentPermanentId, secondIdentity.agentPermanentId) &&
+        firstIdentity.projectName.toLowerCase() === secondIdentity.projectName.toLowerCase()
+    );
+}