@promptbook/cli 0.114.0-13 → 0.114.0-18

package/apps/agents-server/src/utils/chatMessageChips/createAnsweredMessageChipToolCalls.ts

@@ -1,15 +1,20 @@
 import type { ToolCall } from '@promptbook-local/types';
+import type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+import type { AgentMessageTouchedExternalSource } from '../../../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
 import type { AppliedAgentPlannedMessageCommand } from '../localChatRunner/applyLocalAgentPlannedMessageCommands';
 import { createPlannedMessageChipToolCalls } from './createPlannedMessageChipToolCalls';
+import { createTouchedExternalSourceChipToolCalls } from './createTouchedExternalSourceChipToolCalls';
 import { createTouchedProjectChipToolCalls } from './createTouchedProjectChipToolCalls';
 
 /**
  * Creates every extra chip shown below one answered chat message.
  *
  * This is the single place deciding what an answer shows besides its text: the wake-ups it
- * planned and the projects it worked with. The chips travel as tool calls of the assistant
- * message, so they are visible in every chat view — including external chats such as email,
- * whose outbound reply is rendered from the message text alone and therefore stays unchanged.
+ * planned, the projects it worked with — including what it changed in them — and the sources
+ * outside the agent it touched. The chips
+ * travel as tool calls of the assistant message, so they are visible in every chat view —
+ * including external chats such as email, whose outbound reply is rendered from the message text
+ * alone and therefore stays unchanged.
  *
  * @param options - Owning agent plus what the answered message planned and touched.
  * @returns Tool calls rendered as chips below the answer, in a stable order.
@@ -18,17 +23,24 @@ export async function createAnsweredMessageChipToolCalls(options: {
     readonly agentPermanentId: string;
     readonly appliedPlannedMessageCommands: ReadonlyArray<AppliedAgentPlannedMessageCommand>;
     readonly touchedProjectNames: ReadonlyArray<string>;
+    readonly projectChanges?: ReadonlyArray<AgentMessageProjectChange>;
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
     readonly createdAt?: NonNullable<ToolCall['createdAt']>;
 }): Promise<ReadonlyArray<ToolCall>> {
     const createdAt = options.createdAt || (new Date().toISOString() as NonNullable<ToolCall['createdAt']>);
     const projectChipToolCalls = await createTouchedProjectChipToolCalls({
         agentPermanentId: options.agentPermanentId,
         touchedProjectNames: options.touchedProjectNames,
+        projectChanges: options.projectChanges || [],
         createdAt,
     });
 
     return [
         ...projectChipToolCalls,
+        ...createTouchedExternalSourceChipToolCalls({
+            touchedExternalSources: options.touchedExternalSources,
+            createdAt,
+        }),
         ...createPlannedMessageChipToolCalls({
             appliedCommands: options.appliedPlannedMessageCommands,
             createdAt,

package/apps/agents-server/src/utils/chatMessageChips/createPlannedMessageChipToolCalls.ts

@@ -11,11 +11,12 @@ import type { AppliedAgentPlannedMessageCommand } from '../localChatRunner/apply
 const PLANNED_MESSAGE_CHIP_IDEMPOTENCY_PREFIX = 'planned-message';
 
 /**
- * Creates the timeout chips of the message that planned or cancelled a wake-up.
+ * Creates the timeout chips of the message that planned, re-planned, or cancelled a wake-up.
  *
  * The chat already renders `set_timeout` and `cancel_timeout` tool calls as timeout chips with a
  * detail popup, so one planned message becomes exactly one such tool call instead of a second
- * timeout presentation.
+ * timeout presentation. A re-planned message keeps the scheduling chip, because it still ends with a
+ * wake-up waiting ahead.
  *
  * @param options - Planned-message commands applied for one answered message.
  * @returns Timeout tool calls shown as chips below the answer.
@@ -25,9 +26,13 @@ export function createPlannedMessageChipToolCalls(options: {
     readonly createdAt: NonNullable<ToolCall['createdAt']>;
 }): ReadonlyArray<ToolCall> {
     return options.appliedCommands.map(({ command, result }) => ({
-        name: result.action === 'set' ? SET_TIMEOUT_TOOL_CALL_NAME : CANCEL_TIMEOUT_TOOL_CALL_NAME,
+        name: result.action === 'cancel' ? CANCEL_TIMEOUT_TOOL_CALL_NAME : SET_TIMEOUT_TOOL_CALL_NAME,
         arguments: {
             ...(command.milliseconds === undefined ? {} : { milliseconds: command.milliseconds }),
+            ...(command.cronExpression === undefined ? {} : { cronExpression: command.cronExpression }),
+            ...(command.startsAt === undefined ? {} : { startsAt: command.startsAt }),
+            ...(command.endsAt === undefined ? {} : { endsAt: command.endsAt }),
+            ...(command.maxRunCount === undefined ? {} : { maxRunCount: command.maxRunCount }),
             ...(command.message === undefined ? {} : { message: command.message }),
             ...(command.timeoutId === undefined ? {} : { timeoutId: command.timeoutId }),
         },

package/apps/agents-server/src/utils/chatMessageChips/createTouchedExternalSourceChipToolCalls.ts

@@ -0,0 +1,39 @@
+import type { ToolCall } from '@promptbook-local/types';
+import { EXTERNAL_SOURCE_TOOL_CALL_NAME } from '../../../../../src/book-components/Chat/utils/externalSourceToolCall';
+import type { AgentMessageTouchedExternalSource } from '../../../../../src/utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+
+/**
+ * Prefix of the idempotency keys identifying touched-external-source chips.
+ */
+const TOUCHED_EXTERNAL_SOURCE_CHIP_IDEMPOTENCY_PREFIX = 'external-source';
+
+/**
+ * Creates the external-source chips of one answered message.
+ *
+ * An external source is reported by the runner once the answering harness reached beyond the
+ * agent itself — an integration such as Gmail, a website, or a web search — so the chat always
+ * tells which outside services and addresses one answer really involved. Work the agent does
+ * only inside itself reaches this with an empty list and therefore shows no chip.
+ *
+ * @param options - External sources the answer touched.
+ * @returns External-source tool calls shown as chips below the answer.
+ */
+export function createTouchedExternalSourceChipToolCalls(options: {
+    readonly touchedExternalSources: ReadonlyArray<AgentMessageTouchedExternalSource>;
+    readonly createdAt: NonNullable<ToolCall['createdAt']>;
+}): ReadonlyArray<ToolCall> {
+    return options.touchedExternalSources.map((touchedExternalSource) => ({
+        name: EXTERNAL_SOURCE_TOOL_CALL_NAME,
+        arguments: {
+            kind: touchedExternalSource.kind,
+            name: touchedExternalSource.name,
+            ...(touchedExternalSource.url === undefined ? {} : { url: touchedExternalSource.url }),
+        },
+        result: touchedExternalSource,
+        state: 'COMPLETE',
+        idempotencyKey: `${TOUCHED_EXTERNAL_SOURCE_CHIP_IDEMPOTENCY_PREFIX}-${
+            touchedExternalSource.kind
+        }-${touchedExternalSource.name.toLowerCase()}`,
+        createdAt: options.createdAt,
+    }));
+}

