tinywebui 0.1.0

package/src/tools/context_tool.js

@@ -0,0 +1,183 @@
+/**
+ * expand_context -- the restore half of compaction.
+ *
+ * Dropping content from the window is only safe if something in what remains
+ * can bring it back. Every compacted tool result keeps its artifact id, and
+ * this tool reads the stored text by that id.
+ *
+ * It is deliberately built on grep-and-window semantics rather than on semantic
+ * search: the artifact is an opaque blob from an arbitrary MCP server, so there
+ * is no schema to rank against and no safe assumption about what "relevant"
+ * means. Line matching and byte offsets work on anything, are deterministic,
+ * and cost nothing to run. Expansions are appended like any other tool result,
+ * so they never disturb the cached prefix.
+ */
+
+export const EXPAND_CONTEXT = 'expand_context';
+
+/**
+ * Where the substantial prose actually sits.
+ *
+ * A scraped page is mostly navigation, bylines and short boilerplate; the
+ * article itself is the handful of long lines among them. A stub that keeps
+ * only the ends leaves the model guessing at `offset=` values, which is the
+ * expensive failure -- each blind guess costs a whole round and comes back with
+ * sidebar links. Listing where the long lines start turns that into one aimed
+ * read.
+ *
+ * Character offsets, not line numbers, because that is what expand_context's
+ * `offset` takes. Generic and deterministic: it measures line lengths and
+ * nothing else, and never looks at what a tool is.
+ */
+export const MAP_MIN_LINE = 200;
+export const MAP_MAX_ENTRIES = 12;
+
+export function textMap(text) {
+  const rows = [];
+  let pos = 0;
+  for (const line of String(text ?? '').split('\n')) {
+    const len = line.trim().length;
+    if (len >= MAP_MIN_LINE) rows.push({ pos, len });
+    pos += line.length + 1;
+  }
+  if (!rows.length) return '';
+
+  // Longest first so the densest prose survives the cut, then back into reading
+  // order -- the model pages forward, so the list has to read forward too.
+  const top = rows.slice().sort((a, b) => b.len - a.len || a.pos - b.pos).slice(0, MAP_MAX_ENTRIES);
+  top.sort((a, b) => a.pos - b.pos);
+  const omitted = rows.length - top.length;
+
+  return `Long text at offset= ${top.map((r) => `${r.pos} (${r.len} chars)`).join(', ')}`
+    + (omitted > 0 ? `, +${omitted} more` : '');
+}
+
+export function expandToolDef() {
+  return {
+    type: 'function',
+    function: {
+      name: EXPAND_CONTEXT,
+      description: [
+        'Read the full text of an earlier tool result that was compacted out of the',
+        'conversation. Compacted results appear as "[compacted: artifact <id> ...]" and',
+        'show only their first and last few hundred characters.',
+        '',
+        'Use grep to find the part you need (case-insensitive regular expression, matched',
+        'per line), or offset/limit to page through the text. With neither, returns the',
+        'beginning. Output is capped, so prefer a specific grep over paging.'
+      ].join('\n'),
+      parameters: {
+        type: 'object',
+        properties: {
+          artifact_id: {
+            type: 'string',
+            description: 'The id shown in the compacted marker, e.g. "a1b2c3d4".'
+          },
+          grep: {
+            type: 'string',
+            description:
+              'Case-insensitive regular expression. Returns matching lines with surrounding context.'
+          },
+          context_lines: {
+            type: 'integer',
+            description: 'Lines of context to show around each grep match. Default 2.'
+          },
+          offset: {
+            type: 'integer',
+            description: 'Character offset to start reading from. Ignored when grep is given.'
+          },
+          limit: {
+            type: 'integer',
+            description: 'Maximum characters to return. Capped by the server budget.'
+          }
+        },
+        required: ['artifact_id']
+      }
+    }
+  };
+}
+
+function header(artifact, note) {
+  return `[artifact ${artifact.id} · ${artifact.tool_name} · ${artifact.char_len.toLocaleString('en-US')} chars · ${note}]`;
+}
+
+function grepView(text, pattern, contextLines, budget, artifact) {
+  let re;
+  try {
+    re = new RegExp(pattern, 'i');
+  } catch (err) {
+    return `Error: invalid regular expression ${JSON.stringify(pattern)}: ${err.message}`;
+  }
+
+  const lines = text.split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) if (re.test(lines[i])) hits.push(i);
+  if (!hits.length) {
+    // A bare "no match" costs a full round and returns nothing to act on, so the
+    // miss carries the same offset map the stub does: the next call can aim at
+    // real text instead of guessing another pattern.
+    const map = textMap(text);
+    return [
+      header(artifact, `no match for /${pattern}/i`),
+      map || 'No long text blocks -- this artifact is short lines throughout.',
+      'Try a broader pattern, or read a window with offset/limit.'
+    ].join('\n');
+  }
+
+  // Merge overlapping context windows so a dense run of matches prints once.
+  const ranges = [];
+  for (const i of hits) {
+    const from = Math.max(0, i - contextLines);
+    const to = Math.min(lines.length - 1, i + contextLines);
+    const last = ranges[ranges.length - 1];
+    if (last && from <= last.to + 1) last.to = Math.max(last.to, to);
+    else ranges.push({ from, to });
+  }
+
+  const out = [header(artifact, `${hits.length} line(s) match /${pattern}/i`)];
+  let used = out[0].length;
+  let shown = 0;
+  for (const r of ranges) {
+    const block = lines
+      .slice(r.from, r.to + 1)
+      .map((l, k) => `${String(r.from + k + 1).padStart(6)}│${l}`)
+      .join('\n');
+    if (used + block.length > budget) {
+      out.push(`… ${ranges.length - shown} more match group(s) omitted; narrow the pattern.`);
+      break;
+    }
+    out.push(block);
+    used += block.length + 2;
+    shown++;
+  }
+  return out.join('\n\n');
+}
+
+function windowView(text, offset, limit, budget, artifact) {
+  const start = Math.max(0, Math.min(offset, text.length));
+  const size = Math.min(limit > 0 ? limit : budget, budget);
+  const slice = text.slice(start, start + size);
+  const end = start + slice.length;
+  const note = `chars ${start.toLocaleString('en-US')}–${end.toLocaleString('en-US')}`;
+  const more = end < text.length
+    ? `\n[… ${(text.length - end).toLocaleString('en-US')} chars remain; continue with offset=${end}.]`
+    : '';
+  return `${header(artifact, note)}\n${slice}${more}`;
+}
+
+/** Runs one expansion. Returns a string, like every other tool result. */
+export function callExpand(args, { store, chatId, budget = 8000 }) {
+  const id = String(args?.artifact_id || '').trim();
+  if (!id) return 'Error: artifact_id is required.';
+
+  // Scoped to the conversation that produced it at the query level: artifact ids
+  // are short, and one chat must not be able to read another's tool output by guessing.
+  const artifact = store.messages.getArtifact(id, chatId);
+  if (!artifact) return `Error: no artifact "${id}". Ids appear in the "[compacted: artifact <id> ...]" marker.`;
+
+  if (args.grep) {
+    const ctx = Number.isInteger(args.context_lines) ? Math.max(0, Math.min(args.context_lines, 20)) : 2;
+    return grepView(artifact.content, String(args.grep), ctx, budget, artifact);
+  }
+  return windowView(artifact.content, Number(args.offset) || 0, Number(args.limit) || 0, budget, artifact);
+}

