refactor(workspaces): simplify extraction and report readiness

src/features/workspaces/content/workspace-content-contract.ts

@@ -8,6 +8,8 @@ const workspacePathSchema = z.string().min(1);
 
 const readWorkspaceItemsFailureCodes = [
 	"content_changed",
+	"extraction_failed",
+	"extraction_stalled",
 	"invalid_cursor",
 	"invalid_selection",
 	"page_range_out_of_range",
@@ -93,22 +95,48 @@ const workspaceContentReadResultSchema = z.union([
 	z.object({
 		assetKind: workspaceFileAssetKindSchema,
 		content: z.string(),
+		emptyPages: z
+			.array(z.number().int().min(1))
+			.optional()
+			.describe(
+				"Returned pages that extracted no text. Expect these to fill in later while provisional is true.",
+			),
 		format: z.literal("markdown"),
 		itemId: z.string().min(1),
 		location: workspaceReadPagesSchema.extend({ kind: z.literal("pages") }),
 		nextCursor: z.string().optional(),
 		path: workspacePathSchema,
+		provisional: z
+			.boolean()
+			.optional()
+			.describe(
+				"True when this content came from the fast extraction pass and a higher-quality pass is still running.",
+			),
 		relations: workspaceReadRelationsSchema.optional(),
 		status: z.literal("ready"),
 		type: z.literal("file"),
 	}),
 	z.object({
+		elapsedSeconds: z
+			.number()
+			.int()
+			.nonnegative()
+			.describe("How long extraction has been running."),
 		path: workspacePathSchema,
+		phase: z
+			.enum(["queued", "extracting"])
+			.describe("Whether extraction has started yet for this file."),
+		retryAfterSeconds: z
+			.number()
+			.int()
+			.positive()
+			.describe("Suggested wait before reading this path again."),
 		status: z.literal("pending"),
 		type: z.literal("file"),
 	}),
 	z.object({
 		code: z.enum(readWorkspaceItemsFailureCodes),
+		message: z.string().optional().describe("Why extraction failed, when known."),
 		path: workspacePathSchema,
 		status: z.literal("failed"),
 		type: z.literal("file").optional(),

src/features/workspaces/content/workspace-content-reader.ts

@@ -8,6 +8,10 @@ import type {
 	DocumentMarkdownChunkReadResult,
 } from "#/features/workspaces/documents/document-markdown-chunk";
 import { readWorkspacePageProjection } from "#/features/workspaces/extraction/workspace-page-projection";
+import {
+	resolveWorkspaceProjectionReadiness,
+	type WorkspaceProjectionReadiness,
+} from "#/features/workspaces/extraction/workspace-projection-readiness";
 import type { WorkspaceKernelClient } from "#/features/workspaces/kernel/workspace-kernel-access";
 import { resolveWorkspaceFileTypeFromItem } from "#/features/workspaces/model/workspace-file";
 import { serializeWorkspaceRelations } from "#/features/workspaces/operations/relations";
@@ -190,24 +194,12 @@ async function readFile(input: {
 		return { code: "unsupported_item_type", path: input.path, status: "failed" };
 	}
 
-	const projection = await input.kernel.readFileProjection({
-		itemId: input.item.id,
-		format: "pages",
-	});
-	if (
-		!projection ||
-		projection.status === "not_started" ||
-		projection.status === "queued" ||
-		projection.status === "processing"
-	) {
-		return { path: input.path, status: "pending", type: "file" };
-	}
-	if (
-		projection.status !== "ready" ||
-		projection.objectKey === null ||
-		projection.sourceHash === null
-	) {
-		return { code: "projection_failed", path: input.path, status: "failed", type: "file" };
+	const projection = resolveWorkspaceProjectionReadiness(
+		await input.kernel.readFileProjection({ itemId: input.item.id, format: "pages" }),
+		Date.now(),
+	);
+	if (projection.state !== "ready") {
+		return describeUnreadableProjection(projection, input.path);
 	}
 
 	const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
@@ -223,7 +215,7 @@ async function readFile(input: {
 		pageRead = await readWorkspacePageProjection({
 			bucket: input.bucket,
 			expectedSourceHash: projection.sourceHash,
-			manifestObjectKey: projection.objectKey,
+			manifestObjectKey: projection.manifestObjectKey,
 			pages:
 				cursor?.kind === "file"
 					? String(cursor.nextPage)
@@ -241,6 +233,7 @@ async function readFile(input: {
 	return {
 		assetKind: fileType.assetKind,
 		content: pageRead.content,
+		...(pageRead.emptyPages.length > 0 ? { emptyPages: pageRead.emptyPages } : {}),
 		format: "markdown",
 		itemId: input.item.id,
 		location: { kind: "pages", ...pageRead.pages },
@@ -256,11 +249,51 @@ async function readFile(input: {
 					}),
 				}),
 		path: input.path,
+		...(projection.provisional ? { provisional: true } : {}),
 		status: "ready",
 		type: "file",
 	};
 }
 
+/**
+ * Maps a non-ready projection onto the read result the model sees.
+ *
+ * @param projection - Readiness for a projection that is not serving content.
+ * @param path - Absolute workspace path that was read.
+ * @returns The pending or failed read result for that path.
+ */
+function describeUnreadableProjection(
+	projection: Exclude<WorkspaceProjectionReadiness, { state: "ready" }>,
+	path: string,
+): WorkspaceContentReadResult {
+	if (projection.state === "pending") {
+		return {
+			elapsedSeconds: projection.elapsedSeconds,
+			path,
+			phase: projection.phase,
+			retryAfterSeconds: projection.retryAfterSeconds,
+			status: "pending",
+			type: "file",
+		};
+	}
+
+	if (projection.state === "stalled") {
+		return { code: "extraction_stalled", path, status: "failed", type: "file" };
+	}
+
+	if (projection.state === "failed") {
+		return {
+			code: "extraction_failed",
+			...(projection.message ? { message: projection.message } : {}),
+			path,
+			status: "failed",
+			type: "file",
+		};
+	}
+
+	return { code: "projection_failed", path, status: "failed", type: "file" };
+}
+
 async function attachRelationPaths(
 	kernel: WorkspaceKernelClient,
 	readyResults: PendingReadyResult[],

src/features/workspaces/content/workspace-read-references.test.ts

@@ -85,6 +85,89 @@ describe("workspace read references", () => {
 		});
 		expect(modelOutput.results[0]).not.toHaveProperty("pageReferences");
 	});
+
+	it("stays silent when every read succeeded outright", () => {
+		const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
+
+		expect(
+			createWorkspaceReadItemsModelOutput({
+				references: createWorkspaceReadReferences(results),
+				results,
+			}),
+		).not.toHaveProperty("guidance");
+	});
+
+	it("explains a pending read once however many paths are waiting", () => {
+		const results = [
+			{
+				elapsedSeconds: 4,
+				path: "/A.pdf",
+				phase: "extracting",
+				retryAfterSeconds: 15,
+				status: "pending",
+				type: "file",
+			},
+			{
+				elapsedSeconds: 0,
+				path: "/B.pdf",
+				phase: "queued",
+				retryAfterSeconds: 15,
+				status: "pending",
+				type: "file",
+			},
+		] satisfies WorkspaceContentReadResult[];
+		const guidance = createWorkspaceReadItemsModelOutput({ references: [], results }).guidance;
+
+		expect(guidance).toHaveLength(1);
+		expect(guidance?.[0]).toContain("Never sleep");
+	});
+
+	it("separates failures that will never resolve from transient ones", () => {
+		const results = [
+			{ code: "extraction_failed", path: "/A.pdf", status: "failed", type: "file" },
+			{ code: "extraction_stalled", path: "/B.pdf", status: "failed", type: "file" },
+			{ code: "projection_failed", path: "/C.pdf", status: "failed", type: "file" },
+		] satisfies WorkspaceContentReadResult[];
+		const guidance = createWorkspaceReadItemsModelOutput({ references: [], results }).guidance;
+
+		expect(guidance).toHaveLength(2);
+		expect(guidance?.[0]).toContain("do not suggest re-uploading");
+		expect(guidance?.[1]).toContain("One repeat read is reasonable");
+	});
+
+	it("says nothing about failures that are the caller's own mistake", () => {
+		const results = [
+			{ code: "path_not_found", path: "/Missing.pdf", status: "failed" },
+		] satisfies WorkspaceContentReadResult[];
+
+		expect(createWorkspaceReadItemsModelOutput({ references: [], results })).not.toHaveProperty(
+			"guidance",
+		);
+	});
+
+	it("warns that blank pages from the fast pass are not final", () => {
+		const results = [
+			{ ...fileResult(), emptyPages: [13], provisional: true },
+		] satisfies WorkspaceContentReadResult[];
+		const guidance = createWorkspaceReadItemsModelOutput({
+			references: createWorkspaceReadReferences(results),
+			results,
+		}).guidance;
+
+		expect(guidance).toHaveLength(1);
+		expect(guidance?.[0]).toContain("still extracting");
+	});
+
+	it("stays silent about blank pages on a final, non-provisional read", () => {
+		const results = [{ ...fileResult(), emptyPages: [13] }] satisfies WorkspaceContentReadResult[];
+
+		expect(
+			createWorkspaceReadItemsModelOutput({
+				references: createWorkspaceReadReferences(results),
+				results,
+			}),
+		).not.toHaveProperty("guidance");
+	});
 });
 
 function documentResult(): Extract<

src/features/workspaces/content/workspace-read-references.ts

@@ -51,12 +51,70 @@ export function createWorkspaceReadReferences(
 	return createWorkspaceReferenceRecords(locations);
 }
 
+/**
+ * Guidance for read outcomes the model has to react to, keyed by situation.
+ *
+ * These live here rather than in the tool description because none of them
+ * change how a read is issued, and background extraction states are rare enough
+ * that every request should not carry the instructions for handling them.
+ */
+const workspaceReadGuidance = {
+	pending:
+		"Some paths are still extracting. Never sleep, poll, or otherwise stall waiting for them, including inside compute, sandbox_bash, or orchestrate. Either do other work and read those paths again later in this reply, or tell the user they are still processing and to ask again in about retryAfterSeconds. Never read the same pending path more than twice in one reply.",
+	unrecoverable:
+		"Extraction will not finish for some paths. Report the code and any message to the user; do not retry those reads and do not suggest re-uploading the file.",
+	transient:
+		"Some paths failed on a transient storage problem. One repeat read is reasonable; if it fails again, tell the user.",
+	provisional:
+		"Some content came from a fast first pass. Pages listed in emptyPages are still extracting, so read them again later rather than reporting them as blank.",
+} as const;
+
+/**
+ * Collects the handling guidance a set of read results calls for.
+ *
+ * Emitted once per situation rather than once per result so a batch of pending
+ * reads does not repeat the same paragraph for every path.
+ *
+ * @param results - Ordered workspace read results.
+ * @returns Guidance lines for the situations present, most actionable first.
+ */
+function createWorkspaceReadGuidance(results: readonly WorkspaceContentReadResult[]): string[] {
+	const situations = new Set<keyof typeof workspaceReadGuidance>();
+
+	for (const result of results) {
+		if (result.status === "pending") {
+			situations.add("pending");
+			continue;
+		}
+
+		if (result.status === "failed") {
+			if (result.code === "extraction_failed" || result.code === "extraction_stalled") {
+				situations.add("unrecoverable");
+			} else if (result.code === "projection_failed") {
+				situations.add("transient");
+			}
+			continue;
+		}
+
+		// Gate on provisional only: emptyPages on a final (non-provisional) read
+		// describes genuinely blank pages, which must not be reported as still
+		// extracting or the model retries a completed read forever.
+		if (result.type === "file" && result.provisional) {
+			situations.add("provisional");
+		}
+	}
+
+	return (Object.keys(workspaceReadGuidance) as Array<keyof typeof workspaceReadGuidance>)
+		.filter((situation) => situations.has(situation))
+		.map((situation) => workspaceReadGuidance[situation]);
+}
+
 /**
  * Projects a rich workspace read result into compact model-visible JSON.
  *
  * Raw item IDs and durable locations remain in the persisted tool result.
  * Model-visible content receives only opaque refs next to the content they
- * identify.
+ * identify, plus guidance for any outcome that needs handling.
  *
  * @param output - Validated rich workspace read output.
  * @returns JSON-safe results annotated with short workspace refs.
@@ -65,8 +123,10 @@ export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOu
 	const refsByLocation = new Map(
 		output.references.map((record) => [getWorkspaceLocationKey(record.location), record.ref]),
 	);
+	const guidance = createWorkspaceReadGuidance(output.results);
 
 	return {
+		...(guidance.length > 0 ? { guidance } : {}),
 		results: output.results.map((result) => {
 			if (result.status !== "ready") {
 				return result;