@promptbook/cli 0.112.0-112 → 0.112.0-114

package/README.md

@@ -561,11 +561,11 @@ npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompt
 
 npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompts/templates/agents-server.md
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --ignore-git-changes --no-wait
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --ignore-git-changes --no-wait
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -587,11 +587,11 @@ ptbk coder generate-boilerplates
 
 ptbk coder generate-boilerplates --template prompts/templates/common.md
 
-ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test
 
-ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
 
-ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
 
 ptbk coder find-refactor-candidates
 
@@ -616,7 +616,7 @@ ptbk coder verify
 
 | Flag                       | Purpose                                                                                            |
 | -------------------------- | -------------------------------------------------------------------------------------------------- |
-| `--agent <name>`           | Selects the coding backend.                                                                        |
+| `--harness <name>`         | Selects the coding harness.                                                                        |
 | `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`. |
 | `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
 | `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |

package/apps/agents-server/README.md

@@ -9,7 +9,7 @@ The installed CLI can initialize a local Agents Server project before it starts
 ```bash
 npm install ptbk
 ptbk agents-server init
-ptbk agents-server start --agent github-copilot --model gpt-5.4 --thinking-level xhigh
+ptbk agents-server start --harness github-copilot --model gpt-5.4 --thinking-level xhigh
 ```
 
 `ptbk agents-server init` adds missing placeholders to `.env` and local runtime exclusions to `.gitignore` without deleting existing configuration. Use `PTBK_AGENTS_SERVER_DATABASE=supabase` for a Supabase-backed server or `PTBK_AGENTS_SERVER_DATABASE=sqlite` for a standalone local database in `.promptbook`. When using Supabase, fill the initialized values from your project before starting the server. The Supabase project URL and API keys are available in the [Supabase project API settings](https://supabase.com/docs/guides/api/api-keys), and the PostgreSQL connection string is available from the [Supabase database connection guide](https://supabase.com/docs/guides/database/connecting-to-postgres).

package/apps/agents-server/next.config.ts

@@ -1,6 +1,8 @@
+import { withSentryConfig } from '@sentry/nextjs';
 import type { NextConfig } from 'next';
 import { readdirSync } from 'fs';
 import path from 'path';
+import { SENTRY_ORGANIZATION, SENTRY_PROJECT } from './src/utils/errorReporting/sentrySdkConfig';
 
 /**
  * Next.js build output directory.
@@ -20,6 +22,11 @@ const agentsServerNodeModulesPath = process.env.PTBK_AGENTS_SERVER_NODE_MODULES_
  */
 const isNextValidationIgnored = process.env.PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION === 'true';
 
+/**
+ * Whether Sentry source maps can be uploaded during production builds.
+ */
+const IS_SENTRY_SOURCE_MAP_UPLOAD_ENABLED = Boolean(process.env.SENTRY_AUTH_TOKEN);
+
 /**
  * Exact aliases for local generated Promptbook package entrypoints.
  */
@@ -122,7 +129,19 @@ const nextConfig: NextConfig = {
     },
 };
 
-export default nextConfig;
+export default withSentryConfig(nextConfig, {
+    org: SENTRY_ORGANIZATION,
+    project: SENTRY_PROJECT,
+    silent: true,
+    sourcemaps: {
+        disable: !IS_SENTRY_SOURCE_MAP_UPLOAD_ENABLED,
+    },
+    webpack: {
+        treeshake: {
+            removeDebugLogging: true,
+        },
+    },
+});
 
 /**
  * Creates webpack/Turbopack aliases from imports like `@promptbook-local/core` to generated local sources.

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

@@ -1,7 +1,13 @@
 import { CHAT_STREAM_KEEP_ALIVE_INTERVAL_MS } from '@/src/constants/streaming';
 import { isPrivateModeEnabledFromRequest } from '@/src/utils/privateMode';
-import { createUserChatDetailPayload, getUserChat, isFrozenUserChatSource } from '@/src/utils/userChat';
-import type { ChatMessage } from '@promptbook-local/types';
+import {
+    createUserChatDetailPayload,
+    getUserChat,
+    isFrozenUserChatSource,
+    listUserChatJobs,
+} from '@/src/utils/userChat';
+import { hasPotentiallyPendingAssistantMessages } from '@/src/utils/userChat/hasPotentiallyPendingAssistantMessages';
+import { listUserChatTimeouts } from '@/src/utils/userChatTimeout/userChatTimeoutStore';
 import { NextResponse } from 'next/server';
 import { resolveUserChatScope } from '../../resolveUserChatScope';
 
@@ -136,17 +142,17 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
                     return false;
                 }
 
-                const payload = await createUserChatDetailPayload(currentChat);
-                const nextSignature = createUserChatDetailSignature(payload);
+                const livePollState = await loadLiveUserChatPollingState(currentChat);
 
-                if (nextSignature !== lastSnapshotSignature) {
-                    lastSnapshotSignature = nextSignature;
+                if (livePollState.signature !== lastSnapshotSignature) {
+                    const payload = await createUserChatDetailPayload(currentChat);
+                    lastSnapshotSignature = createUserChatPollingSignatureFromDetailPayload(payload);
                     if (!enqueueFrame({ type: 'snapshot', payload })) {
                         return false;
                     }
                 }
 
-                return !isFrozenUserChatSource(payload.chat.source) && payload.activeJobs.length > 0;
+                return !isFrozenUserChatSource(currentChat.source) && livePollState.hasActiveJobs;
             };
 
             /**
@@ -211,69 +217,92 @@ export async function GET(request: Request, { params }: { params: Promise<{ agen
 }
 
 /**
- * Builds a stable signature for the user-visible parts of a canonical chat snapshot.
+ * Minimal live poll state used to avoid rebuilding the full chat payload when nothing visible changed.
  */
