@promptbook/cli 0.114.0-3 → 0.114.0-30

package/src/book-3.0/AgentMessageRunReport.ts

@@ -1,6 +1,10 @@
 // Note: [💞] Ignore a discrepancy between file name and entity name
 
 import type { Usage } from '../execution/Usage';
+import type { AgentMessageProjectChange } from '../utils/agent-message-runtime/AgentMessageProjectChange';
+import { normalizeAgentMessageProjectChange } from '../utils/agent-message-runtime/AgentMessageProjectChange';
+import type { AgentMessageTouchedExternalSource } from '../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+import { normalizeAgentMessageTouchedExternalSource } from '../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
 import type { CodexLoginMethod } from './codexLoginMethod';
 
 /**
@@ -13,6 +17,25 @@ import type { CodexLoginMethod } from './codexLoginMethod';
  */
 export const AGENT_MESSAGE_RUN_REPORT_FILE_SUFFIX = '.report.json';
 
+/**
+ * Exact wall-clock interval during which one harness processed an agent message.
+ *
+ * Note: [🚉] This is fully serializable as JSON
+ *
+ * @private internal type of the agent folder convention
+ */
+export type AgentMessageRunExecutionTiming = {
+    /**
+     * ISO 8601 timestamp captured immediately before the harness begins the message.
+     */
+    readonly startedAt: string;
+
+    /**
+     * ISO 8601 timestamp captured when the harness finishes the message.
+     */
+    readonly finishedAt: string;
+};
+
 /**
  * Report describing how one queued agent message was answered by a CLI harness runner.
  *
@@ -52,6 +75,37 @@ export type AgentMessageRunReport = {
      * Usage statistics of the run (price, token counts, duration).
      */
     readonly usage: Usage;
