onbuzz 5.1.0 → 5.4.0

package/src/tools/baseTool.js

@@ -15,6 +15,7 @@ import {
   SYSTEM_DEFAULTS
 } from '../utilities/constants.js';
 import { NATIVE_SCHEMA_TOOL_NAMES } from './openaiFunctionSchemas.js';
+import { applyMustHaveCapabilities, isMustHaveCapability } from '../utilities/mustHaveCapabilities.js';
 
 class BaseTool {
   constructor(config = {}, logger = null) {
@@ -704,12 +705,23 @@ class ToolsRegistry {
       // behaviour: include text descriptions). Old callers that don't
       // pass this option get the previous behaviour verbatim — back-compat.
       apiType = undefined,
+      // Agent mode ('agent' | 'chat'). Gates the jobdone must-have (autonomous
+      // completion is meaningless in chat). Undefined → treated as non-agent.
+      mode = undefined,
     } = options;
     const isNativeApi = apiType === 'responses';
 
+    // Force-inject the must-have tools (taskmanager always; jobdone in AGENT
+    // mode) into an explicit capability list, honoring `!cap` opt-out — same
+    // spirit as the unconditional 'help' injection below. An empty list still
+    // means "all tools", which already includes them.
+    const effectiveCaps = capabilities.length > 0
+      ? applyMustHaveCapabilities(capabilities, mode)
+      : capabilities;
+
     // Get tools to include — always inject 'help' so agents can query tool docs
-    let toolIds = capabilities.length > 0
-      ? capabilities.filter(cap => this.tools.has(cap))
+    let toolIds = effectiveCaps.length > 0
+      ? effectiveCaps.filter(cap => this.tools.has(cap))
       : Array.from(this.tools.keys());
 
     if (!toolIds.includes('help') && this.tools.has('help')) {
@@ -963,6 +975,12 @@ class ToolsRegistry {
     const tools = [];
 
     for (const [toolId, tool] of this.tools.entries()) {
+      // Must-have tools (taskmanager, jobdone) are always advertised to agents
+      // at prompt/schema build time — they are not user-selectable, so they
+      // are omitted from the UI capability selector to avoid implying they can
+      // be turned off. See utilities/mustHaveCapabilities.js.
+      if (isMustHaveCapability(toolId)) continue;
+
       const capabilities = tool.getCapabilities();
 
       // Prefer the explicit `tool.name` that every BaseTool subclass sets

package/src/tools/imageTool.js

@@ -42,6 +42,7 @@ const IMAGE_CONFIG = {
    * while the tool's own docstring advertised them. See _validateParameters.
    */
   MODEL_SIZES: {
+    'gpt-image-2':   { kind: 'enum',  values: ['1024x1024', '1024x1536', '1536x1024', 'auto'] },
     'gpt-image-1.5': { kind: 'enum',  values: ['1024x1024', '1024x1536', '1536x1024', 'auto'] },
     'gpt-image-1':   { kind: 'enum',  values: ['1024x1024', '1024x1536', '1536x1024', 'auto'] },
     'flux':          { kind: 'range', min: 256, max: 1440, increment: 32 },
@@ -56,15 +57,19 @@ const IMAGE_CONFIG = {
    * Agents were previously confused because `portrait` → 1024x1440 always,
    * even when the tool silently auto-switched to gpt-image-1.5 (where that
    * size is invalid). Now `portrait` resolves to 1024x1536 for gpt-image.
+   *
+   * The `gpt-image` variant is shared by the whole gpt-image-* family
+   * (gpt-image-1, gpt-image-1.5, gpt-image-2) — they accept the same enum
+   * sizes — via the family-aware lookup in _validateParameters.
    */
   SIZE_PRESETS: {
-    'square':         { default: '1024x1024', 'gpt-image-1.5': '1024x1024' },
-    'square_hd':      { default: '1440x1440', 'gpt-image-1.5': '1024x1024' },
-    'portrait':       { default: '1024x1440', 'gpt-image-1.5': '1024x1536' },
-    'landscape':      { default: '1440x1024', 'gpt-image-1.5': '1536x1024' },
-    'portrait_4_3':   { default: '768x1024',  'gpt-image-1.5': '1024x1536' },
-    'landscape_4_3':  { default: '1024x768',  'gpt-image-1.5': '1536x1024' },
-    'small':          { default: '512x512',   'gpt-image-1.5': '1024x1024' },
+    'square':         { default: '1024x1024', 'gpt-image': '1024x1024' },
+    'square_hd':      { default: '1440x1440', 'gpt-image': '1024x1024' },
+    'portrait':       { default: '1024x1440', 'gpt-image': '1024x1536' },
+    'landscape':      { default: '1440x1024', 'gpt-image': '1536x1024' },
+    'portrait_4_3':   { default: '768x1024',  'gpt-image': '1024x1536' },
+    'landscape_4_3':  { default: '1024x768',  'gpt-image': '1536x1024' },
+    'small':          { default: '512x512',   'gpt-image': '1024x1024' },
   },
 
   VALID_FORMATS: ['png', 'jpg', 'jpeg', 'webp'],
@@ -94,6 +99,7 @@ export function resolveEffectiveImageModel(params = {}) {
   if (explicit && explicit !== 'auto') return explicit;
   if (params.transparency === true) return 'gpt-image-1.5';
   if (params.sourceImage)            return 'gpt-image-1.5';
+  if (Array.isArray(params.sourceImages) && params.sourceImages.length > 0) return 'gpt-image-1.5';
   // Null → defer to downstream (aiService resolves from catalog). We
   // still return a sentinel so validators can use `default` rules.
   return '';
@@ -288,6 +294,19 @@ Or, equivalently, with the explicit field:
 \`\`\`
 (The \`sourceImage\` can be any common format — PNG, JPEG, WebP, etc. The OUTPUT format is whatever you specify on \`outputPath\` / \`outputType\`, defaulting to WebP.)
 
+**USAGE — Edit with MULTIPLE input images (compose several references):**
+\`\`\`json
+{
+  "toolId": "image-gen",
+  "parameters": {
+    "prompt": "Place the sneaker from the first image onto the model in the second image",
+    "sourceImages": ["images/sneaker.png", "images/model.jpg"],
+    "model": "gpt-image-1.5",
+    "outputPath": "images/composite.webp"
+  }
+}
+\`\`\`
+
 **Parameters:**
 - **prompt** (required): Description of image to generate OR editing instruction
 - **outputPath** (optional): Path to save image (permanent). Omit for temp file.
@@ -297,8 +316,12 @@ Or, equivalently, with the explicit field:
   An outputPath extension always wins over outputType if both are present.
 - **size** (optional): WIDTHxHEIGHT or preset name. DIFFERENT MODELS ACCEPT DIFFERENT SIZES — read the rules below. Default: 1024x1024.
 - **quality** (optional): "standard" or "hd" (default: standard)
-- **model** (optional): "gpt-image-1.5" or a flux variant. Default: auto. Auto-switches to gpt-image-1.5 if transparency=true OR sourceImage is set.
+- **model** (optional): "gpt-image-2", "gpt-image-1.5", or a flux variant. Default: auto. Auto-switches to gpt-image-1.5 if transparency=true OR sourceImage is set (pass model explicitly to use gpt-image-2 for those).
 - **sourceImage** (optional): Path to source image for editing (forces gpt-image-1.5)
+- **sourceImages** (optional): Array of source image paths for a MULTI-reference edit —
+  the model composes/blends them into one output (e.g. put the product from image 1
+  into the scene from image 2). Forces a gpt-image model. Use instead of sourceImage
+  when you have more than one input.
 - **mask** (optional): Path to mask image for editing (white=edit area, black=keep area)
 - **transparency** (optional): true to generate with transparent background (forces gpt-image-1.5)
 
@@ -311,7 +334,8 @@ is the better default for photo-style outputs.
 
 ⚠ SIZE RULES — read before picking a size:
 
-  (A) gpt-image-1.5 (auto-selected on transparency=true or sourceImage, or set explicitly):
+  (A) gpt-image family — gpt-image-2, gpt-image-1.5, gpt-image-1
+      (gpt-image-1.5 is auto-selected on transparency=true or sourceImage; any can be set explicitly):
       size MUST be one of: 1024x1024, 1024x1536 (portrait), 1536x1024 (landscape), or "auto".
       Any other value is rejected; the error lists the valid options.
       Presets remap automatically — e.g. "portrait" → 1024x1536 on this model.
@@ -442,6 +466,9 @@ Content moderation:
       size: obj.size || IMAGE_CONFIG.DEFAULT_SIZE,
       quality: obj.quality || IMAGE_CONFIG.DEFAULT_QUALITY,
       sourceImage: obj.sourceImage || null,     // Edit mode: path to source image
+      // Multi-reference edit: array of source image paths. Accepts
+      // `sourceImages` (array) or `sourceImage` (single) — both may be set.
+      sourceImages: Array.isArray(obj.sourceImages) ? obj.sourceImages.filter(Boolean) : null,
       mask: obj.mask || null,                   // Edit mode: path to mask image
       transparency: obj.transparency || false   // Generate with transparent background
     };
@@ -470,6 +497,11 @@ Content moderation:
       size: extractTag('size') || IMAGE_CONFIG.DEFAULT_SIZE,
       quality: extractTag('quality') || IMAGE_CONFIG.DEFAULT_QUALITY,
       sourceImage: extractTag('source-image') || null,
+      // <source-images> is a comma-separated list of paths for multi-reference edits.
+      sourceImages: (() => {
+        const v = extractTag('source-images');
+        return v ? v.split(',').map(s => s.trim()).filter(Boolean) : null;
+      })(),
       mask: extractTag('mask') || null,
       transparency: extractTag('transparency') === 'true'
     };
@@ -520,6 +552,15 @@ Content moderation:
           model: imageParams.model,
           size: imageParams.size,
           quality: imageParams.quality,
+          // Edit-mode + transparency inputs. These were parsed into
+          // imageParams but never copied onto the job, so _generateImage
+          // (which reads job.sourceImage/.mask/.transparency) never entered
+          // edit/transparency mode — a latent bug. sourceImages enables
+          // multi-reference edits (compose several inputs into one output).
+          sourceImage: imageParams.sourceImage || null,
+          sourceImages: imageParams.sourceImages || null,
+          mask: imageParams.mask || null,
+          transparency: imageParams.transparency || false,
           projectDir: projectDir || process.cwd(),
           directoryAccess,
           // Carry the caller's per-agent image-gen config onto the job
@@ -609,7 +650,10 @@ Content moderation:
         // preset was resolved Flux-shaped and then rejected downstream.
         const presetEntry = IMAGE_CONFIG.SIZE_PRESETS[img.size];
         if (presetEntry) {
-          img.size = presetEntry[ruleKey] || presetEntry.default;
+          // The whole gpt-image-* family shares one preset variant ('gpt-image');
+          // everything else uses its own key (e.g. 'flux') or the default.
+          const presetKey = ruleKey.startsWith('gpt-image') ? 'gpt-image' : ruleKey;
+          img.size = presetEntry[presetKey] || presetEntry.default;
         }
 
         // Step 2: per-model rule check.
@@ -1010,11 +1054,18 @@ Content moderation:
       throw new Error('AI service not available. Image generation requires AI service.');
     }
 
+    // Normalize the source list: sourceImages[] takes precedence, else the
+    // single sourceImage. Either puts us in edit mode.
+    const sourcePaths = (Array.isArray(job.sourceImages) && job.sourceImages.length > 0)
+      ? job.sourceImages
+      : (job.sourceImage ? [job.sourceImage] : []);
+    const isEdit = sourcePaths.length > 0;
+
     // Auto-select gpt-image-1.5 for transparency or editing
     if (job.transparency && !job.model) {
       job.model = 'gpt-image-1.5';
     }
-    if (job.sourceImage && !job.model) {
+    if (isEdit && !job.model) {
       job.model = 'gpt-image-1.5';
     }
 
@@ -1027,35 +1078,35 @@ Content moderation:
 
     let aiResult;
 
-    // Edit mode: source image provided
-    if (job.sourceImage) {
+    // Edit mode: one or more source images provided
+    if (isEdit) {
       this.logger?.info(`Editing image with ${job.model}`, {
-        sourceImage: job.sourceImage,
+        sourceCount: sourcePaths.length,
         hasMask: !!job.mask
       });
 
-      // Resolve source image path relative to project directory
       const projectDir = job.projectDir || process.cwd();
-      const resolvedSourcePath = path.isAbsolute(job.sourceImage)
-        ? job.sourceImage
-        : path.resolve(projectDir, job.sourceImage);
+      const toBase64 = async (p) => {
+        const resolved = path.isAbsolute(p) ? p : path.resolve(projectDir, p);
+        return (await fs.readFile(resolved)).toString('base64');
+      };
 
-      // Read source image and convert to base64
-      const imageBuffer = await fs.readFile(resolvedSourcePath);
-      const imageBase64 = imageBuffer.toString('base64');
+      // Read every source image to base64 (in order).
+      const imagesBase64 = [];
+      for (const p of sourcePaths) imagesBase64.push(await toBase64(p));
 
       // Read mask if provided
       let maskBase64 = null;
       if (job.mask) {
-        const resolvedMaskPath = path.isAbsolute(job.mask)
-          ? job.mask
-          : path.resolve(projectDir, job.mask);
-        const maskBuffer = await fs.readFile(resolvedMaskPath);
-        maskBase64 = maskBuffer.toString('base64');
+        maskBase64 = await toBase64(job.mask);
       }
 
-      aiResult = await this.aiService.editImage(job.prompt, imageBase64, {
+      // Pass the first image positionally (so an older backend that only
+      // reads imageBase64 still does a single-image edit) AND the full array
+      // (so a multi-image-capable backend composes all of them).
+      aiResult = await this.aiService.editImage(job.prompt, imagesBase64[0], {
         model: job.model,
+        ...(imagesBase64.length > 1 && { imagesBase64 }),
         maskBase64,
         sessionId: job.sessionId
       });

package/src/tools/importAnalysis/__tests__/callableChecker.edge.test.js

@@ -0,0 +1,141 @@
+/**
+ * Adversarial / edge-case battery for the callable checker. The bar:
+ *  - ZERO false positives on tricky-but-valid code (most important — an
+ *    auto-acted tool must not flag working code).
+ *  - Still catches real bugs in tricky syntactic forms.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { parseModule, collectModuleInfo, analyzeCalls } from '../callableChecker.js';
+
+function analyze(files) {
+  const infos = new Map();
+  const asts = new Map();
+  for (const [name, code] of Object.entries(files)) {
+    const ast = parseModule(code, { ts: name.endsWith('.ts') || name.endsWith('.tsx') });
+    asts.set(name, ast);
+    infos.set(name, collectModuleInfo(ast));
+  }
+  const resolve = (_owner, source) => {
+    const base = source.replace(/^\.+\//, '').replace(/\.(js|mjs|ts|jsx|tsx)$/, '');
+    return infos.get(base) || null;
+  };
+  const out = [];
+  for (const [name, ast] of asts) {
+    out.push(...analyzeCalls({ ast, info: infos.get(name), file: name, resolve }));
+  }
+  return out;
+}
+const reasons = (f) => f.map((x) => `${x.confidence}:${x.callee}`);
+const clean = (files) => expect(reasons(analyze(files))).toEqual([]);
+
+describe('scope & shadowing — must NOT false-positive', () => {
+  test('parameter shadows a non-callable named import', () =>
+    clean({ m: 'export const foo = {};', a: "import { foo } from './m'; [1].forEach(foo => foo());" }));
+
+  test('local const shadows a non-callable import inside a function', () =>
+    clean({ m: 'export const config = {};', a: "import { config } from './m'; function s(){ const config = () => {}; config(); }" }));
+
+  test('block-scoped const shadows a not-exported import', () =>
+    clean({ m: 'export const y = 1;', a: "import { foo } from './m'; { const foo = () => {}; foo(); }" }));
+
+  test('catch param shadows an import', () =>
+    clean({ m: 'export const e = {};', a: "import { e } from './m'; try { x(); } catch (e) { e(); }" }));
+
+  test('arrow param shadows a namespace-missing member is N/A but local fn param call is clean', () =>
+    clean({ a: 'function run(cb) { cb(); }' }));
+
+  test('nested function redeclares a top-level non-callable binding', () =>
+    clean({ a: 'const handler = {}; function outer(){ const handler = () => {}; handler(); }' }));
+});
+
+describe('scope fix must NOT over-suppress — module-level bugs still caught', () => {
+  test('non-callable module import invoked inside a nested function (not shadowed) is flagged', () => {
+    const f = analyze({ m: 'export const cfg = {};', a: "import { cfg } from './m'; function run(){ cfg(); }" });
+    expect(reasons(f)).toEqual(['high:cfg']);
+  });
+  test('not-exported import invoked deep inside nested blocks is flagged', () => {
+    const f = analyze({ m: 'export const y = 1;', a: "import { foo } from './m'; if (a) { while (b) { foo(); } }" });
+    expect(reasons(f)).toEqual(['high:foo']);
+  });
+  test('namespace receiver shadowed by a parameter is NOT flagged', () =>
+    clean({ m: 'export const x = 1;', a: "import * as M from './m'; function f(M){ M.x(); }" }));
+  test('module-level object member miss inside a method is flagged', () => {
+    const f = analyze({ a: 'const o = { a() {} }; class C { run(){ o.b(); } }' });
+    expect(reasons(f)).toEqual(['medium:o.b']);
+  });
+});
+
+describe('imports — aliases, renames, type-only', () => {
+  test('aliased import that is not exported is flagged', () => {
+    const f = analyze({ m: 'export const bar = 1;', a: "import { foo as f } from './m'; f();" });
+    expect(reasons(f)).toEqual(['high:f']);
+  });
+  test('renamed export of a function is valid', () =>
+    clean({ m: 'const local = () => {}; export { local as pub };', a: "import { pub } from './m'; pub();" }));
+  test('re-export default as named has unknown kind (not flagged)', () =>
+    clean({ m: "export { default as Thing } from './other';", a: "import { Thing } from './m'; Thing();" }));
+  test('TypeScript type-only import is not treated as a value call', () =>
+    clean({ 'm.ts': 'export interface Foo { a: number }', 'a.ts': "import type { Foo } from './m'; const x: Foo = { a: 1 }; doThing(x);" }));
+});
+
+describe('higher-order / dynamic shapes — must NOT false-positive', () => {
+  test('HOF return invoked', () => clean({ a: 'const make = () => () => {}; make()();' }));
+  test('require result member call', () => clean({ a: "const m = require('./x'); m.foo();" }));
+  test('IIFE', () => clean({ a: '(function () {})();' }));
+  test('deep optional chain call', () => clean({ a: 'a?.b?.c?.();' }));
+  test('logical/conditional init', () => clean({ a: 'const f = a || (() => {}); f(); const g = c ? a : b; g();' }));
+  test('computed member', () => clean({ a: "const o = {}; o['x']();" }));
+});
+
+describe('classes — methods, fields, inheritance, statics, getters', () => {
+  test('arrow class field is callable', () =>
+    clean({ a: 'class F { run = () => {} } const i = new F(); i.run();' }));
+  test('static method call is not falsely flagged', () =>
+    clean({ a: 'class F { static make() {} } F.make();' }));
+  test('getter returning a function is not flagged', () =>
+    clean({ a: 'class F { get h() { return () => {}; } } const i = new F(); i.h();' }));
+  test('inherited method (superclass present) is not flagged', () =>
+    clean({ a: 'class B { run() {} } class F extends B { go() {} } const i = new F(); i.run();' }));
+  test('real missing method on a complete local class is flagged', () => {
+    const f = analyze({ a: 'class F { run() {} } const i = new F(); i.walk();' });
+    expect(reasons(f)).toEqual(['medium:i.walk']);
+  });
+
+  test('class with a computed method name is incomplete (not flagged)', () =>
+    clean({ a: "const k = 'run'; class F { [k]() {} } const i = new F(); i.walk();" }));
+});
+
+describe('objects — computed keys, getters, spreads', () => {
+  test('object with a computed-key method is treated as incomplete (not flagged)', () =>
+    clean({ a: 'const k = "go"; const o = { [k]: () => {} }; o.something();' }));
+  test('object getter is not assumed non-callable', () =>
+    clean({ a: 'const o = { get h() { return () => {}; } }; o.h();' }));
+  test('object with spread is incomplete (not flagged)', () =>
+    clean({ a: 'const base = {}; const o = { ...base, a() {} }; o.b();' }));
+  test('real missing member on a complete object literal is flagged', () => {
+    const f = analyze({ a: 'const o = { a() {} }; o.b();' });
+    expect(reasons(f)).toEqual(['medium:o.b']);
+  });
+});
+
+describe('module forms — default object/instance, CJS, generators/async', () => {
+  test('default export object member valid', () =>
+    clean({ m: 'export default { run() {} };', a: "import api from './m'; api.run();" }));
+  test('default export object missing member flagged', () => {
+    const f = analyze({ m: 'export default { run() {} };', a: "import api from './m'; api.stop();" });
+    expect(reasons(f)).toEqual(['medium:api.stop']);
+  });
+  test('async + generator exports are callable', () =>
+    clean({ m: 'export async function a(){} export function* g(){}', a: "import { a, g } from './m'; a(); g();" }));
+  test('namespace member that is an async function is valid', () =>
+    clean({ m: 'export async function load(){}', a: "import * as M from './m'; M.load();" }));
+  test('class export called WITHOUT new is intentionally not flagged (different error)', () =>
+    clean({ m: 'export class Svc {}', a: "import { Svc } from './m'; Svc();" }));
+});
+
+describe('hoisting & ordering', () => {
+  test('top-level function called before its declaration', () =>
+    clean({ a: 'foo(); function foo() {}' }));
+  test('namespace member valid regardless of order', () =>
+    clean({ m: 'export const run = () => {};', a: "import * as M from './m'; M.run();" }));
+});