onbuzz 4.4.0 → 4.5.0

package/src/modules/widget/__tests__/naming.test.js

@@ -0,0 +1,204 @@
+/**
+ * Widget naming/renaming — optional human-friendly display name.
+ *
+ * Contract:
+ *   - widgetId is the stable identifier; name is purely cosmetic.
+ *   - Names are NOT unique — two widgets can share a name; that's fine.
+ *   - render { name?: string } sets the name on FIRST render only;
+ *     re-renders don't accidentally rename. Use rename action to change.
+ *   - rename { widgetId, name } sets/changes the name.
+ *   - rename { widgetId, name: null } (or '') clears the name.
+ *   - Whitespace is trimmed; control chars rejected; max 80 chars.
+ *   - Emits widget-changed with changeType: 'renamed' (and previousName).
+ */
+
+import { describe, test, expect, beforeEach } from '@jest/globals';
+import { WidgetTool } from '../widgetTool.js';
+
+const LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+const ctx = (agentId = 'a') => ({ agentId, toolConfig: { allowCustomCode: true } });
+
+let tool;
+beforeEach(() => { tool = new WidgetTool({}, LOGGER); });
+
+describe('render — optional name', () => {
+  test('render with name sets the name on the widget record', async () => {
+    const r = await tool.execute({
+      action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1', name: 'My Calculator',
+    }, ctx());
+    expect(r.success).toBe(true);
+    expect(r.widget.name).toBe('My Calculator');
+  });
+
+  test('render without name → widget.name is undefined/null', async () => {
+    const r = await tool.execute({
+      action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1',
+    }, ctx());
+    expect(r.widget.name == null).toBe(true);
+  });
+
+  test('re-render does NOT overwrite an existing name (use rename for that)', async () => {
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1', name: 'Original' }, ctx());
+    const r = await tool.execute({ action: 'render', kind: 'html', content: '<p>v2</p>', widgetId: 'w1', name: 'Different' }, ctx());
+    expect(r.widget.name).toBe('Original');
+  });
+
+  test('render with surrounding whitespace → name is trimmed before storage', async () => {
+    const r = await tool.execute({
+      action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1', name: '  Habit Tracker  ',
+    }, ctx());
+    expect(r.widget.name).toBe('Habit Tracker');
+  });
+
+  test('name validation: rejects empty string', async () => {
+    const r = await tool.execute({
+      action: 'render', kind: 'html', content: '<p/>', name: '   ',
+    }, ctx());
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/non-empty/);
+  });
+
+  test('name validation: rejects non-string', async () => {
+    const r = await tool.execute({
+      action: 'render', kind: 'html', content: '<p/>', name: 42,
+    }, ctx());
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/string/);
+  });
+
+  test('name validation: rejects > 80 chars', async () => {
+    const long = 'x'.repeat(81);
+    const r = await tool.execute({ action: 'render', kind: 'html', content: '<p/>', name: long }, ctx());
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/exceeds 80/);
+  });
+
+  test('name validation: 80 chars exactly is OK', async () => {
+    const exactly80 = 'x'.repeat(80);
+    const r = await tool.execute({ action: 'render', kind: 'html', content: '<p/>', name: exactly80 }, ctx());
+    expect(r.success).toBe(true);
+    expect(r.widget.name).toBe(exactly80);
+  });
+
+  test('name validation: rejects control characters', async () => {
+    const r = await tool.execute({
+      action: 'render', kind: 'html', content: '<p/>', name: 'My\x00Widget',
+    }, ctx());
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/control characters/);
+  });
+});
+
+describe('rename action', () => {
+  beforeEach(async () => {
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1' }, ctx());
+  });
+
+  test('renames an existing widget', async () => {
+    const r = await tool.execute({ action: 'rename', widgetId: 'w1', name: 'Calculator' }, ctx());
+    expect(r.success).toBe(true);
+    expect(r.name).toBe('Calculator');
+    expect(r.previousName).toBeNull();
+    expect(r.widget.name).toBe('Calculator');
+  });
+
+  test('renaming again replaces the name; previousName reports the old', async () => {
+    await tool.execute({ action: 'rename', widgetId: 'w1', name: 'First' }, ctx());
+    const r = await tool.execute({ action: 'rename', widgetId: 'w1', name: 'Second' }, ctx());
+    expect(r.previousName).toBe('First');
+    expect(r.name).toBe('Second');
+  });
+
+  test('rename with null clears the name', async () => {
+    await tool.execute({ action: 'rename', widgetId: 'w1', name: 'Temp' }, ctx());
+    const r = await tool.execute({ action: 'rename', widgetId: 'w1', name: null }, ctx());
+    expect(r.success).toBe(true);
+    expect(r.name).toBeNull();
+    expect(r.previousName).toBe('Temp');
+  });
+
+  test('rename with empty string clears the name', async () => {
+    await tool.execute({ action: 'rename', widgetId: 'w1', name: 'Temp' }, ctx());
+    const r = await tool.execute({ action: 'rename', widgetId: 'w1', name: '' }, ctx());
+    expect(r.name).toBeNull();
+  });
+
+  test('renaming a non-existent widget returns an error', async () => {
+    const r = await tool.execute({ action: 'rename', widgetId: 'never-existed', name: 'X' }, ctx());
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/Widget not found/);
+  });
+
+  test('rename trims whitespace', async () => {
+    const r = await tool.execute({ action: 'rename', widgetId: 'w1', name: '  Spaced Name  ' }, ctx());
+    expect(r.name).toBe('Spaced Name');
+  });
+
+  test('rename validation errors propagate (control chars, too-long, etc.)', async () => {
+    const r = await tool.execute({
+      action: 'rename', widgetId: 'w1', name: 'x'.repeat(81),
+    }, ctx());
+    expect(r.success).toBe(false);
+    expect(r.error).toMatch(/exceeds 80/);
+  });
+});
+
+describe('event bus emits "renamed" change', () => {
+  test('renaming fires widget-changed with changeType "renamed" and previousName', async () => {
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1', name: 'Old' }, ctx());
+    const events = [];
+    tool.events.on('widget-changed', e => events.push(e));
+    await tool.execute({ action: 'rename', widgetId: 'w1', name: 'New' }, ctx());
+    const renamed = events.find(e => e.changeType === 'renamed');
+    expect(renamed).toBeDefined();
+    expect(renamed.summary.name).toBe('New');
+    expect(renamed.previousName).toBe('Old');
+    expect(renamed.widgetId).toBe('w1');
+  });
+
+  test('renamed emission also fires when name is cleared (new=null, previous=set)', async () => {
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1', name: 'Old' }, ctx());
+    const events = [];
+    tool.events.on('widget-changed', e => events.push(e));
+    await tool.execute({ action: 'rename', widgetId: 'w1', name: null }, ctx());
+    const renamed = events.find(e => e.changeType === 'renamed');
+    expect(renamed.summary.name).toBeNull();
+    expect(renamed.previousName).toBe('Old');
+  });
+});
+
+describe('summary + list expose the name', () => {
+  test('name appears on the rendered widget summary', async () => {
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1', name: 'Foo' }, ctx());
+    const summary = tool._buildSummary(tool._widgetsByAgent.get('a').get('w1'));
+    expect(summary.name).toBe('Foo');
+  });
+
+  test('list includes name field for every widget (null when not set)', async () => {
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'a', name: 'Alpha' }, ctx());
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'b' }, ctx());
+    const r = await tool.execute({ action: 'list' }, ctx());
+    const a = r.widgets.find(w => w.widgetId === 'a');
+    const b = r.widgets.find(w => w.widgetId === 'b');
+    expect(a.name).toBe('Alpha');
+    expect(b.name).toBeNull();
+  });
+});
+
+describe('non-uniqueness — two widgets can share a name', () => {
+  test('two widgets with the same name coexist (widgetId is the unique key)', async () => {
+    await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'w1', name: 'Twin' }, ctx());
+    const r = await tool.execute({ action: 'render', kind: 'html', content: '<p/>', widgetId: 'w2', name: 'Twin' }, ctx());
+    expect(r.success).toBe(true);
+    expect(r.widget.name).toBe('Twin');
+    const list = await tool.execute({ action: 'list' }, ctx());
+    const named = list.widgets.filter(w => w.name === 'Twin');
+    expect(named).toHaveLength(2);
+  });
+});
+
+describe('rename appears in supported actions', () => {
+  test('rename listed in getSupportedActions', () => {
+    expect(tool.getSupportedActions()).toContain('rename');
+  });
+});

