@promptbook/cli 0.112.0-99 → 0.113.0-0

package/README.md

@@ -27,6 +27,25 @@ Create persistent AI agents that turn your company's scattered knowledge into ac
 
 
 
+### Standalone VPS
+
+Run the standalone VPS installer only on a fresh server. Interactive mode asks for the installation values:
+
+```bash
+sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash
+```
+
+Non-interactive mode takes defaults from command-line options. When `--openai-api-key` is provided with the default OpenAI Codex runner, the installer installs and configures Codex automatically; other runner authentication can be configured later from the UI or SSH:
+
+```bash
+sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash -s -- \
+    --non-interactive \
+    --yes-i-understand-that-script-should-be-run-on-fresh-server \
+    --domain my-server.com \
+    --openai-api-key sk-proj-xxx \
+    --admin-password xxx
+```
+
 
 
 <blockquote style="color: #ff8811">
@@ -183,7 +202,7 @@ Rest of the documentation is common for **entire promptbook ecosystem**:
 
 Promptbook lets you create **persistent AI agents** that work on real goals for your company. The [**Agents Server**](https://gallery.ptbk.io/) is the heart of the project - a place where your AI agents live, remember context, collaborate in teams, and get things done.
 
-Nowadays, the biggest challenge for most business applications isn't the raw capabilities of AI models. Large language models such as GPT-5.2 and Claude-4.5 are incredibly capable.
+Nowadays, the biggest challenge for most business applications isn't the raw capabilities of AI models. Large language models such as Claude Mythos, GPT-5.6 or Kimi K2.7 are incredibly capable.
 
 The main challenge lies in **managing the context**, providing rules and knowledge, and narrowing the personality.
 
@@ -191,17 +210,20 @@ In Promptbook, you define your agents **using simple Books** - a human-readable
 
 <table style="border: 1px solid #777; border-radius: 10px;"><tr><td>
 
-**<ins>Paul Smith</ins>**<br/>
+**<ins>Lawyer</ins>**<br/>
 <br/>
-**PERSONA** You are a company lawyer.<br/>
+GOAL You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email and keep the company website updated with the latest legal policies.<br/>
+Respond to incoming legal inquiries via email and keep the company website updated with the latest legal policies.<br/>
+<br/>
 **RULE** You are knowledgeable, professional, and detail-oriented.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-**USE EMAIL**<br/>
-**USE BROWSER**<br/>
-**TEAM** You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
+<br/>
+USE EMAIL<br/>
+USE BROWSER<br/>
+<br/>
+TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
 
@@ -234,12 +256,12 @@ Goals define what the agent should actively work toward. Unlike a chatbot that o
 
 <table style="border: 1px solid #777; border-radius: 10px;"><tr><td>
 
-**<ins>Paul Smith & Associés</ins>**<br/>
+**<ins>Company Lawyer</ins>**<br/>
 <br/>
-**PERSONA** You are a company lawyer.<br/>
+GOAL<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 
 </td></tr></table>
 
@@ -257,8 +279,8 @@ Promptbook Engine will automatically enforce this knowledge during interactions.
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
 
@@ -276,8 +298,8 @@ Depending on rule strictness, Promptbook will either propagate it to the prompt
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **RULE** Always ensure compliance with local laws and regulations.<br/>
 **RULE** Never provide legal advice outside your area of expertise.<br/>
 **RULE** Never provide legal advice about criminal law.<br/>
@@ -298,16 +320,16 @@ These are what turn a chatbot into a persistent agent that actually does work.
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **RULE** Always ensure compliance with local laws and regulations.<br/>
 **RULE** Never provide legal advice outside your area of expertise.<br/>
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-**USE EMAIL**<br/>
-**USE BROWSER**<br/>
-**USE SEARCH ENGINE**<br/>
+USE EMAIL<br/>
+USE BROWSER<br/>
+USE SEARCH ENGINE<br/>
 
 </td></tr></table>
 
@@ -321,20 +343,22 @@ Team commitment allows you to define the team structure and advisory fellow memb
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **RULE** Always ensure compliance with local laws and regulations.<br/>
 **RULE** Never provide legal advice outside your area of expertise.<br/>
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-**USE EMAIL**<br/>
-**USE BROWSER**<br/>
-**USE SEARCH ENGINE**<br/>
-**TEAM** You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
+USE EMAIL<br/>
+USE BROWSER<br/>
+USE SEARCH ENGINE<br/>
+TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
 
+
+
 ### Promptbook Ecosystem
 
 Promptbook is an ecosystem of tools centered around the **Agents Server** - a production-ready platform for running persistent AI agents.
@@ -357,6 +381,8 @@ The [Promptbook Engine](https://github.com/webgptorg/promptbook) is the open-sou
 
 
 
+
+
 ## 💜 The Promptbook Project
 
 Promptbook project is an ecosystem centered around the **Agents Server** - a platform for creating, deploying, and running persistent AI agents. Following is a list of the most important pieces of the project:
@@ -394,6 +420,8 @@ Promptbook project is an ecosystem centered around the **Agents Server** - a pla
   </tbody>
 </table>
 
+
+
 ### 🌐 Community & Social Media
 
 Join our growing community of developers and users:
@@ -450,6 +478,8 @@ Join our growing community of developers and users:
 
 
 
+
+
 ## 📚 Documentation
 
 See detailed guides and API reference in the [docs](https://github.com/webgptorg/promptbook/discussions/categories/concepts) or [online](https://discord.gg/x3QWNaa89N).
@@ -541,9 +571,9 @@ Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treate
 #### Features
 
 -   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
--   **Context injection:** `--context AGENTS.md` or inline extra instructions
+-   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
--   **Interactive or unattended runs:** default wait mode, or `--no-wait` for batch execution
+-   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
 -   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
@@ -561,11 +591,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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -587,11 +617,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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes
 
 ptbk coder find-refactor-candidates
 
@@ -604,24 +634,24 @@ ptbk coder verify
 
 #### What each command does
 
-| Command                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
+| Command                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.promptbook`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
-| `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                  |
-| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                           |
-| `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                  | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
-| `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                             |
+| `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                         |
+| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                                  |
+| `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                         | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
+| `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                                    |
 
 #### Most useful `ptbk coder run` flags
 
 | 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.   |
 | `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
-| `--no-wait`                | Skips interactive pauses between prompts for unattended execution.                                 |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue. |
 | `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
 | `--priority <n>`           | Runs only prompts at or above the given priority.                                                  |
 | `--dry-run`                | Prints which prompts are ready instead of executing them.                                          |
@@ -633,8 +663,8 @@ ptbk coder verify
 
 1. Initialize once with `ptbk coder init`.
 2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
-3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--context AGENTS.md`.
-4. Run one prompt at a time interactively, or use `--no-wait` for unattended batches.
+3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--agent agents/coding/developer.book --context AGENTS.md`.
+4. Run unattended batches by default, or pass `--no-auto` to confirm each prompt interactively.
 5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
 
 
@@ -657,6 +687,8 @@ The following glossary is used to clarify certain concepts:
 
 _Note: This section is not a complete dictionary, more list of general AI / LLM terms that has connection with Promptbook_
 
+
+
 ### 💯 Core concepts
 
 -   [📚 Collection of pipelines](https://github.com/webgptorg/promptbook/discussions/65)

package/agents/default/developer.book

@@ -0,0 +1,24 @@
+Developer
+META VISIBILITY PRIVATE
+
+RULE
+Keep in mind the DRY _(don't repeat yourself)_ principle.
+
+RULE
+Keep in mind the SOLID principles.
+
+RULE
+Do a proper analysis of the current functionality before you start implementing.
+
+RULE
+Keep small responsibilities of functions and classes, avoid creating big functions or classes that do many things.
+
+RULE
+Constants should always be `UPPER_SNAKE_CASE`.
+
+RULE
+Boolean variables should always be prefixed with `is`, for example `isUserChatJobLeaseExpired` or `IS_DEBUG_MODE`.
+
+RULE
+Do not use abbreviations, for example use `isExpired` instead of `isExp`, `translateMessage` instead of `t`, etc.
+It is fine to use well-known abbreviations, for example `id`, `url`, `html`, etc.

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).
@@ -41,6 +41,24 @@ ptbk agents-server start --agent github-copilot --model gpt-5.4 --thinking-level
 <a id="agents-server-env-admin-password"></a>
 -   `ADMIN_PASSWORD`: Password for the built-in `admin` login on a self-hosted Agents Server. Choose a private value before using the admin UI.
 
+<a id="agents-server-env-session-secret"></a>
+-   `SESSION_SECRET`: HMAC signing key used to sign the session cookie. Must be set explicitly in production — the server refuses to start session signing when missing instead of falling back to a hardcoded default. Use a long random string, for example the output of `openssl rand -hex 32`. Keep it separate from `ADMIN_PASSWORD` so a leak of either credential cannot forge the other.
+
+<a id="agents-server-env-ptbk-agents-server-user-chat-worker-token"></a>
+-   `PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN`: Shared internal token used to authorize background worker routes (`/api/internal/user-chat-jobs/run`, `/api/internal/user-chat-timeouts/run`, and `/api/internal/agent-runner-limits`). Must be set explicitly in production — the server refuses to resolve the worker token when missing instead of falling back to `ADMIN_PASSWORD`, `SUPABASE_SERVICE_ROLE_KEY`, or a hardcoded constant. Use a long random string, for example the output of `openssl rand -hex 32`. The CLI launcher (`ptbk agents-server start`) generates a per-process value automatically when the variable is empty so local development works without configuration.
+
+<a id="agents-server-env-promptbook-team-agent-access-token"></a>
+-   `PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN`: Dedicated secret used by same-server `TEAM` calls to authorize access to private teammate agents. Must be a dedicated random string — falling back to `ADMIN_PASSWORD` or `SUPABASE_SERVICE_ROLE_KEY` would let a leak of one credential compromise both authentication boundaries. When not configured, same-server team access stays disabled (the integration fails closed) so leaving the variable empty is safe but disables the feature. Use a long random string, for example the output of `openssl rand -hex 32`.
+
+<a id="agents-server-env-sendgrid-inbound-parse-public-key"></a>
+-   `SENDGRID_INBOUND_PARSE_PUBLIC_KEY`: Public verification key from SendGrid Signed Webhook settings for `/api/emails/incoming/sendgrid`. The route verifies `X-Twilio-Email-Event-Webhook-Signature` over the raw multipart body before parsing or inserting an inbound `EMAIL` message. Configure either this public key or `SENDGRID_INBOUND_PARSE_WEBHOOK_SECRET`; the SendGrid public-key flow is preferred.
+
+<a id="agents-server-env-sendgrid-inbound-parse-webhook-secret"></a>
+-   `SENDGRID_INBOUND_PARSE_WEBHOOK_SECRET`: Shared secret for deployments that sign SendGrid Inbound Parse callbacks with HMAC instead of SendGrid's public-key signature flow. Leave empty when `SENDGRID_INBOUND_PARSE_PUBLIC_KEY` is configured. Use a dedicated random string and keep it separate from `SENDGRID_API_KEY`, `ADMIN_PASSWORD`, and other server secrets.
+
+<a id="agents-server-env-sendgrid-inbound-parse-hosts"></a>
+-   `SENDGRID_INBOUND_PARSE_HOSTS`: Comma-separated list of public hostnames allowed to receive SendGrid Inbound Parse callbacks, for example `mail.example.com,parse.example.com`. The route rejects signed requests delivered through any other `Host` / `X-Forwarded-Host`, so point SendGrid only at the hostnames that are also protected by your reverse-proxy or platform IP allowlisting.
+
 ## Creating servers
 
 When creating new Agents server, search across the repository for [☁]
@@ -54,4 +72,3 @@ When creating new Agents server, search across the repository for [☁]
 -   [☁] If using `USE PROJECT` auto-auth, configure [GitHub App integration](./GITHUB_APP.md)
 -   [☁] Add the server to [the list of our servers](https://docs.google.com/spreadsheets/d/1X26iMQqubsxftqD1EJNSlzPYFS94QjCFPXyKdHHDeVs/edit?gid=848307752#gid=848307752)
 -   [☁] Run migration script _(run new instance)_
--   [☁] For testing servers, look at the server and change the `CORE_SERVER` to `https://core-test.ptbk.io/`

package/apps/agents-server/env-manual/GITHUB_APP.md

@@ -32,7 +32,7 @@ GitHub App configuration now lives in **Metadata** so you can customize it per s
     - **GITHUB_APP_ID** – numeric GitHub App ID from the app settings.
     - **GITHUB_APP_SLUG** – slug used in `https://github.com/apps/<slug>`.
     - **GITHUB_APP_PRIVATE_KEY** – PEM-encoded private key. Replace literal newlines with `\n` when editing through the UI and keep the `BEGIN/END` markers.
-    - **GITHUB_APP_STATE_SECRET** (optional, recommended) – random string used to sign OAuth/connect state. If unset, `ADMIN_PASSWORD` will be used as a fallback.
+    - **GITHUB_APP_STATE_SECRET** (optional, recommended) – random string used to sign OAuth/connect state.
 
 The values stored in Metadata override any legacy `.env` entries and can differ per server host.
 

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,18 @@ const agentsServerNodeModulesPath = process.env.PTBK_AGENTS_SERVER_NODE_MODULES_
  */
 const isNextValidationIgnored = process.env.PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION === 'true';
 
+/**
+ * Optional worker count override for CLI-owned production builds on memory-constrained VPS hosts.
+ */
+const AGENTS_SERVER_BUILD_WORKER_COUNT = parseAgentsServerBuildWorkerCount(
+    process.env.PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT,
+);
+
+/**
+ * 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.
  */
@@ -50,6 +64,7 @@ const nextConfig: NextConfig = {
 
     experimental: {
         externalDir: true,
+        ...(AGENTS_SERVER_BUILD_WORKER_COUNT ? { cpus: AGENTS_SERVER_BUILD_WORKER_COUNT } : {}),
     },
 
     turbopack: {
@@ -122,7 +137,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.
@@ -143,3 +170,16 @@ function createPromptbookLocalPackageAliases(): Record<string, string> {
         return {};
     }
 }
+
+/**
+ * Parses a positive integer worker count from the CLI build environment.
+ */
+function parseAgentsServerBuildWorkerCount(rawValue: string | undefined): number | undefined {
+    const parsedValue = Number(rawValue);
+
+    if (!Number.isFinite(parsedValue) || parsedValue < 1) {
+        return undefined;
+    }
+
+    return Math.floor(parsedValue);
+}

package/apps/agents-server/package.json

@@ -7,7 +7,7 @@
         "dev": "next dev -p 4440",
         "test": "npm run lint && npm run test-build && npm run test-e2e",
         "test-e2e": "playwright test",
-        "pretest-build": "npx kill-port 4021",
+        "pretest-build": "npx kill-port 4021 4440 || exit 0",
         "test-build": "node -r ./scripts/ignore-kill-eperm.js ../../node_modules/next/dist/bin/next build && node ./scripts/prerender-homepage.js",
         "build": "node -r ./scripts/ignore-kill-eperm.js ../../node_modules/next/dist/bin/next build && node ./scripts/prerender-homepage.js",
         "start": "next start -p 4440",

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

@@ -26,6 +26,9 @@ const APP_URL = `http://127.0.0.1:${APP_PORT}`;
  */
 const APP_E2E_ENV = {
     ADMIN_PASSWORD: 'e2e-admin-password',
+    SESSION_SECRET: 'e2e-session-secret-must-differ-from-admin-password',
+    PTBK_AGENTS_SERVER_USER_CHAT_WORKER_TOKEN: 'e2e-user-chat-worker-token-must-differ-from-admin-password',
+    PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN: 'e2e-team-agent-access-token-must-differ-from-admin-password',
     NEXT_DIST_DIR: '.next-e2e',
     NEXT_PUBLIC_SITE_URL: APP_URL,
     PTBK_AGENTS_SERVER_DATABASE: 'supabase',

package/apps/agents-server/scripts/prerender-homepage.js

@@ -45,6 +45,10 @@ const WAIT_TIMEOUT_MS = 15000;
  * Timeout for the final homepage download once the server is confirmed ready.
  */
 const HOME_REQUEST_TIMEOUT_MS = 30000;
+/**
+ * Timeout for stopping the temporary production server before escalating cleanup.
+ */
+const STOP_SERVER_TIMEOUT_MS = 10000;
 /**
  * When enabled, homepage prerender failures abort the whole build.
  */
@@ -136,6 +140,65 @@ function waitForServerReady(serverProcess) {
     });
 }
 
+/**
+ * Waits briefly for the temporary production server to exit after cleanup starts.
+ *
+ * @param serverProcess - Spawned `next start` child process.
+ * @param gracefulExit - Promise resolved by the child `exit` event.
+ * @returns Whether the child exited within the timeout window.
+ */
+async function waitForServerStop(serverProcess, gracefulExit) {
+    if (serverProcess.exitCode !== null || serverProcess.signalCode !== null) {
+        return true;
+    }
+
+    return await Promise.race([
+        gracefulExit.then(() => true),
+        new Promise((resolve) => setTimeout(() => resolve(false), STOP_SERVER_TIMEOUT_MS)),
+    ]);
+}
+
+/**
+ * Force-stops the temporary production server when normal shutdown does not finish in time.
+ *
+ * Windows can leave `next start` alive after an `EPERM` kill attempt, so use `taskkill`
+ * against the exact PID before giving up on cleanup.
+ *
+ * @param serverProcess - Spawned `next start` child process.
+ */
+async function forceStopServer(serverProcess) {
+    if (serverProcess.exitCode !== null || serverProcess.signalCode !== null) {
+        return;
+    }
+
+    if (process.platform !== 'win32') {
+        try {
+            serverProcess.kill('SIGKILL');
+        } catch (error) {
+            if (!isIgnorableStopServerError(error)) {
+                throw error;
+            }
+        }
+        return;
+    }
+
+    await new Promise((resolve, reject) => {
+        const taskKillProcess = spawn('taskkill', ['/PID', String(serverProcess.pid), '/T', '/F'], {
+            stdio: 'ignore',
+        });
+
+        taskKillProcess.on('error', reject);
+        taskKillProcess.on('exit', (code) => {
+            if (code === 0 || serverProcess.exitCode !== null || serverProcess.signalCode !== null) {
+                resolve();
+                return;
+            }
+
+            reject(new Error(`Failed to stop temporary production server process ${serverProcess.pid} with taskkill.`));
+        });
+    });
+}
+
 /**
  * Runs the production server for the built app, captures `/`, and keeps the HTML.
  */
@@ -196,7 +259,19 @@ async function prerenderHomePage() {
     } finally {
         detachStopServerHandlers();
         stopServer();
-        await gracefulExit;
+
+        if (!(await waitForServerStop(serverProcess, gracefulExit))) {
+            console.warn(
+                `Timed out waiting ${STOP_SERVER_TIMEOUT_MS}ms for the temporary production server to stop. Trying a forceful shutdown.`,
+            );
+            await forceStopServer(serverProcess);
+
+            if (!(await waitForServerStop(serverProcess, gracefulExit))) {
+                console.warn(
+                    `Timed out waiting ${STOP_SERVER_TIMEOUT_MS}ms for the temporary production server after forceful shutdown.`,
+                );
+            }
+        }
     }
 }
 

package/apps/agents-server/src/app/AddAgentButton.tsx

@@ -1,6 +1,5 @@
 'use client';
 
-import { useRouter } from 'next/navigation';
 import { FileCard } from '../components/Homepage/FileCard';
 import { useAgentNaming } from '../components/AgentNaming/AgentNamingContext';
 import { showAlert } from '../components/AsyncDialogs/asyncDialogs';
@@ -21,15 +20,11 @@ type AddAgentButtonProps = {
  * Renders the add-agent card and creation dialog workflow.
  */
 export function AddAgentButton({ currentFolderId }: AddAgentButtonProps) {
-    const router = useRouter();
     const { formatText } = useAgentNaming();
     const { t } = useServerLanguage();
     const addButtonLabel = formatText(t('agentCreation.addButtonLabel'));
 
     const { isPreparingDialog, openNewAgentDialog, dialog } = useNewAgentDialog({
-        onCreated: ({ targetPath }) => {
-            router.push(targetPath);
-        },
         onCreateFailed: async (error) => {
             console.error('Failed to create agent:', error);
             await showAlert({

package/apps/agents-server/src/app/[agentName]/layout.tsx

@@ -0,0 +1 @@
+export { default, generateMetadata } from '../agents/[agentName]/layout';