@code-yeongyu/senpi 2026.8.16 → 2026.8.17

package/dist/core/agent-session.js

@@ -48,7 +48,7 @@ import { filterContextExcludedMessages } from "./messages.js";
 import { ModelRegistry } from "./model-registry.js";
 import { getModelNarrowingPatterns, resolveModelScope } from "./model-resolver.js";
 import { PROMPT_CACHE_SAFE_WAIT_ENV, resolvePromptCacheSafeWaitSeconds } from "./prompt-cache-budget.js";
-import { expandPromptTemplate } from "./prompt-templates.js";
+import { expandPromptTemplateWithMetadata } from "./prompt-templates.js";
 import { createProviderTimeoutRetryPlan, runBoundedRetryContinuation } from "./provider-timeout-retry.js";
 import { isBillingErrorMessage } from "./retry-fallback/billing.js";
 import { formatSelector } from "./retry-fallback/chains.js";
@@ -71,12 +71,14 @@ import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
 const TURN_RETRY_SUPPRESSION_PREFIX = "senpi:no-turn-retry:";
+const DEFERRED_RETRY_QUEUE_OWNERS = new WeakSet();
 /** Format the user-attributed payload for one or more explicit skill invocations. */
 export function formatSkillInvocationPrompt(skills, userRequest) {
     const skillBlocks = skills.map((skill) => `The user explicitly invoked the "${skill.name}" skill. Follow the instructions in <skill-instruction> as binding for this request, while respecting higher-priority instructions.\n\n<skill-instruction name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${skill.body}\n</skill-instruction>`);
     const expandedSkills = skillBlocks.join("\n\n");
-    const trimmedRequest = userRequest?.trim();
-    return trimmedRequest ? `${expandedSkills}\n\n<user-request>\n${trimmedRequest}\n</user-request>` : expandedSkills;
+    return userRequest && /\S/.test(userRequest)
+        ? `${expandedSkills}\n\n<user-request>\n${userRequest}\n</user-request>`
+        : expandedSkills;
 }
 /**
  * Parse a skill block from message text.
@@ -115,6 +117,86 @@ export function parseSkillBlock(text) {
         userMessage: legacyMatch[4]?.trim() || undefined,
     };
 }
+export const MAX_SKILL_INVOCATION_TOKENS_PER_PROMPT = 64;
+const LEADING_SKILL_INVOCATION_PATTERN = /^(?:\/skill:([a-zA-Z][a-zA-Z0-9:_-]*)|\$([a-zA-Z][a-zA-Z0-9:_-]*))(?=\s|$)/;
+const INLINE_DOLLAR_SKILL_INVOCATION_PATTERN = /(^|\s)\$skill:([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+/**
+ * Find explicit skill invocation tokens without treating ordinary inline dollar
+ * prose (for example `$HOME`) as executable.
+ *
+ * Leading runs accept `/skill:name`, `$name`, and `$skill:name`. Outside the
+ * leading run only the desktop's explicit `$skill:name` token is executable.
+ */
+export function parseSkillInvocationTokens(text) {
+    const tokens = [];
+    let cursor = 0;
+    while (cursor < text.length) {
+        while (cursor < text.length && /\s/.test(text[cursor]))
+            cursor++;
+        const match = text.slice(cursor).match(LEADING_SKILL_INVOCATION_PATTERN);
+        if (!match)
+            break;
+        const syntax = match[1] ? "slash" : "dollar";
+        const dollarName = match[2];
+        const name = match[1] ?? (dollarName?.startsWith("skill:") ? dollarName.slice("skill:".length) : dollarName);
+        if (!name)
+            break;
+        tokens.push({
+            name,
+            syntax,
+            start: cursor,
+            end: cursor + match[0].length,
+            position: "leading",
+        });
+        if (tokens.length >= MAX_SKILL_INVOCATION_TOKENS_PER_PROMPT)
+            return tokens;
+        cursor += match[0].length;
+    }
+    INLINE_DOLLAR_SKILL_INVOCATION_PATTERN.lastIndex = cursor;
+    for (const match of text.matchAll(INLINE_DOLLAR_SKILL_INVOCATION_PATTERN)) {
+        const start = (match.index ?? 0) + match[1].length;
+        tokens.push({
+            name: match[2],
+            syntax: "dollar",
+            start,
+            end: start + `$skill:${match[2]}`.length,
+            position: "inline",
+        });
+        if (tokens.length >= MAX_SKILL_INVOCATION_TOKENS_PER_PROMPT)
+            break;
+    }
+    return tokens;
+}
+function stripLeadingInvocationSeparators(text) {
+    let cursor = 0;
+    while (text[cursor] === " " || text[cursor] === "\t")
+        cursor++;
+    while (text[cursor] === "\n" || (text[cursor] === "\r" && text[cursor + 1] === "\n")) {
+        cursor += text[cursor] === "\r" ? 2 : 1;
+        const lineStart = cursor;
+        while (text[cursor] === " " || text[cursor] === "\t")
+            cursor++;
+        if (text[cursor] !== "\n" && !(text[cursor] === "\r" && text[cursor + 1] === "\n")) {
+            return text.slice(lineStart);
+        }
+    }
+    return text.slice(cursor);
+}
+function removeSkillInvocationTokens(text, tokens) {
+    let cursor = 0;
+    let result = "";
+    for (const token of tokens) {
+        result += text.slice(cursor, token.start);
+        cursor = token.end;
+        if (token.position === "inline" &&
+            (result.endsWith(" ") || result.endsWith("\t")) &&
+            (text[cursor] === " " || text[cursor] === "\t")) {
+            cursor++;
+        }
+    }
+    result += text.slice(cursor);
+    return tokens.some((token) => token.position === "leading") ? stripLeadingInvocationSeparators(result) : result;
+}
 // ============================================================================
 // Types
 // ============================================================================
