tinywebui 0.1.0

package/src/automations/automation.js

@@ -0,0 +1,136 @@
+import { CronExpressionParser } from 'cron-parser';
+
+export function validateSchedule(cron, timezone, now = Date.now()) {
+  const tz = String(timezone || '').trim();
+  if (!tz) throw new Error('timezone is required');
+  try { new Intl.DateTimeFormat('en-US', { timeZone: tz }); }
+  catch { throw new Error(`invalid IANA timezone: ${tz}`); }
+  let nextRunAt;
+  try {
+    nextRunAt = CronExpressionParser.parse(String(cron || ''), {
+      currentDate: new Date(now), tz
+    }).next().getTime();
+  } catch (err) {
+    throw new Error(`invalid cron schedule: ${err.message}`);
+  }
+  return { cron: String(cron).trim(), timezone: tz, nextRunAt };
+}
+
+function cleanFields(input, { requireAll = false } = {}) {
+  const fields = {};
+  for (const key of ['name', 'prompt']) {
+    if (input[key] === undefined && !requireAll) continue;
+    const val = String(input[key] ?? '').trim();
+    if (!val) throw new Error(`${key} is required`);
+    if (val.length > (key === 'prompt' ? 12000 : 120)) throw new Error(`${key} is too long`);
+    fields[key] = val;
+  }
+  if (requireAll || (input.cron !== undefined && input.timezone !== undefined)) {
+    const cron = input.cron ?? '';
+    const timezone = input.timezone ?? '';
+    Object.assign(fields, validateSchedule(cron, timezone));
+  }
+  if (input.enabled !== undefined) fields.enabled = Boolean(input.enabled);
+  return fields;
+}
+
+export function automationToolDef() {
+  return {
+    type: 'function',
+    function: {
+      name: 'manage_automation',
+      description: [
+        'Manage scheduled automations: a prompt that runs on its own, on a cron schedule, in this chat.',
+        'Use it when the user wants something done repeatedly or later without them ("every morning',
+        'summarise...", "check X each Friday"). For steps of the current request use manage_tasks instead.',
+        '',
+        'Each run starts fresh: it sees only its own prompt and the previous run\'s result, not this',
+        'conversation, and nobody is there to answer questions. Write `prompt` so it stands alone:',
+        'what to do, where, and what to report.',
+        '',
+        'Actions and what each needs:',
+        '- list: nothing. Returns every automation with its id, schedule and last result.',
+        '- create: name, prompt, cron, timezone. Starts running on schedule immediately.',
+        '- update: id, plus only the fields to change. cron and timezone are checked together.',
+        '- delete: id. Permanent.',
+        '- trigger: id. Runs it once now; queued if the chat is busy.',
+        '',
+        'An automation keeps running until someone stops it, so before create or delete, make sure',
+        'the user asked for exactly that (schedule, timezone, what it does). If any of those is unclear,',
+        'ask first. Pausing is update with enabled=false.'
+      ].join('\n'),
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['list', 'create', 'update', 'delete', 'trigger'] },
+          id: { type: 'string', description: 'The automation\'s id, from list or create. For update, delete and trigger.' },
+          name: { type: 'string', description: 'Short label shown to the user, e.g. "Morning inbox summary". Up to 120 characters.' },
+          prompt: { type: 'string', description: 'The instruction each run carries out, written to stand alone (see above). Up to 12000 characters.' },
+          cron: { type: 'string', description: 'Five fields: minute hour day-of-month month day-of-week. "0 9 * * 1-5" is 09:00 on weekdays; "*/30 * * * *" is every 30 minutes.' },
+          timezone: { type: 'string', description: 'IANA timezone the cron is read in, e.g. "Europe/Vienna". Required with cron; use the user\'s timezone, and ask if you do not know it.' },
+          enabled: { type: 'boolean', description: 'false pauses the automation without deleting it; true resumes it. New automations are enabled.' }
+        },
+        required: ['action']
+      }
+    }
+  };
+}
+
+export async function manageAutomation(args, { store, chatId, triggerAutomation, unattended = false } = {}) {
+  const action = String(args?.action || '');
+  // A scheduled run has nobody watching it. Letting it start more runs is how
+  // one trigger becomes an endless self-requeueing loop, and how text injected
+  // through a tool result turns into a standing schedule. Adjusting or removing
+  // an existing automation stays allowed -- "stop once X is done" is legitimate.
+  if (unattended && (action === 'create' || action === 'trigger')) {
+    return `Error: "${action}" is not available inside a scheduled run. Tell the user in your result if a new automation or run is needed.`;
+  }
+  const chat = chatId ? store.chats.byId(chatId) : null;
+  const userId = chat?.user_id ?? null;
+  if (action === 'list') return JSON.stringify(store.automations.list(userId));
+  if (action === 'create') {
+    if (!chat) throw new Error('automation creation requires a current chat');
+    const fields = cleanFields(args, { requireAll: true });
+    const row = store.automations.create({ ...fields, chatId, source: 'model' }, userId);
+    return JSON.stringify(row);
+  }
+  if (!args?.id) throw new Error('id is required');
+  if (action === 'delete') return store.automations.delete(args.id, userId)
+    ? `Deleted automation ${args.id}.` : 'Error: no such automation';
+  if (action === 'trigger') {
+    const automation = store.automations.get(args.id, userId);
+    if (!automation) throw new Error('no such automation');
+    if (!triggerAutomation) throw new Error('manual triggering is unavailable');
+    return JSON.stringify(await triggerAutomation(automation, userId));
+  }
+  if (action === 'update') {
+    const current = store.automations.get(args.id, userId);
+    if (!current) throw new Error('no such automation');
+    const fields = cleanFields(args);
+    if (args.cron !== undefined || args.timezone !== undefined) {
+      Object.assign(fields, validateSchedule(fields.cron ?? current.cron, fields.timezone ?? current.timezone));
+    }
+    const row = store.automations.update(args.id, fields, userId);
+    return row ? JSON.stringify(row) : 'Error: no such automation';
+  }
+  throw new Error('action must be list, create, update, delete, or trigger');
+}
+
+export function nextSchedule(cron, timezone, now = Date.now()) {
+  return validateSchedule(cron, timezone, now).nextRunAt;
+}
+
+export function runMessage(automation) {
+  const previous = automation.lastResult
+    ? `\n\nPrevious run result (truncated):\n${automation.lastResult.slice(0, 2000)}` : '';
+  return [
+    `[Scheduled automation: ${automation.name}]`,
+    `Schedule: ${automation.cron} (${automation.timezone})`,
+    // Without this the model reads an ordinary user turn and may stop to ask a
+    // clarifying question that nobody will ever answer.
+    'This is an unattended run: no one is present to answer questions. Complete the task'
+      + ' with sensible assumptions and state them, or report exactly what blocked it.',
+    '',
+    automation.prompt
+  ].join('\n') + previous;
+}