package/apps/agents-server/src/utils/chatMessageChips/createTouchedProjectChipResult.ts

@@ -0,0 +1,45 @@
+import type { AgentProjectToolCallResult } from '../../../../../src/book-components/Chat/utils/agentProjectToolCall';
+import type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
+import { buildAgentProjectProfileHref } from '../agentProjects/agentProjectHrefs';
+import { resolveAgentProjectInfo } from '../agentProjects/resolveAgentProjectInfo';
+import { resolveAgentProjectRuntimeStatus } from '../agentProjects/resolveAgentProjectRuntimeStatus';
+import { formatResourceBytes } from '../resourceMonitor/formatResourceMonitorValue';
+
+/**
+ * Builds everything one project chip shows about the project it stands for.
+ *
+ * The payload is assembled from the very same sources as the project page — project metadata,
+ * runtime state and the formatted project size — so a chip and the page it links to can never
+ * describe one project differently. It travels inside the chat message, which keeps the chip
+ * popup readable in every chat surface without asking the server again.
+ *
+ * @param options - Project identity and what the answered message changed in it.
+ * @returns Chip payload, or `null` when the project no longer exists.
+ */
+export async function createTouchedProjectChipResult(options: {
+    readonly agentPermanentId: string;
+    readonly projectName: string;
+    readonly projectChange: AgentMessageProjectChange | null;
+}): Promise<AgentProjectToolCallResult | null> {
+    const project = await resolveAgentProjectInfo(options.agentPermanentId, options.projectName);
+
+    if (!project) {
+        return null;
+    }
+
+    const runtimeStatus = await resolveAgentProjectRuntimeStatus(options.agentPermanentId, project.projectName);
+
+    return {
+        projectName: project.projectName,
+        displayName: project.displayName,
+        projectHref: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
+        isRunning: runtimeStatus.isRunning,
+        runtimeStatusLabel: runtimeStatus.statusLabel,
+        sizeLabel: formatResourceBytes(project.sizeBytes),
+        fileCount: project.fileCount,
+        isGitRepository: project.isGitRepository,
+        ...(project.description ? { description: project.description } : {}),
+        ...(runtimeStatus.projectUrl ? { projectUrl: runtimeStatus.projectUrl } : {}),
+        ...(options.projectChange ? { change: options.projectChange } : {}),
+    };
+}

