@promptbook/cli 0.114.0-4 → 0.114.0-6

package/apps/agents-server/src/app/admin/email-server/page.tsx

@@ -4,11 +4,12 @@ import { ForbiddenPage } from '../../../components/ForbiddenPage/ForbiddenPage';
 import { StalwartSynchronizeButton } from '../../../components/StalwartSynchronizeButton/StalwartSynchronizeButton';
 import { $provideServer } from '../../../tools/$provideServer';
 import { isUserAdmin } from '../../../utils/isUserAdmin';
-import { createEmailDnsInstructions } from '../../../utils/stalwart/createEmailDnsInstructions';
+import { createEmailDnsRecordsSection } from '../../../utils/stalwart/createEmailDnsRecordsSection';
 import {
     isStalwartEmailSnapshotOperational,
     readStalwartEmailSnapshot,
 } from '../../../utils/stalwart/readStalwartEmailSnapshot';
+import { isManagedServerDnsDiagnosticIssue } from '../../superadmin/servers/ServersRegistryDnsTypes';
 import { AdminConfigurationShell } from '../_components/AdminConfigurationShell';
 import { $synchronizeStalwartEmailDomain } from './actions';
 
@@ -27,7 +28,12 @@ export default async function AdminEmailServerPage() {
 
     const server = await $provideServer();
     const snapshot = await readStalwartEmailSnapshot(server.publicUrl.hostname);
-    const dnsInstructions = createEmailDnsInstructions(snapshot.domain, snapshot.mailDnsDiagnostic.publicIpAddress);
+    const emailDnsRecordsSection = createEmailDnsRecordsSection({
+        domain: snapshot.domain,
+        publicIpAddress: snapshot.mailDnsDiagnostic.publicIpAddress,
+        statusSummary: snapshot.mailDnsDiagnostic.summary,
+        isDnsIssue: isManagedServerDnsDiagnosticIssue(snapshot.mailDnsDiagnostic),
+    });
     const isOperational = isStalwartEmailSnapshotOperational(snapshot);
 
     return (
@@ -111,21 +117,14 @@ export default async function AdminEmailServerPage() {
                     <div className="mt-4">
                         <DnsRecordsInstructions
                             description={
-                                snapshot.mailDnsDiagnostic.publicIpAddress ? (
-                                    <p>
-                                        Add these records at your DNS provider. The A records below use this VPS’s
-                                        detected public address.
-                                    </p>
-                                ) : (
-                                    <p>
-                                        Add these records at your DNS provider. Replace <code>&lt;VPS_PUBLIC_IP&gt;</code>{' '}
-                                        with the public address of this VPS.
-                                    </p>
-                                )
+                                <p>
+                                    Add these records at your DNS provider. The complete DNS setup of this server -
+                                    including its own domain and its generated project domains - is configured together
+                                    on the Super Admin <span className="font-mono">/superadmin/servers</span> page.
+                                </p>
                             }
                             domain={snapshot.domain}
-                            recordSelection="all"
-                            records={dnsInstructions}
+                            sections={[emailDnsRecordsSection]}
                         />
                     </div>
                     <div className="mt-4 space-y-2 rounded-lg bg-blue-50 p-4 text-sm text-blue-950">
@@ -148,9 +147,9 @@ export default async function AdminEmailServerPage() {
                             that hostname.
                         </p>
                         <p>
-                            Open TCP port <code>25</code> publicly. Keep the submission port <code>465</code>{' '}
-                            firewalled unless external mail clients need it, and never expose the Stalwart management
-                            API on port <code>8080</code>.
+                            Open TCP port <code>25</code> publicly. Keep the submission port <code>465</code> firewalled
+                            unless external mail clients need it, and never expose the Stalwart management API on port{' '}
+                            <code>8080</code>.
                         </p>
                     </div>
                     <pre className="mt-4 overflow-auto whitespace-pre-wrap rounded-lg bg-gray-950 p-4 text-xs text-gray-100">

package/apps/agents-server/src/app/admin/task-manager/TaskManagerTaskRow.tsx

@@ -13,6 +13,7 @@ import {
     buildTaskRunReportRows,
     formatTaskDateTime,
     formatTaskDuration,
+    AgentGoalTaskBadge,
     formatTaskKind,
     getTaskQueueAgeMs,
     getTaskRuntimeDurationMs,
@@ -175,6 +176,7 @@ export function TaskManagerTaskRow({
                     <span className="rounded-full border border-gray-200 bg-gray-50 px-2 py-0.5 font-medium text-gray-600">
                         {formatTaskKind(task.kind)}
                     </span>
+                    <AgentGoalTaskBadge task={task} />
                 </div>
                 <div className="mt-2 space-y-1 text-[11px] text-gray-500">
                     <div>

package/apps/agents-server/src/app/admin/task-manager/[taskId]/TaskManagerTaskDetailClient.tsx

@@ -21,6 +21,7 @@ import {
     buildTaskRunReportRows,
     formatTaskDateTime,
     formatTaskDuration,
+    AgentGoalTaskBadge,
     formatTaskKind,
     getTaskQueueAgeMs,
     getTaskRuntimeDurationMs,
@@ -217,6 +218,7 @@ export function TaskManagerTaskDetailClient({ taskId, isSuperAdmin, serverDomain
                             <span className="rounded-full border border-gray-200 bg-gray-50 px-2 py-0.5 text-[11px] font-medium text-gray-600">
                                 {formatTaskKind(task.kind)}
                             </span>
+                            <AgentGoalTaskBadge task={task} />
                             {task.cancelRequestedAt ? (
                                 <span className="text-[11px] font-medium text-orange-700">Cancellation requested</span>
                             ) : null}

package/apps/agents-server/src/app/admin/task-manager/taskManagerTaskPresentation.tsx

@@ -96,6 +96,29 @@ export function TaskStatusBadge({ isStuck, task }: TaskStatusBadgeProps) {
     return <span className={`rounded-full border px-2 py-0.5 text-[11px] font-semibold ${tone}`}>{label}</span>;
 }
 
+/**
+ * Compact badge marking the tasks an agent started for itself in its goal chat.
+ *
+ * Goal-chat tasks keep their normal kind, so this badge is what separates them from the
+ * user-invoked tasks in every task-manager surface.
+ *
+ * @private shared presentation of the admin task manager
+ */
+export function AgentGoalTaskBadge({ task }: { task: AdminChatTaskRecord }) {
+    if (!task.isAgentGoalTask) {
+        return null;
+    }
+
+    return (
+        <span
+            className="rounded-full border border-indigo-200 bg-indigo-50 px-2 py-0.5 text-[11px] font-semibold text-indigo-700"
+            title="Started by the agent itself in its goal chat, not by a user"
+        >
+            Goal chat
+        </span>
+    );
+}
+
 /**
  * Formats a durable task kind for display.
  *

package/apps/agents-server/src/app/agents/[agentName]/api/book/route.ts

@@ -1,4 +1,6 @@
 import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
+import { $provideServer } from '@/src/tools/$provideServer';
+import { scheduleAgentGoalChatModifiedNote } from '@/src/utils/agentGoalChat';
 import { $provideAgentReferenceResolver } from '@/src/utils/agentReferenceResolver/$provideAgentReferenceResolver';
 import { invalidateCachedActiveOrganizationSnapshots } from '@/src/utils/agentOrganization/loadAgentOrganizationState';
 import {
@@ -185,6 +187,11 @@ export async function PUT(request: Request, { params }: { params: Promise<{ agen
 
         const agentId = await collection.getAgentPermanentId(agentName);
         await collection.updateAgentSource(agentId, agentSource, { versionName });
+        scheduleAgentGoalChatModifiedNote({
+            agentPermanentId: agentId,
+            agentName,
+            server: await $provideServer(),
+        });
         invalidateCachedActiveOrganizationSnapshots();
         // <- TODO: [🐱‍🚀] Properly type as string_book
 

package/apps/agents-server/src/app/agents/[agentName]/api/timeouts/[timeoutId]/route.ts

@@ -1,18 +1,12 @@
 import { NextResponse } from 'next/server';
 import { isPrivateModeEnabledFromRequest } from '@/src/utils/privateMode';
-import {
-    cancelScheduledUserChatTimeout,
-    getAgentScopedUserChatTimeout,
-    notifyUserChatTimeoutScheduleChanged,
-    updateAgentScopedUserChatTimeout,
-} from '@/src/utils/userChatTimeout';
-import type { UpdateAgentScopedUserChatTimeoutPatch } from '@/src/utils/userChatTimeout';
+import { cancelScheduledUserChatTimeout, getAgentScopedUserChatTimeout } from '@/src/utils/userChatTimeout';
 import { resolveUserChatScope } from '../../user-chats/resolveUserChatScope';
 
 /**
- * Updates one durable timeout owned by current user for one agent.
+ * Cancels one planned message of the agent from its goal chat.
  */
-export async function PATCH(
+export async function DELETE(
     request: Request,
     { params }: { params: Promise<{ agentName: string; timeoutId: string }> },
 ) {
@@ -37,170 +31,33 @@ export async function PATCH(
         return NextResponse.json({ error: 'Agent not found.' }, { status: 404 });
     }
 
-    try {
-        const existingTimeout = await getAgentScopedUserChatTimeout({
-            userId: scopeResult.scope.userId,
-            agentPermanentId: scopeResult.scope.agentPermanentId,
-            timeoutId,
-        });
-
-        if (!existingTimeout) {
-            return NextResponse.json({ error: 'Timeout not found.' }, { status: 404 });
-        }
-
-        if (
-            existingTimeout.status === 'COMPLETED' ||
-            existingTimeout.status === 'FAILED' ||
-            existingTimeout.status === 'CANCELLED'
-        ) {
-            return NextResponse.json({ error: 'Timeout is already finished.' }, { status: 409 });
-        }
-
-        if (existingTimeout.status === 'RUNNING') {
-            return NextResponse.json({ error: 'Running timeout cannot be edited.' }, { status: 409 });
-        }
-
-        const parsedPatch = await parseTimeoutPatchPayload(request);
-        if (!parsedPatch) {
-            return NextResponse.json({ error: 'No valid timeout fields provided.' }, { status: 400 });
-        }
-
-        const updatedTimeout = await updateAgentScopedUserChatTimeout({
-            userId: scopeResult.scope.userId,
-            agentPermanentId: scopeResult.scope.agentPermanentId,
-            timeoutId,
-            patch: parsedPatch,
-        });
-
-        if (!updatedTimeout) {
-            return NextResponse.json({ error: 'Timeout not found.' }, { status: 404 });
-        }
-
-        notifyUserChatTimeoutScheduleChanged(updatedTimeout);
-
-        return NextResponse.json(updatedTimeout);
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to update timeout.' },
-            { status: 400 },
-        );
-    }
-}
-
-/**
- * Cancels one durable timeout owned by current user for one agent.
- */
-export async function DELETE(
-    request: Request,
-    { params }: { params: Promise<{ agentName: string; timeoutId: string }> },
-) {
-    if (isPrivateModeEnabledFromRequest(request)) {
-        return NextResponse.json({ error: 'Private mode is enabled.' }, { status: 403 });
-    }
-
-    const { agentName: rawAgentName, timeoutId: rawTimeoutId } = await params;
-    const agentName = decodeURIComponent(rawAgentName);
-    const timeoutId = decodeURIComponent(rawTimeoutId);
-    const scopeResult = await resolveUserChatScope(agentName);
-
-    if (!scopeResult.ok) {
-        if (scopeResult.error === 'UNAUTHORIZED') {
-            return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-        }
-
-        if (scopeResult.error === 'FORBIDDEN') {
-            return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
-        }
-
-        return NextResponse.json({ error: 'Agent not found.' }, { status: 404 });
+    if (!scopeResult.scope.viewerCanAccessAgentGoalChat) {
+        return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
     }
 
     try {
+        // Note: Planned messages belong to the agent, so the goal chat may cancel them across every
+        //       chat and every user of the agent
         const existingTimeout = await getAgentScopedUserChatTimeout({
-            userId: scopeResult.scope.userId,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             timeoutId,
         });
 
         if (!existingTimeout) {
-            return NextResponse.json({ error: 'Timeout not found.' }, { status: 404 });
+            return NextResponse.json({ error: 'Planned message not found.' }, { status: 404 });
         }
 
         const cancelledTimeout = await cancelScheduledUserChatTimeout(timeoutId);
 
         if (!cancelledTimeout) {
-            return NextResponse.json({ error: 'Timeout not found.' }, { status: 404 });
+            return NextResponse.json({ error: 'Planned message not found.' }, { status: 404 });
         }
 
         return NextResponse.json(cancelledTimeout);
     } catch (error) {
         return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to cancel timeout.' },
+            { error: error instanceof Error ? error.message : 'Failed to cancel the planned message.' },
             { status: 500 },
         );
     }
 }
-
-/**
- * Parses and validates timeout update payload from one request.
- */
-async function parseTimeoutPatchPayload(request: Request): Promise<UpdateAgentScopedUserChatTimeoutPatch | null> {
-    const payload = (await request.json().catch(() => ({}))) as {
-        dueAt?: unknown;
-        recurrenceIntervalMs?: unknown;
-        message?: unknown;
-        parameters?: unknown;
-        paused?: unknown;
-        extendByMs?: unknown;
-    };
-
-    const patch: UpdateAgentScopedUserChatTimeoutPatch = {};
-
-    if (typeof payload.dueAt === 'string' && payload.dueAt.trim().length > 0) {
-        const normalizedDueAt = payload.dueAt.trim();
-        const dueAtTimestamp = Date.parse(normalizedDueAt);
-        if (!Number.isFinite(dueAtTimestamp)) {
-            throw new Error('`dueAt` must be a valid ISO timestamp.');
-        }
-        patch.dueAt = new Date(dueAtTimestamp).toISOString();
-    }
-
-    if (payload.recurrenceIntervalMs === null) {
-        patch.recurrenceIntervalMs = null;
-    } else if (typeof payload.recurrenceIntervalMs === 'number') {
-        if (!Number.isFinite(payload.recurrenceIntervalMs) || payload.recurrenceIntervalMs <= 0) {
-            throw new Error('`recurrenceIntervalMs` must be a positive number of milliseconds or `null`.');
-        }
-        patch.recurrenceIntervalMs = Math.floor(payload.recurrenceIntervalMs);
-    }
-
-    if (payload.message === null) {
-        patch.message = null;
-    } else if (typeof payload.message === 'string') {
-        patch.message = payload.message;
-    }
-
-    if (payload.parameters !== undefined) {
-        if (!payload.parameters || typeof payload.parameters !== 'object' || Array.isArray(payload.parameters)) {
-            throw new Error('`parameters` must be a JSON object.');
-        }
-        patch.parameters = payload.parameters as Record<string, unknown>;
-    }
-
-    if (typeof payload.paused === 'boolean') {
-        patch.pausedAt = payload.paused ? new Date().toISOString() : null;
-    }
-
-    if (typeof payload.extendByMs === 'number') {
-        if (!Number.isFinite(payload.extendByMs) || payload.extendByMs <= 0) {
-            throw new Error('`extendByMs` must be a positive number of milliseconds.');
-        }
-        patch.extendByMs = Math.floor(payload.extendByMs);
-    }
-
-    if (patch.dueAt !== undefined && patch.extendByMs !== undefined) {
-        throw new Error('`dueAt` and `extendByMs` cannot be used together.');
-    }
-
-    return Object.keys(patch).length > 0 ? patch : null;
-}

package/apps/agents-server/src/app/agents/[agentName]/api/timeouts/route.ts

@@ -5,12 +5,12 @@ import type { UserChatTimeoutRecord, UserChatTimeoutStatus } from '@/src/utils/u
 import { resolveUserChatScope } from '../user-chats/resolveUserChatScope';
 
 /**
- * Upper bound for one agent-wide timeout listing response.
+ * Upper bound for one agent-wide planned-message listing response.
  */
 const MAX_AGENT_TIMEOUT_MANAGER_ITEMS = 500;
 
 /**
- * Deterministic status order used in the timeout manager table.
+ * Deterministic status order used in the goal-chat planned-message list.
  */
 const TIMEOUT_STATUS_ORDER: Record<UserChatTimeoutStatus, number> = {
     RUNNING: 0,
@@ -21,7 +21,7 @@ const TIMEOUT_STATUS_ORDER: Record<UserChatTimeoutStatus, number> = {
 };
 
 /**
- * Lists all durable timeouts owned by current user for one agent across chats.
+ * Lists every planned message of one agent, as shown in its goal chat.
  */
 export async function GET(request: Request, { params }: { params: Promise<{ agentName: string }> }) {
     if (isPrivateModeEnabledFromRequest(request)) {
@@ -44,9 +44,14 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
         return NextResponse.json({ error: 'Agent not found.' }, { status: 404 });
     }
 
+    if (!scopeResult.scope.viewerCanAccessAgentGoalChat) {
+        return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+    }
+
     try {
+        // Note: Planned messages belong to the agent, so the goal chat lists them across every chat
+        //       and every user of the agent
         const timeouts = await listAgentUserChatTimeouts({
-            userId: scopeResult.scope.userId,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             limit: MAX_AGENT_TIMEOUT_MANAGER_ITEMS,
         });

package/apps/agents-server/src/app/agents/[agentName]/api/user-chats/[chatId]/route.ts

@@ -41,6 +41,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
             viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
+            viewerCanAccessAgentGoalChat: scopeResult.scope.viewerCanAccessAgentGoalChat,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             chatId,
         });
@@ -86,6 +87,7 @@ export async function PATCH(request: Request, { params }: { params: Promise<{ ag
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
             viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
+            viewerCanAccessAgentGoalChat: scopeResult.scope.viewerCanAccessAgentGoalChat,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             chatId,
         });
@@ -201,6 +203,7 @@ export async function DELETE(request: Request, { params }: { params: Promise<{ a
             userId: scopeResult.scope.userId,
             viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
             viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
+            viewerCanAccessAgentGoalChat: scopeResult.scope.viewerCanAccessAgentGoalChat,
             agentPermanentId: scopeResult.scope.agentPermanentId,
             chatId,
         });

package/apps/agents-server/src/app/agents/[agentName]/api/user-chats/[chatId]/stream/route.ts

@@ -66,6 +66,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
     const chat = await getUserChat({
         userId: scopeResult.scope.userId,
         viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+        viewerCanAccessAgentGoalChat: scopeResult.scope.viewerCanAccessAgentGoalChat,
         agentPermanentId: scopeResult.scope.agentPermanentId,
         chatId,
     });
@@ -133,6 +134,7 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
                 const currentChat = await getUserChat({
                     userId: scopeResult.scope.userId,
                     viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+                    viewerCanAccessAgentGoalChat: scopeResult.scope.viewerCanAccessAgentGoalChat,
                     agentPermanentId: scopeResult.scope.agentPermanentId,
                     chatId,
                 });

package/apps/agents-server/src/app/agents/[agentName]/api/user-chats/resolveUserChatScope.ts

@@ -1,4 +1,5 @@
 import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
+import { canAccessAgentGoalChat } from '@/src/utils/agentGoalChat';
 import { canAccessAgentVisibility, resolveAgentVisibility } from '@/src/utils/agentAccess';
 import { resolveCurrentUserIdentity } from '@/src/utils/currentUserIdentity';
 import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
@@ -15,6 +16,10 @@ export type ResolvedUserChatScope = {
      * who may browse all users' chats in a view-only mode.
      */
     viewerIsSuperAdmin: boolean;
+    /**
+     * True when the viewer may read the agent source book and therefore also the agent goal chat.
+     */
+    viewerCanAccessAgentGoalChat: boolean;
     agentPermanentId: string;
 };
 
@@ -38,9 +43,10 @@ export async function resolveUserChatScope(
 
     try {
         const collection = await $provideAgentCollectionForServer();
-        const [agentPermanentId, viewerIsSuperAdmin] = await Promise.all([
+        const [agentPermanentId, viewerIsSuperAdmin, viewerCanAccessAgentGoalChat] = await Promise.all([
             collection.getAgentPermanentId(agentIdentifier),
             isUserGlobalAdmin(),
+            canAccessAgentGoalChat(),
         ]);
         const visibility = await resolveAgentVisibility(agentPermanentId);
         const isAllowed = canAccessAgentVisibility({
@@ -58,6 +64,7 @@ export async function resolveUserChatScope(
                 userId: currentUserIdentity.userId,
                 viewerIsAdmin: currentUserIdentity.isAdmin,
                 viewerIsSuperAdmin,
+                viewerCanAccessAgentGoalChat,
                 agentPermanentId,
             },
         };

package/apps/agents-server/src/app/agents/[agentName]/api/user-chats/route.ts

@@ -1,3 +1,4 @@
+import { isAgentGoalChatId, prependAgentGoalChatSummarySeed } from '@/src/utils/agentGoalChat';
 import { isPrivateModeEnabledFromRequest } from '@/src/utils/privateMode';
 import {
     createUserChat,
@@ -38,12 +39,16 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
         const requestUrl = new URL(request.url);
         const requestedChatId = normalizeOptionalString(requestUrl.searchParams.get('chat'));
         const showExternalChats = normalizeBooleanFlag(requestUrl.searchParams.get('showExternalChats'));
-        const chatSummarySeeds = await listUserChatSummarySeeds({
-            userId: scopeResult.scope.userId,
-            viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
-            viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
+        const chatSummarySeeds = await prependAgentGoalChatSummarySeed({
+            chatSummarySeeds: await listUserChatSummarySeeds({
+                userId: scopeResult.scope.userId,
+                viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
+                viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
+                agentPermanentId: scopeResult.scope.agentPermanentId,
+                includeExternalChats: showExternalChats,
+            }),
             agentPermanentId: scopeResult.scope.agentPermanentId,
-            includeExternalChats: showExternalChats,
+            isAgentGoalChatVisible: scopeResult.scope.viewerCanAccessAgentGoalChat,
         });
         const activityUserId =
             (scopeResult.scope.viewerIsAdmin || scopeResult.scope.viewerIsSuperAdmin) && showExternalChats
@@ -62,15 +67,18 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
             }),
         ]);
 
+        // Note: The pinned goal chat is opened only on explicit request, never as the default thread
+        const defaultChatSummarySeed =
+            chatSummarySeeds.find((chat) => !isAgentGoalChatId(chat.id)) || chatSummarySeeds[0] || null;
         const activeChatSummarySeed =
             (requestedChatId ? chatSummarySeeds.find((chat) => chat.id === requestedChatId) : null) ||
-            chatSummarySeeds[0] ||
-            null;
+            defaultChatSummarySeed;
         const activeChat = activeChatSummarySeed
             ? await getUserChat({
                   userId: scopeResult.scope.userId,
                   viewerIsAdmin: scopeResult.scope.viewerIsAdmin,
                   viewerIsSuperAdmin: scopeResult.scope.viewerIsSuperAdmin,
+                  viewerCanAccessAgentGoalChat: scopeResult.scope.viewerCanAccessAgentGoalChat,
                   agentPermanentId: scopeResult.scope.agentPermanentId,
                   chatId: activeChatSummarySeed.id,
               })

package/apps/agents-server/src/app/agents/[agentName]/book/useBookEditorSaving.ts

@@ -1,5 +1,6 @@
 import type { string_book } from '@promptbook-local/types';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { debounce } from '@promptbook-local/utils';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { resolveBookEditorApiErrorMessage } from './resolveBookEditorApiErrorMessage';
 
 /**
@@ -82,13 +83,6 @@ export function useBookEditorSaving({ agentName, initialAgentSource }: UseBookEd
     const [isSaveDebounced, setIsSaveDebounced] = useState(false);
     const [successfulSaveSequence, setSuccessfulSaveSequence] = useState(0);
 
-    /**
-     * Debounce timer ref so pending saves can be replaced before dispatch.
-     *
-     * @private function of useBookEditorWrapper
-     */
-    const debounceTimerRef = useRef<number | null>(null);
-
     /**
      * Stores the newest queued save request.
      *
@@ -175,6 +169,16 @@ export function useBookEditorSaving({ agentName, initialAgentSource }: UseBookEd
         [flushSaveQueue],
     );
 
+    /**
+     * Reuses the shared debounce utility while keeping source persistence separate from goal-chat notifications.
+     *
+     * @private function of useBookEditorWrapper
+     */
+    const debouncedEnqueueSave = useMemo(
+        () => debounce(enqueueSave, SAVE_DEBOUNCE_DELAY_MS),
+        [enqueueSave],
+    );
+
     /**
      * Schedules one autosave after the debounce delay.
      *
@@ -182,19 +186,12 @@ export function useBookEditorSaving({ agentName, initialAgentSource }: UseBookEd
      */
     const scheduleSave = useCallback(
         (nextSource: string_book, version: number) => {
-            if (debounceTimerRef.current) {
-                clearTimeout(debounceTimerRef.current);
-            }
-
             setIsSaveDebounced(true);
             setSaveStatus('pending');
 
-            debounceTimerRef.current = window.setTimeout(() => {
-                debounceTimerRef.current = null;
-                enqueueSave(nextSource, version, null);
-            }, SAVE_DEBOUNCE_DELAY_MS);
+            debouncedEnqueueSave(nextSource, version, null);
         },
-        [enqueueSave],
+        [debouncedEnqueueSave],
     );
 
     /**
@@ -218,14 +215,10 @@ export function useBookEditorSaving({ agentName, initialAgentSource }: UseBookEd
      * @private function of useBookEditorWrapper
      */
     const cancelPendingSave = useCallback(() => {
-        if (debounceTimerRef.current) {
-            clearTimeout(debounceTimerRef.current);
-            debounceTimerRef.current = null;
-        }
-
+        debouncedEnqueueSave.cancel();
         pendingSaveRef.current = null;
         setIsSaveDebounced(false);
-    }, []);
+    }, [debouncedEnqueueSave]);
 
     /**
      * Retries saving the current editor content immediately.
@@ -297,11 +290,9 @@ export function useBookEditorSaving({ agentName, initialAgentSource }: UseBookEd
      */
     useEffect(() => {
         return () => {
-            if (debounceTimerRef.current) {
-                clearTimeout(debounceTimerRef.current);
-            }
+            debouncedEnqueueSave.cancel();
         };
-    }, []);
+    }, [debouncedEnqueueSave]);
 
     /**
      * Indicates whether the latest local source revision is already confirmed on the server.
@@ -329,5 +320,4 @@ export function useBookEditorSaving({ agentName, initialAgentSource }: UseBookEd
     };
 }
 
-// TODO: Prompt: Use `import { debounce } from '@promptbook-local/utils';` instead of custom debounce implementation
 // TODO: [🚗] Transfer the saving logic to `<BookEditor/>` be aware of CRDT / yjs approach to be implementable in future