@promptbook/cli 0.114.0-2 → 0.114.0-21

package/apps/agents-server/src/utils/plannedMessageManager/updateManagedPlannedMessage.ts

@@ -0,0 +1,121 @@
+import { AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS } from '../agentGoalChat/agentGoalChatPlannedMessageActions';
+import type { PlannedMessageManagerRecord } from '../plannedMessagesAdmin';
+import { getUserChatTimeoutById, setAgentScopedUserChatTimeoutPausedState } from '../userChatTimeout';
+import { loadPlannedMessageManagerRecord } from './loadPlannedMessageManagerRecord';
+
+/**
+ * Change requested for one planned message, as it arrives from an administrator.
+ *
+ * Every schedule field is untrusted and validated by the shared planned-message service, exactly the
+ * same way a schedule requested by an agent is. Only `isPaused` is checked before it gets here,
+ * because no later step would check it.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type UpdateManagedPlannedMessageRequest = {
+    readonly message?: unknown;
+    readonly milliseconds?: unknown;
+    readonly cronExpression?: unknown;
+    readonly startsAt?: unknown;
+    readonly endsAt?: unknown;
+    readonly maxRunCount?: unknown;
+    readonly isPaused?: boolean;
+};
+
+/**
+ * Outcome of one administrator change to a planned message.
+ *
+ * `busy` means the planned message is firing right now, so its schedule is being consumed by that
+ * very firing and cannot be rewritten underneath it.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type UpdateManagedPlannedMessageResult =
+    | { readonly status: 'updated'; readonly plannedMessage: PlannedMessageManagerRecord }
+    | { readonly status: 'not_found' }
+    | { readonly status: 'busy' };
+
+/**
+ * Applies one administrator change to a planned message of any agent.
+ *
+ * The change goes through the very same planned-message service an agent re-plans itself with, so an
+ * administrator can never write a schedule the agent itself could not have written.
+ *
+ * @param timeoutId - Id of the planned message being changed.
+ * @param payload - Requested change, where an absent field keeps its stored value.
+ * @returns Changed planned message, or why it could not be changed.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function updateManagedPlannedMessage(
+    timeoutId: string,
+    payload: UpdateManagedPlannedMessageRequest,
+): Promise<UpdateManagedPlannedMessageResult> {
+    const existingPlannedMessage = await getUserChatTimeoutById(timeoutId);
+
+    if (!existingPlannedMessage) {
+        return { status: 'not_found' };
+    }
+
+    const { agentPermanentId } = existingPlannedMessage;
+
+    if (isPlannedMessageScheduleChangeRequested(payload)) {
+        const updateResult = await AGENT_GOAL_CHAT_PLANNED_MESSAGE_ACTIONS.update({
+            agentPermanentId,
+            timeoutId,
+            ...(payload.message === undefined ? {} : { message: payload.message }),
+            ...(payload.milliseconds === undefined ? {} : { milliseconds: payload.milliseconds }),
+            ...(payload.cronExpression === undefined ? {} : { cronExpression: payload.cronExpression }),
+            ...(payload.startsAt === undefined ? {} : { startsAt: payload.startsAt }),
+            ...(payload.endsAt === undefined ? {} : { endsAt: payload.endsAt }),
+            ...(payload.maxRunCount === undefined ? {} : { maxRunCount: payload.maxRunCount }),
+        });
+
+        if (updateResult.status === 'not_found') {
+            return { status: 'not_found' };
+        }
+
+        if (updateResult.status === 'busy') {
+            return { status: 'busy' };
+        }
+    }
+
+    if (payload.isPaused !== undefined) {
+        const pauseResult = await setAgentScopedUserChatTimeoutPausedState({
+            agentPermanentId,
+            timeoutId,
+            isPaused: payload.isPaused,
+        });
+
+        if (!pauseResult.isApplied) {
+            return pauseResult.plannedMessage === null ? { status: 'not_found' } : { status: 'busy' };
+        }
+    }
+
+    const changedPlannedMessage = await loadPlannedMessageManagerRecord(timeoutId);
+
+    if (!changedPlannedMessage) {
+        return { status: 'not_found' };
+    }
+
+    return { status: 'updated', plannedMessage: changedPlannedMessage };
+}
+
+/**
+ * Determines whether one requested change touches the schedule or the text of a planned message.
+ *
+ * @param payload - Requested change.
+ * @returns `true` when anything but the paused state was requested.
+ *
+ * @private function of `updateManagedPlannedMessage`
+ */
+function isPlannedMessageScheduleChangeRequested(payload: UpdateManagedPlannedMessageRequest): boolean {
+    return (
+        payload.message !== undefined ||
+        payload.milliseconds !== undefined ||
+        payload.cronExpression !== undefined ||
+        payload.startsAt !== undefined ||
+        payload.endsAt !== undefined ||
+        payload.maxRunCount !== undefined
+    );
+}

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