package/src/tools/document_tool.js

@@ -0,0 +1,102 @@
+import { ALL_USERS, CORPUS } from '../store/index.js';
+
+/**
+ * read_document -- lets the model read text the user attached to the chat.
+ *
+ * Same shape as expand_context: a document is an opaque blob (extracted text
+ * of whatever the user dropped in), scoped to the chat that owns it, read
+ * either by a narrowing query or by paging through raw offsets. `query`
+ * ranks the document's pre-split passages: FTS5 bm25() by default, or
+ * small-to-big dense / hybrid retrieval when retrieval.mode asks for it
+ * (retrieval.js). The tool's interface is the same in every mode.
+ */
+
+export const READ_DOCUMENT = 'read_document';
+
+export function documentToolDef() {
+  return {
+    type: 'function',
+    function: {
+      name: READ_DOCUMENT,
+      description: [
+        'Read an attached document. Documents appear as',
+        '"[Attached document: ... (id: <id>, ...)]" notes in the conversation.',
+        '',
+        'Give a query to search the document for relevant passages (best for',
+        'long documents and specific questions), or use offset/limit to page through the',
+        'raw text from the start. With neither, returns the beginning of the document.'
+      ].join('\n'),
+      parameters: {
+        type: 'object',
+        properties: {
+          document_id: {
+            type: 'string',
+            description: 'The id shown in the "[Attached document: ...]" note, e.g. "a1b2c3d4".'
+          },
+          query: {
+            type: 'string',
+            description: 'Free-text query. Returns the best-matching passages, ranked by relevance.'
+          },
+          offset: {
+            type: 'integer',
+            description: 'Character offset to start reading from. Ignored when query is given.'
+          },
+          limit: {
+            type: 'integer',
+            description: 'Maximum characters to return. Capped by the server budget.'
+          }
+        },
+        required: ['document_id']
+      }
+    }
+  };
+}
+
+function header(doc, note) {
+  return `[document ${doc.id} · ${doc.filename} · ${doc.char_len.toLocaleString('en-US')} chars · ${note}]`;
+}
+
+async function queryView(store, retrieval, doc, query, budget) {
+  const hits = retrieval ? await retrieval.search(CORPUS.DOCUMENTS, { docId: doc.id }, query, 5) : store.documents.searchPassages(doc.id, query, 5);
+  if (!hits.length) {
+    return `${header(doc, `no match for "${query}"`)}\nTry a broader query, or read from the start with offset/limit.`;
+  }
+  const out = [header(doc, `${hits.length} passage(s) matching "${query}"`)];
+  let used = out[0].length;
+  for (const hit of hits) {
+    const block = `--- passage ${hit.passageIdx} (offset ${hit.charStart.toLocaleString('en-US')}) ---\n${hit.body}`;
+    if (used + block.length > budget) {
+      out.push('… remaining matches omitted; narrow the query.');
+      break;
+    }
+    out.push(block);
+    used += block.length + 2;
+  }
+  return out.join('\n\n');
+}
+
+function windowView(doc, offset, limit, budget) {
+  const text = doc.content;
+  const start = Math.max(0, Math.min(offset, text.length));
+  const size = Math.min(limit > 0 ? limit : budget, budget);
+  const slice = text.slice(start, start + size);
+  const end = start + slice.length;
+  const note = `chars ${start.toLocaleString('en-US')}–${end.toLocaleString('en-US')}`;
+  const more = end < text.length
+    ? `\n[… ${(text.length - end).toLocaleString('en-US')} chars remain; continue with offset=${end}.]`
+    : '';
+  return `${header(doc, note)}\n${slice}${more}`;
+}
+
+/** Runs one read. Returns a string, like every other tool result. */
+export async function callReadDocument(args, { store, retrieval = null, chatId, budget = 8000 }) {
+  const id = String(args?.document_id || '').trim();
+  if (!id) return 'Error: document_id is required.';
+
+  const doc = store.documents.get(id, ALL_USERS);
+  if (!doc) return `Error: no document "${id}". Ids appear in the "[Attached document: ...]" note.`;
+  if (doc.chat_id !== chatId) return `Error: document "${id}" does not belong to this conversation.`;
+
+  if (args.query) return queryView(store, retrieval, doc, String(args.query), budget);
+  return windowView(doc, Number(args.offset) || 0, Number(args.limit) || 0, budget);
+}

