@promptbook/cli 0.113.0-5 → 0.113.0-7

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

@@ -0,0 +1,167 @@
+import type { string_agent_url } from '../../../../src/types/typeAliases';
+
+/**
+ * Parsed local agent route reference.
+ */
+export type LocalAgentRouteReference = {
+    /**
+     * Matched same-instance server origin.
+     */
+    readonly localServerUrl: string;
+
+    /**
+     * Decoded route identifier after `/agents/`.
+     */
+    readonly agentIdentifier: string;
+};
+
+/**
+ * Exact local route alias for one agent URL.
+ */
+export type LocalAgentUrlReference = LocalAgentRouteReference & {
+    /**
+     * Normalized exact local agent URL.
+     */
+    readonly agentUrl: string;
+};
+
+/**
+ * Normalizes same-instance server URLs for route matching.
+ *
+ * @param localServerUrls - Raw server URLs.
+ * @returns Unique normalized origins without trailing slash.
+ */
+export function normalizeLocalServerUrls(localServerUrls: ReadonlyArray<string>): ReadonlyArray<string> {
+    return [
+        ...new Set(
+            localServerUrls
+                .map((localServerUrl) => normalizeServerUrl(localServerUrl))
+                .filter((localServerUrl) => localServerUrl.length > 0),
+        ),
+    ];
+}
+
+/**
+ * Normalizes exact local agent URL aliases for route matching.
+ *
+ * @param localAgentUrls - Raw local agent URLs.
+ * @returns Unique normalized route references.
+ */
+export function normalizeLocalAgentUrlReferences(
+    localAgentUrls: ReadonlyArray<string_agent_url>,
+): ReadonlyArray<LocalAgentUrlReference> {
+    const localAgentUrlReferences: Array<LocalAgentUrlReference> = [];
+    const seenAgentUrls = new Set<string>();
+
+    for (const localAgentUrl of localAgentUrls) {
+        const localAgentRouteReference = parseLocalAgentRouteReference(localAgentUrl);
+
+        if (!localAgentRouteReference) {
+            continue;
+        }
+
+        const normalizedAgentUrl = createLocalAgentUrl(
+            localAgentRouteReference.localServerUrl,
+            localAgentRouteReference.agentIdentifier,
+        );
+
+        if (seenAgentUrls.has(normalizedAgentUrl)) {
+            continue;
+        }
+
+        seenAgentUrls.add(normalizedAgentUrl);
+        localAgentUrlReferences.push({
+            ...localAgentRouteReference,
+            agentUrl: normalizedAgentUrl,
+        });
+    }
+
+    return localAgentUrlReferences;
+}
+
+/**
+ * Extracts a local agent identifier from a same-instance agent URL.
+ *
+ * @param agentUrl - Referenced agent URL.
+ * @param localServerUrls - Normalized same-instance server origins.
+ * @param localAgentUrlReferences - Exact agent URL aliases that should resolve locally.
+ * @returns Route reference or `null` when the URL belongs to another server.
+ */
+export function resolveLocalAgentRouteReference(
+    agentUrl: string_agent_url,
+    localServerUrls: ReadonlyArray<string>,
+    localAgentUrlReferences: ReadonlyArray<LocalAgentUrlReference>,
+): LocalAgentRouteReference | null {
+    const localAgentRouteReference = parseLocalAgentRouteReference(agentUrl);
+
+    if (!localAgentRouteReference) {
+        return null;
+    }
+
+    if (localServerUrls.includes(localAgentRouteReference.localServerUrl)) {
+        return localAgentRouteReference;
+    }
+
+    const normalizedAgentUrl = createLocalAgentUrl(
+        localAgentRouteReference.localServerUrl,
+        localAgentRouteReference.agentIdentifier,
+    );
+    return (
+        localAgentUrlReferences.find((localAgentUrlReference) => localAgentUrlReference.agentUrl === normalizedAgentUrl) ||
+        null
+    );
+}
+
+/**
+ * Builds one local agent profile URL.
+ *
+ * @param localServerUrl - Same-instance server origin.
+ * @param agentIdentifier - Route agent identifier.
+ * @returns Local agent URL.
+ */
+export function createLocalAgentUrl(localServerUrl: string, agentIdentifier: string): string_agent_url {
+    return `${localServerUrl.replace(/\/+$/g, '')}/agents/${encodeURIComponent(agentIdentifier)}` as string_agent_url;
+}
+
+/**
+ * Normalizes one server URL to its origin.
+ *
+ * @param serverUrl - Raw server URL.
+ * @returns Normalized origin or an empty string when invalid.
+ */
+function normalizeServerUrl(serverUrl: string): string {
+    try {
+        return new URL(serverUrl).origin.replace(/\/+$/g, '');
+    } catch {
+        return serverUrl.replace(/\/+$/g, '');
+    }
+}
+
+/**
+ * Extracts a local route reference from an agent profile URL.
+ *
+ * @param agentUrl - Referenced agent URL.
+ * @returns Route reference or `null` when the URL is not an agent profile route.
+ */
+function parseLocalAgentRouteReference(agentUrl: string_agent_url): LocalAgentRouteReference | null {
+    let parsedAgentUrl: URL;
+
+    try {
+        parsedAgentUrl = new URL(agentUrl);
+    } catch {
+        return null;
+    }
+
+    const localServerUrl = normalizeServerUrl(parsedAgentUrl.origin);
+    const pathSegments = parsedAgentUrl.pathname.split('/').filter(Boolean);
+    const agentIdentifier = pathSegments[0] === 'agents' ? pathSegments[1] : null;
+
+    if (!agentIdentifier) {
+        return null;
+    }
+
+    return {
+        localServerUrl,
+        agentIdentifier: decodeURIComponent(agentIdentifier),
+    };
+}

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