package/src/automations/scheduler.js

@@ -0,0 +1,147 @@
+import { nextSchedule, runMessage } from './automation.js';
+import { ORIGIN } from '../../public/shared/origins.js';
+
+/**
+ * Runs automations: on their cron schedule, or on demand. A run needs its
+ * chat idle; a manual trigger for a busy chat waits in a per-chat queue and
+ * starts once the chat's current run ends (`drain`, which the run manager
+ * calls). Scheduled occurrences that find the chat busy are skipped, not
+ * queued, and occurrences missed while the process was down are not replayed.
+ *
+ * `app` supplies the store, runs, and modelFor/toolsFor/ownerFeatures.
+ */
+export function createScheduler(app) {
+  const { store, runs } = app;
+  const pendingManual = new Map();
+  let timer = null;
+  let stopped = false;
+
+  function launch(automation, runId, trigger = 'schedule') {
+    // Nobody is at the keyboard to be turned away, so a disabled or pending
+    // owner is checked here: their schedules stop the moment their access does.
+    if (automation.userId && (store.users.get(automation.userId)?.status !== 'approved' || !app.ownerFeatures(automation.userId).has('automations'))) {
+      store.automations.updateRun(runId, { status: 'skipped', finishedAt: Date.now(), error: 'Owner account is not active.' });
+      return true;
+    }
+    const chat = store.chats.get(automation.chatId, automation.userId);
+    if (!chat) {
+      store.automations.updateRun(runId, { status: 'failed', finishedAt: Date.now(), error: 'Target chat no longer exists.' });
+      return false;
+    }
+    if (runs.isRunning(chat.id)) return false;
+    // A snapshot, not a reference: the card still reads right after the
+    // automation is renamed or deleted.
+    const origin = {
+      type: ORIGIN.AUTOMATION, automationId: automation.id, runId, trigger,
+      name: automation.name, cron: automation.cron, timezone: automation.timezone, prompt: automation.prompt
+    };
+    const firstSeq = store.messages.add(chat.id, { role: 'user', content: runMessage(automation), origin });
+    store.automations.updateRun(runId, { status: 'running', startedAt: Date.now() });
+    const role = automation.userId ? store.users.get(automation.userId)?.role : null;
+    runs.start({
+      chat,
+      model: app.modelFor(automation.userId, role),
+      tools: app.toolsFor(app.ownerFeatures(automation.userId)),
+      historyFromSeq: firstSeq,
+      unattended: true,
+      onFinish: ({ ok, error, result }) => {
+        store.automations.updateRun(runId, {
+          status: ok ? 'completed' : 'failed', finishedAt: Date.now(),
+          result: String(result || '').slice(0, 200000), error: error ? String(error).slice(0, 1000) : null
+        });
+        arm();
+      }
+    });
+    return true;
+  }
+
+  async function trigger(automation, userId) {
+    const owned = store.automations.get(automation.id, userId);
+    if (!owned) throw new Error('no such automation');
+    const runId = store.automations.addRun(owned.id, Date.now(), 'queued', 'manual');
+    if (runs.isRunning(owned.chatId)) {
+      const queue = pendingManual.get(owned.chatId) || [];
+      queue.push({ automationId: owned.id, userId, runId });
+      pendingManual.set(owned.chatId, queue);
+      return { runId, status: 'queued', chatId: owned.chatId };
+    }
+    launch(owned, runId, 'manual');
+    return { runId, status: 'running', chatId: owned.chatId };
+  }
+
+  function drain(chatId) {
+    if (runs.isRunning(chatId)) return;
+    const queue = pendingManual.get(chatId);
+    if (!queue?.length) return;
+    const next = queue.shift();
+    if (!queue.length) pendingManual.delete(chatId);
+    const automation = store.automations.get(next.automationId, next.userId);
+    if (!automation) {
+      store.automations.updateRun(next.runId, { status: 'failed', finishedAt: Date.now(), error: 'Automation no longer exists.' });
+      queueMicrotask(() => drain(chatId));
+      return;
+    }
+    if (!launch(automation, next.runId, 'manual')) {
+      const remaining = pendingManual.get(chatId) || [];
+      remaining.unshift(next);
+      pendingManual.set(chatId, remaining);
+      return;
+    }
+    if (queue.length) pendingManual.set(chatId, queue);
+  }
+
+  function refresh() {
+    const now = Date.now();
+    for (const automation of store.automations.listAll()) {
+      if (!automation.enabled) continue;
+      // Recompute stale timestamps on startup or after changes without replaying
+      // occurrences missed while the process was down.
+      if (!automation.nextRunAt || automation.nextRunAt <= now) {
+        try { store.automations.update(automation.id, { nextRunAt: nextSchedule(automation.cron, automation.timezone, now) }, automation.userId); }
+        catch (err) { store.automations.update(automation.id, { enabled: false, lastStatus: `invalid schedule: ${err.message}` }, automation.userId); }
+      }
+    }
+  }
+
+  function processDue() {
+    if (stopped) return;
+    const now = Date.now();
+    for (const automation of store.automations.due(now)) {
+      const scheduledAt = automation.nextRunAt;
+      const runId = store.automations.addRun(automation.id, scheduledAt, 'queued');
+      let nextRunAt;
+      try { nextRunAt = nextSchedule(automation.cron, automation.timezone, scheduledAt); }
+      catch (err) {
+        store.automations.update(automation.id, { enabled: false, lastStatus: `invalid schedule: ${err.message}`, nextRunAt: null }, automation.userId);
+        store.automations.updateRun(runId, { status: 'failed', finishedAt: now, error: err.message });
+        continue;
+      }
+      store.automations.update(automation.id, { nextRunAt }, automation.userId);
+      if (runs.isRunning(automation.chatId)) {
+        store.automations.updateRun(runId, { status: 'skipped', finishedAt: now, error: 'Target chat was already running.' });
+        continue;
+      }
+      launch(automation, runId);
+    }
+    arm();
+  }
+
+  /** (Re)sets the timer for the next due automation. Call after any change. */
+  function arm() {
+    if (stopped) return;
+    if (timer) clearTimeout(timer);
+    refresh();
+    const next = store.automations.nextDue();
+    if (next == null) { timer = null; return; }
+    timer = setTimeout(processDue, Math.max(25, Math.min(2_147_000_000, next - Date.now())));
+    timer.unref?.();
+  }
+
+  function stop() {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+  }
+
+  store.automations.recoverRuns();
+  return { arm, trigger, drain, stop };
+}