package/apps/agents-server/src/utils/chatMessageChips/createTouchedProjectChipToolCalls.ts

@@ -1,8 +1,8 @@
 import type { ToolCall } from '@promptbook-local/types';
 import { AGENT_PROJECT_TOOL_CALL_NAME } from '../../../../../src/book-components/Chat/utils/agentProjectToolCall';
-import { buildAgentProjectProfileHref } from '../agentProjects/agentProjectHrefs';
+import type { AgentMessageProjectChange } from '../../../../../src/utils/agent-message-runtime/AgentMessageProjectChange';
 import { isSafeAgentProjectPathSegment } from '../agentProjects/agentProjectsPaths';
-import { resolveAgentProjectInfo } from '../agentProjects/resolveAgentProjectInfo';
+import { createTouchedProjectChipResult } from './createTouchedProjectChipResult';
 
 /**
  * Prefix of the idempotency keys identifying touched-project chips.
@@ -13,27 +13,31 @@ const TOUCHED_PROJECT_CHIP_IDEMPOTENCY_PREFIX = 'agent-project';
  * Creates the project chips of one answered message.
  *
  * A project is reported by the runner once the answering harness viewed or edited any of its
- * files, and it is resolved here so the chip carries the same human-readable project name and
- * link as every other project surface. Projects that no longer exist are skipped.
+ * files, and every project the answer really committed something into is included as well — a
+ * changed project was obviously worked with, even when nothing in the harness log said so.
+ * Projects that no longer exist are skipped.
  *
- * @param options - Owning agent and the project directory names its answer touched.
+ * @param options - Owning agent, the project directory names its answer touched and what it changed.
  * @returns Project tool calls shown as chips below the answer.
  */
 export async function createTouchedProjectChipToolCalls(options: {
     readonly agentPermanentId: string;
     readonly touchedProjectNames: ReadonlyArray<string>;
+    readonly projectChanges: ReadonlyArray<AgentMessageProjectChange>;
     readonly createdAt: NonNullable<ToolCall['createdAt']>;
 }): Promise<ReadonlyArray<ToolCall>> {
+    const changeByProjectName = new Map(
+        options.projectChanges.map((projectChange) => [projectChange.projectName.toLowerCase(), projectChange]),
+    );
     const projectChipToolCalls = await Promise.all(
-        options.touchedProjectNames
-            .filter((touchedProjectName) => isSafeAgentProjectPathSegment(touchedProjectName))
-            .map((touchedProjectName) =>
-                createTouchedProjectChipToolCall({
-                    agentPermanentId: options.agentPermanentId,
-                    projectName: touchedProjectName,
-                    createdAt: options.createdAt,
-                }),
-            ),
+        resolveChippedProjectNames(options.touchedProjectNames, options.projectChanges).map((projectName) =>
+            createTouchedProjectChipToolCall({
+                agentPermanentId: options.agentPermanentId,
+                projectName,
+                projectChange: changeByProjectName.get(projectName.toLowerCase()) || null,
+                createdAt: options.createdAt,
+            }),
+        ),
     );
 
     return projectChipToolCalls.filter((projectChipToolCall): projectChipToolCall is ToolCall =>
@@ -41,10 +45,39 @@ export async function createTouchedProjectChipToolCalls(options: {
     );
 }
 
+/**
+ * Resolves which projects deserve a chip, keeping the order in which they were reported.
+ *
+ * @param touchedProjectNames - Projects the harness log showed as viewed or edited.
+ * @param projectChanges - Projects the answer committed something into.
+ * @returns Unique, safe project directory names.
+ *
+ * @private function of `createTouchedProjectChipToolCalls`
+ */
+function resolveChippedProjectNames(
+    touchedProjectNames: ReadonlyArray<string>,
+    projectChanges: ReadonlyArray<AgentMessageProjectChange>,
+): ReadonlyArray<string> {
+    const chippedProjectNames = new Map<string, string>();
+
+    for (const projectName of [
+        ...touchedProjectNames,
+        ...projectChanges.map((projectChange) => projectChange.projectName),
+    ]) {
+        if (!isSafeAgentProjectPathSegment(projectName) || chippedProjectNames.has(projectName.toLowerCase())) {
+            continue;
+        }
+
+        chippedProjectNames.set(projectName.toLowerCase(), projectName);
+    }
+
+    return [...chippedProjectNames.values()];
+}
+
 /**
  * Creates the chip of one touched project.
  *
- * @param options - Owning agent and one touched project directory name.
+ * @param options - Owning agent, one touched project and what the answer changed in it.
  * @returns Project tool call, or `null` when the project no longer exists.
  *
  * @private function of `createTouchedProjectChipToolCalls`
@@ -52,24 +85,25 @@ export async function createTouchedProjectChipToolCalls(options: {
 async function createTouchedProjectChipToolCall(options: {
     readonly agentPermanentId: string;
     readonly projectName: string;
+    readonly projectChange: AgentMessageProjectChange | null;
     readonly createdAt: NonNullable<ToolCall['createdAt']>;
 }): Promise<ToolCall | null> {
-    const project = await resolveAgentProjectInfo(options.agentPermanentId, options.projectName);
+    const projectChipResult = await createTouchedProjectChipResult({
+        agentPermanentId: options.agentPermanentId,
+        projectName: options.projectName,
+        projectChange: options.projectChange,
+    });
 
-    if (!project) {
+    if (!projectChipResult) {
         return null;
     }
 
     return {
         name: AGENT_PROJECT_TOOL_CALL_NAME,
-        arguments: { projectName: project.projectName },
-        result: {
-            projectName: project.projectName,
-            displayName: project.displayName,
-            projectHref: buildAgentProjectProfileHref(options.agentPermanentId, project.projectName),
-        },
+        arguments: { projectName: projectChipResult.projectName },
+        result: projectChipResult,
         state: 'COMPLETE',
-        idempotencyKey: `${TOUCHED_PROJECT_CHIP_IDEMPOTENCY_PREFIX}-${project.projectName.toLowerCase()}`,
+        idempotencyKey: `${TOUCHED_PROJECT_CHIP_IDEMPOTENCY_PREFIX}-${projectChipResult.projectName.toLowerCase()}`,
         createdAt: options.createdAt,
     };
 }

package/apps/agents-server/src/utils/cronExpression/CronExpression.ts

@@ -0,0 +1,63 @@
+/**
+ * Number of fields in a standard minute-based cron expression.
+ *
+ * @private constant of `cronExpression`
+ */
+export const CRON_EXPRESSION_FIELD_COUNT = 5;
+
+/**
+ * Parsed values of one cron field.
+ *
+ * @private type of `cronExpression`
+ */
+export type CronExpressionField = {
+    /**
+     * Accepted numeric values for this field.
+     */
+    readonly values: ReadonlySet<number>;
+
+    /**
+     * Whether the field is the unrestricted `*` wildcard.
+     */
+    readonly isWildcard: boolean;
+};
+
+/**
+ * Parsed five-field cron expression.
+ *
+ * @private type of `cronExpression`
+ */
+export type ParsedCronExpression = {
+    readonly minute: CronExpressionField;
+    readonly hour: CronExpressionField;
+    readonly dayOfMonth: CronExpressionField;
+    readonly month: CronExpressionField;
+    readonly dayOfWeek: CronExpressionField;
+};
+
+/**
+ * Parser configuration of one cron field.
+ *
+ * @private type of `cronExpression`
+ */
+export type CronExpressionFieldOptions = {
+    /**
+     * Field name used in validation errors.
+     */
+    readonly name: string;
+
+    /**
+     * Lowest accepted value.
+     */
+    readonly minimum: number;
+
+    /**
+     * Highest accepted value.
+     */
+    readonly maximum: number;
+
+    /**
+     * Whether `7` is an alias of Sunday, which is only true for the day-of-week field.
+     */
+    readonly isSevenAllowedForSunday?: boolean;
+};

package/apps/agents-server/src/utils/cronExpression/normalizeCronExpression.ts

@@ -0,0 +1,34 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+import { normalizeCronExpressionWhitespace } from './normalizeCronExpressionWhitespace';
+import { parseCronExpression } from './parseCronExpression';
+import { resolveNextCronRunFromParsedExpression } from './resolveNextCronRun';
+
+/**
+ * Normalizes and validates one cron expression.
+ *
+ * An expression which parses but never matches a real date, such as `0 0 30 2 *`, is rejected here
+ * instead of silently becoming a schedule that never runs.
+ *
+ * @param expression - Raw cron expression.
+ * @returns Whitespace-normalized expression.
+ *
+ * @private function of `cronExpression`
+ */
+export function normalizeCronExpression(expression: string): string {
+    const normalizedExpression = normalizeCronExpressionWhitespace(expression);
+
+    if (normalizedExpression === '') {
+        throw new ParseError(
+            spaceTrim(`
+                Cron expression is empty.
+
+                **Use exactly five fields:** minute hour day-of-month month day-of-week.
+            `),
+        );
+    }
+
+    resolveNextCronRunFromParsedExpression(parseCronExpression(normalizedExpression), new Date());
+
+    return normalizedExpression;
+}

package/apps/agents-server/src/utils/cronExpression/normalizeCronExpressionWhitespace.ts

@@ -0,0 +1,11 @@
+/**
+ * Collapses cron whitespace without changing any field value.
+ *
+ * @param expression - Raw cron expression.
+ * @returns Whitespace-normalized expression, which is empty when the input holds no field at all.
+ *
+ * @private function of `cronExpression`
+ */
+export function normalizeCronExpressionWhitespace(expression: string): string {
+    return expression.trim().replace(/\s+/gu, ' ');
+}

package/apps/agents-server/src/utils/cronExpression/parseCronExpression.ts

@@ -0,0 +1,41 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../../../src/errors/ParseError';
+import { CRON_EXPRESSION_FIELD_COUNT, type ParsedCronExpression } from './CronExpression';
+import { normalizeCronExpressionWhitespace } from './normalizeCronExpressionWhitespace';
+import { parseCronExpressionField } from './parseCronExpressionField';
+
+/**
+ * Parses one five-field cron expression into numeric field sets.
+ *
+ * @param expression - Raw cron expression, for example `15 9-17 * * 1-5`.
+ * @returns Parsed cron expression.
+ *
+ * @private function of `cronExpression`
+ */
+export function parseCronExpression(expression: string): ParsedCronExpression {
+    const normalizedExpression = normalizeCronExpressionWhitespace(expression);
+    const fields = normalizedExpression.split(' ');
+
+    if (fields.length !== CRON_EXPRESSION_FIELD_COUNT) {
+        throw new ParseError(
+            spaceTrim(`
+                Cron expression \`${normalizedExpression}\` is invalid.
+
+                **Use exactly five fields:** minute hour day-of-month month day-of-week.
+            `),
+        );
+    }
+
+    return {
+        minute: parseCronExpressionField(fields[0]!, { name: 'minute', minimum: 0, maximum: 59 }),
+        hour: parseCronExpressionField(fields[1]!, { name: 'hour', minimum: 0, maximum: 23 }),
+        dayOfMonth: parseCronExpressionField(fields[2]!, { name: 'day-of-month', minimum: 1, maximum: 31 }),
+        month: parseCronExpressionField(fields[3]!, { name: 'month', minimum: 1, maximum: 12 }),
+        dayOfWeek: parseCronExpressionField(fields[4]!, {
+            name: 'day-of-week',
+            minimum: 0,
+            maximum: 7,
+            isSevenAllowedForSunday: true,
+        }),
+    };
+}

package/apps/agents-server/src/utils/cronExpression/parseCronExpressionField.ts

@@ -0,0 +1,140 @@
+import type { CronExpressionField, CronExpressionFieldOptions } from './CronExpression';
+import { throwInvalidCronExpressionField } from './throwInvalidCronExpressionField';
+
+/**
+ * Parses one cron field with comma lists, ranges, and step values.
+ *
+ * @param field - Raw field value.
+ * @param options - Numeric bounds and label of the field.
+ * @returns Parsed field values.
+ *
+ * @private function of `cronExpression`
+ */
+export function parseCronExpressionField(field: string, options: CronExpressionFieldOptions): CronExpressionField {
+    const values = new Set<number>();
+    const isWildcard = field === '*';
+
+    for (const part of field.split(',')) {
+        if (!part) {
+            throwInvalidCronExpressionField(field, options.name);
+        }
+
+        addCronExpressionFieldPart(values, part, options);
+    }
+
+    if (values.size === 0) {
+        throwInvalidCronExpressionField(field, options.name);
+    }
+
+    return { values, isWildcard };
+}
+
+/**
+ * Adds the values represented by one comma-separated cron field part.
+ *
+ * @param values - Mutable field value set.
+ * @param part - Field part, for example a wildcard, `1-5`, or a stepped wildcard.
+ * @param options - Numeric bounds and label of the field.
+ *
+ * @private function of `parseCronExpressionField`
+ */
+function addCronExpressionFieldPart(values: Set<number>, part: string, options: CronExpressionFieldOptions): void {
+    const stepSplit = part.split('/');
+    if (stepSplit.length > 2) {
+        throwInvalidCronExpressionField(part, options.name);
+    }
+
+    const rangePart = stepSplit[0]!;
+    const step = stepSplit[1] === undefined ? 1 : parseCronExpressionNumber(stepSplit[1], options.name);
+    if (step <= 0) {
+        throwInvalidCronExpressionField(part, options.name);
+    }
+
+    const { start, end } = parseCronExpressionRange(rangePart, options);
+    for (let value = start; value <= end; value += step) {
+        values.add(normalizeCronExpressionFieldValue(value, options));
+    }
+}
+
+/**
+ * Parses the range portion of one cron field part.
+ *
+ * @param rangePart - Range part before the optional `/step`.
+ * @param options - Numeric bounds and label of the field.
+ * @returns Start and end range values.
+ *
+ * @private function of `parseCronExpressionField`
+ */
+function parseCronExpressionRange(
+    rangePart: string,
+    options: CronExpressionFieldOptions,
+): { readonly start: number; readonly end: number } {
+    if (rangePart === '*') {
+        return { start: options.minimum, end: options.maximum };
+    }
+
+    const rangeSplit = rangePart.split('-');
+    if (rangeSplit.length > 2 || rangeSplit.some((value) => value === '')) {
+        throwInvalidCronExpressionField(rangePart, options.name);
+    }
+
+    const start = parseCronExpressionNumber(rangeSplit[0]!, options.name);
+    const end = rangeSplit[1] === undefined ? start : parseCronExpressionNumber(rangeSplit[1], options.name);
+
+    if (start > end) {
+        throwInvalidCronExpressionField(rangePart, options.name);
+    }
+
+    assertCronExpressionFieldValueInRange(start, options);
+    assertCronExpressionFieldValueInRange(end, options);
+
+    return { start, end };
+}
+
+/**
+ * Parses one positive cron integer token.
+ *
+ * @param value - Raw token.
+ * @param fieldName - Field name used in validation errors.
+ * @returns Parsed integer.
+ *
+ * @private function of `parseCronExpressionField`
+ */
+function parseCronExpressionNumber(value: string, fieldName: string): number {
+    if (!/^\d+$/u.test(value)) {
+        throwInvalidCronExpressionField(value, fieldName);
+    }
+
+    return Number.parseInt(value, 10);
+}
+
+/**
+ * Asserts that one parsed cron value is inside the field bounds.
+ *
+ * @param value - Parsed value.
+ * @param options - Numeric bounds and label of the field.
+ *
+ * @private function of `parseCronExpressionField`
+ */
+function assertCronExpressionFieldValueInRange(value: number, options: CronExpressionFieldOptions): void {
+    if (value < options.minimum || value > options.maximum) {
+        throwInvalidCronExpressionField(String(value), options.name);
+    }
+}
+
+/**
+ * Normalizes Sunday from `7` to `0` in the day-of-week field.
+ *
+ * @param value - Parsed field value.
+ * @param options - Numeric bounds and label of the field.
+ * @returns Normalized value.
+ *
+ * @private function of `parseCronExpressionField`
+ */
+function normalizeCronExpressionFieldValue(value: number, options: CronExpressionFieldOptions): number {
+    if (options.isSevenAllowedForSunday && value === 7) {
+        return 0;
+    }
+
+    return value;
+}