+
+    /**
+     * Measured wall-clock timing of the actual harness execution, excluding time spent waiting in the queue.
+     */
+    readonly executionTiming?: AgentMessageRunExecutionTiming;
+
+    /**
+     * Directory names of the agent projects the harness worked with while answering the message.
+     *
+     * Reported by the runner from its live runtime log, which is deleted once the message is
+     * 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>;
 };
 
 /**
@@ -110,9 +164,90 @@ export function normalizeAgentMessageRunReport(value: unknown): AgentMessageRunR
         return null;
     }
 
+    if (report.executionTiming !== undefined && !isSerializedAgentMessageRunExecutionTiming(report.executionTiming)) {
+        return null;
+    }
+
+    if (report.touchedProjectNames !== undefined && !isSerializedProjectNameList(report.touchedProjectNames)) {
+        return null;
+    }
+
+    if (
+        report.touchedExternalSources !== undefined &&
+        !isSerializedTouchedExternalSourceList(report.touchedExternalSources)
+    ) {
+        return null;
+    }
+
+    if (report.projectChanges !== undefined && !isSerializedProjectChangeList(report.projectChanges)) {
+        return null;
+    }
+
     return report as AgentMessageRunReport;
 }
 
+/**
+ * Checks that one value structurally matches a list of project changes.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedProjectChangeList(value: unknown): value is ReadonlyArray<AgentMessageProjectChange> {
+    return (
+        Array.isArray(value) &&
+        value.every((projectChange) => normalizeAgentMessageProjectChange(projectChange) !== null)
+    );
+}
+
+/**
+ * Checks that one value structurally matches a list of touched external sources.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedTouchedExternalSourceList(
+    value: unknown,
+): value is ReadonlyArray<AgentMessageTouchedExternalSource> {
+    return (
+        Array.isArray(value) &&
+        value.every((externalSource) => normalizeAgentMessageTouchedExternalSource(externalSource) !== null)
+    );
+}
+
+/**
+ * Checks that one value structurally matches a list of project directory names.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedProjectNameList(value: unknown): value is ReadonlyArray<string> {
+    return Array.isArray(value) && value.every((projectName) => typeof projectName === 'string');
+}
+
+/**
+ * Checks that one value contains a valid, non-negative agent-message execution interval.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedAgentMessageRunExecutionTiming(value: unknown): value is AgentMessageRunExecutionTiming {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+
+    const executionTiming = value as Record<string, unknown>;
+    if (!isSerializedIsoTimestamp(executionTiming.startedAt) || !isSerializedIsoTimestamp(executionTiming.finishedAt)) {
+        return false;
+    }
+
+    return Date.parse(executionTiming.finishedAt) >= Date.parse(executionTiming.startedAt);
+}
+
+/**
+ * Checks that one JSON value is a parseable ISO timestamp.
+ *
+ * @private internal helper of `normalizeAgentMessageRunReport`
+ */
+function isSerializedIsoTimestamp(value: unknown): value is string {
+    return typeof value === 'string' && value.length > 0 && Number.isFinite(Date.parse(value));
+}
+
 /**
  * Parses one run-report sidecar file content.
  *

package/src/book-3.0/AgentPlannedMessagesSidecar.ts

@@ -0,0 +1,284 @@
+import { join } from 'path';
+import { AGENT_MESSAGES_DIRECTORY_PATH } from './agentFolderPaths';
+import { createAgentMessageSidecarBaseName } from './createAgentMessageSidecarBaseName';
+
+// Note: [💞] This file defines the shared planned-message sidecar convention rather than one standalone entity.
+
+/**
+ * Relative directory holding the planned-message sidecar of each queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_PLANNED_MESSAGES_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'planned');
+
+/**
+ * Command actions an agent can request from its planned-message sidecar.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS = ['set', 'update', 'cancel'] as const;
+
+/**
+ * One planned-message command action.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessageCommandAction = (typeof AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS)[number];
+
+/**
+ * One planned message that is already waiting to wake the agent.
+ *
+ * A planned message 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
+ */
+export type AgentPlannedMessageSnapshot = {
+    readonly timeoutId: string;
+    readonly dueAt: string;
+    readonly message: string | null;
+
+    /**
+     * 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.
+ *
+ * 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, 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;
+};
+
+/**
+ * Planned-message sidecar prepared for one queued message.
+ *
+ * `currentPlannedMessages` is written by the Agents Server and is read-only for the agent, while
+ * `commands` is the only channel through which a coding harness can plan or cancel a wake-up.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentPlannedMessagesSidecar = {
+    readonly version: 1;
+    readonly agentPermanentId: string;
+    readonly currentPlannedMessages: ReadonlyArray<AgentPlannedMessageSnapshot>;
+    readonly commands: ReadonlyArray<AgentPlannedMessageCommand>;
+};
+
+/**
+ * Creates the relative planned-message sidecar path of one queued message.
+ *
+ * @param messageFileName - File name of the queued `.book` message.
+ * @returns Relative path of the sidecar inside the agent folder.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function createAgentPlannedMessagesSidecarPath(messageFileName: string): string {
+    return join(AGENT_PLANNED_MESSAGES_DIRECTORY_PATH, `${createAgentMessageSidecarBaseName(messageFileName)}.json`);
+}
+
+/**
+ * Serializes one planned-message sidecar into its stored representation.
+ *
+ * @param sidecar - Sidecar prepared for one queued message.
+ * @returns Pretty-printed JSON the coding harness can edit by hand.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function createAgentPlannedMessagesSidecarContent(sidecar: AgentPlannedMessagesSidecar): string {
+    return `${JSON.stringify(sidecar, null, 2)}\n`;
+}
+
+/**
+ * Parses one untrusted planned-message sidecar written back by a coding harness.
+ *
+ * A malformed sidecar never fails the already answered chat, so this returns `null` instead of throwing.
+ *
+ * @param sidecarContent - Raw file content read from the agent folder.
+ * @returns Normalized sidecar, or `null` when it cannot be used.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function parseAgentPlannedMessagesSidecar(sidecarContent: string): AgentPlannedMessagesSidecar | null {
+    let parsedSidecar: unknown;
+
+    try {
+        parsedSidecar = JSON.parse(sidecarContent);
+    } catch {
+        return null;
+    }
+
+    if (!parsedSidecar || typeof parsedSidecar !== 'object' || Array.isArray(parsedSidecar)) {
+        return null;
+    }
+
+    const sidecar = parsedSidecar as Partial<AgentPlannedMessagesSidecar>;
+
+    if (sidecar.version !== 1 || typeof sidecar.agentPermanentId !== 'string') {
+        return null;
+    }
+
+    return {
+        version: 1,
+        agentPermanentId: sidecar.agentPermanentId,
+        currentPlannedMessages: normalizeAgentPlannedMessageSnapshots(sidecar.currentPlannedMessages),
+        commands: normalizeAgentPlannedMessageCommands(sidecar.commands),
+    };
+}
+
+/**
+ * Keeps only the commands whose action is understood by the planned-message actions.
+ *
+ * @param rawCommands - Untrusted `commands` value read from one sidecar.
+ * @returns Commands that can be dispatched, in their original order.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessageCommands(rawCommands: unknown): Array<AgentPlannedMessageCommand> {
+    if (!Array.isArray(rawCommands)) {
+        return [];
+    }
+
+    return rawCommands.filter(isAgentPlannedMessageCommand);
+}
+
+/**
+ * Checks whether one untrusted sidecar entry names a supported planned-message action.
+ *
+ * @param value - Untrusted command entry.
+ * @returns `true` when the entry can be dispatched.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function isAgentPlannedMessageCommand(value: unknown): value is AgentPlannedMessageCommand {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+
+    const action = (value as AgentPlannedMessageCommand).action;
+
+    return (
+        typeof action === 'string' &&
+        AGENT_PLANNED_MESSAGE_COMMAND_ACTIONS.includes(action as AgentPlannedMessageCommandAction)
+    );
+}
+
+/**
+ * Keeps only the already planned messages that can be shown to the agent.
+ *
+ * @param rawSnapshots - Untrusted `currentPlannedMessages` value read from one sidecar.
+ * @returns Planned-message snapshots with the fields required for display and cancellation.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessageSnapshots(rawSnapshots: unknown): Array<AgentPlannedMessageSnapshot> {
+    if (!Array.isArray(rawSnapshots)) {
+        return [];
+    }
+
+    return rawSnapshots.filter(isAgentPlannedMessageSnapshot).map(createNormalizedAgentPlannedMessageSnapshot);
+}
+
+/**
+ * Normalizes the optional fields of one already planned message.
+ *
+ * @param snapshot - Planned-message entry with the required identity fields.
+ * @returns Snapshot with a usable schedule and message.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function createNormalizedAgentPlannedMessageSnapshot(
+    snapshot: AgentPlannedMessageSnapshot,
+): AgentPlannedMessageSnapshot {
+    return {
+        timeoutId: snapshot.timeoutId,
+        dueAt: snapshot.dueAt,
+        message: typeof snapshot.message === 'string' ? snapshot.message : null,
+        intervalMs: normalizeAgentPlannedMessagePositiveCount(snapshot.intervalMs),
+        cronExpression: typeof snapshot.cronExpression === 'string' ? snapshot.cronExpression : null,
+        startsAt: typeof snapshot.startsAt === 'string' ? snapshot.startsAt : null,
+        endsAt: typeof snapshot.endsAt === 'string' ? snapshot.endsAt : null,
+        maxRunCount: normalizeAgentPlannedMessagePositiveCount(snapshot.maxRunCount),
+        runCount: normalizeAgentPlannedMessagePositiveCount(snapshot.runCount) || 0,
+    };
+}
+
+/**
+ * Normalizes one optional positive whole number of a planned-message snapshot.
+ *
+ * @param value - Untrusted interval, run count, or run-count limit.
+ * @returns Whole positive number, or `null` when the value cannot be used.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function normalizeAgentPlannedMessagePositiveCount(value: unknown): number | null {
+    const numericValue = Number(value);
+
+    return Number.isFinite(numericValue) && numericValue > 0 ? Math.floor(numericValue) : null;
+}
+
+/**
+ * Checks whether one untrusted sidecar entry describes an already planned message.
+ *
+ * @param value - Untrusted planned-message entry.
+ * @returns `true` when the entry can be shown and cancelled.
+ *
+ * @private internal utility of `parseAgentPlannedMessagesSidecar`
+ */
+function isAgentPlannedMessageSnapshot(value: unknown): value is AgentPlannedMessageSnapshot {
+    return Boolean(
+        value &&
+            typeof value === 'object' &&
+            typeof (value as AgentPlannedMessageSnapshot).timeoutId === 'string' &&
+            typeof (value as AgentPlannedMessageSnapshot).dueAt === 'string',
+    );
+}

package/src/book-3.0/AgentTeamConversationWorkspace.ts

@@ -0,0 +1,170 @@
+import { join } from 'path';
+import { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, AGENT_MESSAGES_DIRECTORY_PATH } from './agentFolderPaths';
+import { createAgentMessageSidecarBaseName } from './createAgentMessageSidecarBaseName';
+
+// Note: [💞] This file defines the shared TEAM workspace convention rather than one standalone entity.
+
+/**
+ * Relative directory for an active TEAM conversation workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_TEAM_CONVERSATIONS_DIRECTORY_PATH = join(AGENT_MESSAGES_DIRECTORY_PATH, 'team');
+
+/**
+ * Relative directory where completed TEAM conversation transcripts are retained.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_FINISHED_TEAM_CONVERSATIONS_DIRECTORY_PATH = join(AGENT_FINISHED_MESSAGES_DIRECTORY_PATH, 'team');
+
+/**
+ * Name of the JSON manifest that describes one TEAM conversation workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME = 'team.json';
+
+/**
+ * Name of the read-only teammate-source directory inside one TEAM workspace.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export const AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME = 'teammates';
+
+/**
+ * One primary agent represented in a TEAM workspace manifest.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationPrimaryAgent = {
+    readonly permanentId: string;
+    readonly agentName: string;
+};
+
+/**
+ * One local teammate made available to the coding harness for a single user turn.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationTeammate = {
+    readonly permanentId: string;
+    readonly agentName: string;
+    readonly url: string;
+    readonly instructions: string;
+    readonly sourceFileName: string;
+};
+
+/**
+ * Persisted roster snapshot for the optional TEAM workspace of one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export type AgentTeamConversationWorkspaceManifest = {
+    readonly version: 1;
+    readonly primaryAgent: AgentTeamConversationPrimaryAgent;
+    readonly teammates: ReadonlyArray<AgentTeamConversationTeammate>;
+};
+
+/**
+ * Creates the stable directory name that belongs to one queued `.book` message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function createAgentTeamConversationWorkspaceDirectoryName(messageFileName: string): string {
+    return createAgentMessageSidecarBaseName(messageFileName);
+}
+
+/**
+ * Creates the relative active workspace path for one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function createAgentTeamConversationWorkspacePath(messageFileName: string): string {
+    return join(
+        AGENT_TEAM_CONVERSATIONS_DIRECTORY_PATH,
+        createAgentTeamConversationWorkspaceDirectoryName(messageFileName),
+    );
+}
+
+/**
+ * Creates the relative completed-workspace path for one queued message.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function createFinishedAgentTeamConversationWorkspacePath(messageFileName: string): string {
+    return join(
+        AGENT_FINISHED_TEAM_CONVERSATIONS_DIRECTORY_PATH,
+        createAgentTeamConversationWorkspaceDirectoryName(messageFileName),
+    );
+}
+
+/**
+ * Creates the source-snapshot file name for one teammate.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function createAgentTeamTeammateSourceFileName(teammatePermanentId: string): string {
+    const normalizedPermanentId = teammatePermanentId
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/gu, '-')
+        .replace(/^[._-]+|[._-]+$/gu, '');
+
+    return `${normalizedPermanentId || 'teammate'}.book`;
+}
+
+/**
+ * Checks whether unknown JSON has the minimum shape required for a TEAM workspace manifest.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function isAgentTeamConversationWorkspaceManifest(
+    value: unknown,
+): value is AgentTeamConversationWorkspaceManifest {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+
+    const manifest = value as Partial<AgentTeamConversationWorkspaceManifest>;
+    if (
+        manifest.version !== 1 ||
+        !isPrimaryAgent(manifest.primaryAgent) ||
+        !Array.isArray(manifest.teammates) ||
+        !manifest.teammates.every(isTeammate)
+    ) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Checks the primary-agent part of an untrusted manifest.
+ *
+ * @private internal utility of `isAgentTeamConversationWorkspaceManifest`
+ */
+function isPrimaryAgent(value: unknown): value is AgentTeamConversationPrimaryAgent {
+    return Boolean(
+        value &&
+            typeof value === 'object' &&
+            typeof (value as AgentTeamConversationPrimaryAgent).permanentId === 'string' &&
+            typeof (value as AgentTeamConversationPrimaryAgent).agentName === 'string',
+    );
+}
+
+/**
+ * Checks one teammate part of an untrusted manifest.
+ *
+ * @private internal utility of `isAgentTeamConversationWorkspaceManifest`
+ */
+function isTeammate(value: unknown): value is AgentTeamConversationTeammate {
+    return Boolean(
+        value &&
+            typeof value === 'object' &&
+            typeof (value as AgentTeamConversationTeammate).permanentId === 'string' &&
+            typeof (value as AgentTeamConversationTeammate).agentName === 'string' &&
+            typeof (value as AgentTeamConversationTeammate).url === 'string' &&
+            typeof (value as AgentTeamConversationTeammate).instructions === 'string' &&
+            typeof (value as AgentTeamConversationTeammate).sourceFileName === 'string',
+    );
+}

package/src/book-3.0/cliAgentEnv.ts

@@ -12,6 +12,7 @@ export const CLI_AGENT_HARNESS_NAMES = [
     'claude-code',
     'opencode',
     'gemini',
+    'qwen-code',
 ] as const;
 
 /**
@@ -24,8 +25,8 @@ export const CLI_AGENT_THINKING_LEVEL_VALUES = ['low', 'medium', 'high', 'xhigh'
 /**
  * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
  *
- * Set this to one of the harness names (`openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`)
- * so that `CliAgent` and `ptbk agent exec` can run without an explicit `harness` option.
+ * Set this to one of the harness names (`openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`,
+ * `qwen-code`) so that `CliAgent` and `ptbk agent exec` can run without an explicit `harness` option.
  *
  * @public exported from `@promptbook/node`
  */

package/src/book-3.0/createAgentMessageSidecarBaseName.ts

@@ -0,0 +1,20 @@
+import { basename } from 'path';
+
+/**
+ * Creates the stable file-system safe base name that belongs to one queued `.book` message.
+ *
+ * Every sidecar the Agents Server prepares next to a queued message (TEAM workspaces, planned-message
+ * files, ...) derives its own name from this one normalization, so a sidecar can always be found again
+ * from the message file name alone.
+ *
+ * @param messageFileName - File name of the queued message, with or without directories.
+ * @returns Normalized base name usable as a directory or file name.
+ *
+ * @private internal convention shared by the Agents Server and agent-folder runner
+ */
+export function createAgentMessageSidecarBaseName(messageFileName: string): string {
+    const rawBaseName = basename(messageFileName).replace(/\.book$/iu, '');
+    const normalizedBaseName = rawBaseName.replace(/[^A-Za-z0-9._-]+/gu, '-').replace(/^[._-]+|[._-]+$/gu, '');
+
+    return normalizedBaseName || 'message';
+}