@newsails/veil-cli 1.0.1

package/ui/views/tasks.js

@@ -0,0 +1,415 @@
+'use strict';
+window.Veil = window.Veil || {};
+window.Veil.views = window.Veil.views || {};
+
+window.Veil.views.tasks = {
+  _selected: null,
+  _stream:   null,
+  _pollTimer: null,
+
+  render() {
+    return `
+      <div style="display:flex;height:100%;">
+        <!-- List panel -->
+        <div style="width:280px;flex-shrink:0;border-right:1px solid var(--border);display:flex;flex-direction:column;overflow:hidden;background:var(--surface);">
+          <div style="padding:10px 14px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:8px;">
+            <span style="font-weight:600;font-size:13px;color:var(--text);flex:1;">Tasks</span>
+            <button id="btn-create-task" class="btn btn-primary btn-sm">+ New</button>
+            <button id="btn-refresh-tasks" class="btn btn-secondary btn-sm" title="Refresh">↻</button>
+          </div>
+          <!-- Filters -->
+          <div style="padding:8px 14px;border-bottom:1px solid var(--border);display:flex;gap:6px;flex-wrap:wrap;">
+            <select id="task-filter-status" class="input" style="flex:1;padding:4px 8px;font-size:12px;cursor:pointer;">
+              <option value="">All statuses</option>
+              <option value="pending">pending</option>
+              <option value="processing">processing</option>
+              <option value="finished">finished</option>
+              <option value="failed">failed</option>
+              <option value="waiting">waiting</option>
+              <option value="canceled">canceled</option>
+            </select>
+            <select id="task-filter-agent" class="input" style="flex:1;padding:4px 8px;font-size:12px;cursor:pointer;">
+              <option value="">All agents</option>
+            </select>
+          </div>
+          <div id="task-list" style="flex:1;overflow-y:auto;"></div>
+        </div>
+        <!-- Detail panel -->
+        <div id="task-detail" style="flex:1;overflow-y:auto;">
+          <div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text3);font-size:13.5px;">
+            Select a task
+          </div>
+        </div>
+      </div>`;
+  },
+
+  async mount(params) {
+    params = params || {};
+    await this._populateAgentFilter();
+    await this._loadList();
+
+    document.getElementById('btn-create-task').addEventListener('click', () => this._showCreateModal());
+    document.getElementById('btn-refresh-tasks').addEventListener('click', () => this._loadList());
+    document.getElementById('task-filter-status').addEventListener('change', () => this._loadList());
+    document.getElementById('task-filter-agent').addEventListener('change', () => this._loadList());
+
+    if (params.taskId) {
+      this._selected = params.taskId;
+      this._loadDetail(params.taskId);
+    }
+  },
+
+  unmount() {
+    if (this._stream)    { this._stream.close(); this._stream = null; }
+    if (this._pollTimer) { clearInterval(this._pollTimer); this._pollTimer = null; }
+    this._selected = null;
+  },
+
+  async _populateAgentFilter() {
+    const sel = document.getElementById('task-filter-agent');
+    if (!sel) return;
+    try {
+      const data   = await window.Veil.state.api.listAgents();
+      const agents = data.agents || [];
+      const preferred = window.Veil.state.currentAgent;
+      agents.forEach(a => {
+        const opt = document.createElement('option');
+        opt.value = a.name; opt.textContent = a.name;
+        if (a.name === preferred) opt.selected = true;
+        sel.appendChild(opt);
+      });
+    } catch {}
+  },
+
+  async _loadList() {
+    const el = document.getElementById('task-list');
+    if (!el) return;
+    el.innerHTML = `<div style="padding:16px;text-align:center;color:var(--text3);">${window.Veil.utils.spinner()}</div>`;
+    const params = {};
+    const status = document.getElementById('task-filter-status')?.value;
+    const agent  = document.getElementById('task-filter-agent')?.value;
+    if (status) params.status    = status;
+    if (agent)  params.agentName = agent;
+    params.limit = 50;
+    try {
+      const data  = await window.Veil.state.api.listTasks(params);
+      const tasks = data.tasks || [];
+      if (tasks.length === 0) {
+        el.innerHTML = `<div style="padding:20px;text-align:center;color:var(--text3);font-size:13px;">No tasks found</div>`;
+        return;
+      }
+      const U = window.Veil.utils;
+      el.innerHTML = tasks.map(t => `
+        <div class="list-item ${this._selected === t.id ? 'selected' : ''}" data-task-id="${U.esc(t.id)}">
+          <div style="display:flex;align-items:center;gap:6px;margin-bottom:3px;">
+            ${U.badge(t.status)}
+            <span style="font-size:12px;color:var(--text3);margin-left:auto;">${U.relTime(t.created_at)}</span>
+          </div>
+          <div style="font-size:12.5px;color:var(--text2);margin-bottom:2px;">${U.esc(t.agent_name)}</div>
+          <div style="font-size:13px;color:var(--text);">${U.esc(U.truncate(t.input, 60))}</div>
+        </div>`).join('');
+      el.querySelectorAll('[data-task-id]').forEach(row => {
+        row.addEventListener('click', () => {
+          const id = row.getAttribute('data-task-id');
+          el.querySelectorAll('.list-item').forEach(r => r.classList.remove('selected'));
+          row.classList.add('selected');
+          this._selected = id;
+          this._loadDetail(id);
+        });
+      });
+      if (this._selected) this._loadDetail(this._selected);
+    } catch (err) {
+      if (el) el.innerHTML = `<div style="padding:14px;color:var(--red);font-size:13px;">${window.Veil.utils.esc(err.message)}</div>`;
+    }
+  },
+
+  async _loadDetail(id) {
+    const el = document.getElementById('task-detail');
+    if (!el) return;
+    if (this._stream)    { this._stream.close(); this._stream = null; }
+    if (this._pollTimer) { clearInterval(this._pollTimer); this._pollTimer = null; }
+    el.innerHTML = `<div style="padding:20px;color:var(--text3);">${window.Veil.utils.spinner()} Loading…</div>`;
+    try {
+      const data = await window.Veil.state.api.getTask(id);
+      this._renderDetail(data.task);
+      await this._renderEvents(id);
+    } catch (err) {
+      if (el) el.innerHTML = `<div style="padding:14px;color:var(--red);font-size:13px;">${window.Veil.utils.esc(err.message)}</div>`;
+    }
+  },
+
+  _renderDetail(task) {
+    const el = document.getElementById('task-detail');
+    if (!el) return;
+    const U = window.Veil.utils;
+    const isActive   = ['pending','processing','waiting'].includes(task.status);
+    const isWaiting  = task.status === 'waiting';
+    const isRunning  = ['pending','processing'].includes(task.status);
+    const duration   = task.started_at && task.finished_at
+      ? U.formatMs(new Date(task.finished_at) - new Date(task.started_at)) : '—';
+
+    const tagsHtml = (task.tags || []).map(t =>
+      `<span style="font-size:11px;background:var(--surface2);border:1px solid var(--border2);color:var(--text2);border-radius:4px;padding:1px 6px;">${U.esc(t)}</span>`
+    ).join(' ');
+
+    el.innerHTML = `
+      <div style="padding:20px;max-width:800px;">
+        <!-- Header -->
+        <div style="display:flex;align-items:flex-start;gap:10px;margin-bottom:14px;flex-wrap:wrap;">
+          <div style="display:flex;align-items:center;gap:8px;flex-wrap:wrap;flex:1;min-width:0;">
+            <span id="task-status-badge">${U.badge(task.status)}</span>
+            ${task.priority && task.priority !== 'normal' ? `<span class="badge badge-${task.priority === 'high' ? 'failed' : 'closed'}">${U.esc(task.priority)}</span>` : ''}
+            <code style="font-size:12px;color:var(--text3);font-family:'JetBrains Mono',monospace;word-break:break-all;">${U.esc(task.id)}</code>
+            ${tagsHtml}
+          </div>
+          <span style="font-size:12px;color:var(--text3);white-space:nowrap;">${U.relTime(task.created_at)}</span>
+        </div>
+        ${task.parent_task_id ? `
+          <div style="font-size:12px;color:var(--text3);margin-bottom:10px;">Spawned by: <a href="#" onclick="event.preventDefault();window.Veil.navigate('tasks',{taskId:'${U.esc(task.parent_task_id)}'})" style="color:var(--accent);">${U.esc(task.parent_task_id)}</a></div>` : ''}
+
+        <!-- Stats grid -->
+        <div class="card" style="padding:14px;margin-bottom:14px;display:grid;grid-template-columns:repeat(auto-fill,minmax(120px,1fr));gap:10px;">
+          <div><div class="info-label">Agent</div><div style="font-size:13px;color:var(--text);margin-top:2px;">${U.esc(task.agent_name)}</div></div>
+          <div><div class="info-label">Duration</div><div style="font-size:13px;color:var(--text);margin-top:2px;">${duration}</div></div>
+          <div><div class="info-label">Iterations</div><div style="font-size:13px;color:var(--text);margin-top:2px;">${task.iterations || 0}</div></div>
+          <div><div class="info-label">Events</div><div style="font-size:13px;color:var(--text);margin-top:2px;">${task.eventCount || 0}</div></div>
+          <div><div class="info-label">Tokens in</div><div style="font-size:13px;color:var(--text);margin-top:2px;">${(task.token_input || 0).toLocaleString()}</div></div>
+          <div><div class="info-label">Tokens out</div><div style="font-size:13px;color:var(--text);margin-top:2px;">${(task.token_output || 0).toLocaleString()}</div></div>
+          ${task.started_at ? `<div><div class="info-label">Started</div><div style="font-size:12px;color:var(--text2);margin-top:2px;">${U.relTime(task.started_at)}</div></div>` : ''}
+          ${task.finished_at ? `<div><div class="info-label">Finished</div><div style="font-size:12px;color:var(--text2);margin-top:2px;">${U.relTime(task.finished_at)}</div></div>` : ''}
+        </div>
+
+        <!-- Actions -->
+        <div style="display:flex;gap:8px;margin-bottom:16px;flex-wrap:wrap;">
+          ${isRunning  ? `<button class="btn btn-danger btn-sm" id="btn-cancel-task">Cancel</button>` : ''}
+          ${isActive   ? `<button class="btn btn-secondary btn-sm" id="btn-stream-task">▶ Stream</button>` : ''}
+          <button class="btn btn-secondary btn-sm" id="btn-refresh-detail">↻ Refresh</button>
+          ${task.session_id ? `<button class="btn btn-secondary btn-sm" id="btn-view-sess-task">→ Session</button>` : ''}
+          <button class="btn btn-danger btn-sm" id="btn-delete-task">${isActive ? 'Force Delete' : 'Delete'}</button>
+        </div>
+
+        <!-- Respond (if waiting) -->
+        ${isWaiting ? `
+          <div class="card" style="padding:14px;margin-bottom:14px;border-color:rgba(234,179,8,0.25);">
+            <div style="font-size:13px;color:var(--yellow);margin-bottom:8px;font-weight:600;">⏳ Task is waiting for a response</div>
+            <div style="display:flex;gap:8px;">
+              <input id="task-respond-input" class="input" placeholder="Enter your response…" />
+              <button class="btn btn-success btn-sm" id="btn-respond-task" style="flex-shrink:0;">Respond</button>
+            </div>
+          </div>` : ''}
+
+        <!-- Input -->
+        <div class="card" style="margin-bottom:12px;">
+          <div class="panel-header" style="display:flex;align-items:center;justify-content:space-between;">
+            <span>Input</span>
+            ${task.priority !== 'normal' ? `<span class="badge badge-${task.priority==='high'?'failed':'closed'}">${U.esc(task.priority)}</span>` : ''}
+          </div>
+          <div style="padding:12px;font-size:13.5px;white-space:pre-wrap;color:var(--text);line-height:1.5;">${U.esc(task.input || '')}</div>
+        </div>
+
+        <!-- Output -->
+        ${task.output != null ? `
+          <div class="card" style="margin-bottom:12px;">
+            <div class="panel-header">Output</div>
+            <div style="padding:12px;font-size:13.5px;white-space:pre-wrap;color:var(--text);line-height:1.5;">${U.esc(task.output)}</div>
+          </div>` : ''}
+
+        <!-- Error -->
+        ${task.error ? (() => {
+          const err = typeof task.error === 'object' ? task.error : { message: task.error };
+          const codeHtml = err.code ? `<span style="font-size:12px;background:rgba(239,68,68,0.12);border:1px solid rgba(239,68,68,0.25);color:var(--red);border-radius:4px;padding:1px 7px;font-family:'JetBrains Mono',monospace;">${U.esc(err.code)}</span>` : '';
+          const msgHtml  = err.message ? `<div style="font-size:13px;color:var(--red);margin-top:6px;line-height:1.5;">${U.esc(err.message)}</div>` : '';
+          const extraKeys = Object.keys(err).filter(k => k !== 'code' && k !== 'message');
+          const extraHtml = extraKeys.length ? `<pre style="font-size:12px;color:var(--text2);margin-top:8px;background:var(--bg);border-radius:5px;padding:8px;overflow-x:auto;">${U.esc(JSON.stringify(Object.fromEntries(extraKeys.map(k=>[k,err[k]])),null,2))}</pre>` : '';
+          return `<div class="card" style="margin-bottom:12px;border-color:rgba(239,68,68,0.25);">
+            <div class="panel-header" style="color:var(--red);display:flex;align-items:center;gap:8px;">Error ${codeHtml}</div>
+            <div style="padding:10px 12px;">${msgHtml}${extraHtml}</div>
+          </div>`;
+        })() : ''}
+
+        <!-- Event Timeline placeholder -->
+        <div class="card" id="task-events-card">
+          <div class="panel-header">Event Timeline</div>
+          <div id="task-events-body" style="padding:12px;color:var(--text3);font-size:13px;">${U.spinner()} Loading events…</div>
+        </div>
+      </div>`;
+
+    document.getElementById('btn-refresh-detail')?.addEventListener('click', () => this._loadDetail(task.id));
+    document.getElementById('btn-cancel-task')?.addEventListener('click', async () => {
+      try {
+        await window.Veil.state.api.cancelTask(task.id);
+        window.Veil.utils.toast('Task canceled', 'success');
+        this._loadDetail(task.id);
+        this._loadList();
+      } catch (err) { window.Veil.utils.toast('Cancel failed: ' + err.message, 'error'); }
+    });
+    document.getElementById('btn-delete-task')?.addEventListener('click', async () => {
+      if (!confirm('Delete this task and all its data?')) return;
+      const force = isActive;
+      try {
+        await window.Veil.state.api.deleteTask(task.id, force);
+        window.Veil.utils.toast('Task deleted', 'success');
+        this._selected = null;
+        document.getElementById('task-detail').innerHTML = `<div style="display:flex;align-items:center;justify-content:center;height:100%;color:var(--text3);font-size:13.5px;">Task deleted</div>`;
+        this._loadList();
+      } catch (err) { window.Veil.utils.toast('Delete failed: ' + err.message, 'error'); }
+    });
+    document.getElementById('btn-stream-task')?.addEventListener('click', () => this._startStream(task.id));
+    document.getElementById('btn-view-sess-task')?.addEventListener('click', () => {
+      window.Veil.navigate('sessions', { sessionId: task.session_id });
+    });
+    document.getElementById('btn-respond-task')?.addEventListener('click', async () => {
+      const input = document.getElementById('task-respond-input');
+      if (!input?.value.trim()) return;
+      try {
+        await window.Veil.state.api.respondTask(task.id, input.value.trim());
+        window.Veil.utils.toast('Response sent', 'success');
+        this._loadDetail(task.id);
+      } catch (err) { window.Veil.utils.toast('Respond failed: ' + err.message, 'error'); }
+    });
+  },
+
+  async _renderEvents(taskId) {
+    const el = document.getElementById('task-events-body');
+    if (!el) return;
+    try {
+      const data   = await window.Veil.state.api.getTaskEvents(taskId, 0);
+      const events = data.events || [];
+      if (events.length === 0) {
+        el.innerHTML = `<span style="color:var(--text3);">No events recorded</span>`; return;
+      }
+      const U = window.Veil.utils;
+      el.innerHTML = events.map(ev => this._renderEventRow(ev, U)).join('');
+    } catch (err) {
+      if (el) el.innerHTML = `<span style="color:var(--red);">${window.Veil.utils.esc(err.message)}</span>`;
+    }
+  },
+
+  _renderEventRow(ev, U) {
+    const d = ev.data || {};
+    let icon = '◦', color = 'var(--text2)', content = '';
+    if (ev.type === 'status.change') {
+      icon = '⟳'; color = 'var(--accent)';
+      content = `${U.esc(d.from || '?')} → ${U.esc(d.to || '?')}${d.reason ? ` (${U.esc(d.reason)})` : ''}`;
+    } else if (ev.type === 'tool.start') {
+      icon = '⚙'; color = 'var(--yellow)';
+      content = `<b style="color:var(--yellow);">${U.esc(d.toolName)}</b>`;
+      if (d.toolInput) content += ` <span style="color:var(--text3);">${U.esc(JSON.stringify(d.toolInput)).slice(0, 120)}</span>`;
+    } else if (ev.type === 'tool.end') {
+      icon = '✓'; color = d.success ? 'var(--green)' : 'var(--red)';
+      content = `<b style="color:${color};">${U.esc(d.toolName)}</b> ${d.durationMs ? U.formatMs(d.durationMs) : ''}`;
+      if (d.outputPreview) content += `<div style="font-family:monospace;font-size:12px;color:var(--text3);margin-top:3px;padding-left:12px;">${U.esc(d.outputPreview.slice(0, 200))}</div>`;
+    }
+    return `<div style="display:flex;gap:10px;padding:6px 0;border-bottom:1px solid var(--border);">
+      <div class="timeline-dot" style="background:${color};margin-top:6px;"></div>
+      <div style="flex:1;">
+        <div style="display:flex;gap:8px;align-items:center;">
+          <span style="font-size:13px;">${content || U.esc(ev.type)}</span>
+          <span style="font-size:12px;color:var(--text3);margin-left:auto;">${U.relTime(ev.created_at)}</span>
+        </div>
+      </div>
+    </div>`;
+  },
+
+  _startStream(taskId) {
+    if (this._stream) { this._stream.close(); this._stream = null; }
+    const evEl = document.getElementById('task-events-body');
+    if (evEl) evEl.innerHTML = `<span style="color:var(--accent);">📡 Streaming live events…</span><br>`;
+    const U = window.Veil.utils;
+    this._stream = window.Veil.state.api.taskStream(taskId, {
+      onStatus: (data) => {
+        const badge = document.getElementById('task-status-badge');
+        if (badge && data.status) badge.innerHTML = U.badge(data.status);
+        if (['finished','failed','canceled'].includes(data.status)) {
+          if (this._stream) { this._stream.close(); this._stream = null; }
+          this._loadDetail(taskId);
+          this._loadList();
+        }
+      },
+      onEvent: (ev) => {
+        const el = document.getElementById('task-events-body');
+        if (!el) return;
+        if (typeof ev === 'object' && ev.type) {
+          el.innerHTML += this._renderEventRow(ev, U);
+          el.scrollTop = el.scrollHeight;
+        }
+      },
+      onError: (msg) => { window.Veil.utils.toast('Stream error: ' + msg, 'error'); },
+    });
+  },
+
+  _showCreateModal() {
+    const U = window.Veil.utils;
+    window.Veil.modal.show(`
+      <div>
+        <h3 style="font-size:16px;font-weight:700;color:var(--text);margin-bottom:16px;">Create Task</h3>
+        <div id="ct-err" style="display:none;background:var(--red-dim);color:var(--red);border:1px solid rgba(239,68,68,0.3);border-radius:6px;padding:8px 12px;margin-bottom:12px;font-size:13px;"></div>
+        <div style="margin-bottom:12px;">
+          <label style="display:block;font-size:11.5px;font-weight:600;color:var(--text3);text-transform:uppercase;letter-spacing:0.06em;margin-bottom:6px;">Agent *</label>
+          <select id="ct-agent" class="input" style="cursor:pointer;"></select>
+        </div>
+        <div style="margin-bottom:12px;">
+          <label style="display:block;font-size:11.5px;font-weight:600;color:var(--text3);text-transform:uppercase;letter-spacing:0.06em;margin-bottom:6px;">Input *</label>
+          <textarea id="ct-input" class="input mono" rows="4" placeholder="Task instructions…" style="resize:vertical;"></textarea>
+        </div>
+        <div style="display:grid;grid-template-columns:1fr 1fr 1fr;gap:10px;margin-bottom:20px;">
+          <div>
+            <label style="display:block;font-size:11.5px;font-weight:600;color:var(--text3);text-transform:uppercase;letter-spacing:0.06em;margin-bottom:6px;">Priority</label>
+            <select id="ct-priority" class="input" style="cursor:pointer;">
+              <option value="normal">normal</option>
+              <option value="high">high</option>
+              <option value="low">low</option>
+            </select>
+          </div>
+          <div>
+            <label style="display:block;font-size:11.5px;font-weight:600;color:var(--text3);text-transform:uppercase;letter-spacing:0.06em;margin-bottom:6px;">Max Iterations</label>
+            <input id="ct-maxiter" class="input" type="number" placeholder="default" />
+          </div>
+          <div>
+            <label style="display:block;font-size:11.5px;font-weight:600;color:var(--text3);text-transform:uppercase;letter-spacing:0.06em;margin-bottom:6px;">Token Budget</label>
+            <input id="ct-budget" class="input" type="number" placeholder="optional" />
+          </div>
+        </div>
+        <div style="display:flex;gap:10px;justify-content:flex-end;">
+          <button class="btn btn-secondary" onclick="window.Veil.modal.hide()">Cancel</button>
+          <button class="btn btn-primary" id="ct-submit">Create Task</button>
+        </div>
+      </div>`);
+
+    window.Veil.state.api.listAgents().then(data => {
+      const sel = document.getElementById('ct-agent');
+      if (!sel) return;
+      const agents = (data.agents || []).filter(a => a.modes && a.modes.includes('task'));
+      const preferred = window.Veil.state.currentAgent;
+      sel.innerHTML = agents.map(a =>
+        `<option value="${U.esc(a.name)}" ${a.name === preferred ? 'selected' : ''}>${U.esc(a.name)}</option>`
+      ).join('') || '<option value="">No task-enabled agents</option>';
+    }).catch(() => {});
+
+    document.getElementById('ct-submit').addEventListener('click', async () => {
+      const agent  = document.getElementById('ct-agent')?.value;
+      const input  = document.getElementById('ct-input')?.value.trim();
+      const errEl  = document.getElementById('ct-err');
+      if (!agent || !input) {
+        errEl.textContent = 'Agent and input are required'; errEl.style.display = 'block'; return;
+      }
+      const body = { input, priority: document.getElementById('ct-priority').value };
+      const maxIter = parseInt(document.getElementById('ct-maxiter').value, 10);
+      const budget  = parseInt(document.getElementById('ct-budget').value, 10);
+      if (maxIter > 0)  body.maxIterations  = maxIter;
+      if (budget  > 0)  body.tokenBudget    = budget;
+      const btn = document.getElementById('ct-submit');
+      btn.disabled = true; btn.innerHTML = U.spinner() + ' Creating…';
+      try {
+        const res = await window.Veil.state.api.createTask(agent, body);
+        window.Veil.modal.hide();
+        window.Veil.utils.toast('Task created: ' + res.taskId, 'success');
+        this._selected = res.taskId;
+        await this._loadList();
+      } catch (err) {
+        btn.disabled = false; btn.textContent = 'Create Task';
+        errEl.textContent = err.message; errEl.style.display = 'block';
+      }
+    });
+  },
+};

