bunnyquery 1.8.6 → 1.8.9

package/src/engine/index.ts

@@ -43,7 +43,7 @@ export * from './prompts';
 
 // Pure helpers (Tier-1.5): error detection, token budgeting, link/path
 // normalization, and history mapping — shared so both consumers stay identical.
-export { getErrorMessage, isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError } from './errors';
+export { getErrorMessage, isErrorResponseBody, isAuthExpiredError, isNonRetryableRequestError, isProviderApiKeyError } from './errors';
 export * from './budget';
 // Per-format UTF-8 declaration for files offered as a download. Shared so a fenced
 // block and a server-published file open identically in Excel, Word and a browser.
@@ -64,6 +64,12 @@ export {
 	// read it the same way or the two will not group together.
 	isIndexingRequestText,
 	parseIndexingRequestText,
+	// One bounded look at the bg-indexing queue: which files still have a live
+	// pass. The dbfile browser's "indexed" badge uses this so a file only goes
+	// green once the run is confirmed over, not when its src:: record appears.
+	fetchLiveIndexingKeys,
+	getSplitChatHistory,
+	__resetSplitHistoryState,
 	type IndexingRequestRef,
 	type MapHistoryOptions,
 } from './history';
@@ -94,6 +100,8 @@ export {
 	type IndexingGroup,
 	type IndexingGroupStatus,
 	type BuildDisplayListOptions,
+	type RunStubInfo,
+	RUN_RECORD_WORKING_STALE_MS,
 } from './indexing_groups';
 
 export {
@@ -105,6 +113,11 @@ export {
 	BG_INDEXING_QUEUE_SUFFIX,
 	bgIndexingQueueName,
 	isBgIndexingQueue,
+	indexDoneUniqueId,
+	runIndexUniqueId,
+	upsertIndexRunRecordSafe,
+	type IndexRunStatus,
+	type IndexRunPatch,
 	MCP_NAME,
 	DEFAULT_CLAUDE_MODEL,
 	DEFAULT_OPENAI_MODEL,
@@ -116,6 +129,7 @@ export {
 	listClaudeModels,
 	listOpenAIModels,
 	getChatHistory,
+	buildHistoryItemFullId,
 	// response extraction
 	extractClaudeText,
 	extractOpenAIText,

package/src/engine/indexing_groups.ts

@@ -198,6 +198,15 @@ export type IndexingGroup = {
 	 *  loaded ones. 'status': the queue has not yet said whether this file is still
 	 *  being worked on, which is the only thing that can end a worker-driven run. */
 	resolvingReason?: 'history' | 'status';
+	/** Synthesized from a durable run:: record: none of the run's passes are
+	 *  among the loaded messages (bg history still deferred, or the run is older
+	 *  than the paging cap). Header-and-status only — members/visibleMembers are
+	 *  empty and there is nothing to cancel; the row is replaced by the real
+	 *  group the moment actual passes load (same `key`, so expansion state
+	 *  carries over). */
+	stub?: boolean;
+	/** The run:: record's stored error text, for a stub row's meta line. */
+	stubError?: string;
 };
 
 export type DisplayEntry =
@@ -222,6 +231,14 @@ export type BuildDisplayListOptions = {
 	/** Whether `liveIndexKeys` has been answered at least once for this chat. False
 	 *  is "we do not know", and a worker-driven run stays unfinished on it. */
 	liveIndexChecked?: boolean;
+	/** Files carrying the durable done:: completion marker (one prefix sweep),
+	 *  keyed like IndexingGroup.key (storage path; the bare-name fallback keys
+	 *  of very old prompts simply never match — they keep the queue inference).
+	 *  A marker is PROOF the file was read to the end: it settles a worker-run
+	 *  green without waiting for the queue answer, and it is never withheld by
+	 *  the resolving logic. A live queue hit still outranks it (a re-index in
+	 *  flight whose marker-cascade delete lagged). */
+	doneKeys?: { [fileKey: string]: boolean };
 	/** Server item ids of passes that were on a row when the user STOPPED it
 	 *  (ChatSession.state.stoppedIndexIds). A run holding any of them is a run the
 	 *  user stopped — see the status derivation for why a stop usually leaves no
@@ -232,8 +249,52 @@ export type BuildDisplayListOptions = {
 	 *  windowedIndexing). Passed in rather than read from config so this stays a
 	 *  pure function of its inputs and can be exercised for both settings. */
 	windowedIndexing?: boolean;
+	/** Durable run:: records, keyed by STORAGE PATH (the consumer's marker
+	 *  sweep). Each key with no real group in the loaded messages gets a
+	 *  synthesized header-only row (see IndexingGroup.stub), placed by its
+	 *  `started` timestamp. A real group for the same file — matched by key,
+	 *  path, or name — always suppresses the stub: loaded passes are evidence,
+	 *  the record is only a summary. */
+	runStubs?: { [storagePath: string]: RunStubInfo };
+	/** The platform whose chat this list is for. run:: records are per-FILE,
+	 *  but a chat is per (project, platform): a run started under Claude has
+	 *  its passes in the Claude conversation and is invisible to the
+	 *  OpenAI-scoped queue probe, so its stub could never be covered and never
+	 *  be confirmed — it just sat there, in a chat it did not belong to.
+	 *  Records minted before this was stamped carry no platform and are shown
+	 *  in both, which keeps the leak to the historical set. */
+	stubPlatform?: 'claude' | 'openai';
+	/** The chat's clear-history horizon (ms epoch). Run records are service-
+	 *  wide and know nothing about a cleared chat, so without this every
+	 *  "Clear chat history" resurrects one row per indexed file. A stub whose
+	 *  run ended (or, unfinished, began) at or before this moment is dropped —
+	 *  unless the queue says the file is live RIGHT NOW, which no horizon can
+	 *  make untrue. */
+	stubClearedAt?: number;
+	/** Clock injection for tests; defaults to Date.now(). Only run-stub
+	 *  staleness reads it. */
+	now?: number;
 };
 
+/** The display-relevant fields of a run:: record (see requests.ts
+ *  runIndexUniqueId for the record's contract). */
+export type RunStubInfo = {
+	status: 'working' | 'done' | 'error' | 'cancelled';
+	filename?: string;
+	started?: number;
+	finished?: number;
+	error?: string;
+	/** Chat that owns this run. Absent on records minted before it was
+	 *  stamped; see BuildDisplayListOptions.stubPlatform. */
+	platform?: 'claude' | 'openai';
+};
+
+/** A 'working' run record older than this with no live-queue confirmation is
+ *  treated as unknown rather than live: a chain that died without reaching any
+ *  error path leaves 'working' dangling, and a row must not spin forever on a
+ *  claim nothing can end. */
+export const RUN_RECORD_WORKING_STALE_MS = 6 * 60 * 60 * 1000;
+
 // The indexing label is view-formatted (formatIndexingLabel), so parsing it is
 // the FALLBACK path only: it exists for bubbles restored from a history cache
 // written before `_indexFile` was stamped. Live and freshly-mapped bubbles carry
@@ -324,12 +385,14 @@ export function buildChatDisplayList(
 	var list = Array.isArray(messages) ? messages : [];
 	var liveIndexKeys = (opts && opts.liveIndexKeys) || {};
 	var liveIndexChecked = !!(opts && opts.liveIndexChecked);
+	var doneKeys = (opts && opts.doneKeys) || {};
 	var stoppedIndexIds = (opts && opts.stoppedIndexIds) || {};
 	var windowedIndexing = opts && opts.windowedIndexing !== undefined
 		? !!opts.windowedIndexing
 		: windowedIndexingEnabled();
 	var hasMoreHistory = !!(opts && opts.hasMoreHistory);
 	var loadingOlderHistory = !!(opts && opts.loadingOlderHistory);
+	var stubPlatform = opts && opts.stubPlatform;
 
 	// One entry per RUN (see IndexingGroup.runKey), addressed by an internal id
 	// while the list is being walked; runKey is assigned at the end, once the
@@ -629,7 +692,13 @@ export function buildChatDisplayList(
 			// permanently false and the two tests below were already carrying the whole
 			// decision. It is gone rather than left as a hook, so this reads as what it
 			// actually is: for a worker-driven run, ONLY the queue can say it is over.
+			// The done:: marker is the third — and strongest — disjunct: written
+			// only at a chain's true end (backend worker, or a client's own
+			// deterministic completion), it answers without any queue round
+			// trip. Gated on the queue NOT claiming the file live, so a
+			// re-index whose marker-cascade delete lagged still shows yellow.
 			grp.finished = !newestRunOfKey[order[oi]] ||
+				(!!doneKeys[grp.key] && !liveIndexKeys[grp.key]) ||
 				(liveIndexChecked && !liveIndexKeys[grp.key]);
 		}
 
@@ -645,7 +714,7 @@ export function buildChatDisplayList(
 			// newest pass's own outcome, and newest-first paging always has that pass.
 			grp.resolving = false;
 		} else if (grp.mayHaveOlder && loadingOlderHistory &&
-			!liveIndexKeys[grp.key] && newestRunOfKey[order[oi]]) {
+			!liveIndexKeys[grp.key] && !doneKeys[grp.key] && newestRunOfKey[order[oi]]) {
 			// The line this draws, and it is the same line the 'status' branch draws:
 			// withhold what is UNKNOWN, and what is only INFERRED settled. Never
 			// withhold what is PROVEN, in either direction. Two proofs, and an older
@@ -692,15 +761,191 @@ export function buildChatDisplayList(
 		}
 	}
 
+	// --- durable run:: stubs ---------------------------------------------------
+	// A run record whose passes are not among the loaded messages still deserves
+	// a row: on a fresh open the bg history is deferred, and a run older than the
+	// paging cap never loads at all. Synthesized as header-only groups and placed
+	// by `started` among the messages' own timestamps; a real group for the same
+	// file always wins (see BuildDisplayListOptions.runStubs).
+	var stubList: { started: number; group: IndexingGroup }[] = [];
+	var runStubs = opts && opts.runStubs;
+	if (runStubs) {
+		// Two namespaces, deliberately NOT one map: storage paths are
+		// project-relative and folder trees repeat basenames routinely, so a
+		// flat map let a real group for "2025/report.pdf" delete the stub for
+		// "2026/report.pdf" with nothing replacing it. A bare NAME only covers
+		// a stub when the group itself has no path (the legacy compact-label
+		// case) and the record has no filename of its own to disambiguate.
+		var coveredPaths: { [k: string]: boolean } = {};
+		var coveredPathlessNames: { [k: string]: boolean } = {};
+		for (var ci = 0; ci < order.length; ci++) {
+			var cg = groups[order[ci]];
+			if (cg.path) { coveredPaths[cg.path] = true; if (cg.key) coveredPaths[cg.key] = true; }
+			else if (cg.name) coveredPathlessNames[cg.name] = true;
+			else if (cg.key) coveredPaths[cg.key] = true;
+		}
+		var now = opts && typeof opts.now === 'number' ? opts.now : Date.now();
+		var stubClearedAt = (opts && typeof opts.stubClearedAt === 'number' && opts.stubClearedAt > 0)
+			? opts.stubClearedAt : 0;
+		for (var sp in runStubs) {
+			var rec = runStubs[sp];
+			if (!sp || !rec || !rec.status || coveredPaths[sp]) continue;
+			var fname = rec.filename || sp.split('/').pop() || sp;
+			// A PATHLESS group (legacy compact label) can only be matched by
+			// name, and that is still the right match: the file already has a
+			// row, so suppressing avoids a duplicate rather than creating a
+			// void. What is gone is the reverse — a group WITH a path no longer
+			// writes into the name namespace, so it can no longer delete a
+			// same-basename stub from another folder.
+			if (coveredPathlessNames[fname]) continue;
+			// A run recorded under the OTHER platform's chat belongs to that
+			// conversation: its passes live in that history (so no real group
+			// can ever cover this stub) and the queue probe is platform-scoped
+			// (so it can never confirm it). Records with no platform are
+			// legacy and keep the old behaviour rather than vanishing.
+			if (stubPlatform && rec.platform && rec.platform !== stubPlatform) continue;
+			// Mirrors the real groups' status precedence: a live queue hit outranks
+			// whatever the record says (a lagged update must not paint a verdict over
+			// visible work), then the record's own terminal statuses, then the
+			// queue's authoritative ABSENCE, and only then the stated wait.
+			var live = !!liveIndexKeys[sp] || !!liveIndexKeys[fname];
+			// Cleared-history horizon: a run that ended at or before the clear is
+			// part of what the user asked to forget. A live queue hit survives it
+			// (see BuildDisplayListOptions.stubClearedAt). A record carrying NO
+			// timestamp at all is unplaceable, not old — the horizon cannot judge
+			// it, so it is never dropped by one.
+			var recWhen = typeof rec.finished === 'number' ? rec.finished
+				: typeof rec.started === 'number' ? rec.started : undefined;
+			if (stubClearedAt && !live && recWhen !== undefined && recWhen <= stubClearedAt) continue;
+			var st: IndexingGroupStatus = 'active';
+			var fin = false;
+			var res = false;
+			var reason: 'history' | 'status' | undefined;
+			if (!live) {
+				// A done:: marker from the same sweep is as terminal as the record's
+				// own 'done' — it settles a dangling 'working' the chain never
+				// flipped (mirrors the real-group doneKeys disjunct).
+				if (rec.status === 'done' || doneKeys[sp] || doneKeys[fname]) { st = 'done'; fin = true; }
+				else if (rec.status === 'error') { st = 'error'; fin = true; }
+				else if (rec.status === 'cancelled') { st = 'cancelled'; fin = true; }
+				else if (liveIndexChecked) {
+					// 'working' is a CLAIM. The queue has now answered, untruncated,
+					// and holds nothing for this file — the same proof the real-group
+					// ladder settles on. Without this disjunct a stub had no
+					// terminator at all: worker-driven runs are never flipped by this
+					// client, so the row sat grey forever (the reported "checking
+					// status that never resolves").
+					st = 'done'; fin = true;
+				} else if (typeof rec.started === 'number' && now - rec.started > RUN_RECORD_WORKING_STALE_MS) {
+					// Older than any real run and still unconfirmed: a dead claim, not
+					// an open question. Same horizon the files page applies.
+					st = 'error'; fin = true;
+				} else {
+					// Genuinely unanswered — the queue reply is one round trip away
+					// and this self-heals the moment it lands.
+					res = true; reason = 'status';
+				}
+			}
+			var sg: IndexingGroup = {
+				key: sp,
+				// ONE identity for the run whether it renders from the record or
+				// from its loaded passes: the views key the DOM off runKey, so a
+				// 'stub:'-prefixed key meant every handoff was an unmount plus a
+				// remount somewhere else. Named after the record's start, which
+				// the real group below reuses when it has one.
+				runKey: 'run:' + sp + '#' + (typeof rec.started === 'number' ? rec.started : 'n'),
+				name: fname,
+				path: sp,
+				mime: undefined,
+				size: undefined,
+				isReindex: false,
+				members: [],
+				passCount: 0,
+				status: st,
+				cancellableIds: [],
+				cancelling: false,
+				stopped: st === 'cancelled',
+				mayHaveOlder: hasMoreHistory,
+				anchorIndex: -1,
+				anchorId: '',
+				visibleMembers: [],
+				driver: !isPagedReadFile(fname, undefined) ? 'single'
+					: isImageVisionFile(fname, undefined) ? 'worker'
+						: (windowedIndexing ? 'worker' : 'client'),
+				finished: fin,
+				resolving: res,
+				resolvingReason: reason,
+				stub: true,
+				stubError: rec.error || (st === 'error' && !rec.error
+					? 'Indexing did not finish.' : undefined),
+			};
+			// A record with no `started` cannot be placed in the conversation.
+			// Infinity sorts it to the END (nearest the newest turns) instead of
+			// above every message the user has ever sent — the row is about
+			// something recent, not about the beginning of time.
+			stubList.push({ started: typeof rec.started === 'number' ? rec.started : Infinity, group: sg });
+		}
+	}
+
+	// --- timestamp-anchor INCOMPLETE real runs ---------------------------------
+	// A real run's row renders at its first LOADED pass, and while older history
+	// pages in (newest-first) that is a moving target: the run first appears at
+	// its newest pass — down by the recent bubbles — then relocates upward as
+	// earlier passes arrive, so the row visibly jumps. The run:: record's
+	// `started` is a stable anchor for exactly that window: emit the row at its
+	// timestamp position instead, and once the true first pass loads
+	// (mayHaveOlder false) emission returns to the anchor, which by then IS the
+	// same spot. Newest run of the file only — the record describes it, and an
+	// older run's passes are already fully placed around it.
+	//
+	// NOT gated on mayHaveOlder: that made the position depend on WHICH passes
+	// happened to be loaded, so a row moved when the sweep resolved, again when
+	// the first pass paged in, and again when paging ended. A record with a
+	// `started` places the run at ONE spot for as long as the record exists.
+	var suppressAnchor: { [runId: string]: boolean } = {};
+	if (runStubs) {
+		for (var ti2 = 0; ti2 < order.length; ti2++) {
+			var tg = groups[order[ti2]];
+			if (!newestRunOfKey[order[ti2]]) continue;
+			var trec = (tg.path && runStubs[tg.path]) || runStubs[tg.key];
+			if (!trec || typeof trec.started !== 'number') continue;
+			if (stubPlatform && trec.platform && trec.platform !== stubPlatform) continue;
+			suppressAnchor[order[ti2]] = true;
+			// Same identity the stub form uses, so a row that upgrades from
+			// record-only to loaded-passes keeps its DOM node and its position.
+			tg.runKey = 'run:' + (tg.path || tg.key) + '#' + trec.started;
+			stubList.push({ started: trec.started, group: tg });
+		}
+	}
+	stubList.sort(function (a, b) { return a.started - b.started; });
+
 	var out: DisplayEntry[] = [];
+	var si = 0;
 	for (var j = 0; j < list.length; j++) {
+		// Splice stubs in by time: everything that started before this message
+		// goes above it. Messages without a timestamp decide nothing.
+		var mts = list[j] && typeof list[j]._ts === 'number' ? (list[j]._ts as number) : undefined;
+		if (mts !== undefined) {
+			while (si < stubList.length && stubList[si].started <= mts) {
+				out.push({ kind: 'indexing', group: stubList[si].group, index: -1 - si });
+				si++;
+			}
+		}
 		var r = runOfIndex[j];
 		if (r === undefined) {
 			out.push({ kind: 'message', msg: list[j], index: j });
 			continue;
 		}
-		// Every other member of the run is represented by the row at the anchor.
-		if (groups[r].anchorIndex === j) out.push({ kind: 'indexing', group: groups[r], index: j });
+		// Every other member of the run is represented by the row at the anchor —
+		// unless the row is timestamp-anchored (incomplete run with a run::
+		// record), in which case the flush above already emitted it.
+		if (groups[r].anchorIndex === j && !suppressAnchor[r]) {
+			out.push({ kind: 'indexing', group: groups[r], index: j });
+		}
+	}
+	while (si < stubList.length) {
+		out.push({ kind: 'indexing', group: stubList[si].group, index: -1 - si });
+		si++;
 	}
 	return out;
 }

package/src/engine/links.ts

@@ -21,6 +21,24 @@ export var LINK_LABEL_MAX_DISPLAY_CHARS = 32;
  */
 export var EXPIRED_LINK_REFRESH_EXPIRES_SECONDS = 20 * 60;
 
+/**
+ * Lifetime of the url minted for an inline image PREVIEW.
+ *
+ * Longer than the click url above, and for a different reason. A click hands the
+ * user a url they may keep, so it stays short. A preview url is consumed by the
+ * page itself and never leaves it, and it is the ONE lever on how long the
+ * downloaded picture stays reusable: get_signed_url will not cache a mint for
+ * longer than the credential inside it survives, so `browser_cache` cannot buy
+ * local availability that `expires` has not paid for. Twenty minutes meant every
+ * image re-downloaded three times an hour of ordinary reading.
+ *
+ * An hour, giving 55 minutes of cache once the server's five minute headroom is
+ * taken off. Short enough that a leaked preview url is not a standing grant, long
+ * enough that a conversation does not re-fetch its own pictures while the user is
+ * still reading it.
+ */
+export var PREVIEW_URL_EXPIRES_SECONDS = 60 * 60;
+
 /**
  * Seconds the browser may reuse a minted preview url (`browser_cache`).
  *
@@ -30,12 +48,17 @@ export var EXPIRED_LINK_REFRESH_EXPIRES_SECONDS = 20 * 60;
  * url comes back out of the browser cache, so the body already on disk stays
  * addressable.
  *
- * Deliberately far longer than EXPIRED_LINK_REFRESH_EXPIRES_SECONDS above, and
- * that is the whole trick: the url is short-lived while the file stays available
- * locally for a WEEK. What keeps an image painting is the cached BODY, not a live
- * url. Once the browser evicts that body it refetches with a url that has since
- * expired, gets a 403, and the error path re-mints with `refresh`. That path is
- * therefore load-bearing, not a rare fallback.
+ * A CEILING, not a promise. get_signed_url caps what it grants at the lifetime of
+ * the url inside the response (expires minus headroom, so 15 minutes for the
+ * platform's 20 minute url), because a mint cached for longer than its own
+ * credential is a guaranteed 403 that the browser keeps serving from its own
+ * store. Asking for the week is still right: it says what this client would
+ * reuse if the url were stable by construction, and the server decides.
+ *
+ * What keeps an image painting is the cached BODY, not a live url. Once the
+ * browser evicts that body it refetches with a url that has since expired, gets a
+ * 403, and the error path re-mints with `refresh` and mintCacheBustStamp. That
+ * path is load-bearing, not a rare fallback.
  *
  * A week is the platform default for reading a private file, not a number chosen
  * here: skapi-js reads every private record file with
@@ -60,6 +83,102 @@ export var PREVIEW_BROWSER_CACHE_SECONDS = 7 * 24 * 60 * 60;
  */
 export var LINK_REFRESH_WINDOW_MS = (EXPIRED_LINK_REFRESH_EXPIRES_SECONDS - 5 * 60) * 1000;
 
+/**
+ * Cache generation for the mint request url. BUMP THIS to abandon every mint
+ * response browsers are currently holding.
+ *
+ * Generation 2 retires the entries written before 2026-08-11. Those were stored
+ * with `max-age=604800` around a presign that dies in twenty minutes, so from
+ * minute 21 each one is a guaranteed 403 that the browser keeps serving from its
+ * own store for the rest of the week. The server no longer grants a lifetime a
+ * url cannot back (get_signed_url resolve_browser_cache), but that fixes what is
+ * written from now on and cannot reach what is already stored on a user's
+ * device. Changing the url is the only thing that can: an entry nobody requests
+ * again is an entry that cannot answer again.
+ */
+export var MINT_CACHE_GENERATION = 2;
+
+/**
+ * Window stamp for a REFRESH mint.
+ *
+ * WINDOWED, not Date.now(): a per-call stamp is a new cache key per image per
+ * retry, which is what made the original `nocache` parameter worse than the
+ * disease. One stamp per refresh window means every repair inside those minutes
+ * shares a single entry, and it rotates before the url it carries can die.
+ */
+export function mintCacheBustStamp(now?: number): number {
+	return Math.floor((now == null ? Date.now() : now) / LINK_REFRESH_WINDOW_MS);
+}
+
+/**
+ * The `nocache` value for a preview mint: the generation, plus a window stamp
+ * when this mint is a repair.
+ *
+ * A repair MUST reach the origin, and the request header the clients used to
+ * rely on cannot do it. `Cache-Control: no-cache` is not a CORS-safelisted
+ * request header, and the record gateway's preflight answers
+ * `Access-Control-Allow-Headers` WITHOUT it (verified against the live api on
+ * 2026-08-11), so a mint carrying that header is rejected by the browser before
+ * it is ever sent. Every repair therefore failed, in every browser, and the chip
+ * went straight to "(unavailable)". Only a phone noticed, because only a phone
+ * drops image bodies often enough to need the repair at all.
+ *
+ * A query parameter has no such problem: it is part of the url, so it needs no
+ * preflight and no cooperation from the cache.
+ */
+export function previewMintCacheToken(refresh?: boolean): string {
+	if (!refresh) return String(MINT_CACHE_GENERATION);
+	return MINT_CACHE_GENERATION + '.' + mintCacheBustStamp();
+}
+
+/**
+ * How long before a presign dies we stop handing it out.
+ *
+ * A url served with one second left is a 403 with extra steps: the request still
+ * has to reach S3, and an image body still has to start arriving.
+ */
+export var PRESIGN_SAFETY_MARGIN_MS = 60 * 1000;
+
+/**
+ * When the url in hand actually dies, read out of the url itself, or null if it
+ * carries no expiry we recognise.
+ *
+ * Every client-side cache here ages a url from the moment it ARRIVED, which is
+ * only the same thing as its lifetime when the mint went to the network. Once
+ * mint responses are cacheable that assumption breaks: a mint answered from the
+ * browser's store can be nearly as old as its own max-age, and the client then
+ * adds its own reuse window on top, so a 20 minute credential can be handed to an
+ * <img> half an hour after it was signed. Asking the url when it dies removes the
+ * stacking instead of trying to budget for it.
+ *
+ * Both signature versions, because the platform mints SigV2 through the host
+ * bucket and SigV4 elsewhere.
+ */
+export function presignExpiryEpochMs(url: string): number | null {
+	if (!url) return null;
+	var q = url.indexOf('?');
+	if (q < 0) return null;
+	var params: URLSearchParams;
+	try { params = new URLSearchParams(url.slice(q + 1)); }
+	catch (e) { return null; }
+
+	// SigV2: Expires is an absolute epoch in seconds.
+	var v2 = params.get('Expires');
+	if (v2 && /^\d+$/.test(v2)) return parseInt(v2, 10) * 1000;
+
+	// SigV4: signing time plus a duration.
+	var signed = params.get('X-Amz-Date');
+	var lifetime = params.get('X-Amz-Expires');
+	if (signed && lifetime && /^\d+$/.test(lifetime)) {
+		var m = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(signed);
+		if (m) {
+			var at = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]);
+			return at + parseInt(lifetime, 10) * 1000;
+		}
+	}
+	return null;
+}
+
 // The two "balanced parens" groups match ONE CHARACTER per step, never a `+`
 // run, so each position has exactly one way to be matched: `[^()\n]` cannot
 // start with `(`, and the nested-paren alternative always does. That disjointness
@@ -545,6 +664,24 @@ export function linkUnavailableKeyForHref(href: string): string {
 	return 'href:' + (href || '');
 }
 
+/**
+ * Every key a stored file can be marked under, given only its path.
+ *
+ * Marking writes ONE key (whichever identifier the failing call had) and the
+ * lookup ORs all of them, which is fine in one direction and wrong in the other:
+ * a view that later learns the file is reachable knows only the path, and
+ * clearing `path:` alone leaves a chip greyed by a failed CLICK (which marks
+ * `href:` too) exactly as dead as before. The placeholder href is derived from
+ * the path, so both keys can be rebuilt from it.
+ */
+export function linkUnavailableKeysForPath(remotePath: string): string[] {
+	if (!remotePath) return [];
+	return [
+		linkUnavailableKeyForPath(remotePath),
+		linkUnavailableKeyForHref(buildDisplayExpiredAttachmentHref(remotePath)),
+	];
+}
+
 export function isLinkUnavailable(
 	link: { href?: string; expiredHref?: string; remotePath?: string } | null | undefined,
 	map: Record<string, boolean | undefined> | null | undefined,

package/src/engine/office.ts

@@ -231,7 +231,28 @@ export interface ComposedUserMessage {
 export function composeUserMessage(
 	text: string,
 	attachmentUrls: Array<{ name: string; url: string; storagePath?: string }>,
+	opts?: {
+		/**
+		 * Inline each server-extractable attachment's whole text into the
+		 * prompt (the `_skapi_extract` directives + BEGIN/END FILE CONTENT
+		 * block). Default true, which is right when the file's content is
+		 * nowhere else yet.
+		 *
+		 * Pass FALSE when the turn is dispatched AFTER the file's indexing run
+		 * has drained. Extraction is the same server-side download+parse the
+		 * indexing pass already performed, so inlining repeats it: the worker
+		 * fetches and re-parses every attachment a second time (which reads,
+		 * from the outside, exactly like the file being indexed again), and the
+		 * whole file text is re-sent as prompt tokens. It is also the WORSE
+		 * copy for anything large, because inline extraction truncates at
+		 * MAX_EXTRACTED_CHARS while the indexed records cover the file end to
+		 * end. The model reaches the content through the records
+		 * (getRecords with reference "src::<path>") or readFileContent.
+		 */
+		inlineExtractedContent?: boolean;
+	},
 ): ComposedUserMessage {
+	const inlineExtracted = opts?.inlineExtractedContent !== false;
 	let composed = text;
 	let composedForLlm = composed;
 	if (attachmentUrls.length > 0) {
@@ -242,7 +263,9 @@ export function composeUserMessage(
 	let extractContent: ExtractDirective[] | undefined;
 	let fileUrls: FileUrlDirective[] | undefined;
 	if (attachmentUrls.length > 0) {
-		const extractFiles = attachmentUrls.filter((u) => isServerExtractable(u.name));
+		const extractFiles = inlineExtracted
+			? attachmentUrls.filter((u) => isServerExtractable(u.name))
+			: [];
 		if (extractFiles.length > 0) {
 			const directives: ExtractDirective[] = [];
 			const sections = extractFiles.map((u) => {

package/src/engine/prompts/chat_system_prompt.ts

@@ -31,7 +31,7 @@ Never assert absence from a partial read. Do not say "there is no X", "none", "n
 Embedded values: a search term is often stored inside a larger string. A merchant "GODADDY" appears as "DNH*GODADDY#4070277042", and a card as "4140****2941". Server-side index filters match only exact values, leading prefixes, or trailing suffixes, and tag filters only EXACT whole-tag values - never a partial or interior substring - so filtering on such a field silently drops rows. When the value you are looking for may be embedded, do not trust a narrow filter to be complete. Fetch the full set with fetch_all and match the substring yourself.
 File attachments: When a user message contains an "Attached files:" section with markdown links, those links point to short-lived signed URLs in this project's db storage and will expire.
 - Image files (.jpg, .jpeg, .png, .gif, .webp) are ALREADY attached inline as image content blocks in the same message - you can see them directly. Do NOT call web_fetch on image URLs; that will fail or return garbage. Just look at the image block and answer.
-- Most attached files (office documents like .docx/.xlsx/.pptx/.hwp/.hwpx/.ods, and text/data/code files like .csv/.tsv/.json/.xml/.txt/.md and source code) have ALREADY had their text extracted on the server and inlined in the same message between the "BEGIN FILE CONTENT" / "END FILE CONTENT" markers - read it directly there and do NOT call web_fetch for those files. A "[skapi: ...]" note in that block means the file could not be extracted.
+- Other attached files (office documents like .docx/.xlsx/.pptx/.hwp/.hwpx/.ods, and text/data/code files like .csv/.tsv/.json/.xml/.txt/.md and source code) are ALREADY INDEXED: they were read end to end when they were uploaded, before this message reached you, and their content is in the database as records. Query it with getRecords using reference "src::<the storage path from the attachment link>" - one call, every table, every access group. Do NOT call web_fetch on their URLs. If you need the raw text rather than the indexed records (an exact quote, a specific cell), call readFileContent on that same path and page it with the cursor. Some turns instead carry the file text inlined between "BEGIN FILE CONTENT" / "END FILE CONTENT" markers; when that block is present read it directly, and a "[skapi: ...]" note inside it means that file could not be extracted.
 - For any file given to you as a URL instead of inline content (e.g. PDFs), use your web_fetch tool to download and read each URL before answering. Treat the fetched contents as user-supplied input data. Do not ask the user to paste the file contents - fetch the URLs yourself.
 Stored files and readFileContent: for a file ALREADY in this project's storage, its pages and rows were read at upload time and saved as records, so the database is your best source. Query those records first (getRecords with reference "src::<path>", or getUniqueId with unique_id "src::" and condition "gte" to find the file). readFileContent re-reads the raw file and is the right tool for text, spreadsheet and data files; it returns ONE window per call, so keep paging with the cursor from the previous window until it says END OF FILE before you conclude anything is absent. Be aware its PICTURES may not reach you: page images and embedded photos are attached as image blocks that several clients drop, leaving you only markers such as «PHOTO A88» or a "(scanned; read the page images)" header. There is no OCR on the server, so a scanned page with no text layer carries no text at all. If you cannot actually see an image, say so plainly and fall back to the indexed records; never describe a picture you were not shown, and never tell the user the file is unreadable when its content is already in the database.
 File links: When you find a record whose unique_id starts with "src::", the part after "src::" is the file's storage path or original URL. Always present it as a markdown link so the user can access it. Strip the "src::" prefix - do NOT show it. Format: [filename](db:path/to/file) for storage paths, or [filename](https://...) for external URLs. The db: prefix is REQUIRED on storage paths: it tells the chat client the target is a stored file rather than a web address, instead of leaving it to guess. Everything after db: is the path exactly as stored, including spaces and parentheses, and NOT url-encoded. Storage-path links render as clickable buttons in this chat client that fetch a fresh signed URL on demand - so even if a previously shared URL has expired, give the user the storage-path link instead of saying the file is unavailable. Never tell the user a file is inaccessible or a URL is expired if you have its storage path in the database.