@jxsuite/studio 10.4.0 → 10.6.0

package/src/panels/statement-editor.ts

@@ -62,6 +62,8 @@ export interface StatementEditorOpts {
   stateDefs: string[];
   stateEntries?: Record<string, JxStateDefinition> | null;
   allowEventRef: boolean;
+  /** Pointers beyond the document's own signals: inside a repeater, its item and that item's fields. */
+  extraRefs?: readonly SurfaceOption[] | null | undefined;
   /** The entry's declared CEM events — offered as dispatchEvent name completions. */
   emits?: CemEvent[];
   /**
@@ -342,6 +344,7 @@ function operandOpts(opts: StatementEditorOpts) {
   return {
     allowEventRef: opts.allowEventRef,
     depth: 0,
+    extraRefs: opts.extraRefs,
     stateDefs: opts.stateDefs,
     stateEntries: opts.stateEntries ?? null,
   };
@@ -578,6 +581,7 @@ export function flattenStatements(
           (n) => commit(n as JxStatement),
           {
             allowEventRef: opts.allowEventRef,
+            extraRefs: opts.extraRefs,
             stateDefs: opts.stateDefs,
             stateEntries: opts.stateEntries ?? null,
           },

package/src/panels/style-panel.ts

@@ -54,6 +54,7 @@ import {
   isNumber,
   isString,
 } from "@jxsuite/schema/guards";
+import { PROJECT_FILE_NAME } from "@jxsuite/schema/project-file";
 import { effect, effectScope, reactive } from "../reactivity";
 import {
   cancelStyleDebounce,
@@ -374,7 +375,7 @@ function stylebookTagOf(selector: string | null): string | null {
  * elements of its own for "in this document" to be about.
  */
 function isProjectStylesheet(path: string): boolean {
-  return /(?:^|\/)project\.json$/.test(path);
+  return path.split("/").pop() === PROJECT_FILE_NAME;
 }
 
 /**

package/src/panels/styles-panel.ts

@@ -34,7 +34,7 @@ import { effect, effectScope } from "../reactivity";
 import { projectState } from "../store";
 import { setDockCollapsed, shell } from "../shell";
 import { workspace } from "../workspace/workspace";
-import { PROJECT_CONFIG_PATH } from "../tabs/tab";
+import { projectConfigPath } from "../tabs/tab";
 import { componentRegistry } from "../files/components";
 import { runActiveReported } from "../commands/run-reported";
 import { showSettingsDocument } from "../settings/settings-document";
@@ -88,7 +88,7 @@ export interface StylesPanelInput {
  * opened with.
  */
 export function stylesConfig(): StylesPanelInput["config"] {
-  const tab = workspace.tabs.get(PROJECT_CONFIG_PATH);
+  const tab = workspace.tabs.get(projectConfigPath());
   return (tab ? tab.doc.document : projectState?.projectConfig) ?? null;
 }
 

package/src/panels/tab-strip.ts

@@ -16,7 +16,7 @@
  * **The chip is a `jx-tab` now, and three of the things it used to draw by hand are the kit's**:
  * the selected state (`aria-selected` on a real `tab` inside a real `tablist`, where an `.active`
  * class used to be), the close button, and the dirty dot. The three that are Studio's own live in
- * `jx-tab`'s slots — the drill-in marker in `icon`, the draft pill in `status`, the pin toggle in
+ * `jx-tab`'s slots — the drill-in marker in `icon`, the hold pill in `status`, the pin toggle in
  * `actions` — which is the gap that kept this strip out of the tab pattern (`ui.md` §5.4). With it
  * closed the strip is one stop in the tab order, the arrows walk it, Home and End reach its ends,
  * and Delete closes a tab: a keyboard contract the × has never had.
@@ -57,8 +57,8 @@ import { gridTabLabel } from "../grid/grid-source";
 import { workspaceTabOrder } from "../workspace/tab-workspace";
 import { workspaceHomeLabel } from "../workspace/workspace-ids";
 import { shell, workspaceDrawsTabStrip } from "../shell";
-import { entryDraftPill } from "../content/entry-editor";
-import { DRAFT_FIELD, isDraftEntry } from "../content/draft-state";
+import { entryHoldPill } from "../content/entry-editor";
+import { holdFields, holdSwitch } from "../content/hold-state";
 import { entryFields } from "../content/entry-fields";
 import { collectionOfPath } from "../content/entry-model";
 import { activeRegistry } from "../commands/active-registry";
@@ -262,9 +262,11 @@ export function mount(host: HTMLElement) {
         void tab.pinned;
         void tab.preview;
         void tab.session.openedFrom;
-        // The draft pill is on the chip, so the chip has to repaint when the flag changes — reading
-        // The absent key tracks its ADDITION too, which is the transition that matters most.
-        void tab.doc.content.frontmatter[DRAFT_FIELD];
+        // The hold pill is on the chip, so the chip has to repaint when a field its rules read
+        // Changes. Reading an absent key tracks its ADDITION too, which matters most.
+        for (const field of holdFields(collectionOfPath(tab.documentPath)?.def)) {
+          void tab.doc.content.frontmatter[field];
+        }
       }
       // An edit is a commitment: a preview tab with unsaved changes is no longer disposable, and
       // The dirty flags this effect already tracks are exactly the signal.
@@ -685,15 +687,15 @@ function chipView(
   if (!tab) {
     return [];
   }
-  /* The draft pill (`site-architecture.md` §7.6). On the CHIP, not only inside the entry editor:
+  /* The hold pill (`site-architecture.md` §7.6). On the CHIP, not only inside the entry editor:
      the mistake this prevents — publishing something you believed was private — is made while
      glancing at a row of tabs, and it is made about a document that may not even be the active
      one. */
-  const pill = entryDraftPill(tab);
+  const pill = entryHoldPill(tab);
   return [
     {
       dirty: tab.doc.dirty || imageEditorDirty(tab),
-      draft: pill?.draft ?? false,
+      held: pill?.held ?? false,
       index,
       key: id,
       label: labels.get(id) ?? "Untitled",
@@ -1011,24 +1013,25 @@ export function dismissTabContextMenu() {
  * A tab addresses ONE document, and this is everything the chip can say about it — keyed by the
  * ARGUMENT NAME that asks for it.
  *
- * The whole `context/tab` placement asks for exactly one argument today: `content.setDraft
- * {draft}`. The other five records take none, because they read the ACTIVE document — which is why
+ * The whole `context/tab` placement asks for exactly one argument today: `content.setHold {hold}`.
+ * The other five records take none, because they read the ACTIVE document — which is why
  * {@link openTabContextMenu} activates the chip before it builds a single row.
  *
  * A fact is stated ONLY when it is true of this tab, and that is what decides whether a command
- * appears at all: `styles/main.css` is an entry of no collection, so it states no `draft`, so "Set
- * Draft" is not offered on it. The condition is `collectionOfPath` — the same question
- * `content.setDraft`'s own `enablement` asks — so the menu never invents a rule the command does
- * not have, and never renders a row into a refusal.
+ * appears at all: `styles/main.css` is an entry of no collection, so it has no hold rules, so "Set
+ * Hold" is not offered on it. The condition is `collectionOfPath` — the same question
+ * `content.setHold`'s own `enablement` asks — so the menu never invents a rule the command does not
+ * have, and never renders a row into a refusal.
  *
  * The VALUE is the state the row would reach, not the state the tab is in: a setter is named for
- * where it lands (`content/draft-state.ts` says why), so the row offers the flip of what is true
- * now and {@link statedChecked} reads the current state back out of it for the checkmark.
+ * where it lands (`content/hold-state.ts` says why), so the row offers the flip of what is true now
+ * and {@link statedChecked} reads the current state back out of it for the checkmark.
  */
 function tabRowFacts(tab: Tab): CommandArgValues {
   const facts: CommandArgValues = {};
-  if (collectionOfPath(tab.documentPath)) {
-    facts.draft = !isDraftEntry(entryFields(tab));
+  const toggle = holdSwitch(collectionOfPath(tab.documentPath)?.def);
+  if (toggle) {
+    facts.hold = entryFields(tab)[toggle.field] !== true;
   }
   return facts;
 }
@@ -1040,16 +1043,16 @@ function tabRowFacts(tab: Tab): CommandArgValues {
  * A menu is the one surface that is READ before it is used, so it is the one surface that can show
  * a boolean instead of asking the author to remember it. That is an argument for the SETTER over
  * the toggle, and it is why this is derived from the args rather than from a list of command ids:
- * `content.setDraft {draft}` names the state it reaches, so the row can say which state the tab is
- * in now and still land somewhere definite when clicked. `document.togglePinned` names no state —
- * "Pin / Unpin Document" is a title that admits it does not know which it will do — so it renders
- * as a plain row here. Its idempotent sibling `document.setPinned {pinned}` would state its own
- * value, with no edit to this file, on the day its record declares `context/tab`; that declaration
- * lives in `workspace/workspace.ts`, which is the only place it can be made.
+ * `content.setHold {hold}` names the state it reaches, so the row can say which state the tab is in
+ * now and still land somewhere definite when clicked. `document.togglePinned` names no state — "Pin
+ * / Unpin Document" is a title that admits it does not know which it will do — so it renders as a
+ * plain row here. Its idempotent sibling `document.setPinned {pinned}` would state its own value,
+ * with no edit to this file, on the day its record declares `context/tab`; that declaration lives
+ * in `workspace/workspace.ts`, which is the only place it can be made.
  *
  * **It is a real checkbox row now, which it could not be under Spectrum.** `sp-menu` reassigned
  * every item's role one frame after connect whenever the menu declared no `selects`, so
- * `role="menuitemcheckbox"` did not survive and the state had to be printed as a sentence ("Draft:
+ * `role="menuitemcheckbox"` did not survive and the state had to be printed as a sentence ("Held:
  * no") in the description line instead. `jx-menu-item` derives `role` and `aria-checked` from
  * `checked` and nothing rewrites them, so the row states the boolean the way a screen reader
  * already knows how to announce — and the five rows that carry no state stay plain `menuitem`s,

package/src/platforms/cloud.ts

@@ -20,6 +20,7 @@ import type { WsCollabConnection } from "@jxsuite/collab/client";
 import { isBoolean, isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JsonObject, JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import { componentMetaFrom } from "@jxsuite/schema/component-meta";
+import { isJxnPath, isNativeDocumentPath, parseJxn } from "@jxsuite/schema/jxn";
 import { streamImport } from "../services/import-client";
 import type {
   AccountEntry,
@@ -1403,7 +1404,7 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
             if (!SKIP.has(entry.name) && !entry.name.startsWith(".")) {
               dirs.push(entry.path);
             }
-          } else if (entry.name.endsWith(".json") && jsonPaths.length < MAX_FILES) {
+          } else if (isNativeDocumentPath(entry.name) && jsonPaths.length < MAX_FILES) {
             jsonPaths.push(entry.path);
           }
         }
@@ -1414,7 +1415,9 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       const metas = await Promise.all(
         jsonPaths.map(async (path) => {
           try {
-            return componentMetaFrom(parseJson(await platform.readFile(path)), path);
+            const text = await platform.readFile(path);
+            const document = isJxnPath(path) ? parseJxn(text) : parseJson(text);
+            return componentMetaFrom(isJsonObject(document) ? document : null, path);
           } catch {
             return null; // Not JSON, not readable, or not a component — all the same answer here.
           }

package/src/services/ai-command-tools.ts

@@ -84,6 +84,7 @@ import type { CommandContext } from "../commands/context";
 import type { AiToolReport, AnyCommand, CommandRegistry } from "../commands/registry";
 import type { Tab } from "../tabs/tab";
 import { runAsActor } from "../tabs/transact";
+import { projectConfigPath } from "../tabs/tab";
 
 /**
  * The record a selection-level projection composes through.
@@ -328,7 +329,7 @@ function defaultPaths(command: AnyCommand, tab: Tab | null): string[] {
     return [tab?.documentPath ?? "(untitled)"];
   }
   if (command.undo === "project") {
-    return ["project.json"];
+    return [projectConfigPath()];
   }
   return ["(unknown file)"];
 }

package/src/services/ai-project-tools.ts

@@ -17,6 +17,7 @@
 import { JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
 import { createToolDefinition } from "@jxsuite/ai/tools";
 import { isJsonObject, isNumber } from "@jxsuite/schema/guards";
+import { classifyJxn, isJxnPath, isNativeDocumentPath, parseJxn } from "@jxsuite/schema/jxn";
 import type { CreateProjectDestination, StudioPlatform } from "../types";
 import type { ToolRegistry } from "@jxsuite/ai/tools";
 import type { JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
@@ -28,8 +29,9 @@ import { adoptCreatedProject } from "./project-adoption";
 import { translateValidationError } from "./ai-tools";
 import { validateDoc, validateProjectConfig } from "./jx-validate";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
-import type { CandidateDocument } from "./ai-write-report";
+import type { CandidateDocument, RenderProbe } from "./ai-write-report";
 import { invalidPathResult, normalizeRelPath } from "./project-path";
+import { isProjectConfigPath } from "@jxsuite/schema/project-file";
 
 /** Directories the file tools never descend into or report. */
 const EXCLUDED_DIRS = new Set(["node_modules", "dist", ".git", ".jx-cache"]);
@@ -49,7 +51,7 @@ const NOT_UNDOABLE = "(saved to disk; not undoable with Cmd+Z)";
  * {@link looksLikeJxDoc} sniff.
  */
 function isJxDocPath(path: string): boolean {
-  return /^(pages|layouts|components|elements)\//.test(path) && path.endsWith(".json");
+  return /^(pages|layouts|components|elements)\//.test(path) && isNativeDocumentPath(path);
 }
 
 /** Structural sniff for Jx-document-shaped JSON values. */
@@ -71,7 +73,7 @@ export interface ProjectToolsCtx {
    * judges the live configuration and a candidate parsed from the model's text alike.
    */
   validateProject?: (config: ProjectConfig | JsonValue) => Promise<string[]>;
-  renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
+  renderCheck?: RenderProbe;
   /** Live getter — the project style appears only after a project is open/bootstrapped. */
   getProjectStyle?: () => Record<string, string> | undefined;
   /** The open tab whose `documentPath` equals the given project-relative path, if any. */
@@ -299,8 +301,19 @@ export function registerProjectTools(
 
         // Pre-validate Jx documents — disk writes have no undo to lean on.
         let parsed: JsonValue | undefined;
-        const isJson = relPath.endsWith(".json") && relPath !== "project.json";
-        if (isJson) {
+        const isJxn = isJxnPath(relPath) && classifyJxn(content) !== "project";
+        const isJson = relPath.endsWith(".json") && !isProjectConfigPath(relPath);
+        if (isJxn) {
+          try {
+            const document = parseJxn(content);
+            parsed = isJsonObject(document) ? document : null;
+          } catch (error) {
+            return {
+              success: false,
+              error: `Content is not valid Jx Notation: ${error instanceof Error ? error.message : String(error)}`,
+            };
+          }
+        } else if (isJson) {
           try {
             // SAFETY: `JSON.parse` without a reviver yields nothing but JSON values.
             parsed = JSON.parse(content) as JsonValue;
@@ -312,7 +325,7 @@ export function registerProjectTools(
           }
         }
         let tokenHints = "";
-        // The parse above sets `parsed` exactly when `isJson` holds: it never yields `undefined`.
+        // The parse above sets `parsed` exactly when one of those holds: it never yields `undefined`.
         if (parsed !== undefined && (isJxDocPath(relPath) || looksLikeJxDoc(parsed))) {
           const errors = await validate(parsed);
           if (errors.length > 0) {
@@ -323,7 +336,7 @@ export function registerProjectTools(
             };
           }
           if (renderCheck) {
-            const renderResult = await renderCheck(parsed);
+            const renderResult = await renderCheck(parsed, { documentPath: relPath });
             if (!renderResult.ok) {
               return {
                 success: false,
@@ -345,7 +358,7 @@ export function registerProjectTools(
         /* Parsed as `unknown` because that is what it is until the schema says otherwise — this is
            model-authored text, and the gate below is the whole reason we do not trust its shape. */
         let projectConfig: ProjectConfig | undefined;
-        if (relPath === "project.json") {
+        if (isProjectConfigPath(relPath)) {
           let parsedConfig: JsonValue;
           try {
             // SAFETY: `JSON.parse` without a reviver yields nothing but JSON values.

package/src/services/ai-tools.ts

@@ -18,7 +18,7 @@ import { validateDoc } from "./jx-validate";
 import { invalidPathResult, normalizeRelPath } from "./project-path";
 import { serializeJson } from "@jxsuite/schema/json-layout";
 import { translateValidationError } from "./ai-write-report";
-import type { CandidateDocument } from "./ai-write-report";
+import type { CandidateDocument, RenderProbe } from "./ai-write-report";
 import { studioDocumentHost, studioWriteReporter } from "./harness/studio-documents";
 
 /* Re-exported from its new home so `ai-project-tools.ts` and the tests keep their import: the
@@ -34,7 +34,7 @@ export { translateValidationError } from "./ai-write-report";
  *   getTab: () => import("../tabs/tab").Tab | null;
  *   validate?: (doc: CandidateDocument) => Promise<string[]>;
  *   saveFile?: (relPath: string, content: string) => Promise<void>;
- *   renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
+ *   renderCheck?: RenderProbe;
  *   projectStyle?: Record<string, string>;
  *   getProjectStyle?: () => Record<string, string> | undefined;
  *   findOpenTab?: (path: string) => import("../tabs/tab").Tab | null;
@@ -56,7 +56,7 @@ export function registerAiTools(
     getTab: () => Tab | null;
     validate?: (doc: CandidateDocument) => Promise<string[]>;
     saveFile?: (relPath: string, content: string) => Promise<void>;
-    renderCheck?: (doc: CandidateDocument) => Promise<{ ok: true } | { ok: false; error: string }>;
+    renderCheck?: RenderProbe;
     projectStyle?: Record<string, string> | undefined;
     /**
      * Live variant of `projectStyle` — takes precedence; re-read per tool call so a project
@@ -164,7 +164,7 @@ export function registerAiTools(
           };
         }
         if (renderCheck) {
-          const renderResult = await renderCheck(content);
+          const renderResult = await renderCheck(content, { documentPath: relPath });
           if (!renderResult.ok) {
             return {
               success: false,
@@ -252,7 +252,7 @@ export function registerAiTools(
           };
         }
         if (renderCheck) {
-          const renderResult = await renderCheck(content);
+          const renderResult = await renderCheck(content, { documentPath: relPath });
           if (!renderResult.ok) {
             return {
               success: false,

package/src/services/ai-write-report.ts

@@ -22,7 +22,7 @@
  */
 
 import type { ToolResult } from "@jxsuite/ai/tools";
-import type { JsonValue, JxMutableNode } from "@jxsuite/schema/types";
+import type { JsonValue, JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
 import { toRaw } from "../reactivity";
 import type { Tab } from "../tabs/tab";
 import { flagHardcodedTokens, formatTokenHints } from "./token-lint";
@@ -37,12 +37,28 @@ export type RenderVerdict = { ok: true } | { ok: false; error: string };
  */
 export type CandidateDocument = JxMutableNode | JsonValue;
 
+/** Where a document under a render check lives: what its route and relative references resolve from. */
+export interface RenderSource {
+  /** Its project-relative path, once it has one. */
+  documentPath?: string | null | undefined;
+  /** A format-class page's frontmatter, which is where its `$paths` is. */
+  frontmatter?: Record<string, JxDocumentValue | undefined> | null | undefined;
+}
+
+/** A detached-DOM render probe. */
+export type RenderProbe = (doc: CandidateDocument, source?: RenderSource) => Promise<RenderVerdict>;
+
+/** Where an open tab's document lives, as a render check reads it. */
+function renderSourceOf(tab: Tab): RenderSource {
+  return { documentPath: tab.documentPath, frontmatter: tab.doc.content.frontmatter };
+}
+
 /** What a write reporter needs. Every member is what `registerAiTools` already takes by injection. */
 export interface WriteReportDeps {
   /** Schema errors for a document, as raw ajv sentences. */
   validate: (doc: CandidateDocument) => Promise<string[]>;
   /** The detached-DOM render probe, when the host has one. */
-  renderCheck?: ((doc: CandidateDocument) => Promise<RenderVerdict>) | undefined;
+  renderCheck?: RenderProbe | undefined;
   /** The project's design tokens, read per call so a project opened mid-session contributes. */
   getProjectStyle?: (() => Record<string, string> | undefined) | undefined;
 }
@@ -122,7 +138,9 @@ export function translateValidationError(rawError: string): string {
 export async function snapshotBeforeWrite(tab: Tab, deps: WriteReportDeps): Promise<WriteSnapshot> {
   const rawBefore = toRaw(tab.doc.document);
   const errors = new Set(await deps.validate(rawBefore));
-  const rendered = deps.renderCheck ? await deps.renderCheck(rawBefore) : { ok: true };
+  const rendered = deps.renderCheck
+    ? await deps.renderCheck(rawBefore, renderSourceOf(tab))
+    : { ok: true };
   return { errors, renderOk: rendered.ok };
 }
 
@@ -159,7 +177,7 @@ export async function reportDocumentWrite(
   }
 
   if (deps.renderCheck && before.renderOk) {
-    const renderResult = await deps.renderCheck(rawAfter);
+    const renderResult = await deps.renderCheck(rawAfter, renderSourceOf(tab));
     if (!renderResult.ok) {
       return {
         success: false,

package/src/services/context-manager.ts

@@ -19,7 +19,8 @@ import {
   toChatMessages,
   toLiveMessages,
 } from "@jxsuite/ai/messages";
-import { isString } from "@jxsuite/schema/guards";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonObject, JsonValue } from "@jxsuite/schema/types";
 import { modelContextWindow } from "./ai-models";
 
 /** How many tool messages {@link pruneOrphanToolMessages} dropped, moved and sealed. */
@@ -161,6 +162,17 @@ function contextTokens(
   chatState: ReturnType<typeof createChatState>,
   systemTokens: number,
 ): number {
+  return (
+    countedTokens(chatState, systemTokens) ??
+    systemTokens + estimateTokens(chatState.toMessagesArray())
+  );
+}
+
+/** The provider's count carried forward to this transcript, when there is one it still covers. */
+function countedTokens(
+  chatState: ReturnType<typeof createChatState>,
+  systemTokens: number,
+): number | null {
   const { usage, messages } = chatState;
   const boundary = usage ? messages[usage.messageCount - 1] : undefined;
   if (usage && boundary && boundary.id === usage.lastMessageId) {
@@ -180,7 +192,7 @@ function contextTokens(
       return reused;
     }
   }
-  return systemTokens + estimateTokens(chatState.toMessagesArray());
+  return null;
 }
 
 /**
@@ -282,6 +294,102 @@ export function trimContext(
   return { estimatedTokens: newTotal, droppedCount };
 }
 
+// ─── Shed ───────────────────────────────────────────────────────────────────
+
+/** What {@link shedToolResults} sheds down to, as a fraction of the window. */
+const SHED_TARGET_FRACTION = 0.6;
+
+/** A result smaller than this is mostly its stub already, and is often an answer worth keeping. */
+const SHED_MIN_CHARS = 1024;
+
+/** What a shed result tells the model. */
+const SHED_NOTE =
+  "This result was removed to save space. Call the tool again if you still need it.";
+
+/** A tool's reply as an object, or an empty one when it is not a result this module can read. */
+function parsedReply(content: string): JsonObject {
+  try {
+    /* SAFETY: JSON.parse without a reviver turns text into nothing but JSON values. */
+    const parsed = JSON.parse(content) as JsonValue;
+    return isJsonObject(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * What is left of a tool's reply once its output is shed: how it ended and what it said it did, so
+ * the model and a restored chip keep the outcome and lose only the bulk.
+ */
+function shedReply(content: string): string {
+  const { success = true, summary, error } = parsedReply(content);
+  return JSON.stringify({ success, summary, error, shed: SHED_NOTE });
+}
+
+/**
+ * Keep a turn inside the model's window between its rounds (specs/ai.md §3.8).
+ *
+ * {@link trimContext} runs when a message is sent, so nothing else bounds what one turn's own tool
+ * results add, and a turn with room to work could fill the window and have its request refused.
+ * Past the same budget the trim uses, this replaces the oldest large tool results with a stub until
+ * the context is back under {@link SHED_TARGET_FRACTION}. The results of the latest round are never
+ * touched, because the model has not read them yet, and the pairs are never broken, because only a
+ * reply's content changes.
+ *
+ * It changes the transcript rather than one request, so a shed result stays shed: the next send
+ * measures what it will really send, and the provider's prompt cache breaks once for a whole batch
+ * rather than on every round after the budget is reached.
+ *
+ * @param {ReturnType<typeof createChatState>} chatState
+ * @param {string} systemPrompt
+ * @returns {number} How many results it shed.
+ */
+export function shedToolResults(
+  chatState: ReturnType<typeof createChatState>,
+  systemPrompt: string,
+): number {
+  const window = contextWindowFor(chatState.model);
+  const systemTokens = estimateTokens(systemPrompt);
+  const { messages } = chatState;
+  let total =
+    countedTokens(chatState, systemTokens) ??
+    systemTokens + estimateTokens(messages.map((message) => wireEntry(message)));
+  if (total <= Math.floor(window * BUDGET_FRACTION)) {
+    return 0;
+  }
+  const target = Math.floor(window * SHED_TARGET_FRACTION);
+  /* The latest round is the trailing run of replies, with the placeholder of the round about to
+     stream after it when there is one. */
+  let latest = messages.length;
+  while (
+    latest > 0 &&
+    messages[latest - 1]!.role === "assistant" &&
+    !messages[latest - 1]!.toolCalls
+  ) {
+    latest -= 1;
+  }
+  while (latest > 0 && messages[latest - 1]!.role === "tool") {
+    latest -= 1;
+  }
+  let shed = 0;
+  for (let i = 0; i < latest && total > target; i++) {
+    const message = messages[i]!;
+    if (message.role === "tool" && message.content.length >= SHED_MIN_CHARS) {
+      const before = estimateTokens(message.content);
+      message.content = shedReply(message.content);
+      total -= before - estimateTokens(message.content);
+      shed += 1;
+    }
+  }
+  if (shed > 0) {
+    // The provider counted the longer transcript; the estimate is all there is until it next counts.
+    chatState.clearUsage();
+    chatState.setTokenCount(total);
+    chatState.setContextWarning(true);
+  }
+  return shed;
+}
+
 // ─── Orphaned tool calls ────────────────────────────────────────────────────
 
 /**

package/src/services/document-assistant.ts

@@ -38,7 +38,7 @@ import { getAiProvider, getBaseUrl, getOpenAiKey } from "./ai-settings";
 import { preferredModel } from "./ai-models";
 import { pruneOrphanToolMessages, trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
-import type { CandidateDocument, RenderVerdict } from "./ai-write-report";
+import type { RenderProbe } from "./ai-write-report";
 import { validateDoc } from "./jx-validate";
 import { reloadFileInTab } from "../files/files";
 import { getExtensionCatalog, refreshExtensionUi } from "../format/format-host";
@@ -68,7 +68,7 @@ function projectConfig(): ProjectConfig | null {
 /* SAFETY: renderCheck runs the whole render inside a try and answers `{ ok: false, error }` for
    anything it cannot render, so JSON that is not (yet) a valid document is exactly what it is safe
    to hand; its JxDocument parameter names what renders, not what may be probed. */
-const probeRender = renderCheck as (doc: CandidateDocument) => Promise<RenderVerdict>;
+const probeRender = renderCheck as RenderProbe;
 
 /**
  * Create a document-assistant session bound to the currently active tab.

package/src/services/harness/chat-reducer.ts

@@ -39,10 +39,15 @@ export function isImportProgressEvent(value: unknown): value is ImportProgressEv
 function applyOutcome(chat: ChatStore, outcome: TurnOutcome): void {
   switch (outcome.kind) {
     case "cap_partial": {
-      // A partial success is said as the assistant, not as a failure (specs/ai.md §3.2).
-      chat.beginAssistantTurn();
-      chat.appendDelta(outcome.cap?.text ?? "");
-      chat.finishStream("length");
+      /* The model's closing reply has already been drawn, and there is nothing to add. Otherwise a
+         partial success is said as the assistant, not as a failure (specs/ai.md §3.2), after
+         removing whatever the closing round that gave no reply left behind. */
+      if (outcome.cap) {
+        chat.cancelStream();
+        chat.beginAssistantTurn();
+        chat.appendDelta(outcome.cap.text);
+        chat.finishStream("length");
+      }
       break;
     }
     case "cap_failed":