package/src/modules/widget/routes.js

@@ -398,6 +398,27 @@ export function registerRoutes(app, orchestrator, extras = {}) {
       res.status(500).json({ success: false, error: error.message });
     }
   });
+
+  // POST /api/widget/rename — user-driven rename via the artifacts panel.
+  // Body: { agentId, widgetId, name } where name=null|'' clears the name.
+  app.post('/api/widget/rename', async (req, res) => {
+    try {
+      const { agentId, widgetId, name } = req.body || {};
+      if (!agentId || !widgetId) {
+        return res.status(400).json({ success: false, error: 'agentId and widgetId are required' });
+      }
+      const tool = getWidgetTool();
+      if (!tool) return res.status(503).json({ success: false, error: 'widget tool unavailable' });
+      const result = await tool.execute(
+        { action: 'rename', widgetId, name: name == null ? null : name },
+        { agentId, toolConfig: { allowCustomCode: true } }
+      );
+      const status = result.success ? 200 : (result.error === 'widget tool unavailable' ? 503 : 400);
+      res.status(status).json(result);
+    } catch (error) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  });
 }
 
 function _summarize(w) {

package/src/modules/widget/schema.js

@@ -18,6 +18,7 @@
 export const WIDGET_LIMITS = {
   MAX_CONTENT_BYTES:   50 * 1024, // 50 KB per widget payload
   MAX_WIDGET_ID_LEN:   128,
+  MAX_WIDGET_NAME_LEN: 80,        // human-friendly display name (not unique)
   MAX_WIDGETS_PER_AGENT: 50,      // LRU-evicted beyond this
   MAX_VERSIONS_PER_WIDGET: 20,    // history ring; older versions evicted
 };
@@ -37,9 +38,42 @@ export const WIDGET_KINDS = Object.freeze(['html', 'jsx', 'webcomponent']);
  * Validate a `render` payload.
  * Returns { valid: true } or { valid: false, error: string }.
  */
+/**
+ * Shared validator for the optional human-friendly display name.
+ * Names are NOT unique per agent — that's the widgetId's job. Names are
+ * purely cosmetic; multiple widgets named "Calculator" coexist fine.
+ */
+function validateName(name) {
+  if (name == null) return { valid: true };
+  if (typeof name !== 'string') return { valid: false, error: 'name must be a string' };
+  // Trim before length check so trailing whitespace doesn't push valid
+  // names over the cap; the canonical (trimmed) value is what we store.
+  const trimmed = name.trim();
+  if (trimmed.length === 0) {
+    return { valid: false, error: 'name must be non-empty (or omit it)' };
+  }
+  if (trimmed.length > WIDGET_LIMITS.MAX_WIDGET_NAME_LEN) {
+    return { valid: false, error: `name exceeds ${WIDGET_LIMITS.MAX_WIDGET_NAME_LEN} chars` };
+  }
+  // Reject control characters — names appear in card UIs and tooltips,
+  // a stray \r or \x00 would mangle layout.
+  if (/[\x00-\x1f\x7f]/.test(trimmed)) {
+    return { valid: false, error: 'name must not contain control characters' };
+  }
+  return { valid: true, normalized: trimmed };
+}
+
+/** Public wrapper so the tool can canonicalize the same way validators do. */
+export function normalizeName(name) {
+  const r = validateName(name);
+  return r.valid && r.normalized != null ? r.normalized : null;
+}
+
 export function validateRenderParams(params) {
   if (!params || typeof params !== 'object') return { valid: false, error: 'params must be an object' };
-  const { kind, content, widgetId, props } = params;
+  const { kind, content, widgetId, props, name } = params;
+  const nameRes = validateName(name);
+  if (!nameRes.valid) return nameRes;
 
   if (!WIDGET_KINDS.includes(kind)) {
     return { valid: false, error: `kind must be one of: ${WIDGET_KINDS.join(', ')}` };
@@ -131,3 +165,17 @@ export function validateGetVersionParams(params) {
 export function validateSetMainParams(params) {
   return validateGetVersionParams(params);
 }
+
+/**
+ * `rename { widgetId, name }` — set/clear the human-friendly display name.
+ * Pass null/empty name to clear. Names are NOT unique — widgetId is.
+ */
+export function validateRenameParams(params) {
+  if (!params || typeof params !== 'object') return { valid: false, error: 'params must be an object' };
+  if (typeof params.widgetId !== 'string' || !params.widgetId) {
+    return { valid: false, error: 'widgetId is required' };
+  }
+  // Allow explicit null/'' to CLEAR the name (revert to widgetId-as-display).
+  if (params.name === null || params.name === '') return { valid: true, clear: true };
+  return validateName(params.name);
+}

package/src/modules/widget/widgetTool.js

@@ -36,6 +36,8 @@ import {
   validateListVersionsParams,
   validateGetVersionParams,
   validateSetMainParams,
+  validateRenameParams,
+  normalizeName,
   WIDGET_LIMITS,
 } from './schema.js';
 import { scanForPhishingKeywords } from './phishingScanner.js';
@@ -139,6 +141,7 @@ export class WidgetTool extends BaseTool {
     if (!widget) return null;
     return {
       widgetId:        widget.widgetId,
+      name:            widget.name || null,
       kind:            widget.kind,
       createdAt:       widget.createdAt,
       updatedAt:       widget.updatedAt,
@@ -589,6 +592,9 @@ SAFETY:
       // Versioning — each render appends a new version. Agent (and
       // user) can promote a version as main or fetch any version's content.
       'list-versions', 'get-version', 'set-main',
+      // Naming — set/clear a human-friendly display name (cosmetic;
+      // widgetId remains the stable identifier).
+      'rename',
       // Gallery — cross-session catalog of shared widget templates.
       'share-to-gallery', 'unshare-from-gallery',
       'list-gallery', 'render-from-gallery',
@@ -619,6 +625,7 @@ SAFETY:
       case 'list-versions':         return this._listVersions(agentId, params);
       case 'get-version':           return this._getVersion(agentId, params);
       case 'set-main':              return this._setMain(agentId, params);
+      case 'rename':                return this._rename(agentId, params);
       case 'share-to-gallery':      return this._shareToGallery(agentId, params, context);
       case 'unshare-from-gallery':  return this._unshareFromGallery(agentId, params);
       case 'list-gallery':          return this._listGallery(params);
@@ -764,6 +771,14 @@ SAFETY:
 
     const widget = this._appendVersion(agentId, widgetId, newVersion);
 
+    // Optional display name: only set on FIRST render (so subsequent
+    // renders don't accidentally clear or change a name the user picked).
+    // To rename an existing widget, use the dedicated `rename` action.
+    const requestedName = normalizeName(params.name);
+    if (requestedName && !widget.name) {
+      widget.name = requestedName;
+    }
+
     this.logger?.info?.('Widget rendered', {
       agentId, widgetId,
       kind:          widget.kind,
@@ -839,6 +854,7 @@ SAFETY:
     // artifacts panel needs to render a card without fetching content.
     const widgets = Array.from(agentWidgets.values()).map(w => ({
       widgetId:        w.widgetId,
+      name:            w.name || null,
       kind:            w.kind,
       createdAt:       w.createdAt,
       updatedAt:       w.updatedAt,
@@ -926,6 +942,43 @@ SAFETY:
     return { success: true, action: 'set-main', widgetId: widget.widgetId, widget };
   }
 
+  /**
+   * `rename { widgetId, name }` — set/clear the human-friendly display name.
+   * Pass null/'' to clear (revert to widgetId-as-display).
+   * Names are NOT unique per agent — multiple widgets can share a name;
+   * widgetId remains the stable identifier.
+   */
+  _rename(agentId, params) {
+    const v = validateRenameParams(params);
+    if (!v.valid) return { success: false, error: v.error };
+    const widget = this._widgetsByAgent.get(agentId)?.get(params.widgetId);
+    if (!widget) return { success: false, error: `Widget not found: ${params.widgetId}` };
+
+    const previous = widget.name || null;
+    if (v.clear) {
+      widget.name = null;
+    } else {
+      // validator returns the trimmed canonical form when valid.
+      widget.name = v.normalized != null ? v.normalized : String(params.name).trim();
+    }
+    widget.updatedAt = new Date().toISOString();
+
+    this.logger?.info?.('Widget renamed', {
+      agentId, widgetId: widget.widgetId,
+      from: previous, to: widget.name,
+    });
+    this._emitChange(agentId, widget.widgetId, 'renamed', widget, {
+      previousName: previous,
+    });
+    return {
+      success: true, action: 'rename',
+      widgetId: widget.widgetId,
+      name: widget.name,
+      previousName: previous,
+      widget,
+    };
+  }
+
   /**
    * Append a new version to a widget (or create a new widget for the
    * agent if none exists). Returns the (mutated) widget record.

package/src/services/__tests__/contextInjectionService.test.js

@@ -202,4 +202,45 @@ describe('ContextInjectionService', () => {
     const result = service.buildSystemConstraints();
     expect(result).toBe('');
   });
+
+  describe('buildCurrentTimeContext', () => {
+    test('formats a fixed Date as "Current local time: hh:mm dd/mm/yyyy"', () => {
+      // Construct a date from explicit local-time fields so this test
+      // doesn't drift across host timezones (which getHours/getDate read).
+      const fixed = new Date(2026, 3, 26, 9, 5, 0); // Apr 26 2026, 09:05 local
+      const result = service.buildCurrentTimeContext(fixed);
+      expect(result).toBe('\n\nCurrent local time: 09:05 26/04/2026');
+    });
+
+    test('zero-pads single-digit hours, minutes, day, month', () => {
+      const fixed = new Date(2026, 0, 3, 7, 4, 0); // Jan 03 2026, 07:04 local
+      const result = service.buildCurrentTimeContext(fixed);
+      expect(result).toBe('\n\nCurrent local time: 07:04 03/01/2026');
+    });
+
+    test('renders midnight as 00:00, not 24:00', () => {
+      const fixed = new Date(2026, 11, 31, 0, 0, 0); // Dec 31 2026, 00:00 local
+      expect(service.buildCurrentTimeContext(fixed)).toBe('\n\nCurrent local time: 00:00 31/12/2026');
+    });
+
+    test('returns empty string for invalid Date', () => {
+      expect(service.buildCurrentTimeContext(new Date('invalid'))).toBe('');
+    });
+
+    test('returns empty string for non-Date input', () => {
+      expect(service.buildCurrentTimeContext('2026-04-26')).toBe('');
+      expect(service.buildCurrentTimeContext(null)).toBe('');
+      expect(service.buildCurrentTimeContext(undefined)).not.toBe('');   // defaults to new Date()
+    });
+
+    test('default argument uses current time (string is non-empty and well-formed)', () => {
+      const result = service.buildCurrentTimeContext();
+      expect(result).toMatch(/^\n\nCurrent local time: \d{2}:\d{2} \d{2}\/\d{2}\/\d{4}$/);
+    });
+
+    test('output begins with two newlines so it cleanly appends to existing prompt', () => {
+      const result = service.buildCurrentTimeContext(new Date(2026, 5, 1, 12, 0, 0));
+      expect(result.startsWith('\n\n')).toBe(true);
+    });
+  });
 });

package/src/services/contextInjectionService.js

@@ -263,6 +263,30 @@ class ContextInjectionService {
       return '';
     }
   }
+
+  /**
+   * Build a "Current local time" line to prepend to the per-turn system
+   * prompt. Re-evaluated on every turn so the agent always sees the time
+   * the model is actually answering at, not the time the agent was created.
+   *
+   * Format: "Current local time: hh:mm dd/mm/yyyy" — fixed, one line.
+   * Locale-independent because LLMs do not need surprises across locales:
+   * agents reasoning about "now is past 17:00, schedule for tomorrow" should
+   * get the same shape regardless of where the host runs.
+   *
+   * @param {Date} [now] override for tests
+   * @returns {string} Empty string if `now` is not a valid Date.
+   */
+  buildCurrentTimeContext(now = new Date()) {
+    if (!(now instanceof Date) || Number.isNaN(now.getTime())) return '';
+    const pad = (n) => String(n).padStart(2, '0');
+    const hh = pad(now.getHours());
+    const mm = pad(now.getMinutes());
+    const dd = pad(now.getDate());
+    const mo = pad(now.getMonth() + 1);
+    const yy = now.getFullYear();
+    return `\n\nCurrent local time: ${hh}:${mm} ${dd}/${mo}/${yy}`;
+  }
 }
 
 export default ContextInjectionService;