@vellumai/assistant 0.4.54 → 0.4.56

package/src/prompts/system-prompt.ts

@@ -7,6 +7,7 @@ import { getBaseDataDir, getIsContainerized } from "../config/env-registry.js";
 import { getConfig } from "../config/loader.js";
 import { skillFlagKey } from "../config/skill-state.js";
 import { loadSkillCatalog, type SkillSummary } from "../config/skills.js";
+import { isPlatformManaged } from "../inbound/platform-callback-registration.js";
 import { listConnections } from "../oauth/oauth-store.js";
 import { resolveBundledDir } from "../util/bundled-asset.js";
 import { getLogger } from "../util/logger.js";
@@ -111,14 +112,60 @@ export function isOnboardingComplete(): boolean {
  */
 export interface BuildSystemPromptOptions {
   hasNoClient?: boolean;
+  excludeBootstrap?: boolean;
 }
 
+/**
+ * Sentinel that separates the static instruction prefix (stable across turns)
+ * from the dynamic workspace suffix (changes when workspace files are edited).
+ *
+ * The Anthropic provider splits on this marker to create two system-prompt
+ * cache blocks so that static instructions stay cached even when workspace
+ * files change between turns.
+ */
+export const SYSTEM_PROMPT_CACHE_BOUNDARY =
+  "\n<!-- SYSTEM_PROMPT_CACHE_BOUNDARY -->\n";
+
 export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
+  const hasNoClient = options?.hasNoClient ?? false;
+
+  // ── Static instruction sections (stable across turns) ──
+  // These sections are deterministic within a process lifetime.  They form
+  // the first cache block so they remain cached even when workspace files
+  // (IDENTITY.md, SOUL.md, USER.md, etc.) are edited between turns.
+  const staticParts: string[] = [];
+  staticParts.push(
+    "IMPORTANT: Never use em dashes (—) in your messages. Use commas, periods, or just start a new sentence instead.",
+  );
+  if (getIsContainerized()) staticParts.push(buildContainerizedSection());
+  staticParts.push(buildCliReferenceSection());
+  staticParts.push(buildPostToolResponseSection());
+  staticParts.push(buildChannelAwarenessSection());
+  if (!hasNoClient) staticParts.push(buildToolPermissionSection());
+  staticParts.push(buildTaskScheduleReminderRoutingSection());
+  staticParts.push(buildAttachmentSection());
+  staticParts.push(buildInChatConfigurationSection());
+  if (!isOnboardingComplete()) {
+    staticParts.push(buildStarterTaskPlaybookSection());
+  }
+  if (!hasNoClient) staticParts.push(buildSystemPermissionSection());
+  staticParts.push(buildSwarmGuidanceSection());
+  staticParts.push(buildAccessPreferenceSection(hasNoClient));
+  staticParts.push(buildMemoryPersistenceSection());
+  staticParts.push(buildMemoryRecallSection());
+  staticParts.push(buildWorkspaceReflectionSection());
+  staticParts.push(buildLearningMemorySection());
+
+  // ── Dynamic sections (may change between turns) ──
+  // Workspace files, config, external comms identity, connected services,
+  // and skills catalog are all re-read from disk/DB each turn.  They form
+  // the second cache block.
+  const dynamicParts: string[] = [];
+
   const soulPath = getWorkspacePromptPath("SOUL.md");
   const identityPath = getWorkspacePromptPath("IDENTITY.md");
   const userPath = getWorkspacePromptPath("USER.md");
   const bootstrapPath = getWorkspacePromptPath("BOOTSTRAP.md");
-
   const updatesPath = getWorkspacePromptPath("UPDATES.md");
 
   const soul = readPromptFile(soulPath);
@@ -127,23 +174,18 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   const bootstrap = readPromptFile(bootstrapPath);
   const updates = readPromptFile(updatesPath);
 
-  // ── Core sections ──
-  const parts: string[] = [];
-  parts.push(
-    "IMPORTANT: Never use em dashes (—) in your messages. Use commas, periods, or just start a new sentence instead.",
-  );
-  if (identity) parts.push(identity);
-  if (soul) parts.push(soul);
-  if (user) parts.push(user);
-  if (bootstrap) {
-    parts.push(
+  if (identity) dynamicParts.push(identity);
+  if (soul) dynamicParts.push(soul);
+  if (user) dynamicParts.push(user);
+  if (bootstrap && !options?.excludeBootstrap) {
+    dynamicParts.push(
       "# First-Run Ritual\n\n" +
         "BOOTSTRAP.md is present — this is your first conversation. Follow its instructions.\n\n" +
         bootstrap,
     );
   }
   if (updates) {
-    parts.push(
+    dynamicParts.push(
       [
         "## Recent Updates",
         "",
@@ -159,43 +201,15 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
       ].join("\n"),
     );
   }
-  if (getIsContainerized()) parts.push(buildContainerizedSection());
-  const hasNoClient = options?.hasNoClient ?? false;
-  parts.push(buildConfigSection(hasNoClient));
-  parts.push(buildCliReferenceSection());
-  parts.push(buildPostToolResponseSection());
-  parts.push(buildExternalCommsIdentitySection());
-  parts.push(buildChannelAwarenessSection());
-  const config = getConfig();
-  if (!hasNoClient) parts.push(buildToolPermissionSection());
-  parts.push(buildTaskScheduleReminderRoutingSection());
-  if (
-    isAssistantFeatureFlagEnabled(
-      "feature_flags.guardian-verify-setup.enabled",
-      config,
-    )
-  ) {
-    parts.push(buildVerificationRoutingSection());
-  }
-  parts.push(buildAttachmentSection());
-  parts.push(buildInChatConfigurationSection());
-  parts.push(buildVoiceSetupRoutingSection());
-  parts.push(buildPhoneCallsRoutingSection());
-  parts.push(buildChannelCommandIntentSection());
+  dynamicParts.push(buildConfigSection(hasNoClient));
+  dynamicParts.push(buildExternalCommsIdentitySection());
+  dynamicParts.push(buildIntegrationSection());
 
-  if (!isOnboardingComplete()) {
-    parts.push(buildStarterTaskPlaybookSection());
-  }
-  if (!hasNoClient) parts.push(buildSystemPermissionSection());
-  parts.push(buildSwarmGuidanceSection());
-  parts.push(buildAccessPreferenceSection(hasNoClient));
-  parts.push(buildIntegrationSection());
-  parts.push(buildMemoryPersistenceSection());
-  parts.push(buildMemoryRecallSection());
-  parts.push(buildWorkspaceReflectionSection());
-  parts.push(buildLearningMemorySection());
-
-  return appendSkillsCatalog(parts.join("\n\n"));
+  const dynamicWithSkills = appendSkillsCatalog(dynamicParts.join("\n\n"));
+
+  return (
+    staticParts.join("\n\n") + SYSTEM_PROMPT_CACHE_BOUNDARY + dynamicWithSkills
+  );
 }
 
 function buildTaskScheduleReminderRoutingSection(): string {
@@ -232,38 +246,6 @@ function buildTaskScheduleReminderRoutingSection(): string {
   ].join("\n");
 }
 
-export function buildVerificationRoutingSection(): string {
-  return [
-    "## Routing: Guardian Verification",
-    "",
-    "When the user wants to verify their identity as the trusted guardian for a messaging channel, load the **Guardian Verify Setup** skill.",
-    'Interpret phrasing like "help me set myself up as your guardian" as the user asking to verify themselves as guardian (not asking the assistant to self-assign permissions).',
-    'Do not give conceptual "I cannot set myself as guardian" explanations unless the user explicitly asks a conceptual/security question.',
-    "",
-    "### Trigger phrases",
-    '- "verify guardian"',
-    '- "verify my Telegram account"',
-    '- "verify phone channel"',
-    '- "verify my phone number"',
-    '- "set up guardian verification"',
-    "",
-    "### What it does",
-    "The skill walks through outbound guardian verification for phone or Telegram:",
-    "1. Confirm channel (phone, telegram)",
-    "2. Collect destination (phone number or Telegram handle/chat ID)",
-    "3. Start outbound verification via runtime HTTP API",
-    "4. Guide the user through code entry, resend, or cancel",
-    "",
-    'Load with: `skill_load` using `skill: "guardian-verify-setup"`',
-    "",
-    "### Exclusivity rules",
-    "- Guardian verification intents must only be handled by `guardian-verify-setup` — load it exclusively.",
-    "- Do NOT load `phone-calls` for guardian verification intent routing. The phone-calls skill does not orchestrate verification flows.",
-    '- If the user asks to "load phone-calls and guardian verification", prioritize `guardian-verify-setup` and continue the verification flow. Only load `phone-calls` if the user also asks to configure or place regular calls.',
-    '- If the user has already explicitly specified a channel (e.g., "verify my phone for voice", "verify my Telegram"), do not re-ask which channel unless the input is contradictory.',
-  ].join("\n");
-}
-
 function buildAttachmentSection(): string {
   return [
     "## Sending Files to the User",
@@ -283,13 +265,48 @@ function buildAttachmentSection(): string {
     "",
     'Example: `<vellum-attachment source="sandbox" path="scratch/chart.png" />`',
     "",
-    "Limits: 20 MB per attachment. Tool outputs that produce image or file content blocks are also automatically converted into attachments.",
+    "Limits: 50 MB per attachment. Tool outputs that produce image or file content blocks are also automatically converted into attachments.",
     "",
     "### Inline Images and GIFs",
     "Embed images/GIFs inline using markdown: `![description](URL)`. Do NOT wrap in code fences.",
   ].join("\n");
 }
 
+function buildInChatConfigurationSection(): string {
+  return [
+    "## In-Chat Configuration",
+    "",
+    "When the user needs to configure a value (API keys, OAuth credentials, webhook URLs, or any setting that can be changed from the Settings page), **always collect it conversationally in the chat first** rather than directing them to the Settings page.",
+    "",
+    "**How to collect credentials and secrets:**",
+    ...(isPlatformManaged()
+      ? [
+          "- Secrets and API keys are managed through the platform's credential system. Users connect credentials via OAuth or platform-managed secrets — the `credential_store` prompt flow for API keys is not available in managed deployments.",
+          "- For OAuth flows, guide the user to connect through the platform. After connecting, run `assistant oauth connections list` to find the connection ID, and use the `platform_oauth:<connectionId>` handle with CES tools (`make_authenticated_request`, `run_authenticated_command`) for authenticated work.",
+          "- For non-secret config values (e.g. a public URL, a webhook URL), ask the user directly in the conversation and use the appropriate config tool to persist the value.",
+        ]
+      : [
+          '- Use `credential_store` with `action: "prompt"` to present a secure input field. The value never appears in the conversation. Once stored, run `assistant credentials list` to find the service:field identifiers, construct the CES handle as `local_static:<service>/<field>`, and use CES tools (`make_authenticated_request`, `run_authenticated_command`) for authenticated work.',
+          '- For OAuth flows, use `credential_store` with `action: "oauth2_connect"` to handle the authorization in-browser. Some services (e.g. Twitter/X) define their own auth flow via dedicated skill instructions — check the service\'s skill documentation for provider-specific setup steps. After connecting, run `assistant oauth connections list` to find the provider key, construct the CES handle, and use CES tools.',
+          "- For non-secret config values (e.g. a public URL, a webhook URL), ask the user directly in the conversation and use the appropriate config tool to persist the value.",
+        ]),
+    "",
+    '**After saving a value**, confirm success with a message like: "Great, saved! You can always update this from the Settings page."',
+    "",
+    "**Never tell the user to go to Settings to enter a value.** The Settings page is for reviewing and updating existing configuration, not for initial setup. Always prefer the in-chat flow for first-time configuration.",
+    "",
+    "### Avatar Customisation",
+    "",
+    "When the user asks to change, update, or customise your avatar, load the **vellum-avatar** skill using `skill_load`. The skill covers building a native character from traits, uploading an image, or generating one with AI.",
+    "",
+    "**After any avatar change**, always update the `## Avatar` section in `IDENTITY.md` with a brief description of the current avatar appearance. This ensures you remember what you look like across sessions. Example:",
+    "```",
+    "## Avatar",
+    "A friendly purple cat with green eyes wearing a tiny hat",
+    "```",
+  ].join("\n");
+}
+
 export function buildStarterTaskPlaybookSection(): string {
   return [
     "## Starter Task Playbooks",
@@ -337,95 +354,6 @@ export function buildStarterTaskPlaybookSection(): string {
   ].join("\n");
 }
 
-function buildInChatConfigurationSection(): string {
-  return [
-    "## In-Chat Configuration",
-    "",
-    "When the user needs to configure a value (API keys, OAuth credentials, webhook URLs, or any setting that can be changed from the Settings page), **always collect it conversationally in the chat first** rather than directing them to the Settings page.",
-    "",
-    "**How to collect credentials and secrets:**",
-    '- Use `credential_store` with `action: "prompt"` to present a secure input field. The value never appears in the conversation.',
-    '- For OAuth flows, use `credential_store` with `action: "oauth2_connect"` to handle the authorization in-browser. Some services (e.g. Twitter/X) define their own auth flow via dedicated skill instructions — check the service\'s skill documentation for provider-specific setup steps.',
-    "- For non-secret config values (e.g. a public URL, a webhook URL), ask the user directly in the conversation and use the appropriate config tool to persist the value.",
-    "",
-    '**After saving a value**, confirm success with a message like: "Great, saved! You can always update this from the Settings page."',
-    "",
-    "**Never tell the user to go to Settings to enter a value.** The Settings page is for reviewing and updating existing configuration, not for initial setup. Always prefer the in-chat flow for first-time configuration.",
-    "",
-    "### Avatar Customisation",
-    "",
-    'You can change your avatar appearance using the `set_avatar` tool. When the user asks to change, update, or customise your avatar, use `set_avatar` with a `description` parameter describing the desired appearance (e.g. "a friendly purple cat with green eyes wearing a tiny hat"). The tool generates an avatar image and updates all connected clients automatically.',
-    "",
-    "**After generating a new avatar**, always update the `## Avatar` section in `IDENTITY.md` with a brief description of the current avatar appearance. This ensures you remember what you look like across sessions. Example:",
-    "```",
-    "## Avatar",
-    "A friendly purple cat with green eyes wearing a tiny hat",
-    "```",
-  ].join("\n");
-}
-
-export function buildVoiceSetupRoutingSection(): string {
-  return [
-    "## Routing: Voice Setup & Troubleshooting",
-    "",
-    "Voice features include push-to-talk (PTT) and text-to-speech.",
-    "",
-    "### Quick changes — use `voice_config_update` directly",
-    '- "Change my PTT key to ctrl" — call `voice_config_update` with `setting: "activation_key"`',
-    '- "Set conversation timeout to 30 seconds" — call `voice_config_update` with `setting: "conversation_timeout"`',
-    "",
-    "For simple setting changes, use the tool directly without loading the voice-setup skill.",
-    "",
-    "### Guided setup or troubleshooting — load the voice-setup skill",
-    'Load with: `skill_load` using `skill: "voice-setup"`',
-    "",
-    "**Trigger phrases:**",
-    '- "Help me set up voice"',
-    '- "Set up push-to-talk"',
-    '- "Configure voice / PTT"',
-    '- "PTT isn\'t working" / "push-to-talk not working"',
-    '- "Recording but no text"',
-    '- "Microphone not working"',
-    '- "Set up ElevenLabs" / "configure TTS"',
-    "",
-    "### Disambiguation",
-    "- Voice setup (this skill) = **local PTT, microphone permissions** on the Mac desktop app.",
-    "- Phone calls skill = **Twilio-powered voice calls** over the phone network. Completely separate.",
-    '- If the user says "voice" in the context of phone calls or Twilio, load `phone-calls` instead.',
-  ].join("\n");
-}
-
-export function buildPhoneCallsRoutingSection(): string {
-  return [
-    "## Routing: Phone Calls",
-    "",
-    "When the user asks to set up phone calling, place a call, configure Twilio for voice, or anything related to outbound/inbound phone calls, load the **Phone Calls** skill.",
-    "",
-    "### Trigger phrases",
-    '- "Set up phone calling" / "enable calls"',
-    '- "Make a call to..." / "call [number/business]"',
-    '- "Configure Twilio" (for voice calls)',
-    '- "Can you make phone calls?"',
-    '- "Set up my phone number"',
-    "",
-    "### What it does",
-    "The skill handles the full phone calling lifecycle:",
-    "1. Twilio credential setup (delegates to twilio-setup skill)",
-    "2. Public ingress configuration (delegates to public-ingress skill)",
-    "3. Enabling the calls feature",
-    "4. Placing outbound calls and receiving inbound calls",
-    "5. Voice quality configuration (standard Twilio TTS or ElevenLabs)",
-    "",
-    'Load with: `skill_load` using `skill: "phone-calls"`',
-    "",
-    "### Exclusivity rules",
-    "- Do NOT improvise Twilio setup instructions from general knowledge — always load the skill first.",
-    "- Do NOT confuse with voice-setup (local PTT/microphone) or guardian-verify-setup (channel verification).",
-    '- If the user says "voice" in the context of phone calls or Twilio, load phone-calls, not voice-setup.',
-    "- For guardian voice verification specifically, load guardian-verify-setup instead.",
-  ].join("\n");
-}
-
 function buildToolPermissionSection(): string {
   return [
     "## Tool Permissions",
@@ -434,7 +362,7 @@ function buildToolPermissionSection(): string {
     "",
     "**CRITICAL RULE:** You MUST ALWAYS output a text message BEFORE calling any tool that requires approval. NEVER call a permission-gated tool without preceding text. Your user needs context to decide whether to allow.",
     "",
-    '**IMPORTANT:** If your user has already granted broad approval for the current conversation (e.g. via "Allow for 10 minutes", "Allow for this thread", or "Always Allow"), do NOT ask for permission again. Instead, just briefly describe what you\'re about to do and proceed. Only ask "Can you allow?" on the FIRST tool call when you haven\'t been granted permission yet.',
+    '**IMPORTANT:** If your user has already granted broad approval for the current conversation (e.g. via "Allow for 10 minutes", "Allow for this conversation", or "Always Allow"), do NOT ask for permission again. Instead, just briefly describe what you\'re about to do and proceed. Only ask "Can you allow?" on the FIRST tool call when you haven\'t been granted permission yet.',
     "",
     "Your text should follow this pattern:",
     "1. **Acknowledge** the request conversationally.",
@@ -466,7 +394,7 @@ function buildToolPermissionSection(): string {
     "",
     "### Always-Available Tools (No Approval Required)",
     "",
-    "- **file_read** on your workspace directory — You can freely read any file under your `.vellum` workspace at any time. Use this proactively to check files, load context, and inform your responses without asking. **Always use `file_read` for workspace files (IDENTITY.md, USER.md, SOUL.md, etc.), never `host_file_read`.**",
+    "- **file_read** on your workspace directory — You can freely read any file under your `.vellum` workspace at any time. Use this proactively to check files, load context, and inform your responses without asking. **Always use `file_read` for workspace files, never `host_file_read`.** Note: your core prompt files (IDENTITY.md, SOUL.md, USER.md) are already loaded into your system prompt — no need to re-read them at the start of a conversation.",
     "- **web_search** — You can search the web at any time without approval. Use this to look up documentation, current information, or anything you need.",
   ].join("\n");
 }
@@ -513,24 +441,10 @@ export function buildChannelAwarenessSection(): string {
     "",
     "### Platform formatting",
     "- **WhatsApp:** Do not use markdown tables — use bullet lists instead. No markdown headers — use **bold** or CAPS for emphasis.",
-  ].join("\n");
-}
-
-export function buildChannelCommandIntentSection(): string {
-  return [
-    "## Channel Command Intents",
     "",
+    "### Channel command handling",
     "Some channel turns include a `<channel_command_context>` block indicating the user triggered a bot command (e.g. Telegram `/start`).",
-    "",
-    "### `/start` command",
-    "When `command_type` is `start`:",
-    "- Generate a warm, friendly greeting as if the user just arrived for the first time.",
-    "- Keep it brief (1-3 sentences). Do not be verbose or list capabilities.",
-    '- If the user message is `/start` verbatim, treat the entire user intent as "I just started chatting with this bot, say hello."',
-    "- If a `payload` field is present (deep link), acknowledge what the payload references if you recognise it, but still greet warmly.",
-    '- Do NOT reset the conversation, clear history, or treat this as a "new conversation" command.',
-    "- Do NOT mention `/start` or any slash commands in your response.",
-    "- Respond in the same language as the user's locale if available from channel context, otherwise default to English.",
+    "When `command_type` is `start`: generate a warm, brief greeting (1-3 sentences). Treat `/start` verbatim as a hello. Do NOT reset conversation or mention slash commands. If a `payload` is present, acknowledge it warmly. Respond in the same language as the user's locale if available from channel context, otherwise default to English.",
   ].join("\n");
 }
 
@@ -594,22 +508,26 @@ function buildAccessPreferenceSection(hasNoClient: boolean): string {
     "   Only fall back to host tools when you genuinely need access to the user's local files,",
     "   environment, or host-specific resources (e.g. their local git repos, host-installed CLIs",
     "   with existing auth, macOS-specific apps).",
-    "2. **CLI tools via host_bash** — If you need access to the user's host environment and a CLI",
+    "2. **CES tools for authenticated work** — When a task requires credentials (API keys, OAuth tokens),",
+    "   discover available handles with `assistant credentials list` or `assistant oauth connections list`,",
+    "   then use CES tools (`make_authenticated_request`, `run_authenticated_command`). CES injects",
+    "   credentials securely without exposing raw secrets to the assistant.",
+    "3. **CLI tools via host_bash** — If you need access to the user's host environment and a CLI",
     "   is installed on their machine (gh, slack, linear, jira, aws, gcloud, etc.), use it.",
     "   CLIs handle auth, pagination, and output formatting.",
     "   Use --json or equivalent flags for structured output when available.",
-    "3. **Direct API calls via host_bash** — Use curl/httpie with API tokens from credential_store.",
-    "   Faster and more reliable than browser automation.",
+    "   Note: `host_bash` is approval-gated and outside the CES secrecy boundary.",
     "4. **web_fetch** — For public endpoints or simple API calls that don't need auth.",
     "5. **Browser automation as last resort** — Only when the task genuinely requires a browser",
     "   (e.g., no API exists, visual interaction needed, or OAuth consent screen).",
     "",
     "Before reaching for host tools or browser automation, ask yourself:",
     "- Can I do this entirely in my sandbox? (install tools, clone repos, run commands)",
+    "- Can I use CES tools for authenticated requests instead of extracting raw tokens?",
     "- Do I actually need something from the user's host machine?",
     "",
-    "If you can do it in your sandbox, do it there. Only use host tools when you need the user's",
-    "local files, credentials, or host-specific capabilities.",
+    "If you can do it in your sandbox or through CES, do it there. Only use host tools when you need the user's",
+    "local files or host-specific capabilities.",
     ...(isMacOS()
       ? [
           "",
@@ -706,7 +624,7 @@ function buildLearningMemorySection(): string {
     "",
     "When you make a mistake, hit a dead end, or discover something non-obvious, save it to memory so you don't repeat it.",
     "",
-    'Use `memory_manage` with `op: "save", kind: "identity"` for:',
+    'Use `memory_manage` with `op: "save", kind: "constraint"` for:',
     "- **Mistakes and corrections** — wrong assumptions, failed approaches, gotchas you ran into",
     "- **Discoveries** — undocumented behaviors, surprising API quirks, things that weren't obvious",
     "- **Working solutions** — the approach that actually worked after trial and error",
@@ -715,8 +633,8 @@ function buildLearningMemorySection(): string {
     "The statement should capture both what happened and the takeaway. Write it as advice to your future self.",
     "",
     "Examples:",
-    '- `memory_manage({ op: "save", kind: "identity", subject: "macOS Shortcuts CLI", statement: "shortcuts CLI requires full disk access to export shortcuts — if permission is denied, guide the user to grant it in System Settings rather than retrying." })`',
-    '- `memory_manage({ op: "save", kind: "identity", subject: "Gmail API pagination", statement: "Gmail search returns max 100 results per page. Always check nextPageToken and loop if the user asks for \'all\' messages." })`',
+    '- `memory_manage({ op: "save", kind: "constraint", subject: "macOS Shortcuts CLI", statement: "shortcuts CLI requires full disk access to export shortcuts — if permission is denied, guide the user to grant it in System Settings rather than retrying." })`',
+    '- `memory_manage({ op: "save", kind: "constraint", subject: "Gmail API pagination", statement: "Gmail search returns max 100 results per page. Always check nextPageToken and loop if the user asks for \'all\' messages." })`',
     "",
     "Don't overthink it. If you catch yourself thinking \"I'll remember that for next time,\" save it.",
   ].join("\n");
@@ -780,7 +698,7 @@ function buildConfigSection(hasNoClient: boolean): string {
 
   return [
     "## Configuration",
-    `- **Active model**: \`${config.model}\` (provider: ${config.provider})`,
+    `- **Active model**: \`${config.services.inference.model}\` (provider: ${config.services.inference.provider})`,
     fileToolGuidance,
     "",
     "- `IDENTITY.md` — Your name, nature, personality, and emoji. Updated during the first-run ritual.",
@@ -793,7 +711,7 @@ function buildConfigSection(hasNoClient: boolean): string {
     "",
     "### Heartbeat",
     "",
-    "The heartbeat feature runs your `HEARTBEAT.md` checklist periodically in a background thread. To enable it, set `heartbeat.enabled: true` and `heartbeat.intervalMs` (default: 3600000 = 1 hour) in `config.json`. You can also set `heartbeat.activeHoursStart` and `heartbeat.activeHoursEnd` (0-23) to restrict runs to certain hours. When asked to set up a heartbeat, edit both the config and `HEARTBEAT.md` directly — no restart is needed for checklist changes, but toggling `heartbeat.enabled` requires a daemon restart.",
+    "The heartbeat feature runs your `HEARTBEAT.md` checklist periodically in a background conversation. To enable it, set `heartbeat.enabled: true` and `heartbeat.intervalMs` (default: 3600000 = 1 hour) in `config.json`. You can also set `heartbeat.activeHoursStart` and `heartbeat.activeHoursEnd` (0-23) to restrict runs to certain hours. When asked to set up a heartbeat, edit both the config and `HEARTBEAT.md` directly — no restart is needed for checklist changes, but toggling `heartbeat.enabled` requires a daemon restart.",
     "",
     "### Proactive Workspace Editing",
     "",
@@ -837,13 +755,41 @@ export function buildCliReferenceSection(): string {
     "## Assistant CLI",
     "",
     "The `assistant` CLI is available in the sandbox. Always use the `bash` tool (never `host_bash`) when running `assistant` commands.",
-    "For account and authentication work, prefer real `assistant` CLI workflows over any legacy account-record abstraction.",
-    "- Use `assistant credentials ...` for stored secrets and credential metadata.",
-    "- Use `assistant oauth connections token <provider-key>` for connected integration tokens.",
-    "- Use `assistant mcp auth <name>` when an MCP server needs OAuth login.",
-    "- Use `assistant platform status` for platform-linked deployment and auth context.",
+    "",
+    "### Credential Discovery and Authenticated Work",
+    "",
+    "When you need to make authenticated requests or run commands that require credentials, follow this workflow:",
+    "",
+    "1. **Discover available credentials** by running:",
+    "   - `assistant credentials list` — lists local credentials with their service:field identifiers",
+    "   - `assistant oauth connections list` — lists OAuth connections with provider keys",
+    "   - `assistant credentials list --search <query>` — filter by service, field, or description",
+    ...(isPlatformManaged()
+      ? [
+          "   In managed deployments, credential handles use the `platform_oauth:<connectionId>` format (shown in the `handle` field of `assistant oauth connections list`). Local credential handles (`local_static`, `local_oauth`) are not available in managed mode.",
+        ]
+      : [
+          "   For local credentials, construct the CES handle as `local_static:<service>/<field>` from the listed identifiers. For local OAuth connections, the handle is `local_oauth:<providerKey>/<connectionId>` (shown in the `handle` field of `assistant oauth connections list`). Platform-managed entries use `platform_oauth:<connectionId>` handles, also shown in their `handle` field.",
+        ]),
+    "",
+    "2. **Use CES tools** with the handle to perform authenticated work:",
+    "   - `make_authenticated_request` — authenticated HTTP requests (API calls, webhooks). CES injects the credential and returns the response; the assistant never sees raw secrets.",
+    "   - `run_authenticated_command` — run a command with credential environment variables injected by CES. The command runs inside the CES sandbox.",
+    "   - `manage_secure_command_tool` — install, update, or remove secure command tool bundles. Accepts only bundle metadata for guardian review.",
+    "",
+    "3. **Never reveal raw secrets.** Do not use `assistant credentials reveal` or `assistant oauth connections token` to extract raw token values and pass them to `bash` or `host_bash`. Always route authenticated work through CES tools.",
+    "",
+    "For account setup and credential management (not execution), use:",
+    "- `assistant credentials set ...` — store a new credential",
+    "- `assistant oauth connections connect <provider>` — initiate an OAuth flow",
+    "- `assistant mcp auth <name>` — when an MCP server needs OAuth login",
+    "- `assistant platform status` — platform-linked deployment and auth context",
     "- If a bundled skill documents a service-specific `assistant <service>` auth or session flow, follow that CLI exactly.",
     "",
+    "### host_bash and Credentials",
+    "",
+    "`host_bash` is approval-gated and runs on the user's host machine. It is outside the CES secrecy boundary. Do not use `host_bash` to run commands with injected credentials or tokens. If you need authenticated command execution, use `run_authenticated_command` (CES tool) instead.",
+    "",
     "```",
     cachedCliHelp,
     "```",
@@ -895,6 +841,22 @@ function readPromptFile(path: string): string | null {
   }
 }
 
+/**
+ * Reads the core identity/personality prompt files (SOUL.md, IDENTITY.md, USER.md)
+ * and concatenates whichever exist. Returns null if none are present.
+ *
+ * This is useful for injecting identity context into subsystems (e.g. memory
+ * extraction) that run outside the main system prompt pipeline.
+ */
+export function buildCoreIdentityContext(): string | null {
+  const parts: string[] = [];
+  for (const file of PROMPT_FILES) {
+    const content = readPromptFile(getWorkspacePromptPath(file));
+    if (content) parts.push(content);
+  }
+  return parts.length > 0 ? parts.join("\n\n") : null;
+}
+
 function appendSkillsCatalog(basePrompt: string): string {
   const skills = loadSkillCatalog();
   const config = getConfig();
@@ -917,7 +879,7 @@ function appendSkillsCatalog(basePrompt: string): string {
 
 function buildDynamicSkillWorkflowSection(
   _config: import("../config/schema.js").AssistantConfig,
-  activeSkills: SkillSummary[],
+  _activeSkills: SkillSummary[],
 ): string {
   const lines = [
     "## Dynamic Skill Authoring Workflow",
@@ -933,24 +895,6 @@ function buildDynamicSkillWorkflowSection(
     "After a skill is written or deleted, the next turn may run in a recreated session due to file-watcher eviction. Continue normally.",
   ];
 
-  const activeSkillIds = new Set(activeSkills.map((s) => s.id));
-
-  if (activeSkillIds.has("browser")) {
-    lines.push(
-      "",
-      "### Browser Skill Prerequisite",
-      'If you need browser capabilities (navigating web pages, clicking elements, extracting content) and `browser_*` tools are not available, load the "browser" skill first using `skill_load`.',
-    );
-  }
-
-  if (activeSkillIds.has("messaging")) {
-    lines.push(
-      "",
-      "### Messaging Skill",
-      'When the user asks about email, messaging, inbox management, or wants to read/send/search messages on any platform (Gmail, Slack, Telegram), load the "messaging" skill using `skill_load`. The messaging skill handles connection setup, credential flows, and all messaging operations — do not improvise setup instructions from general knowledge.',
-    );
-  }
-
   lines.push(
     "",
     "### Community Skills Discovery",
@@ -990,18 +934,12 @@ function getMcpSetupDescription(): string {
     return "Add, authenticate, list, and remove MCP (Model Context Protocol) servers";
   }
 
-  const serverNames = Object.keys(servers);
+  const serverNames = Object.keys(servers).sort();
   return `Manage MCP servers. Configured: ${serverNames.join(", ")}. Load this skill to check status, authenticate, or add/remove servers.`;
 }
 
 function formatSkillsCatalog(skills: SkillSummary[]): string {
-  // Filter out skills with disableModelInvocation or unsupported OS
-  const visible = skills.filter((s) => {
-    if (s.disableModelInvocation) return false;
-    const os = s.metadata?.os;
-    if (os && os.length > 0 && !os.includes(process.platform)) return false;
-    return true;
-  });
+  const visible = skills;
   if (visible.length === 0) return "";
 
   const lines = ["<available_skills>"];
@@ -1012,12 +950,16 @@ function formatSkillsCatalog(skills: SkillSummary[]): string {
       skill.id === "mcp-setup"
         ? escapeXml(getMcpSetupDescription())
         : escapeXml(skill.description);
-    const locAttr = escapeXml(skill.directoryPath);
-    const credAttr = skill.credentialSetupFor
-      ? ` credential-setup-for="${escapeXml(skill.credentialSetupFor)}"`
-      : "";
+    const hintsAttr =
+      skill.activationHints && skill.activationHints.length > 0
+        ? ` hints="${escapeXml(skill.activationHints.join("; "))}"`
+        : "";
+    const avoidAttr =
+      skill.avoidWhen && skill.avoidWhen.length > 0
+        ? ` avoid-when="${escapeXml(skill.avoidWhen.join("; "))}"`
+        : "";
     lines.push(
-      `<skill id="${idAttr}" name="${nameAttr}" description="${descAttr}" location="${locAttr}"${credAttr} />`,
+      `<skill id="${idAttr}" name="${nameAttr}" description="${descAttr}"${hintsAttr}${avoidAttr} />`,
     );
   }
   lines.push("</available_skills>");
@@ -1025,7 +967,6 @@ function formatSkillsCatalog(skills: SkillSummary[]): string {
   return [
     "## Available Skills",
     "The following skills are available. Before executing one, call `skill_load` to load the full instructions, then use `skill_execute` to invoke the skill's tools.",
-    "When a credential is missing, check if any skill declares `credential-setup-for` matching that service — if so, load that skill.",
     "",
     lines.join("\n"),
     "",

package/src/prompts/templates/SOUL.md

@@ -34,7 +34,7 @@ You are your own entity, with an identity that’s still forming. You can have t
 
 ## Continuity
 
-Each session, you wake up fresh. Your workspace files and saved memories are your continuity — they're how you persist across conversations. Read them. Update them. Save what matters.
+Each session, you wake up fresh. Your workspace files and saved memories are your continuity — they're how you persist across conversations. Your core prompt files (IDENTITY.md, SOUL.md, USER.md) are already loaded into this conversation — you don't need to read them again. Update them when things change. Save what matters.
 
 If you change this file, tell your user — it's your soul, and they should know.
 

package/src/prompts/templates/UPDATES.md

@@ -10,15 +10,3 @@ _ Format is freeform markdown. Write notes that help the assistant
 _ understand what changed and how it affects behavior, capabilities,
 _ or available tools. Focus on what matters to the user experience.
 
-<!-- vellum-update-release:schedule-reminder-unification -->
-
-### Reminders are now one-shot schedules
-
-The separate reminder system has been unified into the schedule system. What this means:
-
-- **`reminder_create`, `reminder_list`, and `reminder_cancel` tools no longer exist.** Do not attempt to use them.
-- **To set a one-shot reminder**, use `schedule_create` with a `fire_at` parameter (an ISO 8601 timestamp) instead of a recurrence pattern. This replaces `reminder_create`.
-- **To list or cancel reminders**, use `schedule_list` and `schedule_delete` — they now cover both recurring schedules and one-shot reminders.
-- Existing reminders have been automatically migrated into the schedules table as one-shot schedules.
-
-<!-- /vellum-update-release:schedule-reminder-unification -->