@@ -0,0 +1,200 @@
+import type { PlannedMessageEndReason } from './plannedMessageManager/resolvePlannedMessageEndReason';
+import type { PlannedMessageLifecycle } from './plannedMessageManager/resolvePlannedMessageLifecycle';
+import type { PlannedMessageRecurrenceKind } from './plannedMessageManager/resolvePlannedMessageRecurrenceKind';
+import type { UserChatTimeoutStatus } from './userChatTimeout/UserChatTimeoutRecord';
+
+/**
+ * One planned message (durable chat timeout) as shown in the admin planned-message manager.
+ *
+ * This is the whole planned message, not the queue view of it the task manager shows: it carries the
+ * schedule the agent planned, where that plan stands now, and who it belongs to.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerRecord = {
+    timeoutId: string;
+    status: UserChatTimeoutStatus;
+    lifecycle: PlannedMessageLifecycle;
+    recurrenceKind: PlannedMessageRecurrenceKind;
+    endReason: PlannedMessageEndReason;
+    message: string | null;
+
+    createdAt: string;
+    updatedAt: string;
+    dueAt: string;
+    startsAt: string | null;
+    endsAt: string | null;
+    lastFiredAt: string | null;
+    completedAt: string | null;
+    cancelRequestedAt: string | null;
+    pausedAt: string | null;
+
+    recurrenceIntervalMs: number | null;
+    cronExpression: string | null;
+    maxRunCount: number | null;
+    runCount: number;
+    attemptCount: number;
+    failureReason: string | null;
+
+    userId: number;
+    username: string | null;
+    agentPermanentId: string;
+    agentName: string | null;
+    chatId: string;
+
+    /**
+     * True when the planned message lives in the agent's own goal chat, which is where an agent plans
+     * its own work.
+     */
+    isAgentGoalChat: boolean;
+};
+
+/**
+ * Full payload returned by the admin planned-message listing endpoint.
+ *
+ * The whole bounded set is returned at once, so filtering, sorting, and counting all see the same
+ * rows and can never disagree with each other.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerListResponse = {
+    items: Array<PlannedMessageManagerRecord>;
+    generatedAt: string;
+
+    /**
+     * True when more planned messages exist than the endpoint is willing to return at once.
+     */
+    hasMore: boolean;
+};
+
+/**
+ * Stage filter offered by the planned-message manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerView =
+    | 'active'
+    | 'scheduled'
+    | 'not-started'
+    | 'ongoing'
+    | 'paused'
+    | 'finished'
+    | 'all';
+
+/**
+ * Recurrence (frequency) filter offered by the planned-message manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerRecurrenceFilter = 'all' | PlannedMessageRecurrenceKind;
+
+/**
+ * Last-run filter offered by the planned-message manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerLastRunFilter = 'all' | 'never' | 'hour' | 'day' | 'week' | 'older';
+
+/**
+ * Sortable planned-message manager columns.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerSortField =
+    | 'plannedMessage'
+    | 'agent'
+    | 'frequency'
+    | 'nextRun'
+    | 'lastRun'
+    | 'runs'
+    | 'state';
+
+/**
+ * Change requested for one planned message by an administrator.
+ *
+ * Leaving a field out keeps it as it is and passing `null` removes the bound, exactly like the
+ * re-planning an agent can do itself.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type PlannedMessageManagerUpdatePayload = {
+    message?: string;
+    milliseconds?: number | null;
+    cronExpression?: string | null;
+    startsAt?: string | null;
+    endsAt?: string | null;
+    maxRunCount?: number | null;
+
+    /**
+     * Whether the planned message should be held back from waking its agent.
+     */
+    isPaused?: boolean;
+};
+
+/**
+ * Route of the admin planned-message manager API.
+ *
+ * @private internal admin utility of Agents Server
+ */
+const ADMIN_PLANNED_MESSAGES_API_PATH = '/api/admin/planned-messages';
+
+/**
+ * Fetches every planned message of this server for the admin manager.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $fetchAdminPlannedMessages(): Promise<PlannedMessageManagerListResponse> {
+    const response = await fetch(ADMIN_PLANNED_MESSAGES_API_PATH, { method: 'GET' });
+
+    if (!response.ok) {
+        const payload = await response.json().catch(() => ({}));
+        throw new Error(payload.error || 'Failed to load planned messages.');
+    }
+
+    return (await response.json()) as PlannedMessageManagerListResponse;
+}
+
+/**
+ * Applies one administrator change to a planned message.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $updateAdminPlannedMessage(
+    timeoutId: string,
+    payload: PlannedMessageManagerUpdatePayload,
+): Promise<PlannedMessageManagerRecord> {
+    const response = await fetch(`${ADMIN_PLANNED_MESSAGES_API_PATH}/${encodeURIComponent(timeoutId)}`, {
+        method: 'PATCH',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(payload),
+    });
+
+    const data = (await response.json().catch(() => ({}))) as {
+        plannedMessage?: PlannedMessageManagerRecord;
+        error?: string;
+    };
+
+    if (!response.ok || !data.plannedMessage) {
+        throw new Error(data.error || 'Failed to update the planned message.');
+    }
+
+    return data.plannedMessage;
+}
+
+/**
+ * Cancels one planned message so it never wakes its agent again.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export async function $cancelAdminPlannedMessage(timeoutId: string): Promise<void> {
+    const response = await fetch(`${ADMIN_PLANNED_MESSAGES_API_PATH}/${encodeURIComponent(timeoutId)}`, {
+        method: 'DELETE',
+    });
+
+    if (!response.ok) {
+        const payload = await response.json().catch(() => ({}));
+        throw new Error(payload.error || 'Failed to cancel the planned message.');
+    }
+}

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

@@ -4,7 +4,6 @@ import { padBook } from '../../../../src/book-2.0/agent-source/padBook';
 import { isVoidPseudoAgentReference } from '../../../../src/book-2.0/agent-source/pseudoAgentReferences';
 import { validateBook } from '../../../../src/book-2.0/agent-source/string_book';
 import { ParseError } from '../../../../src/errors/ParseError';
-import { UnexpectedError } from '../../../../src/errors/UnexpectedError';
 import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
 import { isValidAgentUrl } from '../../../../src/utils/validators/url/isValidAgentUrl';
 import {
@@ -15,6 +14,7 @@ import {
     type AgentReferenceResolutionIssue,
     consumeAgentReferenceResolutionIssues,
 } from './agentReferenceResolver/AgentReferenceResolutionIssue';
+import { collectExplicitFromCommitments, getExplicitFromCommitmentContent } from './explicitFromCommitment';
 import { type ImportAgentOptions } from './importAgent';
 import { importAgentWithFallback } from './importAgentWithFallback';
 
@@ -103,57 +103,6 @@ function insertNotesAfterTitle(agentSource: string_book, notes: ReadonlyArray<st
     return padBook(validateBook(nextLines.join('\n')));
 }
 
-/**
- * Returns the last explicit single-line commitment content for one commitment type.
- *
- * This lightweight parser is intentionally limited to the subset needed by
- * inheritance resolution so it stays safe to bundle into the Next.js proxy path.
- *
- * @param agentSource - Raw book source.
- * @param commitmentType - Commitment keyword to search for.
- * @returns Trimmed commitment content, empty string for a blank explicit commitment, or `undefined` when absent.
- */
-function getLastSingleLineCommitmentContent(agentSource: string_book, commitmentType: 'FROM'): string | undefined {
-    const commitmentPrefix = `${commitmentType} `;
-    const lines = agentSource.split(/\r?\n/);
-    let hasSeenTitle = false;
-    let isInsideCodeBlock = false;
-    let matchedContent: string | undefined;
-
-    for (const line of lines) {
-        const trimmedLine = line.trim();
-
-        if (!hasSeenTitle) {
-            if (!trimmedLine) {
-                continue;
-            }
-
-            hasSeenTitle = true;
-            continue;
-        }
-
-        if (trimmedLine.startsWith('```')) {
-            isInsideCodeBlock = !isInsideCodeBlock;
-            continue;
-        }
-
-        if (isInsideCodeBlock) {
-            continue;
-        }
-
-        if (trimmedLine === commitmentType) {
-            matchedContent = '';
-            continue;
-        }
-
-        if (trimmedLine.startsWith(commitmentPrefix)) {
-            matchedContent = trimmedLine.slice(commitmentPrefix.length).trim();
-        }
-    }
-
-    return matchedContent;
-}
-
 /**
  * Resolves the effective `FROM` parent URL using only lightweight commitment parsing.
  *
@@ -165,7 +114,7 @@ async function resolveParentAgentUrlFromCommitments(
     rawAgentSource: string_book,
     agentReferenceResolver?: AgentReferenceResolver,
 ): Promise<string_agent_url | null | undefined> {
-    const explicitFromContent = getLastSingleLineCommitmentContent(rawAgentSource, 'FROM');
+    const explicitFromContent = getExplicitFromCommitmentContent(rawAgentSource);
 
     if (explicitFromContent === undefined) {
         return undefined;
@@ -285,6 +234,11 @@ type ResolvedParentAgentContext = {
      * Unresolved compact-reference issues captured while resolving `FROM`.
      */
     readonly fromResolutionIssues: Array<AgentReferenceResolutionIssue>;