-function createUserChatDetailSignature(payload: Awaited<ReturnType<typeof createUserChatDetailPayload>>): string {
-    return JSON.stringify({
-        chatId: payload.chat.id,
-        updatedAt: payload.chat.updatedAt,
-        draftMessage: payload.draftMessage || '',
-        messages: payload.messages.map(createUserChatMessageSignature),
-        activeJobs: payload.activeJobs.map((job) => ({
-            id: job.id,
-            status: job.status,
-            cancelRequestedAt: job.cancelRequestedAt,
-        })),
-        activeTimeouts: payload.activeTimeouts.map((timeout) => ({
-            id: timeout.id,
-            status: timeout.status,
-            dueAt: timeout.dueAt,
-            cancelRequestedAt: timeout.cancelRequestedAt,
-        })),
-    });
-}
+type LiveUserChatPollState = {
+    signature: string;
+    hasActiveJobs: boolean;
+};
 
 /**
- * Builds one compact stable signature for a user-visible chat message.
+ * Loads the lightweight state needed to decide whether the active chat payload changed.
+ *
+ * The expensive detail payload does job reconciliation, local-runner synchronization, and full
+ * transcript serialization. Polling first with the persisted timestamps + active resource state
+ * keeps long-lived chat streams cheap when the conversation is idle.
+ *
+ * @param chat - Current scoped chat record.
+ * @returns Poll signature plus whether the chat should keep using the active-job cadence.
  */
