bernard-agent 0.8.1 → 0.9.0

package/dist/providers/profiles.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * Model-specific prompt optimization profiles.
+ *
+ * Each provider + model family has a {@link ModelProfile} that adjusts how a user
+ * message is wrapped and what short advisory block is appended to the system
+ * prompt. Profiles are resolved once per turn and applied deterministically —
+ * no extra LLM call. Cache-safe: the system-prompt suffix depends only on the
+ * selected model, not on the user's input, so the KV-cache prefix stays stable
+ * across a session with a fixed model.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getModelProfile = getModelProfile;
+const ANTHROPIC_SUFFIX = `## Model Notes
+This model responds best to XML-structured input. User-authored text is wrapped in a \`<user_request>\` tag to make the primary instruction explicit. Treat the tag contents as the authoritative request; also attend to other content supplied with the same user turn (attached images, system-inserted context notices) as relevant context. Text outside the tag is not a new standalone instruction from the user.`;
+const OPENAI_REASONING_SUFFIX = `Formatting re-enabled
+
+## Model Notes
+This model reasons internally. Do not narrate chain-of-thought ("think step by step", "explain your reasoning before acting") — state conclusions and take actions directly. Prefer zero-shot; keep instructions terse.`;
+const OPENAI_STANDARD_SUFFIX = `## Model Notes
+- Persistence: keep working until the user's request is fully resolved before yielding.
+- Tool-calling: if you are unsure about file content or codebase structure, call a tool to read it — do not guess.
+- Planning: plan before each function call and reflect on the outcome of the previous call before the next.`;
+const XAI_REASONING_SUFFIX = `## Model Notes
+This model reasons internally. Do not narrate chain-of-thought ("think step by step", "explain your reasoning before acting") — state conclusions and take actions directly. Keep instructions terse.`;
+const ANTHROPIC_REWRITER_HINT = 'Use natural prose framed with XML-style tags (<task>, <context>, <constraints>) when the request has distinct parts. Keep the original voice; do not over-structure short conversational requests.';
+const OPENAI_REASONING_REWRITER_HINT = 'Keep the rewrite terse. Drop filler ("please", "could you"). One or two short paragraphs or a tight bullet list is ideal. No chain-of-thought prompts.';
+const OPENAI_STANDARD_REWRITER_HINT = 'Prefer explicit "Task:", "Constraints:", and "Output:" sections when the request has multiple parts. Keep very short requests in natural prose.';
+const XAI_REASONING_REWRITER_HINT = 'Terse and direct. Strip conversational padding. State the goal in one or two sentences; add a short numbered list only when multiple distinct steps are implied.';
+const XAI_STANDARD_REWRITER_HINT = 'Direct, explicit, minimal verbosity. A short "Task: … / Requirements: …" shape works well for compound requests.';
+const DEFAULT_REWRITER_HINT = 'Keep the rewrite close to the original phrasing. Only add structure when the original has multiple distinct parts.';
+const DEFAULT_PROFILE = {
+    family: 'default',
+    wrapUserMessage: (msg) => msg,
+    systemSuffix: '',
+    rewriterHint: DEFAULT_REWRITER_HINT,
+};
+const ANTHROPIC_PROFILE = {
+    family: 'anthropic-claude',
+    wrapUserMessage: (msg) => `<user_request>\n${msg}\n</user_request>`,
+    systemSuffix: ANTHROPIC_SUFFIX,
+    rewriterHint: ANTHROPIC_REWRITER_HINT,
+};
+const OPENAI_REASONING_PROFILE = {
+    family: 'openai-reasoning',
+    wrapUserMessage: (msg) => msg,
+    systemSuffix: OPENAI_REASONING_SUFFIX,
+    rewriterHint: OPENAI_REASONING_REWRITER_HINT,
+};
+const OPENAI_STANDARD_PROFILE = {
+    family: 'openai-standard',
+    wrapUserMessage: (msg) => `# Request\n${msg}`,
+    systemSuffix: OPENAI_STANDARD_SUFFIX,
+    rewriterHint: OPENAI_STANDARD_REWRITER_HINT,
+};
+const XAI_REASONING_PROFILE = {
+    family: 'xai-grok-reasoning',
+    wrapUserMessage: (msg) => msg,
+    systemSuffix: XAI_REASONING_SUFFIX,
+    rewriterHint: XAI_REASONING_REWRITER_HINT,
+};
+const XAI_STANDARD_PROFILE = {
+    family: 'xai-grok-standard',
+    wrapUserMessage: (msg) => `# Request\n${msg}`,
+    systemSuffix: '',
+    rewriterHint: XAI_STANDARD_REWRITER_HINT,
+};
+/**
+ * Resolves the {@link ModelProfile} for a provider + model pair.
+ *
+ * Matching is first-match-wins and pattern-based so new models in an existing
+ * family pick up the right profile automatically. Unknown combinations fall
+ * back to a conservative passthrough profile.
+ *
+ * For custom providers (user-defined endpoints that wrap an installed AI-SDK)
+ * pass the wrapped SDK family via `sdk` so the model picks up family-specific
+ * prompt tuning regardless of the registered provider name.
+ */
+function getModelProfile(provider, model, sdk) {
+    const m = model.toLowerCase();
+    const family = sdk ?? provider;
+    if (family === 'anthropic') {
+        return ANTHROPIC_PROFILE;
+    }
+    if (family === 'openai') {
+        // o-series reasoning models: o1, o3, o3-mini, o4-mini, …
+        if (/^o\d/.test(m))
+            return OPENAI_REASONING_PROFILE;
+        return OPENAI_STANDARD_PROFILE;
+    }
+    if (family === 'xai') {
+        // Explicit non-reasoning variants take precedence over the generic grok-4 rule.
+        if (m.includes('non-reasoning'))
+            return XAI_STANDARD_PROFILE;
+        if (m.includes('reasoning'))
+            return XAI_REASONING_PROFILE;
+        // Grok 4.x is a reasoning family by default unless tagged otherwise.
+        if (/^grok-4(\b|[-.])/.test(m))
+            return XAI_REASONING_PROFILE;
+        return XAI_STANDARD_PROFILE;
+    }
+    return DEFAULT_PROFILE;
+}
+// References for maintainers updating the suffix constants:
+//   https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
+//   https://developers.openai.com/cookbook/examples/gpt4-1_prompting_guide
+//   https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide
+//   https://developers.openai.com/api/docs/guides/reasoning-best-practices
+//   https://docs.x.ai/docs/guides/chat
+//# sourceMappingURL=profiles.js.map