+
+    /**
+     * Whether the effective parent closed the current lineage and must be materialized as `FROM @Null`.
+     */
+    readonly isCyclicFrom: boolean;
 };
 
 /**
@@ -357,6 +311,28 @@ type ResolvedFromCommitmentLine = {
     readonly fromResolutionIssues: Array<AgentReferenceResolutionIssue>;
 };
 
+/**
+ * One cycle found while following a source-resolution lineage.
+ *
+ * @private internal helper for Agents Server inherited/imported agent resolution
+ */
+type ResolutionCycle = {
+    /**
+     * Normalized URL that closes the cycle.
+     */
+    readonly normalizedReferenceUrl: string_agent_url;
+
+    /**
+     * URLs visited before the repeated reference was encountered.
+     */
+    readonly lineage: ReadonlyArray<string_agent_url>;
+
+    /**
+     * Position in `lineage` where the cycle begins.
+     */
+    readonly cycleStartIndex: number;
+};
+
 /**
  * Normalizes agent URLs used for cycle detection and lineage reporting.
  *
@@ -387,6 +363,30 @@ function createResolutionLineage(options?: ResolveInheritedAgentSourceOptions):
     return [...new Set(lineage.map(normalizeAgentUrl))];
 }
 
+/**
+ * Finds a cycle that would be closed by resolving one more agent reference.
+ *
+ * @param referenceUrl - Next agent reference to resolve.
+ * @param options - Current resolution options.
+ * @returns Cycle details, or `null` when the reference is not in the current lineage.
+ *
+ * @private internal helper for Agents Server inherited/imported agent resolution
+ */
+function findResolutionCycle(
+    referenceUrl: string_agent_url,
+    options?: ResolveInheritedAgentSourceOptions,
+): ResolutionCycle | null {
+    const normalizedReferenceUrl = normalizeAgentUrl(referenceUrl);
+    const lineage = createResolutionLineage(options);
+    const cycleStartIndex = lineage.findIndex((visitedUrl) => visitedUrl === normalizedReferenceUrl);
+
+    if (cycleStartIndex === -1) {
+        return null;
+    }
+
+    return { normalizedReferenceUrl, lineage, cycleStartIndex };
+}
+
 /**
  * Creates the shared import context used throughout one resolution pass.
  *
@@ -415,6 +415,7 @@ function createAgentImportContext(options?: ResolveInheritedAgentSourceOptions):
  * @param hasExplicitFromCommitment - Whether the source explicitly declared `FROM`.
  * @param adamAgentUrl - Default Adam ancestor URL.
  * @param currentAgentUrl - Canonical URL of the source being resolved.
+ * @param currentAgentAliases - Additional URLs that identify the source being resolved.
  * @param agentSource - Raw source used for unexpected diagnostics.
  * @returns Effective parent URL or `null` when inheritance is disabled.
  */
