@moxxy/sdk 0.41.2 → 0.42.0

package/src/progress.ts

@@ -0,0 +1,73 @@
+import type { MoxxyEvent } from './events.js';
+import type { ModeContext } from './mode.js';
+import type { TurnCheckpoint } from './mode/checkpoint.js';
+
+/**
+ * What a tool result says about the thing it looked at: `key` names it (a
+ * browser tab, a job), `pending` says what was still under way there, or null
+ * when nothing was. A result that knows nothing about it leaves `progress` out.
+ */
+export interface Progress {
+  readonly key: string;
+  readonly pending: string | null;
+}
+
+export function progressOf(output: unknown): Progress | null {
+  if (typeof output !== 'object' || output === null) return null;
+  const progress = (output as { progress?: unknown }).progress;
+  if (typeof progress !== 'object' || progress === null) return null;
+  const { key, pending } = progress as { key?: unknown; pending?: unknown };
+  if (typeof key !== 'string') return null;
+  return { key, pending: typeof pending === 'string' ? pending : null };
+}
+
+/** What was still under way the last time each thing was looked at, in `events`. */
+export function unfinishedWork(events: ReadonlyArray<MoxxyEvent>): string[] {
+  const latest = new Map<string, string | null>();
+  for (const e of events) {
+    if (e.type !== 'tool_result' || !e.ok) continue;
+    const progress = progressOf(e.output);
+    if (progress) latest.set(progress.key, progress.pending);
+  }
+  return [...latest.values()].filter((pending): pending is string => pending !== null);
+}
+
+export function unfinishedWorkNudge(pending: ReadonlyArray<string>): string {
+  return (
+    `Before you report: the last time you looked, this was still in progress — ${pending.join('; ')}. ` +
+    'What it leads to is not known yet, and anything you checked before it may no longer hold. ' +
+    'Wait for it to finish (with a tool’s own wait, if it has one), look again, and report what you see then. ' +
+    'If it does not finish, say plainly that it has not.'
+  );
+}
+
+const turnOf = (ctx: ModeContext): string => `${ctx.sessionId}/${ctx.turnId}`;
+
+/** Turns already asked, so one turn is asked at most once. Bounded: oldest go first. */
+const MAX_REMEMBERED_TURNS = 256;
+
+/**
+ * At the end of a turn, one reminder when the last look at something found
+ * work still under way. The report is then based on a state that has not
+ * settled — the agent pressed Deploy and reported the address from a check
+ * made before it. Asked once per turn: the agent may well have good reason to
+ * report anyway, and it is told how to say so.
+ */
+export function unfinishedWorkCheckpoint(): TurnCheckpoint {
+  const asked = new Set<string>();
+  return {
+    name: 'unfinished-work',
+    applies: (ctx: ModeContext) =>
+      !asked.has(turnOf(ctx)) && unfinishedWork(ctx.log.byTurn(ctx.turnId)).length > 0,
+    async run(_check, ctx: ModeContext) {
+      const pending = unfinishedWork(ctx.log.byTurn(ctx.turnId));
+      if (pending.length === 0) return { action: 'pass' };
+      asked.add(turnOf(ctx));
+      for (const oldest of asked) {
+        if (asked.size <= MAX_REMEMBERED_TURNS) break;
+        asked.delete(oldest);
+      }
+      return { action: 'inject', text: unfinishedWorkNudge(pending), volatile: true };
+    },
+  };
+}

package/src/provider.ts

@@ -53,6 +53,9 @@ export interface CacheHint {
   readonly target: 'tools' | 'system' | { readonly messageIndex: number };
 }
 
+/** How deeply a reasoning model should think; `xhigh` is the deepest. */
+export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
+
 export interface ProviderRequest {
   readonly model: string;
   /**
@@ -81,7 +84,13 @@ export interface ProviderRequest {
    * each provider's native knob (Anthropic thinking budget, OpenAI/Codex
    * `reasoning.effort`).
    */
-  readonly reasoning?: { readonly effort?: 'low' | 'medium' | 'high' } | boolean;
+  readonly reasoning?: { readonly effort?: ReasoningEffort } | boolean;
+  /**
+   * Serve this request on the provider's faster, pricier tier (OpenAI
+   * `service_tier: "priority"`). Set by the loop only for a model whose
+   * descriptor has `supportsFast`.
+   */
+  readonly fast?: boolean;
 }
 
 export type ProviderEvent =