@@ -547,7 +629,7 @@ export class AgentSession {
         this.agent.beforeToolCall = async ({ toolCall, args }) => {
             this._toolExecutionDepth++;
             try {
-                const result = await this._emitBeforeToolCallHooks(toolCall, args);
+                const result = await this.preflightToolCall(toolCall, args);
                 if (result?.block) {
                     this._toolExecutionDepth--;
                 }
@@ -567,7 +649,7 @@ export class AgentSession {
             }
         };
     }
-    async _emitBeforeToolCallHooks(toolCall, args, options = {}) {
+    async preflightToolCall(toolCall, args, options = {}) {
         if (options.waitForEventQueue !== false) {
             await this._agentEventQueue;
         }
@@ -1232,6 +1314,7 @@ export class AgentSession {
         // Check auto-retry and auto-compaction after agent completes.
         let launchedContinuation = false;
         let retryContinuationBlocked = false;
+        let retryExhaustionAllowsQueuedContinuation = false;
         let allowsPostCompactionUsageExemptContinuation = false;
         const userAbortSuppressedQueuedContinuation = event.type === "agent_end" && this._suppressQueuedContinuationAfterUserAbort;
         if (userAbortSuppressedQueuedContinuation) {
@@ -1261,6 +1344,8 @@ export class AgentSession {
                 retryContinuationBlocked = !compactedBeforeRetry && !this._isCompactionDelegated();
             }
             let retryOutcome = "not-handled";
+            const retryOwnedDeferredQueue = DEFERRED_RETRY_QUEUE_OWNERS.has(this);
+            DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
             if (!retryContinuationBlocked && !userAbortSuppressedQueuedContinuation) {
                 if (retryableError) {
                     retryOutcome = await this._handleRetryableError(msg);
@@ -1273,6 +1358,16 @@ export class AgentSession {
                 this._abortProvenance.closeAgentEndBoundary();
                 return;
             }
+            // Provider-timeout retries deliberately skip their first queue poll so
+            // steering cannot be consumed by another doomed retry request. Once the
+            // managed retry owner exhausts its budget, hand that retained queue back
+            // to the normal scheduled-continuation path instead of parking it until
+            // an unrelated later prompt arrives.
+            retryExhaustionAllowsQueuedContinuation =
+                !userAbortSuppressedQueuedContinuation &&
+                    retryOwnedDeferredQueue &&
+                    retryOutcome === "not-handled" &&
+                    (msg.stopReason === "error" || msg.stopReason === "aborted");
             if (retryOutcome === "not-handled" && this._retryAttempt > 0 && msg.errorMessage) {
                 const attempt = this._retryAttempt;
                 this._retryAttempt = 0;
@@ -1317,7 +1412,9 @@ export class AgentSession {
             this._flushPendingBashMessages();
             if (!launchedContinuation &&
                 !retryContinuationBlocked &&
-                (allowsQueuedContinuation || allowsPostCompactionUsageExemptContinuation) &&
+                (allowsQueuedContinuation ||
+                    allowsPostCompactionUsageExemptContinuation ||
+                    retryExhaustionAllowsQueuedContinuation) &&
                 this.agent.hasQueuedMessages()) {
                 // A scheduled continuation owns the queue now; the stored admission
                 // rejection from a superseded required compaction must not surface.
@@ -1798,7 +1895,7 @@ export class AgentSession {
         catch (err) {
             throw new ExecuteToolError("invalid_params", toolName, err instanceof Error ? err.message : String(err), activeTools);
         }
-        const beforeResult = await this._emitBeforeToolCallHooks(prepared.toolCall, prepared.args, {
+        const beforeResult = await this.preflightToolCall(prepared.toolCall, prepared.args, {
             waitForEventQueue: this._toolExecutionDepth === 0,
         });
         if (beforeResult?.block) {
@@ -1845,6 +1942,15 @@ export class AgentSession {
      * Also rebuilds the system prompt to reflect the new tool set.
      * Changes take effect on the next agent turn.
      */
+    /**
+     * Resolve an executable tool from the full registry (builtin + extension
+     * tools), independent of the active set. The Cursor exec bridge uses this:
+     * Cursor drives its native tools (read/bash/grep/ls/write) over the exec
+     * channel regardless of which tools the request advertised.
+     */
+    getRegisteredTool(name) {
+        return this._toolRegistry.get(name);
+    }
     setActiveToolsByName(toolNames) {
         const tools = [];
         const validToolNames = [];
@@ -2107,6 +2213,13 @@ export class AgentSession {
         let titlePrompt;
         let consumedNextTurnMessages;
         let inputId;
+        let pendingCommandInvocation;
+        const emitPendingCommandInvocation = () => {
+            if (!pendingCommandInvocation)
+                return;
+            this._emit({ type: "command_invocation", command: pendingCommandInvocation });
+            pendingCommandInvocation = undefined;
+        };
         const emitInputDisposition = async (disposition) => {
             if (inputId === undefined)
                 return;
@@ -2135,7 +2248,16 @@ export class AgentSession {
             let expandedText = currentText;
             if (expandPromptTemplates) {
                 expandedText = this._expandSkillCommand(expandedText);
-                expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+                const templateExpansion = expandPromptTemplateWithMetadata(expandedText, [...this.promptTemplates]);
+                expandedText = templateExpansion.text;
+                if (templateExpansion.template) {
+                    pendingCommandInvocation = {
+                        name: templateExpansion.template.name,
+                        source: "prompt",
+                        sourceInfo: templateExpansion.template.sourceInfo,
+                        syntax: "slash",
+                    };
+                }
             }
             titlePrompt = options?.sessionTitlePrompt === false ? undefined : (options?.sessionTitlePrompt ?? text);
             // If streaming, queue via steer() or followUp() based on option
@@ -2152,6 +2274,7 @@ export class AgentSession {
                 else {
                     await this._queueSteer(expandedText, currentImages);
                 }
+                emitPendingCommandInvocation();
                 await emitInputDisposition("queued");
                 promptDisposition?.("queued");
                 preflightResult?.(true);
@@ -2170,6 +2293,7 @@ export class AgentSession {
                 else {
                     await this._queueSteer(expandedText, currentImages);
                 }
+                emitPendingCommandInvocation();
                 await emitInputDisposition("queued");
                 promptDisposition?.("queued");
                 preflightResult?.(true);
@@ -2194,6 +2318,7 @@ export class AgentSession {
                     else {
                         await this._queueSteer(expandedText, currentImages);
                     }
+                    emitPendingCommandInvocation();
                     await emitInputDisposition("queued");
                     promptDisposition?.("queued");
                     preflightResult?.(true);
@@ -2215,6 +2340,7 @@ export class AgentSession {
                 else {
                     await this._queueSteer(expandedText, currentImages);
                 }
+                emitPendingCommandInvocation();
                 await emitInputDisposition("queued");
                 promptDisposition?.("queued");
                 preflightResult?.(true);
@@ -2308,6 +2434,7 @@ export class AgentSession {
             return;
         }
         promptDisposition?.("started");
+        emitPendingCommandInvocation();
         preflightResult?.(true);
         if (options?.thinkingLevel !== undefined) {
             this.setSessionThinkingLevel(options.thinkingLevel);
@@ -2343,6 +2470,15 @@ export class AgentSession {
         const command = this._extensionRunner.getCommand(commandName);
         if (!command)
             return false;
+        this._emit({
+            type: "command_invocation",
+            command: {
+                name: commandName,
+                source: "extension",
+                sourceInfo: command.sourceInfo,
+                syntax: "slash",
+            },
+        });
         // Get command context from extension runner (includes session control methods)
         const ctx = this._extensionRunner.createCommandContext();
         try {
@@ -2360,67 +2496,73 @@ export class AgentSession {
         }
     }
     /**
-     * Expand a leading run of skill commands (/skill:name /skill:other args) to their full content.
-     * Returns the expanded text, or the original text if the first skill command is not found.
-     * Emits errors via extension runner if file reads fail or the expansion cap is reached.
+     * Expand explicit skill invocations to their full content.
+     * Leading runs accept slash and dollar syntax; inline expansion is limited to
+     * the desktop's explicit `$skill:name` token so ordinary dollar prose stays literal.
      */
     _expandSkillCommand(text) {
-        if (!text.startsWith("/skill:"))
+        const invocationTokens = parseSkillInvocationTokens(text);
+        if (invocationTokens.length === 0)
             return text;
         const skills = this.resourceLoader.getSkills().skills;
         const expandedSkillNames = new Set();
         const skillBlocks = [];
-        let tokenStart = 0;
-        while (tokenStart < text.length) {
-            let tokenEnd = tokenStart;
-            while (tokenEnd < text.length && !/\s/.test(text[tokenEnd])) {
-                tokenEnd += 1;
-            }
-            const token = text.slice(tokenStart, tokenEnd);
-            if (!token.startsWith("/skill:"))
-                break;
-            const skillName = token.slice(7);
-            const skill = skills.find((candidate) => candidate.name === skillName);
-            if (!skill)
-                break; // Unknown skills and everything after them remain literal text.
-            if (!expandedSkillNames.has(skill.name)) {
-                if (skillBlocks.length >= MAX_SKILL_EXPANSIONS_PER_PROMPT) {
-                    this._extensionRunner.emitError({
-                        extensionPath: "skill:expansion",
-                        event: "skill_expansion",
-                        error: `Expanded at most ${MAX_SKILL_EXPANSIONS_PER_PROMPT} skills; remaining skill commands were left as literal text.`,
-                    });
+        const invocationMetadata = [];
+        const removedTokens = [];
+        for (const token of invocationTokens) {
+            const skill = skills.find((candidate) => candidate.name === token.name);
+            if (!skill) {
+                if (token.position === "leading")
                     break;
-                }
-                try {
-                    const content = readFileSync(skill.filePath, "utf-8");
-                    const body = stripFrontmatter(content).trim();
-                    skillBlocks.push({
-                        name: skill.name,
-                        filePath: skill.filePath,
-                        baseDir: skill.baseDir,
-                        body,
-                    });
-                    expandedSkillNames.add(skill.name);
-                }
-                catch (err) {
-                    this._extensionRunner.emitError({
-                        extensionPath: skill.filePath,
-                        event: "skill_expansion",
-                        error: err instanceof Error ? err.message : String(err),
-                    });
-                    return text; // Return the original prompt when any skill file cannot be read.
-                }
+                continue;
+            }
+            if (skillBlocks.length >= MAX_SKILL_EXPANSIONS_PER_PROMPT) {
+                this._extensionRunner.emitError({
+                    extensionPath: "skill:expansion",
+                    event: "skill_expansion",
+                    error: `Expanded at most ${MAX_SKILL_EXPANSIONS_PER_PROMPT} skills; remaining skill commands were left as literal text.`,
+                });
+                break;
             }
-            tokenStart = tokenEnd;
-            while (tokenStart < text.length && /\s/.test(text[tokenStart])) {
-                tokenStart += 1;
+            removedTokens.push(token);
+            if (expandedSkillNames.has(skill.name)) {
+                this._extensionRunner.emitError({
+                    extensionPath: skill.filePath,
+                    event: "skill_expansion",
+                    error: `Skipped duplicate skill invocation: ${skill.name}`,
+                });
+                continue;
+            }
+            try {
+                const content = readFileSync(skill.filePath, "utf-8");
+                const body = stripFrontmatter(content).trim();
+                skillBlocks.push({
+                    name: skill.name,
+                    filePath: skill.filePath,
+                    baseDir: skill.baseDir,
+                    body,
+                });
+                expandedSkillNames.add(skill.name);
+                invocationMetadata.push({
+                    name: skill.name,
+                    path: skill.filePath,
+                    syntax: token.syntax,
+                });
+            }
+            catch (err) {
+                this._extensionRunner.emitError({
+                    extensionPath: skill.filePath,
+                    event: "skill_expansion",
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return text; // Return the original prompt when any skill file cannot be read.
             }
         }
         if (skillBlocks.length === 0)
             return text;
-        const args = text.slice(tokenStart).trim();
-        return formatSkillInvocationPrompt(skillBlocks, args);
+        const userRequest = removeSkillInvocationTokens(text, removedTokens);
+        this._emit({ type: "skill_invocation", skills: invocationMetadata });
+        return formatSkillInvocationPrompt(skillBlocks, userRequest);
     }
     /**
      * Queue a steering message while the agent is running.
@@ -2437,8 +2579,20 @@ export class AgentSession {
         }
         // Expand skill commands and prompt templates
         let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        const templateExpansion = expandPromptTemplateWithMetadata(expandedText, [...this.promptTemplates]);
+        expandedText = templateExpansion.text;
         await this._queueSteer(expandedText, images, recovery?.enqueueOrder);
+        if (templateExpansion.template) {
+            this._emit({
+                type: "command_invocation",
+                command: {
+                    name: templateExpansion.template.name,
+                    source: "prompt",
+                    sourceInfo: templateExpansion.template.sourceInfo,
+                    syntax: "slash",
+                },
+            });
+        }
     }
     /**
      * Queue a follow-up message to be processed after the agent finishes.
@@ -2454,8 +2608,20 @@ export class AgentSession {
         }
         // Expand skill commands and prompt templates
         let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
+        const templateExpansion = expandPromptTemplateWithMetadata(expandedText, [...this.promptTemplates]);
+        expandedText = templateExpansion.text;
         await this._queueFollowUp(expandedText, images, recovery?.enqueueOrder);
+        if (templateExpansion.template) {
+            this._emit({
+                type: "command_invocation",
+                command: {
+                    name: templateExpansion.template.name,
+                    source: "prompt",
+                    sourceInfo: templateExpansion.template.sourceInfo,
+                    syntax: "slash",
+                },
+            });
+        }
     }
     _startSessionTitleGeneration(firstPrompt) {
         if (!this._autoTitleSessions || this.sessionManager.getSessionName() || shouldSkipSessionTitle(firstPrompt)) {
@@ -4164,9 +4330,15 @@ export class AgentSession {
         const finishContinuationWork = this._sessionWorkBarrier.begin();
         const continueAfterEvent = async () => {
             try {
-                await this._continueAgentAfterCurrentRun(options, retryTimeoutMs);
+                const outcome = await this._continueAgentAfterCurrentRun(options, retryTimeoutMs);
+                if (retryContinuation && outcome === "taken-over") {
+                    DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
+                }
             }
             catch (error) {
+                if (retryContinuation) {
+                    DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
+                }
                 const message = error instanceof Error ? error.message : String(error);
                 this._emit({
                     type: "continuation_error",
@@ -5333,7 +5505,7 @@ export class AgentSession {
                 finalError: "Retry cancelled",
             });
             this._resolveRetry();
-            return "not-handled";
+            return "cancelled";
         }
         this._retryAbortController = undefined;
         // Turn boundary: a suppression that expired during the backoff sleep lets
@@ -5379,6 +5551,12 @@ export class AgentSession {
             timeoutMs: this.agent.timeoutMs,
             streamStartTimeoutMs: this.agent.streamStartTimeoutMs,
         });
+        if (continuation.options.deferQueuedMessages === true) {
+            DEFERRED_RETRY_QUEUE_OWNERS.add(this);
+        }
+        else {
+            DEFERRED_RETRY_QUEUE_OWNERS.delete(this);
+        }
         this.agent.suppressQueuedMessageDrain();
         this._scheduleContinuationAfterCurrentEvent(continuation.options, true, continuation.watchdogTimeoutMs);
         return "continued";