@promptbook/cli 0.114.0-3 → 0.114.0-30

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

@@ -1,24 +1,14 @@
-import { string_promptbook_server_url } from '@promptbook-local/types';
+import type { string_promptbook_server_url } from '@promptbook-local/types';
+import { FEDERATED_SERVERS_METADATA_KEY } from '../constants/federatedAgentImport';
 import { getMetadataMap } from '../database/getMetadata';
-
-/**
- * Metadata key storing the comma-separated federated servers list.
- *
- * @private
- */
-const FEDERATED_SERVERS_METADATA_KEY = 'FEDERATED_SERVERS';
+import { parseFederatedServers } from './parseFederatedServers';
 
 /**
  * Reads FEDERATED_SERVERS metadata and returns a normalized list of server URLs.
  *
  * @public exported from `apps/agents-server`
  */
-export async function getFederatedServers(): Promise<string_promptbook_server_url[]> {
+export async function getFederatedServers(): Promise<Array<string_promptbook_server_url>> {
     const metadata = await getMetadataMap([FEDERATED_SERVERS_METADATA_KEY]);
-    const federatedServersString = metadata[FEDERATED_SERVERS_METADATA_KEY] || '';
-
-    return federatedServersString
-        .split(',')
-        .map((server) => server.trim())
-        .filter((server): server is string_promptbook_server_url => server !== '');
+    return parseFederatedServers(metadata[FEDERATED_SERVERS_METADATA_KEY]);
 }

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

@@ -1,5 +1,6 @@
 import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../../../servers';
 import { string_agent_url } from '../../../../src/_packages/types.index'; // <- [🚾]
+import { createWellKnownAgentUrl } from './createWellKnownAgentUrl';
 import { resolveCurrentOrInternalServerOrigin } from './resolveCurrentOrInternalServerOrigin';
 
 /**
@@ -14,7 +15,5 @@ export async function getWellKnownAgentUrl(
     agentName: keyof typeof CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES,
 ): Promise<string_agent_url> {
     const localServerOrigin = await resolveCurrentOrInternalServerOrigin();
-    const normalizedServerOrigin = localServerOrigin.replace(/\/+$/g, '');
-
-    return `${normalizedServerOrigin}/agents/${CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES[agentName]}` as string_agent_url;
+    return createWellKnownAgentUrl(localServerOrigin, agentName);
 }

package/apps/agents-server/src/utils/handleChatCompletion/createHandleChatCompletionPromptContext.ts

@@ -1,5 +1,6 @@
 import { createChatHistoryRecorder } from '@/src/utils/chat/createChatHistoryRecorder';
 import { composePromptParametersWithMemoryContext } from '@/src/utils/memoryRuntimeContext';
+import { createAgentGoalChatTimeoutTools } from '@/src/tools/agentGoalChatTimeoutTools';
 import type { ChatMessage, ChatPrompt } from '@promptbook-local/types';
 import { $getCurrentDate } from '@promptbook-local/utils';
 import type { NextRequest } from 'next/server';
@@ -64,12 +65,12 @@ export async function createHandleChatCompletionPromptContext(options: {
         projectRepositories: runtime.projectRepositories,
         projectGithubToken: runtime.projectGithubToken,
         emailSmtpCredential: runtime.emailSmtpCredential,
-        emailFromAddress: runtime.useEmailConfiguration.senderEmail,
         calendarGoogleAccessToken: runtime.calendarGoogleAccessToken,
         calendarConnections: runtime.calendarConnections,
         localServerUrl: runtime.localServerUrl,
         teamInternalAccessToken: resolveTeamInternalAgentAccessToken(),
     });
+    const runtimeTools = createAgentGoalChatTimeoutTools(parsedRequest.runtimeTools || []);
     const prompt: ChatPrompt = {
         title,
         content: lastMessage.content,
@@ -80,7 +81,7 @@ export async function createHandleChatCompletionPromptContext(options: {
         },
         parameters: promptParameters,
         thread,
-        ...(parsedRequest.runtimeTools ? { tools: parsedRequest.runtimeTools } : {}),
+        tools: runtimeTools,
     };
 
     return {

package/apps/agents-server/src/utils/handleChatCompletion/resolveHandleChatCompletionRuntime.ts

@@ -5,7 +5,6 @@ import type { string_book, TODO_any } from '@promptbook-local/types';
 import { createInlineKnowledgeSourceUploader } from '@/src/utils/knowledge/createInlineKnowledgeSourceUploader';
 import { resolveCurrentUserMemoryIdentity } from '@/src/utils/userMemory';
 import { extractUseCalendarConnectionsFromAgentSource } from '@/src/utils/calendars/extractUseCalendarConnectionsFromAgentSource';
-import { extractUseEmailConfigurationFromAgentSource } from '@/src/utils/emails/extractUseEmailConfigurationFromAgentSource';
 import { extractProjectRepositoriesFromAgentSource } from '@/src/utils/projects/extractProjectRepositoriesFromAgentSource';
 import { resolveUseEmailSmtpCredential } from '@/src/utils/resolveUseEmailSmtpCredential';
 import { resolveUseCalendarGoogleToken } from '@/src/utils/resolveUseCalendarGoogleToken';
@@ -43,7 +42,6 @@ export type HandleChatCompletionRuntime = {
     agentHash: string;
     projectRepositories: ReturnType<typeof extractProjectRepositoriesFromAgentSource>;
     calendarConnections: ReturnType<typeof extractUseCalendarConnectionsFromAgentSource>;
-    useEmailConfiguration: ReturnType<typeof extractUseEmailConfigurationFromAgentSource>;
     currentUserIdentity: Awaited<ReturnType<typeof resolveCurrentUserMemoryIdentity>>;
     projectGithubToken: Awaited<ReturnType<typeof resolveUseProjectGithubToken>>;
     calendarGoogleAccessToken: Awaited<ReturnType<typeof resolveUseCalendarGoogleToken>>;
@@ -95,7 +93,6 @@ export async function resolveHandleChatCompletionRuntime(options: {
     const unresolvedAgentSource = resolvedAgentContext.unresolvedAgentSource;
     const projectRepositories = extractProjectRepositoriesFromAgentSource(agentSource);
     const calendarConnections = extractUseCalendarConnectionsFromAgentSource(agentSource);
-    const useEmailConfiguration = extractUseEmailConfigurationFromAgentSource(agentSource);
     const messageSuffix = resolveMessageSuffixFromAgentSource(agentSource);
     const { agentSourceWithContext, hasDynamicContext } = appendSystemMessagesToAgentSource(agentSource, messages);
     agentSource = agentSourceWithContext;
@@ -121,7 +118,6 @@ export async function resolveHandleChatCompletionRuntime(options: {
             currentUserIdentity,
             agentId,
             calendarConnections,
-            useEmailConfiguration,
         });
     const agent = await createHandleChatCompletionAgent({
         agentName,
@@ -145,7 +141,6 @@ export async function resolveHandleChatCompletionRuntime(options: {
         agentHash,
         projectRepositories,
         calendarConnections,
-        useEmailConfiguration,
         currentUserIdentity,
         projectGithubToken,
         calendarGoogleAccessToken,
@@ -213,7 +208,6 @@ async function resolveHandleChatCompletionCredentials(options: {
     currentUserIdentity: Awaited<ReturnType<typeof resolveCurrentUserMemoryIdentity>>;
     agentId: string;
     calendarConnections: ReturnType<typeof extractUseCalendarConnectionsFromAgentSource>;
-    useEmailConfiguration: ReturnType<typeof extractUseEmailConfigurationFromAgentSource>;
 }): Promise<{
     projectGithubToken: Awaited<ReturnType<typeof resolveUseProjectGithubToken>>;
     calendarGoogleAccessToken: Awaited<ReturnType<typeof resolveUseCalendarGoogleToken>>;
@@ -231,12 +225,10 @@ async function resolveHandleChatCompletionCredentials(options: {
                   agentPermanentId: options.agentId,
               })
             : Promise.resolve(undefined),
-        options.useEmailConfiguration.isEnabled
-            ? resolveUseEmailSmtpCredential({
-                  userId,
-                  agentPermanentId: options.agentId,
-              })
-            : Promise.resolve(undefined),
+        resolveUseEmailSmtpCredential({
+            userId,
+            agentPermanentId: options.agentId,
+        }),
     ]);
 
     return {

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

@@ -0,0 +1,261 @@
+import { readFile, rm } from 'fs/promises';
+import { join } from 'path';
+import { serializeError } from '@promptbook-local/utils';
+import {
+    createAgentPlannedMessagesSidecarPath,
+    parseAgentPlannedMessagesSidecar,
+    type AgentPlannedMessageCommand,
+} from '../../../../../src/book-3.0/AgentPlannedMessagesSidecar';
+import {
+    AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS,
+    type CancelAgentGoalChatPlannedMessageResult,
+    type SetAgentGoalChatPlannedMessageResult,
+    type UpdateAgentGoalChatPlannedMessageResult,
+} from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import type { UserChatJobRecord } from '../userChat/UserChatJobRecord';
+import type { LocalUserChatJobMetadata } from './LocalUserChatJobMetadata';
+
+/**
+ * Planned-message operations used while applying one sidecar.
+ */
+export type LocalAgentPlannedMessageActions = Pick<
+    typeof AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS,
+    'set' | 'update' | 'cancel'
+>;
+
+/**
+ * One planned-message command that was applied together with its result.
+ *
+ * The command carries what the agent asked for (for example the requested schedule) and the result
+ * carries what really happened, so the chat can show the wake-up below the message that planned it.
+ */
+export type AppliedAgentPlannedMessageCommand = {
+    readonly command: AgentPlannedMessageCommand;
+    readonly result:
+        | SetAgentGoalChatPlannedMessageResult
+        | UpdateAgentGoalChatPlannedMessageResult
+        | CancelAgentGoalChatPlannedMessageResult;
+};
+
+/**
+ * Applies every planned-message command a coding harness wrote while answering one message.
+ *
+ * The sidecar is consumed exactly once: it is removed afterwards so a replayed worker tick can never
+ * schedule the very same wake-up twice.
+ *
+ * @param options - Answered job, its agent folder path, and the local runner metadata of the message.
+ * @returns Planned-message commands that were applied successfully, in sidecar order.
+ */
+export async function applyLocalAgentPlannedMessageCommands(options: {
+    readonly job: Pick<UserChatJobRecord, 'id' | 'chatId' | 'agentPermanentId'>;
+    readonly agentDirectoryPath: string;
+    readonly metadata: LocalUserChatJobMetadata;
+    readonly actions?: LocalAgentPlannedMessageActions;
+}): Promise<ReadonlyArray<AppliedAgentPlannedMessageCommand>> {
+    const sidecarPath = resolveLocalAgentPlannedMessagesSidecarPath(options.agentDirectoryPath, options.metadata);
+    const sidecarContent = await readOptionalTextFile(sidecarPath);
+
+    await removeLocalAgentPlannedMessagesSidecar(options.agentDirectoryPath, options.metadata);
+
+    if (sidecarContent === null) {
+        return [];
+    }
+
+    const sidecar = parseAgentPlannedMessagesSidecar(sidecarContent);
+
+    if (!sidecar) {
+        console.warn('[local-chat-runner] planned_messages_sidecar_unreadable', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+        });
+        return [];
+    }
+
+    const actions = options.actions || AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS;
+    const appliedCommands: Array<AppliedAgentPlannedMessageCommand> = [];
+
+    for (const command of sidecar.commands) {
+        const result = await applyLocalAgentPlannedMessageCommand({
+            command,
+            actions,
+            agentPermanentId: options.job.agentPermanentId,
+            job: options.job,
+        });
+
+        if (result) {
+            appliedCommands.push({ command, result });
+        }
+    }
+
+    return appliedCommands;
+}
+
+/**
+ * Removes the planned-message sidecar of one queued message.
+ *
+ * @param agentDirectoryPath - Absolute path of the local agent folder.
+ * @param metadata - Local runner metadata of the queued message.
+ */
+export async function removeLocalAgentPlannedMessagesSidecar(
+    agentDirectoryPath: string,
+    metadata: LocalUserChatJobMetadata,
+): Promise<void> {
+    await rm(resolveLocalAgentPlannedMessagesSidecarPath(agentDirectoryPath, metadata), { force: true }).catch(
+        () => undefined,
+    );
+}
+
+/**
+ * Dispatches one planned-message command through the shared planned-message actions.
+ *
+ * One rejected command never blocks the remaining ones, because the agent already answered and the
+ * harness owns this sidecar.
+ *
+ * @param options - Command, actions, and the agent whose goal chat owns the planned message.
+ * @returns Result of the applied command, or `null` when it was rejected.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+async function applyLocalAgentPlannedMessageCommand(options: {
+    readonly command: AgentPlannedMessageCommand;
+    readonly actions: LocalAgentPlannedMessageActions;
+    readonly agentPermanentId: string;
+    readonly job: Pick<UserChatJobRecord, 'id' | 'chatId'>;
+}): Promise<AppliedAgentPlannedMessageCommand['result'] | null> {
+    try {
+        if (options.command.action === 'set') {
+            const plannedMessage = await options.actions.set({
+                agentPermanentId: options.agentPermanentId,
+                ...createLocalAgentPlannedMessageScheduleRequest(options.command),
+                message: options.command.message,
+            });
+
+            console.info('[local-chat-runner]', 'planned_message_set', {
+                chatId: options.job.chatId,
+                jobId: options.job.id,
+                timeoutId: plannedMessage.timeoutId,
+                dueAt: plannedMessage.dueAt,
+            });
+
+            return plannedMessage;
+        }
+
+        if (options.command.action === 'update') {
+            const updatedPlannedMessage = await options.actions.update({
+                agentPermanentId: options.agentPermanentId,
+                timeoutId: options.command.timeoutId,
+                ...createLocalAgentPlannedMessageScheduleRequest(options.command),
+                ...(options.command.message === undefined ? {} : { message: options.command.message }),
+            });
+
+            console.info('[local-chat-runner]', 'planned_message_update', {
+                chatId: options.job.chatId,
+                jobId: options.job.id,
+                timeoutId: updatedPlannedMessage.timeoutId,
+                status: updatedPlannedMessage.status,
+                dueAt: updatedPlannedMessage.dueAt,
+            });
+
+            return updatedPlannedMessage.status === 'updated' ? updatedPlannedMessage : null;
+        }
+
+        const cancelledPlannedMessage = await options.actions.cancel({
+            agentPermanentId: options.agentPermanentId,
+            timeoutId: options.command.timeoutId,
+        });
+
+        console.info('[local-chat-runner]', 'planned_message_cancel', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            timeoutId: cancelledPlannedMessage.timeoutId,
+            status: cancelledPlannedMessage.status,
+        });
+
+        return cancelledPlannedMessage.status === 'cancelled' ? cancelledPlannedMessage : null;
+    } catch (error) {
+        console.error('[local-chat-runner]', 'planned_message_command_failed', {
+            chatId: options.job.chatId,
+            jobId: options.job.id,
+            action: options.command.action,
+            error: serializeError(error as Error),
+        });
+
+        return null;
+    }
+}
+
+/**
+ * Collects the schedule fields of one sidecar command.
+ *
+ * A field the harness did not write stays absent, which is what tells "keep this part of the schedule"
+ * apart from "remove this bound".
+ *
+ * @param command - Planned-message command written by the coding harness.
+ * @returns Schedule fields passed to the shared planned-message actions.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+function createLocalAgentPlannedMessageScheduleRequest(command: AgentPlannedMessageCommand): {
+    readonly [FieldName: string]: unknown;
+} {
+    return {
+        ...(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 }),
+    };
+}
+
+/**
+ * Resolves the absolute planned-message sidecar path of one queued message.
+ *
+ * @param agentDirectoryPath - Absolute path of the local agent folder.
+ * @param metadata - Local runner metadata of the queued message.
+ * @returns Absolute sidecar path.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+function resolveLocalAgentPlannedMessagesSidecarPath(
+    agentDirectoryPath: string,
+    metadata: LocalUserChatJobMetadata,
+): string {
+    return join(agentDirectoryPath, createAgentPlannedMessagesSidecarPath(metadata.fileName));
+}
+
+/**
+ * Reads one text file and treats a missing planned-message sidecar as absent.
+ *
+ * @param path - Absolute sidecar path.
+ * @returns File content, or `null` when the sidecar does not exist.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+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.
+ *
+ * @param error - Caught filesystem failure.
+ * @returns `true` for missing-path errors.
+ *
+ * @private function of `applyLocalAgentPlannedMessageCommands`
+ */
+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/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'),
+    );
+}