@@ -148,6 +157,8 @@ export interface ModelDescriptor {
    * for this model. When false, `ProviderRequest.reasoning` is ignored.
    */
   readonly supportsReasoning?: boolean;
+  /** Whether the provider can serve this model on a faster tier (see `ProviderRequest.fast`). */
+  readonly supportsFast?: boolean;
   /**
    * Tools executed by the provider on behalf of this model (for example
    * OpenAI Responses or Anthropic server tools). A matching client ToolDef

package/src/resolvers.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createDeferredPermissionResolver, evaluateToolRule } from './resolvers.js';
+import { createAllowListResolver, createDeferredPermissionResolver, evaluateToolRule } from './resolvers.js';
 import type { PendingToolCall, PermissionRule } from './permission.js';
 
 function call(name: string, input: unknown = {}): PendingToolCall {
@@ -70,3 +70,16 @@ describe('createDeferredPermissionResolver scoped session grants', () => {
     expect(prompts).toBe(2);
   });
 });
+
+describe('a decision made now', () => {
+  it('is marked when the prompt was answered for this call, not when an earlier answer is reused', async () => {
+    const resolver = createDeferredPermissionResolver({ prompt: async () => ({ mode: 'allow_session' }) });
+    const ctx = { sessionId: 's' };
+    expect((await resolver.check(call('computer_run', { app: 'Notes' }), ctx)).decidedNow).toBe(true);
+    expect((await resolver.check(call('computer_run', { app: 'Mail' }), ctx)).decidedNow).toBeUndefined();
+  });
+
+  it('is marked for a tool the run was started with on its allow-list', async () => {
+    expect((await createAllowListResolver(['computer_run']).check(call('computer_run', {}), { sessionId: 's' })).decidedNow).toBe(true);
+  });
+});

package/src/resolvers.ts

@@ -37,7 +37,7 @@ export function createAllowListResolver(toolNames: ReadonlyArray<string>): Permi
   return {
     name: 'allow-list',
     async check(call) {
-      if (allowed.has(call.name)) return { mode: 'allow_session', reason: 'allow-list' };
+      if (allowed.has(call.name)) return { mode: 'allow_session', reason: 'allow-list', decidedNow: true };
       return { mode: 'deny', reason: `Tool '${call.name}' not in allow-list` };
     },
   };
@@ -123,7 +123,7 @@ export function createDeferredPermissionResolver(
       } else if (decision.mode === 'allow_session' || decision.mode === 'allow_always') {
         sessionAllows.add(call.name);
       }
-      return decision;
+      return decision.mode === 'deny' ? decision : { ...decision, decidedNow: true };
     },
     abortAll(reason = 'channel closed') {
       for (const r of pending) r({ mode: 'deny', reason });

package/src/schemas.ts

@@ -66,6 +66,9 @@ export const skillFrontmatterSchema = z.object({
   description: z.string().min(1).max(240),
   triggers: z.array(z.string().min(1)).optional(),
   'allowed-tools': z.array(z.string().min(1)).optional(),
+  aliases: z.array(z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, 'alias must be slug-like')).optional(),
+  'disallowed-tools': z.array(z.string().min(1)).optional(),
+  label: z.string().min(1).max(40).optional(),
   version: z.string().optional(),
   tags: z.array(z.string().min(1)).optional(),
   /** Opt the skill into automatic recurring/one-shot execution. */

package/src/server.ts

@@ -41,6 +41,8 @@ export {
   redactProxyUrl,
   hasProxy,
 } from './egress.js';
+// The UTF-8 character type a GUI-launched process lacks (read from process.env).
+export { utf8Locale } from './locale.js';
 // Cross-process "fire exactly once" lock (node:fs). Value lives here; its
 // options type is re-exported from the main barrel like other erased types.
 export { CrossProcessFireLock } from './cross-process-lock.js';

package/src/session-like.ts

@@ -4,7 +4,7 @@ import type { CapabilitySpec } from './isolation.js';
 import type { EventLogReader } from './log.js';
 import type { ApprovalResolver, ModeBadge } from './mode.js';
 import type { PermissionResolver } from './permission.js';
-import type { ModelDescriptor, ProviderKeyValidation } from './provider.js';
+import type { ModelDescriptor, ProviderKeyValidation, ReasoningEffort } from './provider.js';
 import type { PluginSetupSpec } from './schemas.js';
 import type { ToolIcon } from './tool-icon.js';
 import type { ToolCompactPresentation } from './tool.js';
@@ -18,6 +18,8 @@ import type { ComputerControlService } from './computer-control.js';
  */
 export interface RunTurnOptions {
   readonly model?: string;
+  /** Optional context-window estimate for a custom model that is not in the provider catalog. */
+  readonly contextWindow?: number;
   readonly systemPrompt?: string;
   readonly maxIterations?: number;
   /**
@@ -91,6 +93,11 @@ export interface ToolInfo {
 export interface SkillInfo {
   readonly id: string;
   readonly name: string;
+  readonly description?: string;
+  /** Other names an @ mention can use; the first is what the @ menu inserts. */
+  readonly aliases?: ReadonlyArray<string>;
+  /** How the @ menu shows the skill ("Computer Use"); a skill with one is offered first. */
+  readonly label?: string;
 }
 
 /** Serializable slash-command metadata for the picker / `/help`. */
@@ -150,6 +157,19 @@ export interface SessionInfo {
   /** Name of the active synthesizer, or null. Lets a thin client proxy TTS
    *  (the desktop routes "Read aloud" through it; null → OS voice fallback). */
   readonly activeSynthesizer: string | null;
+  /** Tool calls run without asking in this conversation (see `auto-approve.ts`).
+   *  Absent from runners that predate the shared switch. */
+  readonly autoApprove?: boolean;
+  /**
+   * How deeply the model thinks in this conversation: a set effort, `default` when reasoning is on at the
+   * provider's own default effort, null when it is off. Absent from older runners.
+   */
+  readonly reasoningEffort?: ReasoningEffort | 'default' | null;
+  /** Whether turns ask for the provider's faster tier. Absent from older runners. */
+  readonly fast?: boolean;
+  /** Turns running now, whichever client (or in-process channel) started them.
+   *  Reported by a runner to its clients; absent from runners that predate it. */
+  readonly runningTurns?: ReadonlyArray<string>;
 }
 
 /**

package/src/skill-mentions.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest';
+import { asSkillId } from './ids.js';
+import type { ToolRegistry } from './mode.js';
+import type { Skill, SkillFrontmatter } from './skill.js';
+import { insertMention, mentionedSkills, mentionOptions, mentionQueryAt, skillAttachment, withoutTools } from './skill-mentions.js';
+import type { SkillInfo } from './session-like.js';
+import { defineTool } from './define.js';
+import { z } from 'zod';
+
+const skill = (frontmatter: Omit<SkillFrontmatter, 'description'>, body = 'Do it on the desktop.'): Skill => ({
+  id: asSkillId(`plugin/${frontmatter.name}`),
+  path: `/skills/${frontmatter.name}.md`,
+  scope: 'plugin',
+  frontmatter: { description: 'test skill', ...frontmatter },
+  body,
+});
+
+const computer = skill({ name: 'computer-control', aliases: ['computer-use'], 'disallowed-tools': ['browser_*'] });
+const browser = skill({ name: 'browser' });
+
+describe('mentionedSkills', () => {
+  it('finds a skill the prompt names with @, by an alias written with underscores', () => {
+    expect(mentionedSkills('@computer_use otwórz Canvę w Arc', [browser, computer])).toEqual([computer]);
+  });
+
+  it('finds a skill by its own name, in any letter case, anywhere in the prompt', () => {
+    expect(mentionedSkills('zrób to przez @Computer-Control, proszę', [computer])).toEqual([computer]);
+  });
+
+  it('names each skill once however often it is mentioned', () => {
+    expect(mentionedSkills('@computer_use i jeszcze raz @computer-control', [computer])).toEqual([computer]);
+  });
+
+  it('ignores an e-mail address and a mention of no skill', () => {
+    expect(mentionedSkills('napisz do kamil@computer-use.pl o @nobody', [computer])).toEqual([]);
+  });
+});
+
+describe('skillAttachment', () => {
+  it('carries the skill to the model as a file, saying the user asked for it and which tools are off', () => {
+    const attachment = skillAttachment(computer);
+
+    expect(attachment).toMatchObject({ kind: 'file', name: 'computer-control skill' });
+    expect(attachment.content).toContain('The user called this skill with an @ mention');
+    expect(attachment.content).toContain('browser_*');
+    expect(attachment.content.endsWith('Do it on the desktop.')).toBe(true);
+  });
+});
+
+describe('withoutTools', () => {
+  const tool = (name: string) => defineTool({ name, description: name, inputSchema: z.object({}), handler: async () => name });
+  const registry: ToolRegistry = {
+    list: () => [tool('browser_click'), tool('computer_click'), tool('web_fetch')],
+    get: (name) => registry.list().find((t) => t.name === name),
+    execute: async (name) => name,
+  };
+
+  it('leaves the withheld tools out of the list and out of reach by name', async () => {
+    const narrowed = withoutTools(registry, ['browser_*']);
+
+    expect(narrowed.list().map((t) => t.name)).toEqual(['computer_click', 'web_fetch']);
+    expect(narrowed.get('browser_click')).toBeUndefined();
+    await expect(narrowed.execute('computer_click', {}, new AbortController().signal)).resolves.toBe('computer_click');
+    await expect(narrowed.execute('browser_click', {}, new AbortController().signal)).rejects.toThrow(/browser_click is off for this request/);
+  });
+});
+
+describe('mentionQueryAt', () => {
+  it('reads the @ word the caret is in, from its @ to its end', () => {
+    expect(mentionQueryAt('zrób to @com', 12)).toEqual({ start: 8, end: 12, query: 'com' });
+    expect(mentionQueryAt('@comp reszta', 3)).toEqual({ start: 0, end: 5, query: 'comp' });
+    expect(mentionQueryAt('@', 1)).toEqual({ start: 0, end: 1, query: '' });
+  });
+
+  it('is nothing outside an @ word, in an e-mail address, or after a space', () => {
+    expect(mentionQueryAt('zwykły tekst', 5)).toBeNull();
+    expect(mentionQueryAt('kamil@gmail', 11)).toBeNull();
+    expect(mentionQueryAt('@computer_use ', 14)).toBeNull();
+  });
+});
+
+describe('mentionOptions', () => {
+  const skills: SkillInfo[] = [
+    { id: 'builtin/web-research', name: 'web-research', description: 'Research a topic on the web' },
+    { id: 'builtin/browser', name: 'browser', label: 'Moxxy Browser', aliases: ['moxxy_browser', 'przegladarka'], description: 'Drive the in-window browser' },
+    { id: 'plugin/computer-control', name: 'computer-control', label: 'Computer Use', aliases: ['computer_use', 'komputer'], description: 'Operate desktop apps' },
+  ];
+
+  it('offers the labelled skills first, each to be inserted by its first alias', () => {
+    expect(mentionOptions(skills, '').map((o) => o.token)).toEqual(['computer_use', 'moxxy_browser', 'web-research']);
+    expect(mentionOptions(skills, '')[0]).toEqual({ name: 'computer-control', token: 'computer_use', label: 'Computer Use', description: 'Operate desktop apps' });
+  });
+
+  it('matches what was typed against names, aliases and labels, diacritics and _ aside', () => {
+    expect(mentionOptions(skills, 'com').map((o) => o.name)).toEqual(['computer-control']);
+    expect(mentionOptions(skills, 'przeglą').map((o) => o.name)).toEqual(['browser']);
+    expect(mentionOptions(skills, 'computer-u').map((o) => o.name)).toEqual(['computer-control']);
+    expect(mentionOptions(skills, 'brow').map((o) => o.name)).toEqual(['browser']);
+    expect(mentionOptions(skills, 'zzz')).toEqual([]);
+  });
+
+  it('puts a word that starts with the query before one that only holds it', () => {
+    expect(mentionOptions(skills, 'res').map((o) => o.name)).toEqual(['web-research']);
+    expect(mentionOptions(skills, 'r').map((o) => o.name)).toEqual(['web-research', 'computer-control', 'browser']);
+  });
+});
+
+describe('insertMention', () => {
+  it('replaces the @ word with the token and a space, the caret after it', () => {
+    expect(insertMention('zrób @com', { start: 5, end: 9, query: 'com' }, 'computer_use')).toEqual({ text: 'zrób @computer_use ', caret: 19 });
+    expect(insertMention('@co reszta', { start: 0, end: 3, query: 'co' }, 'computer_use')).toEqual({ text: '@computer_use reszta', caret: 14 });
+  });
+});

package/src/skill-mentions.ts

@@ -0,0 +1,108 @@
+import type { UserPromptAttachment } from './events.js';
+import type { ToolRegistry } from './mode.js';
+import type { SkillInfo } from './session-like.js';
+import type { Skill } from './skill.js';
+
+/** `@computer_use`, but not the `@` inside an e-mail address. */
+const MENTION = /(?<![\p{L}\p{N}_@.])@(\p{L}[\p{L}\p{N}_-]*)/gu;
+
+/** `computer_use`, `Computer-Use` and `computer-use` name the same skill; so do `przeglądarka` and `przegladarka`. */
+const key = (name: string): string =>
+  name.toLowerCase().normalize('NFD').replace(/\p{M}/gu, '').replace(/ł/gu, 'l').replace(/[_\s]+/gu, '-');
+
+/** The skills a prompt calls by an @ mention of their name or an alias, each once, in mention order. */
+export function mentionedSkills(text: string, skills: ReadonlyArray<Skill>): Skill[] {
+  const byKey = new Map<string, Skill>();
+  for (const skill of skills) {
+    for (const name of [skill.frontmatter.name, ...(skill.frontmatter.aliases ?? [])]) byKey.set(key(name), skill);
+  }
+  const found = new Set<Skill>();
+  for (const [, name] of text.matchAll(MENTION)) {
+    const skill = byKey.get(key(name ?? ''));
+    if (skill) found.add(skill);
+  }
+  return [...found];
+}
+
+/** The mentioned skill, recorded on the prompt so every surface and every replay sees the same request. */
+export function skillAttachment(skill: Skill): UserPromptAttachment {
+  const withheld = skill.frontmatter['disallowed-tools'] ?? [];
+  const off = withheld.length > 0 ? ` The tools ${withheld.join(', ')} are off for this request.` : '';
+  return {
+    kind: 'file',
+    name: `${skill.frontmatter.name} skill`,
+    content: `The user called this skill with an @ mention: follow it for this request.${off}\n\n${skill.body}`,
+  };
+}
+
+/** Whether a tool name fits an `allowed-tools`-style pattern (`browser_*` or an exact name). */
+export function toolPatternMatches(pattern: string, name: string): boolean {
+  return pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : name === pattern;
+}
+
+/** The registry without the tools the patterns name: not offered to the model, and refused if called anyway. */
+export function withoutTools(tools: ToolRegistry, patterns: ReadonlyArray<string>): ToolRegistry {
+  const withheld = (name: string) => patterns.some((pattern) => toolPatternMatches(pattern, name));
+  return {
+    list: () => tools.list().filter((tool) => !withheld(tool.name)),
+    get: (name) => (withheld(name) ? undefined : tools.get(name)),
+    execute: async (name, input, signal, opts) => {
+      if (withheld(name)) throw new Error(`${name} is off for this request: the user called a skill that rules it out`);
+      return tools.execute(name, input, signal, opts);
+    },
+  };
+}
+
+/** The @ word being typed: where it starts (its `@`), where it ends, and what follows the `@`. */
+export interface MentionQuery {
+  readonly start: number;
+  readonly end: number;
+  readonly query: string;
+}
+
+const TYPED = /(?:^|[\s(])@([\p{L}\p{N}_-]*)$/u;
+const REST = /^[\p{L}\p{N}_-]*/u;
+
+/** The @ word the caret is in, or null when it is in none (an e-mail address is none). */
+export function mentionQueryAt(text: string, caret: number): MentionQuery | null {
+  const typed = TYPED.exec(text.slice(0, caret));
+  if (!typed) return null;
+  const query = typed[1] ?? '';
+  const rest = REST.exec(text.slice(caret))?.[0] ?? '';
+  return { start: caret - query.length - 1, end: caret + rest.length, query: query + rest };
+}
+
+/** One skill the @ menu offers: shown by `label`, inserted as `@token`. */
+export interface MentionOption {
+  readonly name: string;
+  readonly token: string;
+  readonly label: string;
+  readonly description: string;
+}
+
+/**
+ * The skills that answer an @ query: a word of a name, alias or label that starts with the query
+ * before one that only holds it, skills with a label (the tool-like ones) first, then by label.
+ */
+export function mentionOptions(skills: ReadonlyArray<SkillInfo>, query: string, limit = 8): MentionOption[] {
+  const wanted = key(query);
+  const ranked = skills.flatMap((skill) => {
+    const keys = [skill.name, ...(skill.aliases ?? []), ...(skill.label ? [skill.label] : [])].map(key);
+    const rank = keys.some((k) => k.split('-').some((word) => word.startsWith(wanted)) || k.startsWith(wanted))
+      ? 0
+      : keys.some((k) => k.includes(wanted)) ? 1 : undefined;
+    if (rank === undefined) return [];
+    const option = { name: skill.name, token: skill.aliases?.[0] ?? skill.name, label: skill.label ?? skill.name, description: skill.description ?? '' };
+    return [{ option, rank, labelled: skill.label ? 0 : 1 }];
+  });
+  ranked.sort((a, b) => a.rank - b.rank || a.labelled - b.labelled || a.option.label.localeCompare(b.option.label));
+  return ranked.slice(0, limit).map((entry) => entry.option);
+}
+
+/** The text with the @ word replaced by `@token` and a space, and the caret after that space. */
+export function insertMention(text: string, at: MentionQuery, token: string): { text: string; caret: number } {
+  const after = text.slice(at.end);
+  const spaced = /^\s/u.test(after) ? after : ` ${after}`;
+  const next = `${text.slice(0, at.start)}@${token}${spaced}`;
+  return { text: next, caret: at.start + token.length + 2 };
+}

package/src/skill.ts

@@ -13,6 +13,12 @@ export interface SkillFrontmatter {
   readonly description: string;
   readonly triggers?: ReadonlyArray<string>;
   readonly 'allowed-tools'?: ReadonlyArray<string>;
+  /** Other names a prompt can call the skill by with an @ mention (`computer_use`; `_` and `-` read the same). */
+  readonly aliases?: ReadonlyArray<string>;
+  /** How the chat's @ menu shows the skill ("Computer Use"); a skill with one is offered first. */
+  readonly label?: string;
+  /** Tools withheld from a turn whose prompt calls the skill by an @ mention (`browser_*` or exact names). */
+  readonly 'disallowed-tools'?: ReadonlyArray<string>;
   readonly version?: string;
   readonly tags?: ReadonlyArray<string>;
   readonly schedule?: SkillSchedule;

package/src/stuck-loop.test.ts

@@ -18,6 +18,18 @@ describe('createStuckLoopDetector', () => {
     expect(d.record('Read', input).stuck).toBe(true); // 8th identical call trips
   });
 
+  it('lets a live-state tool repeat between other calls, and still trips on a back-to-back run', () => {
+    const d = createStuckLoopDetector({ repeatThreshold: 3 });
+    const look = { app: 'Finder' };
+    for (let i = 0; i < 10; i++) {
+      expect(d.record('computer_get_app_state', look, { liveState: true }).stuck).toBe(false);
+      expect(d.record('computer_click', { element_index: i }).stuck).toBe(false);
+    }
+    expect(d.record('computer_get_app_state', look, { liveState: true }).stuck).toBe(false);
+    expect(d.record('computer_get_app_state', look, { liveState: true }).stuck).toBe(false);
+    expect(d.record('computer_get_app_state', look, { liveState: true })).toMatchObject({ stuck: true, count: 3, kind: 'exact' });
+  });
+
   it('never trips when disabled (relies on maxIterations alone)', () => {
     const d = createStuckLoopDetector({ enabled: false, repeatThreshold: 2 });
     const input = { x: 1 };

package/src/supersede.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+import { assertDefined } from './assert.js';
+import { asEventId, asSessionId, asTurnId } from './ids.js';
+import type { EventLogReader } from './log.js';
+import type { MoxxyEvent, MoxxyEventOfType, MoxxyEventType } from './events.js';
+import type { TurnId } from './ids.js';
+import { computeElisionState, toolResultStubbed } from './elision-state.js';
+import { estimateContextTokens } from './compactor-helpers.js';
+import { projectMessagesFromLog } from './mode/project-messages.js';
+
+/**
+ * A read of a page stops meaning anything once the same page has been read
+ * whole again. In the Coolify task the first turn's reads (one of them 178,073
+ * characters) were sent again on each of the 44 calls of the second turn, long
+ * after the agent had moved on to other pages. A result that names what it
+ * reads (`supersede.key`) is sent as a short marker once a later result reads
+ * the same thing whole; `recall` still brings it back.
+ */
+const sid = asSessionId('s1');
+const t1 = asTurnId('t1');
+
+function event(seq: number, partial: Omit<MoxxyEvent, 'id' | 'seq' | 'ts' | 'sessionId'>): MoxxyEvent {
+  return { id: asEventId(`e${seq}`), seq, ts: seq, sessionId: sid, ...partial } as MoxxyEvent;
+}
+
+function reader(events: ReadonlyArray<MoxxyEvent>): EventLogReader {
+  return {
+    length: events.length,
+    at: (seq) => events[seq],
+    slice: (from = 0, to = events.length) => events.slice(from, to),
+    ofType: <T extends MoxxyEventType>(type: T): ReadonlyArray<MoxxyEventOfType<T>> =>
+      events.filter((e): e is MoxxyEventOfType<T> => e.type === type),
+    byTurn: (turnId: TurnId) => events.filter((e) => e.turnId === turnId),
+    toJSON: () => events,
+  };
+}
+
+/** A tool call and its result, at seq and seq + 1. */
+function read(seq: number, callId: string, key: string, whole: boolean, text = 'x'.repeat(5_000)): MoxxyEvent[] {
+  return [
+    event(seq, { type: 'tool_call_requested', turnId: t1, source: 'model', callId, name: 'browser_snapshot', input: {} }),
+    event(seq + 1, {
+      type: 'tool_result',
+      turnId: t1,
+      source: 'tool',
+      callId,
+      ok: true,
+      output: { text, supersede: { key, whole } },
+    }),
+  ];
+}
+
+const log: MoxxyEvent[] = [
+  event(0, { type: 'user_prompt', turnId: t1, source: 'user', text: 'go' }),
+  ...read(1, 'page-1', 'browser:t1', true),
+  ...read(3, 'diff-1', 'browser:t1', false),
+  ...read(5, 'other-tab', 'browser:t2', true),
+  ...read(7, 'page-2', 'browser:t1', true, 'the page now'),
+];
+
+function resultOf(callId: string): Extract<MoxxyEvent, { type: 'tool_result' }> {
+  const found = log.find(
+    (e): e is Extract<MoxxyEvent, { type: 'tool_result' }> => e.type === 'tool_result' && e.callId === callId,
+  );
+  assertDefined(found, `result ${callId}`);
+  return found;
+}
+
+function sentFor(events: MoxxyEvent[], callId: string): string {
+  for (const m of projectMessagesFromLog({ log: reader(events) })) {
+    for (const block of m.content) {
+      if (block.type === 'tool_result' && block.toolUseId === callId) return String(block.content);
+    }
+  }
+  return '';
+}
+
+describe('a result read again whole is superseded', () => {
+  it('marks every earlier result of the same key once a later one is whole', () => {
+    const state = computeElisionState(log);
+
+    expect(toolResultStubbed(resultOf('page-1'), state)).toBe(true);
+    expect(toolResultStubbed(resultOf('diff-1'), state)).toBe(true);
+  });
+
+  it('keeps the newest whole read, and what another key read', () => {
+    const state = computeElisionState(log);
+
+    expect(toolResultStubbed(resultOf('page-2'), state)).toBe(false);
+    expect(toolResultStubbed(resultOf('other-tab'), state)).toBe(false);
+  });
+
+  it('does not let a partial read stand in for the whole one before it', () => {
+    // The changes alone mean something only against the read they change.
+    const partialLast = [...log.slice(0, 5)];
+    const state = computeElisionState(partialLast);
+
+    expect(toolResultStubbed(resultOf('page-1'), state)).toBe(false);
+  });
+
+  it('sends a superseded result as a marker that says how to get it back', () => {
+    const sent = sentFor(log, 'page-1');
+
+    expect(sent).toContain('recall("page-1")');
+    expect(sent.length).toBeLessThan(200);
+    expect(sentFor(log, 'page-2')).toContain('the page now');
+  });
+
+  it('counts the marker, not the read, when estimating the context', () => {
+    const withoutLater = log.slice(0, 7);
+
+    // Adding a short whole read takes the earlier reads out of the estimate.
+    expect(estimateContextTokens(reader(log))).toBeLessThan(estimateContextTokens(reader(withoutLater)));
+  });
+});

package/src/supersede.ts

@@ -0,0 +1,55 @@
+import type { MoxxyEvent } from './events.js';
+
+/**
+ * Results that a later result made stale.
+ *
+ * A tool that reads something which changes — a page in a browser tab — can
+ * name what it read in its result (`supersede.key`) and say whether the read is
+ * whole or only what changed since the last one. Once a later result reads the
+ * same key whole, every earlier result of that key says nothing the model still
+ * needs, and is sent as a short marker instead (`recall` brings it back).
+ *
+ * In the Coolify task the first turn's page reads, one of them 178,073
+ * characters, were sent again on each of the 44 calls of the second turn, long
+ * after the agent had moved on to other pages. A partial read never stands in
+ * for a whole one: what changed means something only against what it changed.
+ *
+ * Decided from the log alone, so projection and the context estimate agree, and
+ * deterministic, so a prefix only changes when a new whole read arrives.
+ */
+export interface Supersede {
+  /** What the result read, e.g. `browser:t1`. Results of different keys never touch. */
+  readonly key: string;
+  /** The whole of it, rather than only what changed since the last read. */
+  readonly whole: boolean;
+}
+
+/** The `supersede` a tool output carries, if it carries a well-formed one. */
+export function supersedeOf(output: unknown): Supersede | null {
+  if (typeof output !== 'object' || output === null) return null;
+  const s = (output as { supersede?: unknown }).supersede;
+  if (typeof s !== 'object' || s === null) return null;
+  const { key, whole } = s as { key?: unknown; whole?: unknown };
+  return typeof key === 'string' && key !== '' && typeof whole === 'boolean' ? { key, whole } : null;
+}
+
+/** callIds of results a later whole result of the same key replaced. */
+export function supersededCallIds(events: ReadonlyArray<MoxxyEvent>): ReadonlySet<string> {
+  const superseded = new Set<string>();
+  const readWholeLater = new Set<string>();
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i];
+    if (e === undefined || e.type !== 'tool_result' || e.error) continue;
+    const s = supersedeOf(e.output);
+    if (!s) continue;
+    if (readWholeLater.has(s.key)) superseded.add(e.callId);
+    else if (s.whole) readWholeLater.add(s.key);
+  }
+  return superseded;
+}
+
+/** Deterministic marker for a superseded result. Stable bytes → cache-safe. */
+export function supersededStub(callId: string, bytes: number): string {
+  const label = bytes >= 1024 ? `${(Math.round(bytes / 102.4) / 10).toFixed(1)} KB` : `${bytes} B`;
+  return `[superseded — a later result read the same thing whole · ${label} · recall("${callId}") to view]`;
+}