package/src/chat/compact.js

@@ -0,0 +1,242 @@
+import { textMap, EXPAND_CONTEXT } from '../tools/context_tool.js';
+
+/**
+ * Context compaction.
+ *
+ * The append-only rule is what makes prompt caching work: every provider caches
+ * on an exact prefix match, so rewriting an earlier message throws away the
+ * cache from that point on. But nothing ever leaving is how a four-message
+ * research chat reaches 150k tokens, because every tool result is replayed in
+ * full on every subsequent turn.
+ *
+ * The resolution is to rewrite rarely and then stop. When the prompt crosses a
+ * threshold we demote old tool results to stubs exactly once, write the stubs
+ * back to the store, and from then on that prefix is frozen and byte-identical
+ * again. One cache miss buys many cheap turns. The alternative -- ageing
+ * messages out every turn -- changes the prefix on every request and never
+ * caches anything.
+ *
+ * Two invariants everything here depends on:
+ *
+ *  1. Deterministic. A stub is a pure function of the artifact. No model call,
+ *     no timestamp, no counter. It is also stored rather than recomputed, so a
+ *     later change to this file cannot disturb a frozen prefix.
+ *  2. Tool-agnostic. Tool output is an opaque blob from an arbitrary MCP
+ *     server. Nothing below may look at a tool's name or know its schema; the
+ *     only structure we infer is generic (JSON, XML-ish, or neither).
+ */
+
+export const DIGEST_HEAD = 400;
+export const DIGEST_TAIL = 200;
+
+/**
+ * A one-line shape hint, derived only from generic structure. Gives the model
+ * enough to judge whether re-reading is worth an expand_context call, without
+ * the stub pretending to summarise content it has not understood.
+ */
+function outline(text) {
+  const trimmed = text.trim();
+
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) return `json array, ${parsed.length} item(s)`;
+      if (parsed && typeof parsed === 'object') {
+        const keys = Object.keys(parsed);
+        const shown = keys.slice(0, 12).join(', ');
+        return `json object, keys: ${shown}${keys.length > 12 ? `, +${keys.length - 12} more` : ''}`;
+      }
+    } catch { /* not JSON after all; fall through */ }
+  }
+
+  // XML-ish covers a lot of MCP output without committing to a parser.
+  const tags = trimmed.match(/<([a-zA-Z][\w:.-]*)(?=[\s/>])/g);
+  if (tags && tags.length >= 2) {
+    const counts = new Map();
+    for (const t of tags) {
+      const name = t.slice(1);
+      counts.set(name, (counts.get(name) || 0) + 1);
+    }
+    // Sorted by count, then name, so the line is stable for identical input.
+    const top = [...counts.entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .slice(0, 8)
+      .map(([name, n]) => `${name}×${n}`);
+    return `tags: ${top.join(', ')}`;
+  }
+
+  const lines = trimmed ? trimmed.split('\n').length : 0;
+  return `plain text, ${lines} line(s)`;
+}
+
+/**
+ * Builds the stub that replaces a tool result on the wire. Head and tail are
+ * kept verbatim because the ends of a tool result are where the useful framing
+ * usually is, and because a verbatim excerpt cannot hallucinate.
+ */
+export function digest(artifact, { head = DIGEST_HEAD, tail = DIGEST_TAIL } = {}) {
+  const text = artifact.content ?? '';
+  const len = text.length;
+  const id = artifact.id;
+  const name = artifact.tool_name || 'tool';
+
+  if (len <= head + tail) {
+    // Nothing to gain; keep it whole rather than emit a stub bigger than its source.
+    return text;
+  }
+
+  const elided = len - head - tail;
+  // Only for prose: a JSON or XML outline already names its own structure, and
+  // the model greps those by key or tag rather than paging through them.
+  const shape = outline(text);
+  const map = shape.startsWith('plain text') ? textMap(text) : '';
+  return [
+    `[compacted: artifact ${id} · ${name} · ${len.toLocaleString('en-US')} chars · ${shape}]`,
+    ...(map ? [map] : []),
+    text.slice(0, head),
+    `\n… ${elided.toLocaleString('en-US')} chars elided …\n`,
+    text.slice(len - tail),
+    `[Full output retained. Read it with ${EXPAND_CONTEXT}("${id}", grep=... or offset/limit).]`
+  ].join('\n');
+}
+
+/** What one image is counted as, in characters of text (about 1.5k tokens). */
+export const IMAGE_CHARS = 6000;
+
+/** Rough size of a tool block, so a large MCP toolset isn't mistaken for history. */
+export function estimateToolTokens(tools = []) {
+  return tools.length ? Math.ceil(JSON.stringify(tools).length / 4) : 0;
+}
+
+/** Rough size of the wire payload, for when a provider reports no usage at all. */
+export function estimateTokens(wireMessages) {
+  let chars = 0;
+  for (const m of wireMessages) {
+    if (typeof m.content === 'string') chars += m.content.length;
+    else if (Array.isArray(m.content)) {
+      for (const p of m.content) {
+        if (p.type === 'text') chars += p.text.length;
+        // Base64 length says nothing about what an image costs; providers bill
+        // a tile-based figure in the low thousands of tokens.
+        else if (p.type === 'image_url') chars += IMAGE_CHARS;
+      }
+    }
+    if (m.tool_calls) chars += JSON.stringify(m.tool_calls).length;
+  }
+  return Math.ceil(chars / 4);
+}
+
+/**
+ * Decides whether this turn should open a new epoch, and what to demote.
+ *
+ * Returns null when nothing should change -- which is the common case, and the
+ * case that keeps the prefix cached. Called once at the start of a turn, never
+ * mid-turn, so within a turn the prefix only ever grows.
+ */
+export function planEpoch(rows, { threshold, keepTurns, promptTokens }) {
+  if (!(promptTokens > threshold)) return null;
+
+  // Everything from the Nth-from-last user message onward stays verbatim: the
+  // model is most likely to still be working from the recent turns.
+  const userSeqs = rows.filter((r) => r.role === 'user').map((r) => r.seq);
+  if (userSeqs.length <= keepTurns) return null;
+  const boundarySeq = userSeqs[userSeqs.length - keepTurns];
+
+  // Old images go the same way as old tool output: they are resent in full on
+  // every turn, and unlike text nothing ever shrinks them otherwise.
+  const targets = rows.filter((r) => r.seq < boundarySeq && (
+    (r.role === 'tool' && r.artifact_id && !r.stub_text)
+    || (r.images_json && !r.images_dropped)
+  ));
+  // No candidates means bumping the epoch would cost a cache miss for nothing.
+  if (!targets.length) return null;
+
+  return { boundarySeq, targets };
+}
+
+/**
+ * Applies the plan: writes each stub back to the store and records the new
+ * boundary. After this returns, the prefix up to `boundarySeq` is frozen --
+ * stubs are persisted, so every later rebuild produces identical bytes.
+ */
+export function applyEpoch(store, chat, plan, { minSaved = 0 } = {}) {
+  // Stubs are worked out before anything is written: an epoch costs a full
+  // cache miss, so one that would only shave a few hundred characters is not
+  // worth opening, and the check has to happen before the store is touched.
+  const stubs = [];
+  let saved = 0;
+  const drops = [];
+  for (const row of plan.targets) {
+    if (row.role !== 'tool') {
+      drops.push(row.id);
+      saved += JSON.parse(row.images_json).length * IMAGE_CHARS;
+      continue;
+    }
+    const artifact = store.messages.getArtifact(row.artifact_id, chat.id);
+    if (!artifact) continue;
+    const stub = digest(artifact);
+    if (stub.length >= (row.content?.length ?? 0)) continue;
+    stubs.push([row.id, stub]);
+    saved += (row.content?.length ?? 0) - stub.length;
+  }
+  if (!saved || saved < minSaved) return null;
+  for (const [id, stub] of stubs) store.messages.setStub(id, stub);
+  for (const id of drops) store.messages.dropImages(id);
+  const epoch = chat.epoch + 1;
+  store.chats.touch(chat.id, { epoch, boundary_seq: plan.boundarySeq });
+  return { epoch, boundarySeq: plan.boundarySeq, saved };
+}
+
+/**
+ * The hard window: what happens when stubbing is not enough.
+ *
+ * Compaction only ever shrinks tool output and images, so a long conversation
+ * of plain text has nothing to give back and would grow until the provider
+ * refuses it outright. Past `maxTokens` the oldest turns leave the wire
+ * entirely. The cut always lands on a user message, so no tool call is ever
+ * separated from its result, and it moves back far enough to bring the history
+ * down to `targetTokens` -- a big step taken rarely, since every move is a full
+ * cache miss, the same trade an epoch makes. The last `keepTurns` turns are
+ * never cut, whatever they cost.
+ *
+ * Returns the new first visible seq, or null to leave the window where it is.
+ * `rows` must already be what the model would see (window applied, stubs in).
+ */
+export function planWindow(rows, { maxTokens, targetTokens, keepTurns, toWire }) {
+  if (!(maxTokens > 0)) return null;
+  const sizes = rows.map((r) => estimateTokens([toWire(r)]));
+  let total = sizes.reduce((a, b) => a + b, 0);
+  if (total <= maxTokens) return null;
+
+  const userIdx = rows.map((r, i) => (r.role === 'user' ? i : -1)).filter((i) => i >= 0);
+  if (userIdx.length <= keepTurns) return null;
+  const lastCut = userIdx[userIdx.length - keepTurns];
+
+  let cut = 0;
+  for (const i of userIdx) {
+    if (i === 0) continue;
+    if (i > lastCut) break;
+    for (let k = cut; k < i; k++) total -= sizes[k];
+    cut = i;
+    if (total <= targetTokens) break;
+  }
+  return cut > 0 ? rows[cut].seq : null;
+}
+
+/**
+ * Applies a window to stored rows: drops what is before it and marks the
+ * first remaining message so the model knows the conversation did not start
+ * there. Pure and deterministic, so every rebuild sends the same bytes.
+ */
+export function windowRows(rows, windowSeq, { summarized = false } = {}) {
+  if (!(windowSeq >= 0)) return rows;
+  const kept = rows.filter((r) => r.seq >= windowSeq);
+  const dropped = rows.length - kept.length;
+  if (!dropped || !kept.length || kept[0].role !== 'user') return kept;
+  const note = `[Earlier conversation omitted: ${dropped} message${dropped === 1 ? '' : 's'} before this`
+    + ' point were removed to keep the conversation within the context window. '
+    + (summarized
+      ? 'They are summarised in the system prompt; if something you need is missing there, ask the user.]'
+      : 'If something from before is needed and is not restated here, ask the user.]');
+  return [{ ...kept[0], content: `${note}\n\n${kept[0].content ?? ''}` }, ...kept.slice(1)];
+}