onbuzz 4.8.0 → 4.8.1

package/src/tools/__tests__/baseTool.test.js

@@ -364,6 +364,148 @@ describe('ToolsRegistry', () => {
     expect(desc).toContain('HOW TO GET TOOL DOCUMENTATION');
   });
 
+  describe('OPERATING POSTURE section', () => {
+    // Minimal fakes so the registry will accept these as memory/skills/taskmanager.
+    // BaseTool derives `this.id` from the class name (lowercased, with
+    // "Tool" stripped) — so the class must be named exactly *Tool* and
+    // the id is derived. We override `this.id` after super() to pin it
+    // independently of the class name, which keeps the test classes
+    // readable. validateTool() also requires parseParameters.
+    class FakeMemoryTool extends BaseTool {
+      constructor() { super(); this.id = 'memory'; }
+      getDescription() { return 'Memory tool stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeSkillsTool extends BaseTool {
+      constructor() { super(); this.id = 'skills'; }
+      getDescription() { return 'Skills tool stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeTaskManagerTool extends BaseTool {
+      constructor() { super(); this.id = 'taskmanager'; }
+      getDescription() { return 'TaskManager tool stub'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+
+    test('appears when memory tool is in capabilities (proactive memory nudge)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['memory']);
+      expect(desc).toContain('OPERATING POSTURE');
+      expect(desc).toMatch(/memory.*list/i);
+      // Plan/* should be cross-referenced here so agents writing a plan
+      // memory isn't an isolated tip buried in the memory tool's own desc.
+      expect(desc).toContain('plan/');
+    });
+
+    test('appears when skills tool is in capabilities (proactive skills nudge)', async () => {
+      await registry.registerTool(FakeSkillsTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['skills']);
+      expect(desc).toContain('OPERATING POSTURE');
+      expect(desc).toMatch(/skills.*list/i);
+    });
+
+    test('does NOT appear when neither memory nor skills is in capabilities', async () => {
+      await registry.registerTool(TestTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['test']);
+      expect(desc).not.toContain('OPERATING POSTURE');
+    });
+
+    test('distinguishes memory vs taskmanager when both are present (so agents know which to use)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      await registry.registerTool(FakeTaskManagerTool);
+      const desc = registry.generateToolDescriptionsForPrompt(['memory', 'taskmanager']);
+      expect(desc).toContain('OPERATING POSTURE');
+      expect(desc).toContain('persistent knowledge'); // memory
+      expect(desc).toContain('step-by-step');          // taskmanager
+    });
+  });
+
+  // ── Per-model prompt shape: skip text docs for tools with native schemas
+  //    when the target uses the Responses API (codex / o-series / gpt-5-pro).
+  describe('apiType="responses" — trims duplication with native function schemas', () => {
+    class FakeMemoryTool extends BaseTool {
+      constructor() { super(); this.id = 'memory'; }
+      getDescription() { return 'Memory tool stub with LONG description that would normally take many tokens'; }
+      getSummary() { return 'Persistent memory'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeTerminalTool extends BaseTool {
+      constructor() { super(); this.id = 'terminal'; }
+      getDescription() { return 'Terminal tool LONG description that would normally take many tokens'; }
+      getSummary() { return 'Shell access'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+    class FakeWebTool extends BaseTool {
+      // 'web' is NOT in OPENAI_FUNCTION_SCHEMAS — its text doc must always appear.
+      constructor() { super(); this.id = 'web'; }
+      getDescription() { return 'Web tool LONG description that would normally take many tokens'; }
+      getSummary() { return 'Browser automation'; }
+      parseParameters() { return {}; }
+      async execute() { return { ok: true }; }
+    }
+
+    test('omits text description for tools that have native function schemas (memory, terminal)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      await registry.registerTool(FakeTerminalTool);
+
+      const responsesDesc = registry.generateToolDescriptionsForPrompt(
+        ['memory', 'terminal'],
+        { apiType: 'responses' },
+      );
+      // Header still present + one-line pointer to structured schema.
+      expect(responsesDesc).toContain('AVAILABLE TOOLS');
+      expect(responsesDesc).toContain('see structured schema');
+      // The big multi-line text doc must NOT be repeated.
+      expect(responsesDesc).not.toContain('### MEMORY TOOL');
+      expect(responsesDesc).not.toContain('### TERMINAL TOOL');
+      expect(responsesDesc).not.toContain('LONG description that would normally take many tokens');
+    });
+
+    test('keeps text description for tools that do NOT have native function schemas (e.g. web)', async () => {
+      await registry.registerTool(FakeWebTool);
+      const responsesDesc = registry.generateToolDescriptionsForPrompt(
+        ['web'],
+        { apiType: 'responses' },
+      );
+      // 'web' has no native schema → text doc MUST be present.
+      expect(responsesDesc).toContain('### WEB TOOL');
+      expect(responsesDesc).toContain('LONG description that would normally take many tokens');
+    });
+
+    test('BACKWARD COMPAT: without apiType option, behaves exactly as before (full text for everything)', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      await registry.registerTool(FakeTerminalTool);
+
+      const defaultDesc = registry.generateToolDescriptionsForPrompt(['memory', 'terminal']);
+      // No apiType → keep the heavy text docs as today.
+      expect(defaultDesc).toContain('### MEMORY TOOL');
+      expect(defaultDesc).toContain('### TERMINAL TOOL');
+    });
+
+    test('BACKWARD COMPAT: apiType="chat_completion" is equivalent to no apiType', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      const a = registry.generateToolDescriptionsForPrompt(['memory'], { apiType: 'chat_completion' });
+      const b = registry.generateToolDescriptionsForPrompt(['memory']);
+      expect(a).toBe(b);
+    });
+
+    test('enhanceSystemPrompt forwards apiType option to the description builder', async () => {
+      await registry.registerTool(FakeMemoryTool);
+      const native = registry.enhanceSystemPrompt('Base.', ['memory'], { apiType: 'responses' });
+      const inline = registry.enhanceSystemPrompt('Base.', ['memory']);
+      // Native form is meaningfully shorter (we dropped the per-tool block).
+      expect(native.length).toBeLessThan(inline.length);
+      // Both still contain the section headers and the original base prompt.
+      expect(native).toContain('Base.');
+      expect(native).toContain('AVAILABLE TOOLS');
+    });
+  });
+
   test('enhanceSystemPrompt appends tool docs', async () => {
     await registry.registerTool(TestTool);
     const enhanced = registry.enhanceSystemPrompt('Base prompt.', []);

package/src/tools/baseTool.js

@@ -15,6 +15,7 @@ import {
   ERROR_TYPES,
   SYSTEM_DEFAULTS
 } from '../utilities/constants.js';
+import { NATIVE_SCHEMA_TOOL_NAMES } from './openaiFunctionSchemas.js';
 
 class BaseTool {
   constructor(config = {}, logger = null) {
@@ -690,8 +691,20 @@ class ToolsRegistry {
       includeUsageGuidelines = true,
       includeSecurityNotes = true,
       compact = false,
-      layered = false
+      layered = false,
+      // 'responses' | 'chat_completion' | undefined.
+      // When 'responses', the target model uses native function-calling
+      // (Codex / o-series / gpt-5-pro). For tools that have a native
+      // schema in openaiFunctionSchemas.js, the structured schema sent
+      // in `tools:` IS the canonical source of truth for the model —
+      // so we skip baking the same information into the system prompt
+      // as text. This eliminates ~3K duplicated tokens per turn on the
+      // models that need it most. Defaults to undefined (= 'chat_completion'
+      // behaviour: include text descriptions). Old callers that don't
+      // pass this option get the previous behaviour verbatim — back-compat.
+      apiType = undefined,
     } = options;
+    const isNativeApi = apiType === 'responses';
 
     // Get tools to include — always inject 'help' so agents can query tool docs
     let toolIds = capabilities.length > 0
@@ -751,6 +764,19 @@ class ToolsRegistry {
         const tool = this.tools.get(toolId);
         if (!tool || !tool.isEnabled) continue;
 
+        // Skip text descriptions for tools that have a native function
+        // schema, when the target model uses the Responses API. The
+        // structured schema is the canonical source for these models.
+        // We DO still emit a one-line pointer so the agent isn't blind
+        // to the tool's existence (its capability list lives in the
+        // system prompt elsewhere too, but a single-line mention here
+        // costs ~10 tokens and is a useful breadcrumb).
+        if (isNativeApi && NATIVE_SCHEMA_TOOL_NAMES.has(toolId.toLowerCase())) {
+          const summary = this.toolSummaries.get(toolId) || `${toolId} tool`;
+          description += `- **${toolId}** — ${summary} (see structured schema)\n`;
+          continue;
+        }
+
         try {
           if (compact) {
             // Compact format - just tool name and brief description
@@ -795,6 +821,58 @@ class ToolsRegistry {
     description += '- **TOOL RESULTS ARE AVAILABLE ONLY AFTER YOUR MESSAGE ENDS**: Tools execute after your entire message is sent. You will NOT see any tool results until your next turn. This means: if the next tool call depends on results from a previous one, they MUST be in separate messages. You may batch independent tool calls in a single message, but never assume or guess the output of a tool — always wait for the actual result in the next turn before proceeding.\n\n';
     description += 'After invoking a tool, WAIT for the actual response. Do NOT generate imaginary responses.\n\n';
 
+    // ── Operating posture ────────────────────────────────────────────
+    // Cross-cutting habits agents should adopt VOLUNTARILY. The tool
+    // descriptions tell them WHAT each tool does; this block tells them
+    // WHEN to reach for them without being asked. Without this, agents
+    // tend to:
+    //   • skip the memory/skills check at the start of a new task,
+    //     re-discovering things the team already wrote down
+    //   • never create a plan/* memory, losing the thread across the
+    //     first compaction
+    //   • only invoke `help`/`skills` after a failure, not proactively
+    // Only emitted when the relevant tools are actually in the agent's
+    // capability set — no point teaching "check skills" to an agent
+    // that doesn't have the skills tool.
+    const hasMemory = toolIds.includes('memory');
+    const hasSkills = toolIds.includes('skills');
+    if (hasMemory || hasSkills) {
+      description += '## OPERATING POSTURE\n\n';
+      description += 'Treat these as habits, not optional extras. Use them proactively, before you need them.\n\n';
+
+      if (hasMemory || hasSkills) {
+        description += '**At the start of a new task or topic shift:**\n';
+        if (hasMemory) {
+          description += '- Run `memory` → `list` (titles only) to scan for relevant context the team or your past self stored. If a title looks relevant, `read` it before improvising.\n';
+        }
+        if (hasSkills) {
+          description += '- Run `skills` → `list` to see if a skill already encodes how to do this task. If yes, follow its checklist instead of inventing one.\n';
+        }
+        description += '\n';
+      }
+
+      if (hasMemory) {
+        description += '**When you recognize the work is multi-turn or multi-session:**\n';
+        description += '- Save a `memory` entry with title starting `plan/` (e.g. `plan/refactor-auth`). The content auto-injects into your system prompt every turn under "AGENT WORKING PLAN" until you delete it. This is how you survive compaction — anything important enough to remember next session belongs here.\n';
+        description += '- Update or delete the plan as the situation changes. A stale plan is worse than no plan.\n\n';
+      }
+
+      if (hasMemory) {
+        description += '**When you learn something durable** (a user preference, a non-obvious constraint, an architectural fact the next agent will want):\n';
+        description += '- Save it as a `memory` (non-`plan/` title). One-shot facts go here, NOT in your reply.\n\n';
+      }
+
+      description += '**Distinction:**\n';
+      description += '- `memory` = persistent knowledge that survives sessions (why, constraints, durable facts, working plans).\n';
+      if (toolIds.includes('taskmanager')) {
+        description += '- `taskmanager` = step-by-step checkboxes for the CURRENT task (what to do next, in order).\n';
+      }
+      if (hasSkills) {
+        description += '- `skills` = reusable playbooks the team curated for recurring tasks.\n';
+      }
+      description += '\n';
+    }
+
     // Add exploration strategy if code-map is available
     if (toolIds.includes('code-map')) {
       description += '## CODE EXPLORATION STRATEGY\n\n';
@@ -817,6 +895,10 @@ class ToolsRegistry {
    * @returns {string} Enhanced system prompt
    */
   enhanceSystemPrompt(existingPrompt, capabilities = [], options = {}) {
+    // `options.apiType` ('responses' | 'chat_completion' | undefined)
+    // is forwarded to the description builder so native-API models get
+    // a trimmed prompt that doesn't duplicate the structured schemas.
+    // Old callers omit it and get pre-existing behaviour unchanged.
     const toolSection = this.generateToolDescriptionsForPrompt(capabilities, options);
 
     if (!toolSection.trim()) {

package/src/tools/openaiFunctionSchemas.js

@@ -322,4 +322,18 @@ export function getToolSchemasForAgent(capabilities = []) {
   return OPENAI_FUNCTION_SCHEMAS.filter(s => allowed.has(s.name.toLowerCase()));
 }
 
+/**
+ * Names of every tool that has a native function schema in this file.
+ * Importable as a Set so other modules (notably baseTool's system-prompt
+ * builder) can decide "is the structured schema the canonical source of
+ * truth for this tool, or do we still need to bake a text description
+ * into the system prompt?". When a model uses the Responses API (which
+ * is RLHFed for native function-calling), the structured schema in
+ * `tools:` is the canonical source — emitting the text description as
+ * well doubles the same information in the context window.
+ */
+export const NATIVE_SCHEMA_TOOL_NAMES = new Set(
+  OPENAI_FUNCTION_SCHEMAS.map(s => s.name.toLowerCase())
+);
+
 export default OPENAI_FUNCTION_SCHEMAS;