-function createUserChatMessageSignature(
-    message: Awaited<ReturnType<typeof createUserChatDetailPayload>>['messages'][number],
-): Record<string, unknown> {
+async function loadLiveUserChatPollingState(chat: NonNullable<Awaited<ReturnType<typeof getUserChat>>>): Promise<LiveUserChatPollState> {
+    const shouldInspectActiveJobs = hasPotentiallyPendingAssistantMessages(chat.messages);
+    const [activeJobs, activeTimeouts] = await Promise.all([
+        shouldInspectActiveJobs
+            ? listUserChatJobs({
+                  userId: chat.userId,
+                  agentPermanentId: chat.agentPermanentId,
+                  chatId: chat.id,
+                  onlyActive: true,
+              })
+            : Promise.resolve([]),
+        listUserChatTimeouts({
+            userId: chat.userId,
+            agentPermanentId: chat.agentPermanentId,
+            chatId: chat.id,
+            onlyActive: true,
+        }),
+    ]);
+
     return {
-        id: message.id ?? null,
-        sender: message.sender,
-        isComplete: message.isComplete,
-        lifecycleState: message.lifecycleState ?? null,
-        lifecycleError: message.lifecycleError ?? null,
-        contentLength: message.content.length,
-        contentHash: createStableTextDigest(message.content),
-        replyingTo: message.replyingTo ? JSON.stringify(message.replyingTo) : null,
-        progressCard: message.progressCard ? JSON.stringify(message.progressCard) : null,
-        ongoingToolCalls: createToolCallsSignature(message.ongoingToolCalls),
-        completedToolCalls: createToolCallsSignature(message.completedToolCalls),
-        toolCalls: createToolCallsSignature(message.toolCalls),
+        signature: createUserChatPollingSignature({
+            chatUpdatedAt: chat.updatedAt,
+            draftMessage: chat.draftMessage,
+            activeJobs,
+            activeTimeouts,
+        }),
+        hasActiveJobs: activeJobs.length > 0,
     };
 }
 
 /**
- * Creates one compact stable digest for message text without pulling in heavier hashing helpers.
+ * Builds the polling signature for a fully hydrated detail payload.
  */
-function createStableTextDigest(value: string): string {
-    let hash = 2_166_136_261;
-
-    for (let index = 0; index < value.length; index++) {
-        hash ^= value.charCodeAt(index);
-        hash = Math.imul(hash, 16_777_619);
-    }
-
-    return (hash >>> 0).toString(16);
+function createUserChatPollingSignatureFromDetailPayload(
+    payload: Awaited<ReturnType<typeof createUserChatDetailPayload>>,
+): string {
+    return createUserChatPollingSignature({
+        chatUpdatedAt: payload.chat.updatedAt,
+        draftMessage: payload.draftMessage,
+        activeJobs: payload.activeJobs,
+        activeTimeouts: payload.activeTimeouts,
+    });
 }
 
 /**
- * Serializes optional tool-call arrays for snapshot signature comparisons.
+ * Builds a stable signature for the user-visible state that changes stream snapshots.
  */
-function createToolCallsSignature(toolCalls: ChatMessage['toolCalls']): string | null {
-    return toolCalls && toolCalls.length > 0 ? JSON.stringify(toolCalls) : null;
+function createUserChatPollingSignature(options: {
+    chatUpdatedAt: string;
+    draftMessage: string | null;
+    activeJobs: ReadonlyArray<Awaited<ReturnType<typeof createUserChatDetailPayload>>['activeJobs'][number]>;
+    activeTimeouts: ReadonlyArray<Awaited<ReturnType<typeof createUserChatDetailPayload>>['activeTimeouts'][number]>;
+}): string {
+    return JSON.stringify({
+        updatedAt: options.chatUpdatedAt,
+        draftMessage: options.draftMessage || '',
+        activeJobs: options.activeJobs.map((job) => ({
+            id: job.id,
+            status: job.status,
+            cancelRequestedAt: job.cancelRequestedAt,
+        })),
+        activeTimeouts: options.activeTimeouts.map((timeout) => ({
+            id: timeout.id,
+            status: timeout.status,
+            dueAt: timeout.dueAt,
+            cancelRequestedAt: timeout.cancelRequestedAt,
+            pausedAt: timeout.pausedAt,
+        })),
+    });
 }
 
 /**

package/apps/agents-server/src/app/agents/[agentName]/chat/useAgentChatHistorySyncEffects.ts

@@ -22,13 +22,6 @@ const USER_CHAT_STREAM_RECONNECT_DELAY_MS = 1_500;
  */
 const DISCONNECTED_CHAT_REFRESH_INTERVAL_MS = 4_000;
 
-/**
- * Periodic sidebar/list refresh cadence while the active chat stream is healthy.
- *
- * @private function of useAgentChatHistoryClientState
- */
-const CHAT_LIST_REFRESH_INTERVAL_MS = 20_000;
-
 /**
  * Inputs required to register side effects for durable chat-history synchronization.
  *
@@ -504,7 +497,7 @@ function keepActiveChatStreamConnected(params: {
 }
 
 /**
- * Refreshes the selected chat periodically and on tab visibility/focus changes.
+ * Refreshes the selected chat on disconnect polling and on tab visibility/focus changes.
  *
  * @private function of useAgentChatHistoryClientState
  */
@@ -529,9 +522,6 @@ function registerActiveChatRefreshPolling(params: {
         return undefined;
     }
 
-    const pollIntervalMs = isActiveChatStreamConnected
-        ? CHAT_LIST_REFRESH_INTERVAL_MS
-        : DISCONNECTED_CHAT_REFRESH_INTERVAL_MS;
     const runRefresh = () => {
         if (typeof document !== 'undefined' && document.hidden) {
             return;
@@ -540,7 +530,9 @@ function registerActiveChatRefreshPolling(params: {
         void refreshActiveChat({ preserveDirtyDraft: true });
     };
 
-    const interval = window.setInterval(runRefresh, pollIntervalMs);
+    const interval = isActiveChatStreamConnected
+        ? null
+        : window.setInterval(runRefresh, DISCONNECTED_CHAT_REFRESH_INTERVAL_MS);
     const handleVisibilityChange = () => {
         if (typeof document !== 'undefined' && !document.hidden) {
             runRefresh();
@@ -554,7 +546,9 @@ function registerActiveChatRefreshPolling(params: {
     window.addEventListener('focus', handleFocus);
 
     return () => {
-        window.clearInterval(interval);
+        if (interval !== null) {
+            window.clearInterval(interval);
+        }
         document.removeEventListener('visibilitychange', handleVisibilityChange);
         window.removeEventListener('focus', handleFocus);
     };

package/apps/agents-server/src/app/api/admin/code-runners/route.ts

@@ -52,7 +52,7 @@ export async function PATCH(request: Request) {
         }
 
         await updateVpsEnvironmentVariables({
-            PTBK_AGENT: body.agent || '',
+            PTBK_HARNESS: body.agent || '',
             PTBK_MODEL: body.model || '',
             PTBK_THINKING_LEVEL: body.thinkingLevel || '',
         });

package/apps/agents-server/src/app/api/internal/user-chat-jobs/run/route.ts

@@ -57,7 +57,7 @@ async function handleUserChatJobWorkerRequest(request: Request) {
 
         after(() =>
             triggerUserChatJobWorker({ origin }).catch((error) =>
-                console.error('[user-chat-job] requeue failed', error),
+                console.warn('[user-chat-job] requeue failed', error),
             ),
         );
 

package/apps/agents-server/src/database/migrations/2026-06-1300-user-chat-active-read-indexes.sql

@@ -0,0 +1,7 @@
+CREATE INDEX IF NOT EXISTS "prefix_UserChatJob_chatId_userId_agentPermanentId_active_createdAt_idx"
+    ON "prefix_UserChatJob" ("chatId", "userId", "agentPermanentId", "createdAt" ASC)
+    WHERE "status" IN ('QUEUED', 'RUNNING');
+
+CREATE INDEX IF NOT EXISTS "prefix_UserChatTimeout_chatId_userId_agentPermanentId_active_dueAt_idx"
+    ON "prefix_UserChatTimeout" ("chatId", "userId", "agentPermanentId", "dueAt" ASC, "createdAt" ASC)
+    WHERE "status" IN ('QUEUED', 'RUNNING') AND "pausedAt" IS NULL;

package/apps/agents-server/src/instrumentation-client.ts

@@ -0,0 +1,28 @@
+import * as Sentry from '@sentry/nextjs';
+import {
+    createSentrySdkTags,
+    resolveBrowserSentryDsn,
+    resolveSentrySdkEnvironment,
+    resolveSentrySdkRelease,
+    SENTRY_TRACE_PROPAGATION_TARGETS,
+    SENTRY_TRACES_SAMPLE_RATE,
+} from './utils/errorReporting/sentrySdkConfig';
+
+Sentry.init({
+    dsn: resolveBrowserSentryDsn(),
+    tracesSampleRate: SENTRY_TRACES_SAMPLE_RATE,
+    environment: resolveSentrySdkEnvironment(),
+    release: resolveSentrySdkRelease(),
+    integrations: [Sentry.browserTracingIntegration()],
+    tracePropagationTargets: SENTRY_TRACE_PROPAGATION_TARGETS,
+    initialScope: {
+        tags: createSentrySdkTags(),
+    },
+});
+
+/**
+ * Reports app-router navigation spans to Sentry.
+ *
+ * @private Sentry hook for Next.js client navigation instrumentation
+ */
+export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

package/apps/agents-server/src/instrumentation.ts

@@ -1,3 +1,5 @@
+import * as Sentry from '@sentry/nextjs';
+
 /**
  * Registers startup hooks for the Agents Server runtime.
  *
@@ -5,11 +7,18 @@
  * @private internal startup hook for Agents Server runtime
  */
 export async function register(): Promise<void> {
+    if (process.env.NEXT_RUNTIME === 'edge') {
+        await import('./sentry.edge.config');
+        return;
+    }
+
     if (process.env.NEXT_RUNTIME !== 'nodejs') {
         return;
     }
 
     try {
+        await import('./sentry.server.config');
+
         const { registerServerErrorSentryLogging } = await import('./utils/errorReporting/registerServerErrorSentryLogging');
         registerServerErrorSentryLogging();
 
@@ -25,3 +34,10 @@ export async function register(): Promise<void> {
         });
     }
 }
+
+/**
+ * Reports request errors from the Next.js app router to Sentry.
+ *
+ * @private Sentry hook for Next.js request instrumentation
+ */
+export const onRequestError = Sentry.captureRequestError;

package/apps/agents-server/src/sentry.edge.config.ts

@@ -0,0 +1,18 @@
+import * as Sentry from '@sentry/nextjs';
+import {
+    createSentrySdkTags,
+    resolveBrowserSentryDsn,
+    resolveSentrySdkEnvironment,
+    resolveSentrySdkRelease,
+    SENTRY_TRACES_SAMPLE_RATE,
+} from './utils/errorReporting/sentrySdkConfig';
+
+Sentry.init({
+    dsn: resolveBrowserSentryDsn(),
+    tracesSampleRate: SENTRY_TRACES_SAMPLE_RATE,
+    environment: resolveSentrySdkEnvironment(),
+    release: resolveSentrySdkRelease(),
+    initialScope: {
+        tags: createSentrySdkTags(),
+    },
+});

package/apps/agents-server/src/sentry.server.config.ts

@@ -0,0 +1,19 @@
+import * as Sentry from '@sentry/nextjs';
+import { createAgentsServerSentryContext } from './utils/errorReporting/agentsServerSentryContext';
+import { resolveServerSentryDsn, SENTRY_TRACES_SAMPLE_RATE } from './utils/errorReporting/sentrySdkConfig';
+
+/**
+ * Shared diagnostic context applied to server-side SDK events at initialization time.
+ */
+const agentsServerSentryContext = createAgentsServerSentryContext();
+
+Sentry.init({
+    dsn: resolveServerSentryDsn(),
+    tracesSampleRate: SENTRY_TRACES_SAMPLE_RATE,
+    environment: agentsServerSentryContext.environment,
+    release: agentsServerSentryContext.release,
+    initialScope: {
+        tags: agentsServerSentryContext.tags,
+        extra: agentsServerSentryContext.extra,
+    },
+});

package/apps/agents-server/src/utils/agentRouting/resolveAgentRouteTarget.ts

@@ -102,6 +102,13 @@ async function resolveAgentRouteTargetUncached(
         };
     }
 
+    if (!options?.forceRefresh) {
+        const fastLocalRouteTarget = await resolveFastLocalAgentRouteTarget(normalizedReference, localServerUrl);
+        if (fastLocalRouteTarget) {
+            return fastLocalRouteTarget;
+        }
+    }
+
     const resolver = await $provideAgentReferenceResolver({ forceRefresh: options?.forceRefresh });
     let resolvedUrlValue: string;
 
@@ -145,6 +152,37 @@ async function resolveAgentRouteTargetUncached(
     };
 }
 
+/**
+ * Resolves the common local-agent case without constructing the heavier shared reference resolver.
+ *
+ * Normal page and chat routes almost always target one local agent by its stored name or permanent id.
+ * Handling that case up front keeps route resolution cheap while still falling back to the full TEAM/federation
+ * resolver for aliases, remote agents, and fuzzy matches.
+ *
+ * @param reference - Normalized route/reference text.
+ * @param localServerUrl - Normalized URL of the current Agents Server instance.
+ * @returns Local route target or `null` when a direct lookup does not match.
+ */
+async function resolveFastLocalAgentRouteTarget(
+    reference: string,
+    localServerUrl: string,
+): Promise<AgentRouteTarget | null> {
+    const collection = await $provideAgentCollectionForServer();
+    const directMatch = await collection.findAgentBasicInformation(reference);
+
+    if (!directMatch) {
+        return null;
+    }
+
+    const canonicalAgentId = directMatch.permanentId || directMatch.agentName;
+
+    return {
+        kind: 'local',
+        canonicalAgentId,
+        canonicalUrl: `${localServerUrl}${AGENT_PATH_PREFIX}${encodeURIComponent(canonicalAgentId)}`,
+    };
+}
+
 /**
  * Memoized route-target resolver used for normal page rendering.
  */

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

@@ -37,7 +37,7 @@ export async function readConfiguredCodeRunner(): Promise<ConfiguredCodeRunner>
     >;
 
     return {
-        agent: environmentByKey.PTBK_AGENT || process.env.PTBK_AGENT || 'github-copilot',
+        agent: environmentByKey.PTBK_HARNESS || process.env.PTBK_HARNESS || process.env.PTBK_AGENT || 'github-copilot',
         model: environmentByKey.PTBK_MODEL || process.env.PTBK_MODEL || 'gpt-5.4',
         thinkingLevel: environmentByKey.PTBK_THINKING_LEVEL || process.env.PTBK_THINKING_LEVEL || 'xhigh',
     };