@@ -144,7 +144,7 @@ async function enqueueLocalUserChatJob(job: UserChatJobRecord): Promise<ProcessL
         throw new Error(`User message "${job.userMessageId}" was not found in chat "${job.chatId}".`);
     }
 
-    const threadMessages = createUserChatRunnerThreadMessages({
+    const threadMessages = await createUserChatRunnerThreadMessages({
         messages: chat.messages,
         userMessageId: job.userMessageId,
         resolveInitialAgentMessage: () => parseAgentSource(agentSourceSnapshot.agentSource).initialMessage,

package/apps/agents-server/src/utils/managementApi/managementApiAgents.ts

@@ -4,8 +4,10 @@ import { loadLocalOrganizationSearchDataset } from '../../search/createDefaultSe
 import { stringifyJsonForSearch } from '../../search/createDefaultServerSearchProviders/stringifyJsonForSearch';
 import { $getTableName } from '../../database/$getTableName';
 import { $provideSupabaseForServer } from '../../database/$provideSupabaseForServer';
+import { $provideAgentCollectionForServer } from '../../tools/$provideAgentCollectionForServer';
 import type { OwnedAgentRow } from '../agentOwnership';
 import { $provideAgentReferenceResolver } from '../agentReferenceResolver/$provideAgentReferenceResolver';
+import { createLocalAgentSourceImporter } from '../createLocalAgentSourceImporter';
 import { getWellKnownAgentUrl } from '../getWellKnownAgentUrl';
 import { resolveCurrentOrInternalServerOrigin } from '../resolveCurrentOrInternalServerOrigin';
 import { resolveStoredAgentState } from '../resolveStoredAgentState';
@@ -42,10 +44,22 @@ export type ManagementAgentListItem = {
  * @returns Resolved agent state derived from the stored unresolved source.
  */
 export async function resolveOwnedAgentDerivedState(row: OwnedAgentRow) {
+    const localServerUrl = await resolveCurrentOrInternalServerOrigin();
+    const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+    const agentReferenceResolver = await $provideAgentReferenceResolver();
+    const agentSourceImporter = createLocalAgentSourceImporter({
+        collection: await $provideAgentCollectionForServer(),
+        localServerUrls: [localServerUrl],
+        localAgentUrls: [adamAgentUrl],
+        adamAgentUrl,
+        fallbackResolver: agentReferenceResolver,
+    });
+
     return resolveStoredAgentState(row, {
-        localServerUrl: await resolveCurrentOrInternalServerOrigin(),
-        adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
-        agentReferenceResolver: await $provideAgentReferenceResolver(),
+        localServerUrl,
+        adamAgentUrl,
+        agentReferenceResolver,
+        agentSourceImporter,
     });
 }
 

package/apps/agents-server/src/utils/messages/sendMessage.ts

@@ -3,6 +3,7 @@ import { EMAIL_PROVIDERS } from '../../message-providers';
 import type { MessageProvider } from '../../message-providers/interfaces/MessageProvider';
 import type { OutboundEmail } from '../../message-providers/email/_common/Email';
 import { createMessage } from './createMessage';
+import { humanizeOutboundEmail } from './humanizeOutboundEmail';
 import { sendMessageAttempt } from './sendMessageAttempt';
 
 /**
@@ -63,14 +64,15 @@ export function isSendMessageDeliveryError(error: unknown): error is SendMessage
  * Persists a message and, for outbound emails, creates send attempts until one provider succeeds.
  */
 export async function sendMessage(message: OutboundEmail, options?: SendMessageOptions): Promise<SendMessageResult> {
-    const insertedMessage = await createMessage(message);
+    const email = humanizeOutboundEmail(message);
+    const insertedMessage = await createMessage(email);
     const baseResult: SendMessageResult = {
         messageId: insertedMessage.id,
         status: 'stored-only',
         attempts: [],
     };
 
-    if (message.direction !== 'OUTBOUND' || message.channel !== 'EMAIL') {
+    if (email.direction !== 'OUTBOUND' || email.channel !== 'EMAIL') {
         return baseResult;
     }
 
@@ -88,7 +90,7 @@ export async function sendMessage(message: OutboundEmail, options?: SendMessageO
             messageId: insertedMessage.id,
             providerName,
             provider,
-            message,
+            message: email,
         });
 
         baseResult.attempts.push(attempt);

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

@@ -3,7 +3,7 @@ import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-sour
 import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
 import { parseAgentSource } from '../../../../src/book-2.0/agent-source/parseAgentSource';
 import { resolveTeamCapabilitiesFromAgentSource } from './agentReferenceResolver/resolveTeamCapabilitiesFromAgentSource';
-import { resolveInheritedAgentSource } from './resolveInheritedAgentSource';
+import { resolveInheritedAgentSource, type AgentSourceImporter } from './resolveInheritedAgentSource';
 
 /**
  * Options for deriving the canonical resolved agent state from an editable source.
@@ -33,6 +33,11 @@ export type ResolveAgentStateFromSourceOptions = {
      * Retry configuration used when loading imported agents from federated servers.
      */
     readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+
+    /**
+     * Optional importer for same-instance agent sources.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
 };
 
 /**
@@ -112,6 +117,7 @@ export async function resolveAgentStateFromSource(
         currentAgentAliases: options.currentAgentAliases,
         agentReferenceResolver: options.agentReferenceResolver,
         federatedAgentImportConfiguration: options.federatedAgentImportConfiguration,
+        agentSourceImporter: options.agentSourceImporter,
     });
     const resolvedAgentProfile = parseAgentSource(resolvedAgentSource);
     const resolvedTeamCapabilities = await resolveTeamCapabilitiesFromAgentSource(

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

@@ -231,8 +231,42 @@ type ResolveInheritedAgentSourceOptions = ImportAgentOptions & {
      * Retry configuration used for federated imported-agent loading.
      */
     readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+    /**
+     * Optional same-instance source importer used before falling back to HTTP import.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
 };
 
+/**
+ * Context passed to a custom agent source importer.
+ */
+export type AgentSourceImporterContext = {
+    /**
+     * Commitment that requested the imported source.
+     */
+    readonly commitmentType: 'FROM' | 'IMPORT';
+
+    /**
+     * Import options propagated from the current resolution pass.
+     */
+    readonly importAgentOptions: ImportAgentOptions;
+
+    /**
+     * Retry configuration used by the default HTTP importer.
+     */
+    readonly federatedAgentImportConfiguration: FederatedAgentImportConfiguration;
+};
+
+/**
+ * Imports one agent source before the resolver falls back to the default HTTP importer.
+ *
+ * Return `null` when the importer does not own the given URL.
+ */
+export type AgentSourceImporter = (
+    agentUrl: string_agent_url,
+    context: AgentSourceImporterContext,
+) => Promise<string_book | null>;
+
 /**
  * Parent inheritance state derived before rewriting the source body.
  */
@@ -277,6 +311,11 @@ type AgentImportContext = {
      */
     readonly importAgentOptions: ImportAgentOptions;
 
+    /**
+     * Optional importer for same-instance agent sources.
+     */
+    readonly agentSourceImporter?: AgentSourceImporter;
+
     /**
      * Original resolution options used for cycle detection.
      */
@@ -364,6 +403,7 @@ function createAgentImportContext(options?: ResolveInheritedAgentSourceOptions):
             recursionLevel: options?.recursionLevel || 0,
             inheritancePath: createResolutionLineage(options),
         },
+        agentSourceImporter: options?.agentSourceImporter,
         resolutionOptions: options,
     };
 }
@@ -427,11 +467,20 @@ async function importAgentCorpus(
 ): Promise<string> {
     assertNoResolutionCycle(agentUrl, commitmentType, context.resolutionOptions);
 
-    const importedAgentSource = await importAgentWithFallback(
-        agentUrl,
-        context.importAgentOptions,
-        context.federatedAgentImportConfiguration,
-    );
+    const locallyImportedAgentSource = context.agentSourceImporter
+        ? await context.agentSourceImporter(agentUrl, {
+              commitmentType,
+              importAgentOptions: context.importAgentOptions,
+              federatedAgentImportConfiguration: context.federatedAgentImportConfiguration,
+          })
+        : null;
+    const importedAgentSource =
+        locallyImportedAgentSource ??
+        (await importAgentWithFallback(
+            agentUrl,
+            context.importAgentOptions,
+            context.federatedAgentImportConfiguration,
+        ));
 
     return getAgentSourceCorpus(importedAgentSource as string_book);
 }

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

@@ -1,6 +1,7 @@
 import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-source/AgentReferenceResolver';
 import type { AgentCollection } from '../../../../src/collection/agent-collection/AgentCollection';
 import { resolveBookScopedAgentContext, type ResolvedBookScopedAgentContext } from './agentReferenceResolver/bookScopedAgentReferences';
+import { createLocalAgentSourceImporter } from './createLocalAgentSourceImporter';
 import { loadFederatedAgentImportConfiguration } from './federatedAgentImportConfiguration';
 import { getWellKnownAgentUrl } from './getWellKnownAgentUrl';
 import { resolveAgentStateFromSource, type ResolvedAgentState } from './resolveAgentStateFromSource';
@@ -46,12 +47,22 @@ export async function resolveServerAgentContext(
 ): Promise<ResolvedServerAgentContext> {
     const bookScopedAgentContext = await resolveBookScopedAgentContext(options);
     const federatedAgentImportConfiguration = await loadFederatedAgentImportConfiguration();
+    const adamAgentUrl = await getWellKnownAgentUrl('ADAM');
+    const agentSourceImporter = createLocalAgentSourceImporter({
+        collection: options.collection,
+        localServerUrls: [options.localServerUrl],
+        localAgentUrls: [adamAgentUrl],
+        adamAgentUrl,
+        fallbackResolver: options.fallbackResolver,
+        federatedAgentImportConfiguration,
+    });
     const resolvedAgentState = await resolveAgentStateFromSource(bookScopedAgentContext.unresolvedAgentSource, {
-        adamAgentUrl: await getWellKnownAgentUrl('ADAM'),
+        adamAgentUrl,
         canonicalAgentUrl: bookScopedAgentContext.canonicalAgentUrl,
         currentAgentAliases: bookScopedAgentContext.currentAgentAliases,
         agentReferenceResolver: bookScopedAgentContext.scopedAgentReferenceResolver,
         federatedAgentImportConfiguration,
+        agentSourceImporter,
     });
 
     return {

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

@@ -30,7 +30,7 @@ export type ResolvedStoredAgentState<TAgent extends StoredAgentSourceRecord> = T
  */
 export type ResolveStoredAgentStateOptions = Pick<
     ResolveAgentStateFromSourceOptions,
-    'adamAgentUrl' | 'agentReferenceResolver' | 'federatedAgentImportConfiguration'
+    'adamAgentUrl' | 'agentReferenceResolver' | 'federatedAgentImportConfiguration' | 'agentSourceImporter'
 > & {
     /**
      * Public/current server origin used to build canonical local agent URLs.
@@ -91,6 +91,7 @@ export async function resolveStoredAgentState<TAgent extends StoredAgentSourceRe
         currentAgentAliases: createCanonicalLocalAgentAliases(agent, options.localServerUrl),
         agentReferenceResolver: options.agentReferenceResolver,
         federatedAgentImportConfiguration,
+        agentSourceImporter: options.agentSourceImporter,
     });
 
     return {

package/apps/agents-server/src/utils/speech-to-text/SpeechToTextFailoverRecognition/SpeechToTextFailoverRecognitionProviderRuntime.ts

@@ -172,7 +172,6 @@ export class SpeechToTextFailoverRecognitionProviderRuntime {
             }
         }
 
-        this.options.onForceIdleStop();
         return false;
     }
 

package/apps/agents-server/src/utils/speech-to-text/SpeechToTextFailoverRecognition.ts

@@ -302,13 +302,45 @@ export class SpeechToTextFailoverRecognition implements SpeechRecognition {
      * Handles stall watchdog restart/failover escalation.
      */
     private handleStallDetected(): void {
+        void this.handleStallDetectedAsync();
+    }
+
+    /**
+     * Handles stall watchdog restart/failover escalation.
+     */
+    private async handleStallDetectedAsync(): Promise<void> {
+        const providerId = this.providerRuntime.currentProviderId;
+
         if (!this.providerRuntime.hasRestartedCurrentProvider) {
             this.providerRuntime.markCurrentProviderRestarted();
-            void this.providerRuntime.restartCurrentProvider('stall-detected');
+            this.telemetryReporter.emit({
+                type: 'provider-restart',
+                providerId,
+                elapsedMs: Date.now() - this.sessionStartedAtMs,
+                detail: 'stall-detected',
+            });
+
+            const restartSucceeded = await this.providerRuntime.restartCurrentProvider('stall-detected');
+            if (restartSucceeded) {
+                return;
+            }
+        }
+
+        const failoverSucceeded = await this.providerRuntime.failoverToNextProvider('stall-after-restart');
+        if (failoverSucceeded) {
             return;
         }
 
-        void this.providerRuntime.failoverToNextProvider('stall-after-restart');
+        this._state = 'ERROR';
+        this.emit({
+            type: 'ERROR',
+            message: 'Speech recognition stalled while audio was detected. No fallback speech-to-text provider was available.',
+            code: 'unknown',
+            providerId,
+            canRetry: true,
+            canOpenBrowserSettings: false,
+        });
+        this.forceIdleStop();
     }
 
     /**

package/apps/agents-server/src/utils/userChat/userChatMessageLifecycle.ts

@@ -1,4 +1,6 @@
 import type { ChatMessage } from '../../../../../src/_packages/types.index';
+import { appendChatAttachmentContextWithContent } from '../../../../../src/utils/chat/chatAttachments/appendChatAttachmentContextWithContent';
+
 /**
  * Lifecycle states rendered on canonical server-owned chat messages.
  */
@@ -99,11 +101,11 @@ export function resolvePromptThreadBeforeUserMessage(
 /**
  * Creates the complete chat thread mirrored to a runner before it writes the next answer.
  */
-export function createUserChatRunnerThreadMessages(options: {
+export async function createUserChatRunnerThreadMessages(options: {
     messages: ReadonlyArray<ChatMessage>;
     userMessageId: string;
     resolveInitialAgentMessage: () => string | null | undefined;
-}): Array<UserChatRunnerThreadMessage> {
+}): Promise<Array<UserChatRunnerThreadMessage>> {
     const userMessage = options.messages.find((message) => message.id === options.userMessageId);
     if (!userMessage) {
         return [];
@@ -111,19 +113,16 @@ export function createUserChatRunnerThreadMessages(options: {
 
     const previousThreadMessages = resolvePromptThreadBeforeUserMessage(options.messages, options.userMessageId);
 
-    return [
+    const threadMessages = [
         ...createInitialUserChatRunnerThreadMessages({
             isFirstUserTurn: previousThreadMessages.length === 0,
             resolveInitialAgentMessage: options.resolveInitialAgentMessage,
         }),
         ...previousThreadMessages,
         userMessage,
-    ]
-        .filter(isUserChatRunnerThreadMessage)
-        .map((message) => ({
-            sender: message.sender,
-            content: message.content,
-        }));
+    ].filter(isUserChatRunnerThreadMessage);
+
+    return await Promise.all(threadMessages.map(createUserChatRunnerThreadMessage));
 }
 
 /**
@@ -176,3 +175,34 @@ function isUserChatRunnerThreadMessage(message: ChatMessage): message is ChatMes
     const isRunnerSender = message.sender === 'USER' || message.sender === 'AGENT';
     return message.isComplete !== false && isRunnerSender;
 }
+
+/**
+ * Creates one runner-visible message with attachment context inlined into user-authored content.
+ *
+ * @private helper of `createUserChatRunnerThreadMessages`
+ */
+async function createUserChatRunnerThreadMessage(
+    message: ChatMessage & UserChatRunnerThreadMessage,
+): Promise<UserChatRunnerThreadMessage> {
+    return {
+        sender: message.sender,
+        content: await createUserChatRunnerThreadMessageContent(message),
+    };
+}
+
+/**
+ * Adds attachment URLs and best-effort text previews to user messages mirrored into runner `.book` files.
+ *
+ * @private helper of `createUserChatRunnerThreadMessage`
+ */
+async function createUserChatRunnerThreadMessageContent(
+    message: ChatMessage & UserChatRunnerThreadMessage,
+): Promise<string> {
+    if (message.sender !== 'USER' || !message.attachments || message.attachments.length === 0) {
+        return message.content;
+    }
+
+    return await appendChatAttachmentContextWithContent(message.content, message.attachments, {
+        allowLocalhost: true,
+    });
+}

package/apps/agents-server/tests/e2e/support/ChatHistoryNavigationSupport.ts

@@ -212,6 +212,7 @@ async function delayNextMatchingRequest(
     options: DelayNextMatchingRequestOptions,
 ): Promise<DelayedRequestControl> {
     let hasInterceptedTargetRequest = false;
+    let isReleased = false;
     let releaseRequest: (() => void) | null = null;
     let markStarted: (() => void) | null = null;
     let markFinished: (() => void) | null = null;
@@ -239,6 +240,9 @@ async function delayNextMatchingRequest(
 
         await new Promise<void>((resolve) => {
             releaseRequest = resolve;
+            if (isReleased) {
+                resolve();
+            }
         });
 
         try {
@@ -255,6 +259,7 @@ async function delayNextMatchingRequest(
         waitUntilStarted,
         waitUntilFinished,
         release() {
+            isReleased = true;
             releaseRequest?.();
         },
         async dispose() {