@@ -423,6 +424,7 @@ function determineParentAgentUrl(
     hasExplicitFromCommitment: boolean,
     adamAgentUrl: string_agent_url,
     currentAgentUrl?: string_agent_url,
+    currentAgentAliases?: ReadonlyArray<string_agent_url>,
     agentSource?: string_book,
 ): string_agent_url | null {
     if (isValidAgentUrl(resolvedParentAgentUrl)) {
@@ -434,9 +436,14 @@ function determineParentAgentUrl(
     }
 
     if (resolvedParentAgentUrl === undefined || resolvedParentAgentUrl === null) {
-        return currentAgentUrl && normalizeAgentUrl(currentAgentUrl) === normalizeAgentUrl(adamAgentUrl)
-            ? null
-            : adamAgentUrl;
+        const currentAgentUrls = [currentAgentUrl, ...(currentAgentAliases || [])].filter(
+            (agentUrl): agentUrl is string_agent_url => Boolean(agentUrl),
+        );
+        const isCurrentAgentAdam = currentAgentUrls.some(
+            (agentUrl) => normalizeAgentUrl(agentUrl) === normalizeAgentUrl(adamAgentUrl),
+        );
+
+        return isCurrentAgentAdam ? null : adamAgentUrl;
     }
 
     throw new ParseError(
@@ -496,7 +503,7 @@ async function resolveParentAgentContext(
     agentSource: string_book,
     context: AgentImportContext,
 ): Promise<ResolvedParentAgentContext> {
-    const explicitFromContent = getLastSingleLineCommitmentContent(agentSource, 'FROM');
+    const explicitFromContent = getExplicitFromCommitmentContent(agentSource);
     const hasExplicitFromCommitment = explicitFromContent !== undefined;
     const resolvedParentAgentUrl = await resolveParentAgentUrlFromCommitments(
         agentSource,
@@ -510,14 +517,21 @@ async function resolveParentAgentContext(
         hasExplicitFromCommitment,
         context.adamAgentUrl,
         context.resolutionOptions?.currentAgentUrl,
+        context.resolutionOptions?.currentAgentAliases,
         agentSource,
     );
-    const parentAgentSourceCorpus = parentAgentUrl ? await importAgentCorpus(parentAgentUrl, 'FROM', context) : null;
+    const isCyclicFrom = Boolean(parentAgentUrl && findResolutionCycle(parentAgentUrl, context.resolutionOptions));
+    const effectiveParentAgentUrl = isCyclicFrom ? null : parentAgentUrl;
+    const parentAgentSourceCorpus = effectiveParentAgentUrl
+        ? await importAgentCorpus(effectiveParentAgentUrl, 'FROM', context)
+        : null;
 
     return {
-        parentAgentUrl,
+        // A parent that closes the current lineage has the same runtime effect as `FROM @Null`.
+        parentAgentUrl: effectiveParentAgentUrl,
         parentAgentSourceCorpus,
         fromResolutionIssues,
+        isCyclicFrom,
     };
 }
 
@@ -591,36 +605,18 @@ async function resolveImportCommitmentLine(line: string, context: AgentImportCon
 }
 
 /**
- * Resolves one explicit `FROM ...` line into inherited content or fallback NOTE lines.
+ * Resolves the effective `FROM ...` line into inherited content or fallback NOTE lines.
  *
  * @param line - Current source line.
- * @param agentSource - Full source used for duplicate-`FROM` diagnostics.
- * @param isFromResolved - Whether a previous `FROM ...` line was already handled.
  * @param parentContext - Effective parent state computed earlier in the resolution.
  * @returns Output lines and remaining `FROM` issues.
  */
 function resolveFromCommitmentLine(
     line: string,
-    agentSource: string_book,
-    isFromResolved: boolean,
     parentContext: ResolvedParentAgentContext,
 ): ResolvedFromCommitmentLine {
-    if (isFromResolved) {
-        throw new UnexpectedError(
-            spaceTrim(
-                (block) => `
-                    Multiple \`FROM\` commitments found in agent source:
-
-                    \`\`\`book
-                    ${block(agentSource)}
-                    \`\`\`
-                `,
-            ),
-        );
-    }
-
     if (parentContext.parentAgentUrl === null) {
-        const agentSourceChunks = [line];
+        const agentSourceChunks = [parentContext.isCyclicFrom ? 'FROM @Null' : line];
 
         if (parentContext.fromResolutionIssues.length > 0) {
             appendResolutionIssueNotes(agentSourceChunks, parentContext.fromResolutionIssues);
@@ -654,6 +650,23 @@ function resolveFromCommitmentLine(
     };
 }
 
+/**
+ * Finds the `FROM` lines that a later `FROM` takes precedence over.
+ *
+ * A book is allowed to repeat `FROM`; the last one wins, so every earlier one is dropped instead of being resolved.
+ * The Book editor warns about this while the author is still writing the book.
+ *
+ * @param explicitFromCommitments - Explicit parent declarations found in source order.
+ * @returns Zero-based indexes of every overridden `FROM` line, empty when at most one `FROM` is present.
+ */
+function collectOverriddenFromLineIndexes(
+    explicitFromCommitments: ReadonlyArray<{ readonly lineIndex: number }>,
+): ReadonlySet<number> {
+    return new Set(
+        explicitFromCommitments.slice(0, -1).map((explicitFromCommitment) => explicitFromCommitment.lineIndex),
+    );
+}
+
 /**
  * Rewrites the source body line by line while delegating each branching step to a focused helper.
  *
@@ -669,26 +682,31 @@ async function resolveAgentSourceBuild(
 ): Promise<ResolvedAgentSourceBuild> {
     const agentSourceChunks = spaceTrim(agentSource).split(/\r?\n/);
     const resolvedAgentSourceChunks: Array<string> = [];
+    const explicitFromCommitments = collectExplicitFromCommitments(agentSourceChunks);
+    const effectiveFromCommitment = explicitFromCommitments[explicitFromCommitments.length - 1];
+    const overriddenFromLineIndexes = collectOverriddenFromLineIndexes(explicitFromCommitments);
     let isFromResolved = false;
     let fromResolutionIssues = parentContext.fromResolutionIssues;
     // <- TODO: [🈲] Simple and encapsulated way to split book into commitments
 
-    for (const line of agentSourceChunks) {
+    for (let lineIndex = 0; lineIndex < agentSourceChunks.length; lineIndex++) {
+        const line = agentSourceChunks[lineIndex] || '';
+
+        // Note: A repeated `FROM` is overridden by the last one, so the outdated line is dropped from the resolved source.
+        if (overriddenFromLineIndexes.has(lineIndex)) {
+            continue;
+        }
+
         if (line.trim().startsWith('IMPORT ')) {
             resolvedAgentSourceChunks.push(...(await resolveImportCommitmentLine(line, context)));
             continue;
         }
 
-        if (line.trim().startsWith('FROM ')) {
-            const resolvedFromCommitment = resolveFromCommitmentLine(
-                line,
-                agentSource,
-                isFromResolved,
-                {
-                    ...parentContext,
-                    fromResolutionIssues,
-                },
-            );
+        if (effectiveFromCommitment?.lineIndex === lineIndex) {
+            const resolvedFromCommitment = resolveFromCommitmentLine(line, {
+                ...parentContext,
+                fromResolutionIssues,
+            });
 
             resolvedAgentSourceChunks.push(...resolvedFromCommitment.agentSourceChunks);
             fromResolutionIssues = resolvedFromCommitment.fromResolutionIssues;
@@ -779,15 +797,16 @@ function assertNoResolutionCycle(
     commitmentType: 'FROM' | 'IMPORT',
     options?: ResolveInheritedAgentSourceOptions,
 ): void {
-    const normalizedReferenceUrl = normalizeAgentUrl(referenceUrl);
-    const lineage = createResolutionLineage(options);
-    const cycleStartIndex = lineage.findIndex((visitedUrl) => visitedUrl === normalizedReferenceUrl);
+    const resolutionCycle = findResolutionCycle(referenceUrl, options);
 
-    if (cycleStartIndex === -1) {
+    if (!resolutionCycle) {
         return;
     }
 
-    const cycleChain = [...lineage.slice(cycleStartIndex), normalizedReferenceUrl]
+    const cycleChain = [
+        ...resolutionCycle.lineage.slice(resolutionCycle.cycleStartIndex),
+        resolutionCycle.normalizedReferenceUrl,
+    ]
         .map((visitedUrl) => `- \`${visitedUrl}\``)
         .join('\n');
 

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

@@ -4,7 +4,7 @@ import {
 } from './userWallet';
 
 /**
- * Resolves SMTP credential payload for USE EMAIL from wallet records.
+ * Resolves SMTP credential payload for agent email from wallet records.
  */
 export async function resolveUseEmailSmtpCredential(
     options: ResolveUseEmailSmtpCredentialOptions,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/insertManagedServerRegistryRow.ts

@@ -22,11 +22,11 @@ export async function insertManagedServerRegistryRow(
     sqlRecorder: SqlRecorder,
 ): Promise<ServerRecord> {
     const insertRegistryResult = await client.query<Record<string, unknown>>(
-        `
+        spaceTrim(`
             INSERT INTO "${SERVER_REGISTRY_TABLE_NAME}" ("name", "environment", "domain", "tablePrefix")
             VALUES ($1, $2, $3, $4)
             RETURNING "id", "name", "environment", "domain", "tablePrefix", "createdAt", "updatedAt"
-        `,
+        `),
         [input.name, input.environment, input.domain, input.tablePrefix],
     );