package/utils/context.js

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * CWD + version singleton.
+ * Set ONCE at startup in cli/index.js. All other modules read from here.
+ * Never call process.cwd() outside cli/index.js.
+ */
+
+let _cwd = null;
+let _version = null;
+
+module.exports = {
+  /**
+   * @param {string} cwd - Absolute path to the project working directory
+   */
+  setCwd(cwd) {
+    _cwd = cwd;
+  },
+
+  /**
+   * @returns {string} Absolute path to the project working directory
+   */
+  getCwd() {
+    if (!_cwd) throw new Error('Context not initialized — call setCwd() at startup before using getCwd()');
+    return _cwd;
+  },
+
+  /**
+   * @param {string} version - Package version string
+   */
+  setVersion(version) {
+    _version = version;
+  },
+
+  /**
+   * @returns {string} Package version string
+   */
+  getVersion() {
+    return _version || '0.0.0';
+  },
+
+  /**
+   * Reset for testing purposes only
+   */
+  _reset() {
+    _cwd = null;
+    _version = null;
+  }
+};

package/utils/id.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Generate a unique ID with an optional prefix.
+ * Uses crypto.randomBytes — no external dependency.
+ *
+ * @param {string} [prefix=''] - Prefix for the ID (e.g. 'sess_', 'task_')
+ * @returns {string} Unique ID string
+ */
+function generateId(prefix = '') {
+  return `${prefix}${crypto.randomBytes(8).toString('hex')}`;
+}
+
+module.exports = { generateId };