package/src/tools/task_tool.js

@@ -0,0 +1,63 @@
+/** A small, chat-scoped checklist that the model can maintain during a task. */
+export const MANAGE_TASKS = 'manage_tasks';
+
+export function taskToolDef() {
+  return {
+    type: 'function',
+    function: {
+      name: MANAGE_TASKS,
+      description: 'Keep a visible checklist for this chat. Create tasks when a request has multiple steps. Mark a task in_progress when you start it and completed as soon as it is done; before your final answer, make sure no finished task is still open. Update several tasks at once with ids. This is a checklist, not a scheduled automation.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['add', 'update', 'list'] },
+          title: { type: 'string', description: 'Short task title for add.' },
+          id: { type: 'string', description: 'Task ID returned by add or list, for update.' },
+          ids: { type: 'array', items: { type: 'string' }, description: 'Several task IDs to set to the same status, for update.' },
+          status: { type: 'string', enum: ['pending', 'in_progress', 'completed'], description: 'New status for update.' }
+        },
+        required: ['action']
+      }
+    }
+  };
+}
+
+export function callManageTasks(args, { store, chatId, onChange } = {}) {
+  if (!store || !chatId) return 'Error: this tool requires a chat.';
+  const { action } = args || {};
+  if (action === 'list') return JSON.stringify({ tasks: store.chats.listTasks(chatId) });
+  if (action === 'add') {
+    const title = typeof args.title === 'string' ? args.title.trim() : '';
+    if (!title || title.length > 200) return 'Error: title must be 1–200 characters.';
+    if (store.chats.listTasks(chatId).length >= 50) return 'Error: this chat has reached the 50-task limit.';
+    const task = store.chats.addTask(chatId, title);
+    onChange?.(store.chats.listTasks(chatId));
+    return JSON.stringify({ task });
+  }
+  if (action === 'update') {
+    const ids = Array.isArray(args.ids) ? args.ids : [args.id];
+    if (!ids.length || ids.some((id) => typeof id !== 'string' || !id)
+      || !['pending', 'in_progress', 'completed'].includes(args.status)) {
+      return 'Error: update requires a valid task id (or ids) and status.';
+    }
+    const tasks = ids.map((id) => store.chats.updateTask(chatId, id, args.status));
+    const missing = ids.filter((_, i) => !tasks[i]);
+    if (missing.length === ids.length) return 'Error: task not found in this chat.';
+    onChange?.(store.chats.listTasks(chatId));
+    if (!Array.isArray(args.ids)) return JSON.stringify({ task: tasks[0] });
+    return JSON.stringify({ tasks: tasks.filter(Boolean), ...(missing.length ? { not_found: missing } : {}) });
+  }
+  return 'Error: action must be add, update, or list.';
+}
+
+/**
+ * The open checklist, for the budget footer. The model otherwise sees tasks
+ * only in the tool results that created them, which scroll out of attention
+ * within a turn and are gone from view entirely on the next one.
+ */
+export function openTasksNote(tasks) {
+  const open = (tasks || []).filter((t) => t.status !== 'completed');
+  if (!open.length) return '';
+  const lines = open.map((t) => `- ${t.id} [${t.status}] ${t.title}`);
+  return `\n[Open tasks -- update them with ${MANAGE_TASKS} as you finish each one:\n${lines.join('\n')}]`;
+}