@promptbook/cli 0.114.0-2 → 0.114.0-20

package/apps/agents-server/src/utils/localChatRunner/parseLocalTeamConversations.ts

@@ -0,0 +1,281 @@
+import type { ToolCall } from '@promptbook-local/types';
+import { readdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import { Book } from '../../../../../src/book-3.0/Book';
+import {
+    AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME,
+    createFinishedAgentTeamConversationWorkspacePath,
+    isAgentTeamConversationWorkspaceManifest,
+    type AgentTeamConversationTeammate,
+    type AgentTeamConversationWorkspaceManifest,
+} from '../../../../../src/book-3.0/AgentTeamConversationWorkspace';
+import { createTeamToolName } from '../../../../../src/book-2.0/agent-source/createTeamToolName';
+import type { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
+
+/**
+ * One normalized message parsed from a coding-harness TEAM transcript.
+ */
+export type LocalTeamConversationMessage = {
+    readonly sender: 'AGENT' | 'TEAMMATE';
+    readonly name: string;
+    readonly content: string;
+};
+
+/**
+ * One valid harness-created teammate conversation ready for persistence and chip rendering.
+ */
+export type ParsedLocalTeamConversation = {
+    readonly transcriptFileName: string;
+    readonly teammate: AgentTeamConversationTeammate;
+    readonly conversation: ReadonlyArray<LocalTeamConversationMessage>;
+    readonly toolCall: ToolCall;
+};
+
+/**
+ * Reads every valid teammate transcript that the coding harness left beside a finished message.
+ */
+export async function parseFinishedLocalTeamConversations(options: {
+    readonly agentDirectoryPath: string;
+    readonly metadata: LocalUserChatJobMetadata;
+    readonly job: Pick<UserChatJobRecord, 'id' | 'queuedAt'>;
+}): Promise<Array<ParsedLocalTeamConversation>> {
+    const workspacePath = join(
+        options.agentDirectoryPath,
+        createFinishedAgentTeamConversationWorkspacePath(options.metadata.fileName),
+    );
+    const manifestContent = await readOptionalTextFile(join(workspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME));
+    const manifest = manifestContent ? parseTeamConversationManifest(manifestContent) : null;
+
+    if (!manifest) {
+        return [];
+    }
+
+    const transcriptFileNames = await listTranscriptFileNames(workspacePath);
+    const conversations: Array<ParsedLocalTeamConversation> = [];
+
+    for (const transcriptFileName of transcriptFileNames) {
+        const transcriptContent = await readOptionalTextFile(join(workspacePath, transcriptFileName));
+        if (!transcriptContent) {
+            continue;
+        }
+
+        const conversation = parseLocalTeamConversationBook({
+            transcriptFileName,
+            transcriptContent,
+            manifest,
+            job: options.job,
+        });
+
+        if (conversation) {
+            conversations.push(conversation);
+        }
+    }
+
+    return conversations;
+}
+
+/**
+ * Parses one TEAM transcript and translates it to the ordinary TEAM tool-call shape used by chat chips.
+ */
+export function parseLocalTeamConversationBook(options: {
+    readonly transcriptFileName: string;
+    readonly transcriptContent: string;
+    readonly manifest: AgentTeamConversationWorkspaceManifest;
+    readonly job: Pick<UserChatJobRecord, 'id' | 'queuedAt'>;
+}): ParsedLocalTeamConversation | null {
+    const teammate = resolveTranscriptTeammate(options.transcriptFileName, options.manifest.teammates);
+    if (!teammate) {
+        return null;
+    }
+
+    const conversation = parseTranscriptMessages(
+        options.transcriptContent,
+        options.manifest.primaryAgent.agentName,
+        teammate.agentName,
+    );
+    if (!conversation) {
+        return null;
+    }
+
+    const request = conversation[0]!.content;
+    const response = conversation[conversation.length - 1]!.content;
+    const toolName = createTeamToolName(teammate.url, teammate.agentName);
+
+    return {
+        transcriptFileName: options.transcriptFileName,
+        teammate,
+        conversation,
+        toolCall: {
+            name: toolName,
+            arguments: { message: request },
+            result: {
+                teammate: {
+                    url: teammate.url,
+                    label: teammate.agentName,
+                    instructions: teammate.instructions || undefined,
+                    toolName,
+                },
+                request,
+                response,
+                conversation,
+            },
+            state: 'COMPLETE',
+            idempotencyKey: `local-team:${options.job.id}:${options.transcriptFileName}`,
+            createdAt: options.job.queuedAt as NonNullable<ToolCall['createdAt']>,
+        },
+    };
+}
+
+/**
+ * Finds the teammate addressed by a transcript file name.
+ */
+function resolveTranscriptTeammate(
+    transcriptFileName: string,
+    teammates: ReadonlyArray<AgentTeamConversationTeammate>,
+): AgentTeamConversationTeammate | null {
+    return (
+        teammates.find(
+            (teammate) =>
+                transcriptFileName === `${teammate.permanentId}.book` ||
+                transcriptFileName.startsWith(`${teammate.permanentId}--`),
+        ) || null
+    );
+}
+
+/**
+ * Parses and validates alternating primary-agent and teammate messages from one transcript.
+ */
+function parseTranscriptMessages(
+    transcriptContent: string,
+    primaryAgentName: string,
+    teammateName: string,
+): Array<LocalTeamConversationMessage> | null {
+    let messages: ReturnType<Book['getMessages']>;
+
+    try {
+        messages = Book.parse(transcriptContent as string_book).getMessages();
+    } catch {
+        // Note: The coding harness owns this sidecar. A malformed optional transcript must not block
+        //       the already completed primary chat from being synchronized.
+        return null;
+    }
+
+    const conversation: Array<LocalTeamConversationMessage> = [];
+
+    for (const message of messages) {
+        const content = message.content.trim();
+        const sender = resolveTranscriptSender(String(message.sender), primaryAgentName, teammateName);
+
+        if (!content || !sender) {
+            return null;
+        }
+
+        if (conversation.at(-1)?.sender === sender) {
+            return null;
+        }
+
+        conversation.push({
+            sender,
+            name: sender === 'AGENT' ? primaryAgentName : teammateName,
+            content,
+        });
+    }
+
+    if (
+        conversation.length < 2 ||
+        conversation[0]?.sender !== 'AGENT' ||
+        conversation[conversation.length - 1]?.sender !== 'TEAMMATE'
+    ) {
+        return null;
+    }
+
+    return conversation;
+}
+
+/**
+ * Maps one Book participant marker to the transcript role it represents.
+ */
+function resolveTranscriptSender(
+    sender: string,
+    primaryAgentName: string,
+    teammateName: string,
+): LocalTeamConversationMessage['sender'] | null {
+    const normalizedSender = normalizeParticipantName(sender);
+
+    if (normalizedSender === 'AGENT' || normalizedSender === normalizeParticipantName(primaryAgentName)) {
+        return 'AGENT';
+    }
+
+    if (normalizedSender === 'TEAMMATE' || normalizedSender === normalizeParticipantName(teammateName)) {
+        return 'TEAMMATE';
+    }
+
+    return null;
+}
+
+/**
+ * Normalizes a participant name for case-insensitive Book transcript matching.
+ */
+function normalizeParticipantName(name: string): string {
+    return name.trim().toLocaleUpperCase();
+}
+
+/**
+ * Parses an untrusted TEAM workspace manifest.
+ */
+function parseTeamConversationManifest(manifestContent: string): AgentTeamConversationWorkspaceManifest | null {
+    try {
+        const manifest: unknown = JSON.parse(manifestContent);
+        return isAgentTeamConversationWorkspaceManifest(manifest) ? manifest : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Lists direct `.book` transcript files from a finished TEAM workspace.
+ */
+async function listTranscriptFileNames(workspacePath: string): Promise<Array<string>> {
+    try {
+        const entries = await readdir(workspacePath, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.book'))
+            .map((entry) => entry.name)
+            .sort((firstFileName, secondFileName) => firstFileName.localeCompare(secondFileName));
+    } catch (error) {
+        if (isFileNotFoundError(error)) {
+            return [];
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Reads one text file and treats a missing finished sidecar as absent.
+ */
+async function readOptionalTextFile(path: string): Promise<string | null> {
+    try {
+        return await readFile(path, 'utf-8');
+    } catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Returns true when one filesystem error indicates a missing path.
+ */
+function isFileNotFoundError(error: unknown): boolean {
+    return Boolean(
+        error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            ((error as { code?: string }).code === 'ENOENT' || (error as { code?: string }).code === 'ENOTDIR'),
+    );
+}

package/apps/agents-server/src/utils/localChatRunner/persistLocalTeamConversations.ts

@@ -0,0 +1,71 @@
+import type { ChatMessage, ToolCall } from '@promptbook-local/types';
+import { persistFrozenUserChat } from '../userChat/persistFrozenUserChat';
+import { attachTeamMemberUserChatContext } from '../userChat/teamMemberUserChatContext';
+import { USER_CHAT_SOURCES } from '../userChat/UserChatSource';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { ParsedLocalTeamConversation } from './parseLocalTeamConversations';
+
+/**
+ * Persists teammate transcripts as frozen chats and returns their chip-ready tool calls.
+ */
+export async function persistLocalTeamConversations(options: {
+    readonly job: Pick<UserChatJobRecord, 'id' | 'userId' | 'agentPermanentId' | 'chatId' | 'queuedAt'>;
+    readonly conversations: ReadonlyArray<ParsedLocalTeamConversation>;
+}): Promise<ReadonlyArray<ToolCall>> {
+    for (const conversation of options.conversations) {
+        await persistFrozenUserChat({
+            userId: options.job.userId,
+            agentPermanentId: conversation.teammate.permanentId,
+            source: USER_CHAT_SOURCES.TEAM_MEMBER,
+            chatId: createLocalTeamMemberChatId(options.job.id, conversation.transcriptFileName),
+            messages: createFrozenTeamConversationMessages(options.job, conversation),
+        });
+    }
+
+    return options.conversations.map((conversation) => conversation.toolCall);
+}
+
+/**
+ * Creates the frozen teammate-chat transcript and its primary-chat relation.
+ */
+function createFrozenTeamConversationMessages(
+    job: Pick<UserChatJobRecord, 'id' | 'agentPermanentId' | 'chatId' | 'queuedAt'>,
+    conversation: ParsedLocalTeamConversation,
+): Array<ChatMessage> {
+    const queuedAt = Date.parse(job.queuedAt);
+    const baseTimestamp = Number.isFinite(queuedAt) ? queuedAt : Date.now();
+    const transcriptIdentifier = normalizeTranscriptIdentifier(conversation.transcriptFileName);
+    const messages = conversation.conversation.map((message, index) => ({
+        id: `team-${job.id}-${transcriptIdentifier}-${index + 1}`,
+        sender: message.sender === 'AGENT' ? 'USER' : 'AGENT',
+        content: message.content,
+        isComplete: true,
+        createdAt: new Date(baseTimestamp + index * 1_000).toISOString() as NonNullable<ChatMessage['createdAt']>,
+    }));
+
+    return attachTeamMemberUserChatContext(messages, {
+        version: 1,
+        primaryAgentPermanentId: job.agentPermanentId,
+        primaryAgentName: conversation.conversation[0]?.name || 'Agent',
+        primaryChatId: job.chatId,
+    });
+}
+
+/**
+ * Creates a stable frozen-chat id so repeated synchronization refreshes the same transcript.
+ */
+function createLocalTeamMemberChatId(jobId: string, transcriptFileName: string): string {
+    return `team-${jobId}-${normalizeTranscriptIdentifier(transcriptFileName)}`;
+}
+
+/**
+ * Converts a direct transcript filename into a conservative id-safe segment.
+ */
+function normalizeTranscriptIdentifier(transcriptFileName: string): string {
+    return (
+        transcriptFileName
+            .replace(/\.book$/iu, '')
+            .replace(/[^A-Za-z0-9._-]+/gu, '-')
+            .replace(/^[._-]+|[._-]+$/gu, '') || 'conversation'
+    );
+}

package/apps/agents-server/src/utils/localChatRunner/prepareLocalAgentPlannedMessagesSidecar.ts

@@ -0,0 +1,74 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname, join } from 'path';
+import {
+    createAgentPlannedMessagesSidecarContent,
+    createAgentPlannedMessagesSidecarPath,
+    type AgentPlannedMessageSnapshot,
+    type AgentPlannedMessagesSidecar,
+} from '../../../../../src/book-3.0/AgentPlannedMessagesSidecar';
+import {
+    AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS,
+    type AgentGoalChatPlannedMessageItem,
+} from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { LocalAgentFolder } from './ensureLocalAgentFolder';
+import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
+
+/**
+ * Writes the planned-message sidecar a coding harness uses to see and change its future wake-ups.
+ *
+ * The sidecar is the only planning channel of a locally executed turn: the harness never has to reach
+ * the Agents Server over the network, and a wake-up exists only when it was actually requested here.
+ * Planned messages repeat on their own, so an empty `commands` array keeps the current plan intact.
+ *
+ * @param options - Answered job, its agent folder, and the local runner metadata of the queued message.
+ */
+export async function prepareLocalAgentPlannedMessagesSidecar(options: {
+    readonly job: Pick<UserChatJobRecord, 'agentPermanentId'>;
+    readonly agentFolder: LocalAgentFolder;
+    readonly metadata: LocalUserChatJobMetadata;
+}): Promise<void> {
+    const sidecarPath = join(
+        options.agentFolder.directoryPath,
+        createAgentPlannedMessagesSidecarPath(options.metadata.fileName),
+    );
+    const plannedMessages = await AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS.list({
+        agentPermanentId: options.job.agentPermanentId,
+    });
+    const sidecar: AgentPlannedMessagesSidecar = {
+        version: 1,
+        agentPermanentId: options.job.agentPermanentId,
+        currentPlannedMessages: plannedMessages.items.map(createLocalAgentPlannedMessageSnapshot),
+        commands: [],
+    };
+
+    await mkdir(dirname(sidecarPath), { recursive: true });
+    await writeFile(sidecarPath, createAgentPlannedMessagesSidecarContent(sidecar), 'utf-8');
+}
+
+/**
+ * Reduces one stored planned message to the fields a coding harness needs.
+ *
+ * The whole schedule travels into the sidecar, so the harness can compare a plan with its goal instead
+ * of only seeing when the next wake-up happens.
+ *
+ * @param plannedMessage - Planned message returned by the shared planned-message actions.
+ * @returns Snapshot written into the sidecar.
+ *
+ * @private function of `prepareLocalAgentPlannedMessagesSidecar`
+ */
+function createLocalAgentPlannedMessageSnapshot(
+    plannedMessage: AgentGoalChatPlannedMessageItem,
+): AgentPlannedMessageSnapshot {
+    return {
+        timeoutId: plannedMessage.timeoutId,
+        dueAt: plannedMessage.dueAt,
+        message: plannedMessage.message,
+        intervalMs: plannedMessage.intervalMs,
+        cronExpression: plannedMessage.cronExpression,
+        startsAt: plannedMessage.startsAt,
+        endsAt: plannedMessage.endsAt,
+        maxRunCount: plannedMessage.maxRunCount,
+        runCount: plannedMessage.runCount,
+    };
+}

package/apps/agents-server/src/utils/localChatRunner/prepareLocalTeamConversationWorkspace.ts

@@ -0,0 +1,233 @@
+import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
+import { mkdir, rm, stat, writeFile } from 'fs/promises';
+import { join } from 'path';
+import type { string_agent_url } from '../../../../../src/types/typeAliases';
+import {
+    AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME,
+    AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME,
+    createAgentTeamConversationWorkspacePath,
+    createAgentTeamTeammateSourceFileName,
+    type AgentTeamConversationTeammate,
+    type AgentTeamConversationWorkspaceManifest,
+} from '../../../../../src/book-3.0/AgentTeamConversationWorkspace';
+import {
+    resolveCachedServerAgentContext,
+    resolveCachedServerAgentModelRequirements,
+} from '../cachedServerAgentRuntime';
+import { createServerAgentReferenceResolver } from '../agentReferenceResolver/createServerAgentReferenceResolver';
+import { normalizeLocalServerUrls, resolveLocalAgentRouteReference } from '../localAgentRouteReferences';
+import { resolveCurrentOrInternalServerOrigin } from '../resolveCurrentOrInternalServerOrigin';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { LocalAgentFolder } from './ensureLocalAgentFolder';
+import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
+
+/**
+ * Resolves local TEAM members and snapshots their sources for one local coding-harness job.
+ */
+export async function prepareLocalTeamConversationWorkspace(options: {
+    readonly job: Pick<UserChatJobRecord, 'agentPermanentId'>;
+    readonly agentFolder: LocalAgentFolder;
+    readonly metadata: LocalUserChatJobMetadata;
+    readonly primaryAgentName: string;
+}): Promise<void> {
+    const workspacePath = join(
+        options.agentFolder.directoryPath,
+        createAgentTeamConversationWorkspacePath(options.metadata.fileName),
+    );
+    const manifestPath = join(workspacePath, AGENT_TEAM_CONVERSATION_MANIFEST_FILE_NAME);
+
+    if (await isExistingPath(manifestPath)) {
+        return;
+    }
+
+    const localServerUrl = await resolveCurrentOrInternalServerOrigin();
+    const collection = await $provideAgentCollectionForServer();
+    const agentReferenceResolver = await createServerAgentReferenceResolver({
+        agentCollection: collection,
+        localServerUrl,
+    });
+    const primaryAgentContext = await resolveCachedServerAgentContext({
+        collection,
+        agentIdentifier: options.job.agentPermanentId,
+        localServerUrl,
+        fallbackResolver: agentReferenceResolver,
+    });
+    const preparedRequirements = await resolveCachedServerAgentModelRequirements({
+        resolvedAgentContext: primaryAgentContext,
+        localServerUrl,
+        fallbackResolver: agentReferenceResolver,
+    });
+    const teammates = await resolveLocalTeamConversationTeammates({
+        teammates: getPreparedTeamMetadata(preparedRequirements.modelRequirements._metadata?.teammates),
+        collection,
+        localServerUrl,
+        primaryAgentPermanentId: options.job.agentPermanentId,
+        agentReferenceResolver,
+    });
+
+    if (teammates.length === 0) {
+        return;
+    }
+
+    const manifest: AgentTeamConversationWorkspaceManifest = {
+        version: 1,
+        primaryAgent: {
+            permanentId: options.job.agentPermanentId,
+            agentName: options.primaryAgentName,
+        },
+        teammates: teammates.map(({ teammate }) => teammate),
+    };
+
+    // Note: The path is deterministically derived from this one queued message, so clearing a stale
+    //       incomplete workspace cannot affect another user turn.
+    await rm(workspacePath, { recursive: true, force: true });
+    await mkdir(join(workspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME), { recursive: true });
+    await Promise.all([
+        writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8'),
+        ...teammates.map(({ teammate, source }) =>
+            writeFile(
+                join(workspacePath, AGENT_TEAMMATE_SOURCES_DIRECTORY_NAME, teammate.sourceFileName),
+                ensureTrailingNewline(source),
+                'utf-8',
+            ),
+        ),
+    ]);
+}
+
+/**
+ * TEAM metadata retained by the TEAM commitment while building model requirements.
+ */
+type PreparedTeamMetadata = {
+    readonly url: string;
+    readonly label?: string;
+    readonly instructions?: string;
+};
+
+/**
+ * One workspace teammate paired with its resolved read-only source.
+ */
+type LocalTeamConversationTeammate = {
+    readonly teammate: AgentTeamConversationTeammate;
+    readonly source: string;
+};
+
+/**
+ * Extracts valid TEAM metadata from untyped commitment metadata.
+ */
+function getPreparedTeamMetadata(value: unknown): Array<PreparedTeamMetadata> {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+
+    return value.filter(isPreparedTeamMetadata);
+}
+
+/**
+ * Checks one TEAM metadata item from `AgentModelRequirements._metadata`.
+ */
+function isPreparedTeamMetadata(value: unknown): value is PreparedTeamMetadata {
+    return Boolean(value && typeof value === 'object' && typeof (value as PreparedTeamMetadata).url === 'string');
+}
+
+/**
+ * Resolves only teammates hosted by this Agents Server, because only their durable histories can be persisted here.
+ */
+async function resolveLocalTeamConversationTeammates(options: {
+    readonly teammates: ReadonlyArray<PreparedTeamMetadata>;
+    readonly collection: Awaited<ReturnType<typeof $provideAgentCollectionForServer>>;
+    readonly localServerUrl: string;
+    readonly primaryAgentPermanentId: string;
+    readonly agentReferenceResolver: Awaited<ReturnType<typeof createServerAgentReferenceResolver>>;
+}): Promise<Array<LocalTeamConversationTeammate>> {
+    const localServerUrls = normalizeLocalServerUrls([options.localServerUrl]);
+    const seenPermanentIds = new Set<string>();
+    const resolvedTeammates: Array<LocalTeamConversationTeammate> = [];
+
+    for (const preparedTeammate of options.teammates) {
+        const routeReference = resolveLocalAgentRouteReference(
+            preparedTeammate.url as string_agent_url,
+            localServerUrls,
+            [],
+        );
+        if (!routeReference) {
+            continue;
+        }
+
+        const basicInformation = await options.collection.findAgentBasicInformation(routeReference.agentIdentifier);
+        const teammatePermanentId = basicInformation?.permanentId;
+        if (
+            !teammatePermanentId ||
+            isSamePermanentId(teammatePermanentId, options.primaryAgentPermanentId) ||
+            seenPermanentIds.has(teammatePermanentId)
+        ) {
+            continue;
+        }
+
+        const teammateContext = await resolveCachedServerAgentContext({
+            collection: options.collection,
+            agentIdentifier: teammatePermanentId,
+            localServerUrl: options.localServerUrl,
+            fallbackResolver: options.agentReferenceResolver,
+        });
+        const teammateName = preparedTeammate.label?.trim() || teammateContext.resolvedAgentName;
+        if (!teammateName) {
+            continue;
+        }
+
+        seenPermanentIds.add(teammatePermanentId);
+        resolvedTeammates.push({
+            teammate: {
+                permanentId: teammatePermanentId,
+                agentName: teammateName,
+                url: preparedTeammate.url,
+                instructions: preparedTeammate.instructions?.trim() || '',
+                sourceFileName: createAgentTeamTeammateSourceFileName(teammatePermanentId),
+            },
+            source: teammateContext.resolvedAgentSource,
+        });
+    }
+
+    return resolvedTeammates;
+}
+
+/**
+ * Compares permanent ids case-insensitively, matching Agents Server routing semantics.
+ */
+function isSamePermanentId(firstPermanentId: string, secondPermanentId: string): boolean {
+    return firstPermanentId.toLowerCase() === secondPermanentId.toLowerCase();
+}
+
+/**
+ * Keeps source snapshots friendly to the Book parser and coding harness.
+ */
+function ensureTrailingNewline(source: string): string {
+    return source.endsWith('\n') ? source : `${source}\n`;
+}
+
+/**
+ * Checks whether a fixed per-message workspace manifest already exists.
+ */
+async function isExistingPath(path: string): Promise<boolean> {
+    try {
+        await stat(path);
+        return true;
+    } catch (error) {
+        if (isFileNotFoundError(error)) {
+            return false;
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Returns true when one filesystem error indicates a missing path.
+ */
+function isFileNotFoundError(error: unknown): boolean {
+    return Boolean(
+        error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            ((error as { code?: string }).code === 'ENOENT' || (error as { code?: string }).code === 'ENOTDIR'),
+    );
+}