package/utils/models.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const MODELS_PATH = path.join(__dirname, '..', 'config', 'models.json');
+
+let _cache = null;
+
+/**
+ * Load and cache the models index from config/models.json.
+ * @returns {{ updated_at: string, models: Object }}
+ */
+function loadModels() {
+  if (_cache) return _cache;
+  try {
+    _cache = JSON.parse(fs.readFileSync(MODELS_PATH, 'utf8'));
+  } catch {
+    _cache = { updated_at: null, models: {} };
+  }
+  return _cache;
+}
+
+/**
+ * Invalidate the in-memory cache (e.g. after re-fetching models).
+ */
+function invalidateCache() {
+  _cache = null;
+}
+
+/**
+ * Get the full data entry for a model by its ID.
+ * Returns null if not found.
+ *
+ * @param {string} modelId - e.g. "anthropic/claude-sonnet-4.6"
+ * @returns {Object|null}
+ */
+function getModel(modelId) {
+  if (!modelId) return null;
+  const { models } = loadModels();
+  return models[modelId] || null;
+}
+
+/**
+ * Get the context window size (in tokens) for a model.
+ * Returns null if the model is unknown.
+ *
+ * @param {string} modelId
+ * @returns {number|null}
+ */
+function getContextLimit(modelId) {
+  const m = getModel(modelId);
+  return m ? (m.context_length || null) : null;
+}
+
+/**
+ * Calculate the estimated cost in USD for a set of token counts.
+ * Falls back to 0 if the model is unknown or pricing is missing.
+ *
+ * @param {string} modelId
+ * @param {{ input: number, output: number, cache: number }} tokens
+ * @returns {number} cost in USD
+ */
+function calculateCost(modelId, { input = 0, output = 0, cache = 0 } = {}) {
+  const m = getModel(modelId);
+  if (!m) return 0;
+
+  const { prompt = 0, completion = 0, cache_read = 0 } = m.pricing || {};
+
+  // cache tokens are a subset of input tokens that were read from cache
+  // billed at cache_read rate instead of prompt rate
+  const billableInput = Math.max(0, input - cache);
+  return (billableInput * prompt) + (cache * cache_read) + (output * completion);
+}
+
+/**
+ * Return the full flat list of models (array form) for API responses.
+ * @returns {Object[]}
+ */
+function listModels() {
+  const { updated_at, models } = loadModels();
+  return {
+    updated_at,
+    models: Object.entries(models).map(([id, data]) => ({ id, ...data })),
+  };
+}
+
+module.exports = { loadModels, getModel, getContextLimit, calculateCost, listModels, invalidateCache };