package/dist/providers/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/providers/profiles.ts"],"names":[],"mappings":"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"}

package/dist/providers/types.d.ts

@@ -1,5 +1,14 @@
-/** Supported LLM provider identifiers. */
-export type ProviderName = 'anthropic' | 'openai' | 'xai';
+/** The three AI-SDK packages we ship; custom providers must wrap one of these. */
+export type SupportedSdk = 'anthropic' | 'openai' | 'xai';
+/** Built-in provider identifiers — fall back to the official endpoints. */
+export declare const BUILTIN_PROVIDERS: readonly ["anthropic", "openai", "xai"];
+export type BuiltinProvider = (typeof BUILTIN_PROVIDERS)[number];
+/**
+ * Provider identifier — `'anthropic' | 'openai' | 'xai'` for built-ins, or any
+ * user-chosen name registered as a custom provider. The literal union documents
+ * intent; runtime values are plain strings.
+ */
+export type ProviderName = BuiltinProvider | (string & {});
 /** Provider and model pair used to instantiate an AI SDK `LanguageModel`. */
 export interface ProviderConfig {
     /** Which LLM provider to use. */

package/dist/providers/types.js

@@ -1,3 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_PROVIDERS = void 0;
+/** Built-in provider identifiers — fall back to the official endpoints. */
+exports.BUILTIN_PROVIDERS = ['anthropic', 'openai', 'xai'];
 //# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":";;;AAGA,2EAA2E;AAC9D,QAAA,iBAAiB,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAC"}

package/dist/rag-query.js

@@ -19,6 +19,20 @@ const BOUNDARY_PREFIXES = [
     '[Previous session ended',
     '[Earlier conversation was truncated',
 ];
+/**
+ * Strip model-profile wrappers applied by `wrapUserMessage` (XML tag for Claude,
+ * `# Request` heading for standard OpenAI/xAI). Passthrough profiles are no-ops.
+ * Kept in sync with `src/providers/profiles.ts` by shape, not import, to avoid
+ * cycling the providers module into RAG.
+ */
+function stripProfileWrapper(text) {
+    const xmlMatch = text.match(/^<user_request>\n([\s\S]*)\n<\/user_request>$/);
+    if (xmlMatch)
+        return xmlMatch[1];
+    if (text.startsWith('# Request\n'))
+        return text.slice('# Request\n'.length);
+    return text;
+}
 /**
  * Walk history backward and collect up to `maxMessages` user-role text strings.
  * Skips system-injected boundary messages (context summaries, session markers).
@@ -36,7 +50,7 @@ function extractRecentUserTexts(history, maxMessages = exports.DEFAULT_WINDOW_SI
         // Skip system-injected boundary messages
         if (BOUNDARY_PREFIXES.some((prefix) => text.startsWith(prefix)))
             continue;
-        texts.push((0, datetime_js_1.stripTimestamp)(text));
+        texts.push((0, datetime_js_1.stripTimestamp)(stripProfileWrapper(text)));
     }
     // Reverse to chronological order (oldest first)
     texts.reverse();

package/dist/rag-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"rag-query.js","sourceRoot":"","sources":["../src/rag-query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"rag-query.js","sourceRoot":"","sources":["../src/rag-query.ts"],"names":[],"mappings":"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"}

package/dist/react.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ReAct (coordinator) mode primitives shared by the main agent and specialist
+ * dispatch tools (`specialist_run`). Extracted from `agent.ts` so tools — which
+ * are imported BY agent.ts — can use them without forming a circular import.
+ */
+export declare const REACT_COORDINATOR_PROMPT = "## Coordinator Mode (Active)\n\nYou are operating as a coordinator, not a sole executor. Your primary role is to decompose, delegate, and synthesize \u2014 not to do all work yourself.\n\n### Reason before acting\nBefore each tool call or batch of parallel calls, state in 1-3 sentences:\n- What you know so far\n- What gap this action fills\n- What success looks like\n\n### Delegate scoped work\nPrefer delegation for any work that can be expressed as a self-contained scope:\n- Information gathering (shell commands, file reads, web research) \u2192 agent or task\n- Structured data extraction or transformation \u2192 task\n- Domain-specific work matching a specialist \u2192 specialist_run or tool_wrapper_run\n\nDo the work yourself only when:\n- It requires conversation history a sub-agent cannot have\n- It is trivially small (1-2 tool calls) and delegation overhead is not worth it\n- You need intermediate results before deciding the next step\n\n### Treat subagent outputs as observations\nWhen a sub-agent returns, interpret the result \u2014 do not echo it. Extract the signal, discard the noise, and state what it means for the task. If a sub-agent returns 500 lines, your synthesis should be 2-5 sentences.\n\n### Context discipline\nDo not accumulate long chains of raw tool output in your reasoning. Once you have gathered sufficient information, synthesize it and move forward. Do not re-list everything you know \u2014 refer to prior findings and build on them.\n\n### The think \u2192 act \u2192 evaluate \u2192 decide loop\nEvery step follows the same rhythm. Do not skip stages.\n\n1. **Think** \u2014 call `think` with a 1-3 sentence statement of what you know, what gap the next action fills, and what success looks like.\n2. **Act** \u2014 make the tool call (or batch of parallel calls).\n3. **Stop and evaluate** \u2014 call `evaluate` immediately after the action completes. State in 1-3 sentences whether the result matched expectations, whether any surprise / error / risk was revealed, and whether to continue or course-correct. Be willing to catch yourself \u2014 \"Actually, that's not right because...\" or \"Wait \u2014 this might make things worse, let me take a different approach\" is exactly what evaluate is for.\n4. **Decide** \u2014 based on the evaluation, either continue to the next think/act or go back and try a different approach. If you course-correct, say so before acting.\n\nSkip this full cycle only for trivially small work (1-2 tool calls). For any non-trivial step, all four stages happen.\n\n### Use the `plan` tool\n\n**At the start of each new user request**, assess whether the task requires planning. Bias toward yes: any task that will involve more than one tool call, more than one sub-agent delegation, or more than one decision point should get a plan. Only skip planning for trivially small work (1-2 tool calls).\n\n**The plan store is reset on every user turn.** Any `plan` tool calls visible in earlier turns of the conversation are stale \u2014 their step IDs no longer exist. Start fresh by calling `plan` with action `create` and an ordered list of step objects. Do not try to `update` IDs from a previous turn; they will not resolve.\n\n**Each step has two parts at creation time:**\n- `description`: what the step accomplishes.\n- `verification`: a concrete, observable check that will prove the step succeeded \u2014 a command to run, a file/URL to read, a specific output substring, an exit code, a status code. Must be something a third party could re-run; never subjective (\"looks right\", \"should work\").\n\n**Step lifecycle:**\n- Before starting a step: `update` it to `in_progress`.\n- After completing it: actually run the verification, then `update` to `done` with a `signoff` that cites the concrete evidence you observed (command output excerpt, file contents, status code, URL, etc.). The sign-off is your attestation that the verification was performed \u2014 not a restatement of the description. If the verification has not been run, the step is not done.\n- If a step becomes unnecessary (user pivoted, work no longer needed): mark it `cancelled` with a `note`.\n- If a step is genuinely unachievable, or verification failed and you cannot fix it (permission denied, resource missing, tool broken): mark it `error` with a `note` explaining what went wrong. Do not sign off on a step whose verification did not pass \u2014 mark it `error` and adapt the plan instead.\n- If a step needs user input to proceed (intent, choice, missing argument), call the `ask_user` tool from inside the step. The answer comes back as the tool result; use it to continue. Never end the turn with a question written in prose \u2014 enforcement will trigger and the turn will be auto-cancelled before the user can answer.\n\n**Before composing your final response**, verify every step is in a terminal state (`done`, `cancelled`, or `error`) and that every `done` step carries a sign-off. If you are giving up on the task \u2014 partially or fully \u2014 mark the remaining non-terminal steps `cancelled` or `error` with notes **before** writing the user-facing text. Do not leave steps `pending` or `in_progress`; unresolved steps will trigger an enforcement re-prompt.\n\n### Keep reflective notes in `scratch`\nThe `plan` note is a one-line summary \u2014 `scratch` is where the evidence lives. For any non-trivial step:\n- After a substantive tool call, sub-agent return, or batch of parallel calls, write a scratch entry with key `step-{id}` (or `findings-{topic}` for cross-cutting observations) containing: what you did, the concrete result (command output excerpts, file paths, numeric values, URLs \u2014 facts, not vibes), and any follow-ups this uncovered.\n- Update the same key as you learn more within a single step; do not spawn a new key per tool call.\n- Treat scratch as your working record. When you need to recall what happened several steps ago, read from scratch rather than scrolling back through tool results.\n\n### Synthesize the final response from scratch\nWhen all plan steps are in terminal states and you are ready to respond to the user:\n1. Call `scratch` with action `list` to see what you captured.\n2. Call `scratch` with action `read` for the relevant keys.\n3. Compose the response from those notes \u2014 not from the conversation tail. Conversation history is noisy and can include stale intermediate state; your scratch notes are the curated record of what actually happened.\n4. Skip this synthesis step only for trivial work where no plan was created.";
+/**
+ * Pure predicate: should the ReAct plan-enforcement loop run after the main
+ * generateText call?
+ */
+export declare function shouldEnforcePlan(args: {
+    reactMode: boolean;
+    aborted: boolean;
+    stepLimitHit: boolean;
+    hasSteps: boolean;
+}): boolean;
+/**
+ * Upper ceiling on the per-turn step budget when reactMode triples maxSteps.
+ * Prevents pathological cost amplification when a user has set a high
+ * BERNARD_MAX_STEPS for the non-react path.
+ */
+export declare const REACT_MAX_STEPS_CEILING = 150;
+/**
+ * Returns the per-turn step budget for an agent loop. In reactMode the base
+ * budget is tripled (deliberation + delegation + synthesis), then clamped to
+ * {@link REACT_MAX_STEPS_CEILING} so a high base cannot blow up.
+ */
+export declare function computeEffectiveMaxSteps(maxSteps: number, reactMode: boolean): number;
+/** Max plan-enforcement re-prompts after the main generateText call. */
+export declare const REACT_ENFORCEMENT_MAX_RETRIES = 2;
+/** Note attached to plan steps auto-cancelled after enforcement retries are exhausted. */
+export declare const REACT_AUTO_CANCEL_NOTE = "auto-cancelled: enforcement retries exhausted";
+/**
+ * Builds the user-facing enforcement re-prompt used when a plan still has
+ * unresolved steps after the main generateText call. Shared by the agent and
+ * specialist enforcement loops so the wording cannot drift between the two.
+ */
+export declare function buildEnforcementFeedback(planRender: string): string;

package/dist/react.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * ReAct (coordinator) mode primitives shared by the main agent and specialist
+ * dispatch tools (`specialist_run`). Extracted from `agent.ts` so tools — which
+ * are imported BY agent.ts — can use them without forming a circular import.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REACT_AUTO_CANCEL_NOTE = exports.REACT_ENFORCEMENT_MAX_RETRIES = exports.REACT_MAX_STEPS_CEILING = exports.REACT_COORDINATOR_PROMPT = void 0;
+exports.shouldEnforcePlan = shouldEnforcePlan;
+exports.computeEffectiveMaxSteps = computeEffectiveMaxSteps;
+exports.buildEnforcementFeedback = buildEnforcementFeedback;
+exports.REACT_COORDINATOR_PROMPT = `## Coordinator Mode (Active)
+
+You are operating as a coordinator, not a sole executor. Your primary role is to decompose, delegate, and synthesize — not to do all work yourself.
+
+### Reason before acting
+Before each tool call or batch of parallel calls, state in 1-3 sentences:
+- What you know so far
+- What gap this action fills
+- What success looks like
+
+### Delegate scoped work
+Prefer delegation for any work that can be expressed as a self-contained scope:
+- Information gathering (shell commands, file reads, web research) → agent or task
+- Structured data extraction or transformation → task
+- Domain-specific work matching a specialist → specialist_run or tool_wrapper_run
+
+Do the work yourself only when:
+- It requires conversation history a sub-agent cannot have
+- It is trivially small (1-2 tool calls) and delegation overhead is not worth it
+- You need intermediate results before deciding the next step
+
+### Treat subagent outputs as observations
+When a sub-agent returns, interpret the result — do not echo it. Extract the signal, discard the noise, and state what it means for the task. If a sub-agent returns 500 lines, your synthesis should be 2-5 sentences.
+
+### Context discipline
+Do not accumulate long chains of raw tool output in your reasoning. Once you have gathered sufficient information, synthesize it and move forward. Do not re-list everything you know — refer to prior findings and build on them.
+
+### The think → act → evaluate → decide loop
+Every step follows the same rhythm. Do not skip stages.
+
+1. **Think** — call \`think\` with a 1-3 sentence statement of what you know, what gap the next action fills, and what success looks like.
+2. **Act** — make the tool call (or batch of parallel calls).
+3. **Stop and evaluate** — call \`evaluate\` immediately after the action completes. State in 1-3 sentences whether the result matched expectations, whether any surprise / error / risk was revealed, and whether to continue or course-correct. Be willing to catch yourself — "Actually, that's not right because..." or "Wait — this might make things worse, let me take a different approach" is exactly what evaluate is for.
+4. **Decide** — based on the evaluation, either continue to the next think/act or go back and try a different approach. If you course-correct, say so before acting.
+
+Skip this full cycle only for trivially small work (1-2 tool calls). For any non-trivial step, all four stages happen.
+
+### Use the \`plan\` tool
+
+**At the start of each new user request**, assess whether the task requires planning. Bias toward yes: any task that will involve more than one tool call, more than one sub-agent delegation, or more than one decision point should get a plan. Only skip planning for trivially small work (1-2 tool calls).
+
+**The plan store is reset on every user turn.** Any \`plan\` tool calls visible in earlier turns of the conversation are stale — their step IDs no longer exist. Start fresh by calling \`plan\` with action \`create\` and an ordered list of step objects. Do not try to \`update\` IDs from a previous turn; they will not resolve.
+
+**Each step has two parts at creation time:**
+- \`description\`: what the step accomplishes.
+- \`verification\`: a concrete, observable check that will prove the step succeeded — a command to run, a file/URL to read, a specific output substring, an exit code, a status code. Must be something a third party could re-run; never subjective ("looks right", "should work").
+
+**Step lifecycle:**
+- Before starting a step: \`update\` it to \`in_progress\`.
+- After completing it: actually run the verification, then \`update\` to \`done\` with a \`signoff\` that cites the concrete evidence you observed (command output excerpt, file contents, status code, URL, etc.). The sign-off is your attestation that the verification was performed — not a restatement of the description. If the verification has not been run, the step is not done.
+- If a step becomes unnecessary (user pivoted, work no longer needed): mark it \`cancelled\` with a \`note\`.
+- If a step is genuinely unachievable, or verification failed and you cannot fix it (permission denied, resource missing, tool broken): mark it \`error\` with a \`note\` explaining what went wrong. Do not sign off on a step whose verification did not pass — mark it \`error\` and adapt the plan instead.
+- If a step needs user input to proceed (intent, choice, missing argument), call the \`ask_user\` tool from inside the step. The answer comes back as the tool result; use it to continue. Never end the turn with a question written in prose — enforcement will trigger and the turn will be auto-cancelled before the user can answer.
+
+**Before composing your final response**, verify every step is in a terminal state (\`done\`, \`cancelled\`, or \`error\`) and that every \`done\` step carries a sign-off. If you are giving up on the task — partially or fully — mark the remaining non-terminal steps \`cancelled\` or \`error\` with notes **before** writing the user-facing text. Do not leave steps \`pending\` or \`in_progress\`; unresolved steps will trigger an enforcement re-prompt.
+
+### Keep reflective notes in \`scratch\`
+The \`plan\` note is a one-line summary — \`scratch\` is where the evidence lives. For any non-trivial step:
+- After a substantive tool call, sub-agent return, or batch of parallel calls, write a scratch entry with key \`step-{id}\` (or \`findings-{topic}\` for cross-cutting observations) containing: what you did, the concrete result (command output excerpts, file paths, numeric values, URLs — facts, not vibes), and any follow-ups this uncovered.
+- Update the same key as you learn more within a single step; do not spawn a new key per tool call.
+- Treat scratch as your working record. When you need to recall what happened several steps ago, read from scratch rather than scrolling back through tool results.
+
+### Synthesize the final response from scratch
+When all plan steps are in terminal states and you are ready to respond to the user:
+1. Call \`scratch\` with action \`list\` to see what you captured.
+2. Call \`scratch\` with action \`read\` for the relevant keys.
+3. Compose the response from those notes — not from the conversation tail. Conversation history is noisy and can include stale intermediate state; your scratch notes are the curated record of what actually happened.
+4. Skip this synthesis step only for trivial work where no plan was created.`;
+/**
+ * Pure predicate: should the ReAct plan-enforcement loop run after the main
+ * generateText call?
+ */
+function shouldEnforcePlan(args) {
+    return args.reactMode && !args.aborted && !args.stepLimitHit && args.hasSteps;
+}
+/**
+ * Upper ceiling on the per-turn step budget when reactMode triples maxSteps.
+ * Prevents pathological cost amplification when a user has set a high
+ * BERNARD_MAX_STEPS for the non-react path.
+ */
+exports.REACT_MAX_STEPS_CEILING = 150;
+/**
+ * Returns the per-turn step budget for an agent loop. In reactMode the base
+ * budget is tripled (deliberation + delegation + synthesis), then clamped to
+ * {@link REACT_MAX_STEPS_CEILING} so a high base cannot blow up.
+ */
+function computeEffectiveMaxSteps(maxSteps, reactMode) {
+    if (!reactMode)
+        return maxSteps;
+    return Math.min(maxSteps * 3, exports.REACT_MAX_STEPS_CEILING);
+}
+/** Max plan-enforcement re-prompts after the main generateText call. */
+exports.REACT_ENFORCEMENT_MAX_RETRIES = 2;
+/** Note attached to plan steps auto-cancelled after enforcement retries are exhausted. */
+exports.REACT_AUTO_CANCEL_NOTE = 'auto-cancelled: enforcement retries exhausted';
+/**
+ * Builds the user-facing enforcement re-prompt used when a plan still has
+ * unresolved steps after the main generateText call. Shared by the agent and
+ * specialist enforcement loops so the wording cannot drift between the two.
+ */
+function buildEnforcementFeedback(planRender) {
+    return (`Your plan still has unresolved steps:\n\n${planRender}\n\n` +
+        `Resolve each remaining step: complete it (plan update -> done), mark it cancelled with a note if the user's intent changed or the step is no longer needed, or mark it error with a note if it is genuinely unachievable. Do not leave steps pending or in_progress.`);
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AA2EH,8CAOC;AAcD,4DAGC;AAaD,4DAKC;AAnHY,QAAA,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6EAmEqC,CAAC;AAE9E;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,IAKjC;IACC,OAAO,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,QAAQ,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACU,QAAA,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,QAAgB,EAAE,SAAkB;IAC3E,IAAI,CAAC,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,EAAE,+BAAuB,CAAC,CAAC;AACzD,CAAC;AAED,wEAAwE;AAC3D,QAAA,6BAA6B,GAAG,CAAC,CAAC;AAE/C,0FAA0F;AAC7E,QAAA,sBAAsB,GAAG,+CAA+C,CAAC;AAEtF;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,UAAkB;IACzD,OAAO,CACL,4CAA4C,UAAU,MAAM;QAC5D,sQAAsQ,CACvQ,CAAC;AACJ,CAAC"}

package/dist/reasoning-log.d.ts

@@ -0,0 +1,30 @@
+/**
+ * One entry per `tool_wrapper_run` invocation. Appended as a JSONL line to
+ * {@link TOOL_WRAPPER_LOG}. The log is append-only and user-readable; it
+ * exists primarily so failed runs can be inspected, replayed, or converted
+ * into correction candidates.
+ */
+export interface ReasoningLogEntry {
+    ts: string;
+    specialistId: string;
+    input: string;
+    toolCalls: Array<{
+        tool: string;
+        args: unknown;
+        resultPreview: string;
+    }>;
+    finalOutput: unknown;
+    status: 'ok' | 'error' | 'parse_failed';
+    error?: string;
+    reasoning?: string[];
+    /** Session id if available (short identifier to correlate related runs). */
+    sessionId?: string;
+}
+export declare function appendReasoningLog(entry: ReasoningLogEntry): void;
+/**
+ * Reads and parses the reasoning log, returning the most recent `limit` entries.
+ * Skips malformed lines.
+ */
+export declare function readReasoningLog(limit?: number): ReasoningLogEntry[];
+/** Trims the reasoning log to the last `keep` entries. Used for maintenance. */
+export declare function rotateReasoningLog(keep?: number): void;

package/dist/reasoning-log.js

@@ -0,0 +1,102 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendReasoningLog = appendReasoningLog;
+exports.readReasoningLog = readReasoningLog;
+exports.rotateReasoningLog = rotateReasoningLog;
+const fs = __importStar(require("node:fs"));
+const paths_js_1 = require("./paths.js");
+/**
+ * Appends one entry to the reasoning log. Never throws — logging must not
+ * break the hot path.
+ */
+let logsDirReady = false;
+function appendReasoningLog(entry) {
+    try {
+        if (!logsDirReady) {
+            fs.mkdirSync(paths_js_1.LOGS_DIR, { recursive: true });
+            logsDirReady = true;
+        }
+        fs.appendFileSync(paths_js_1.TOOL_WRAPPER_LOG, JSON.stringify(entry) + '\n', 'utf-8');
+    }
+    catch {
+        // best-effort; swallow
+    }
+}
+/**
+ * Reads and parses the reasoning log, returning the most recent `limit` entries.
+ * Skips malformed lines.
+ */
+function readReasoningLog(limit = 100) {
+    try {
+        if (!fs.existsSync(paths_js_1.TOOL_WRAPPER_LOG))
+            return [];
+        const contents = fs.readFileSync(paths_js_1.TOOL_WRAPPER_LOG, 'utf-8');
+        const lines = contents.split('\n').filter((l) => l.trim().length > 0);
+        const tail = lines.slice(-limit);
+        const entries = [];
+        for (const line of tail) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch {
+                /* skip */
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+/** Trims the reasoning log to the last `keep` entries. Used for maintenance. */
+function rotateReasoningLog(keep = 1000) {
+    try {
+        if (!fs.existsSync(paths_js_1.TOOL_WRAPPER_LOG))
+            return;
+        const contents = fs.readFileSync(paths_js_1.TOOL_WRAPPER_LOG, 'utf-8');
+        const lines = contents.split('\n').filter((l) => l.trim().length > 0);
+        if (lines.length <= keep)
+            return;
+        const tail = lines.slice(-keep);
+        const tmp = paths_js_1.TOOL_WRAPPER_LOG + '.tmp';
+        fs.writeFileSync(tmp, tail.join('\n') + '\n', 'utf-8');
+        fs.renameSync(tmp, paths_js_1.TOOL_WRAPPER_LOG);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+//# sourceMappingURL=reasoning-log.js.map

package/dist/reasoning-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-log.js","sourceRoot":"","sources":["../src/reasoning-log.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,gDAUC;AAMD,4CAkBC;AAGD,gDAaC;AA9ED,4CAA8B;AAC9B,yCAAwD;AAqBxD;;;GAGG;AACH,IAAI,YAAY,GAAG,KAAK,CAAC;AAEzB,SAAgB,kBAAkB,CAAC,KAAwB;IACzD,IAAI,CAAC;QACH,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,EAAE,CAAC,SAAS,CAAC,mBAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,EAAE,CAAC,cAAc,CAAC,2BAAgB,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,uBAAuB;IACzB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,KAAK,GAAG,GAAG;IAC1C,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,2BAAgB,CAAC;YAAE,OAAO,EAAE,CAAC;QAChD,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,2BAAgB,EAAE,OAAO,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,OAAO,GAAwB,EAAE,CAAC;QACxC,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAsB,CAAC,CAAC;YACtD,CAAC;YAAC,MAAM,CAAC;gBACP,UAAU;YACZ,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,SAAgB,kBAAkB,CAAC,IAAI,GAAG,IAAI;IAC5C,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,2BAAgB,CAAC;YAAE,OAAO;QAC7C,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,2BAAgB,EAAE,OAAO,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACtE,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI;YAAE,OAAO;QACjC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,GAAG,GAAG,2BAAgB,GAAG,MAAM,CAAC;QACtC,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;QACvD,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,2BAAgB,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC"}

package/dist/reference-resolver.d.ts

@@ -0,0 +1,47 @@
+import { type CoreMessage } from 'ai';
+import { type MemoryStore } from './memory.js';
+import type { RAGStore } from './rag.js';
+import type { BernardConfig } from './config.js';
+/** Sentinel sourceKey used for resolutions drawn from the RAG knowledge base. */
+export declare const RAG_SOURCE_KEY = "rag";
+/**
+ * Derive a memory key from a natural-language reference phrase.
+ * Strips a leading possessive/demonstrative and replaces internal spaces with dashes.
+ *
+ * Examples: "my brother" → "brother", "the car" → "car", "my brother Tom" → "brother-tom".
+ */
+export declare function deriveKeyFromReference(reference: string): string;
+export interface ResolvedEntry {
+    phrase: string;
+    resolvedTo: string;
+    sourceKey: string;
+}
+export interface Candidate {
+    label: string;
+    sourceKey: string;
+    preview: string;
+}
+export type ResolveResult = {
+    status: 'noop';
+} | {
+    status: 'resolved';
+    entries: ResolvedEntry[];
+} | {
+    status: 'ambiguous';
+    reference: string;
+    candidates: Candidate[];
+} | {
+    status: 'unknown';
+    reference: string;
+};
+/**
+ * Remove tokens that the main agent can resolve with tools (URLs, PR/issue refs,
+ * file paths, commit hashes) before the reference resolver sees the input.
+ * Mirrors {@link ./image.ts:stripImagePaths} in shape and intent.
+ */
+export declare function stripToolResolvableTokens(text: string): string;
+export declare function shouldSkipResolver(userInput: string): boolean;
+export declare function buildRecentTurnsBlock(history: CoreMessage[]): string;
+export declare function validateAgainstMemory(result: ResolveResult, memoryKeys: Set<string>, ragAvailable?: boolean): ResolveResult;
+export declare function resolveReferences(userInput: string, memoryStore: MemoryStore, config: BernardConfig, hints?: Map<string, string>, abortSignal?: AbortSignal, ragStore?: RAGStore, recentHistory?: CoreMessage[]): Promise<ResolveResult>;
+export declare function renderResolvedBlock(entries: ResolvedEntry[]): string;