feat(T2b): sources v0 — read tool + pdf-reader sub-agent
Learner source files, on the teacher's own terms (nothing auto-injects): - read tool (src/agent/tools/read.ts): pi-read port — path/offset/limit, 2000-line/50KB truncation with use-offset continuation notices, image files (jpg/png/gif/webp/bmp) returned as native image content parts (new LhToolImageResult escape hatch in lh-tool.ts). Always-on in both the prober and teacher registries (user-decided 2026-09). - pdf-reader sub-agent (JobKind 'pdf', toggleable, ack-and-steer): triage via pdf_info (pdfjs text layer: per-page text/image/math-density), targeted pdf_extract, regex pdf_search (hits count as consultation), and pdf_render — pages painted by pdfjs onto a canvas shim in headless Chrome (the pdfium viewer doesn't paint headless), screenshot fed back image-in-the-loop (visual-maker idiom, providerSafePng applied). The unread-finish gate bounces a zero-consultation brief once. Teacher gets a text brief with page citations only; renders never leave the loop. - MODELS.pdfReader = qwen/qwen3.8-flash (user override 2026-09-19: the look-at-renders workload wants the vision-proven model; catalog listed glm-5.3-flash as image-capable but qwen is the known-good daily driver). - UI: PdfCompleteBadge + PdfBriefCard (steer-card, job-card), dispatch card + activity-dock kind entries (type-forced, flagged for UI review). - Prompts: 'Learner source files' section in teacher/30-jobs.md; read line in prober/10-probe-doctrine.md. Doctrine rides tool descriptions per the self-contained-tools principle.
This commit is contained in:
amosblomqvist
+28
-2
@@ -21,7 +21,7 @@ export interface JobToolContext {
|
||||
/** Fire the background runner for a fresh job — fire-and-forget. The
|
||||
* input rides along because the spawn happens MID-STREAM, before
|
||||
* onFinish persists the tool part — a transcript scan would race it. */
|
||||
spawn: (job: JobRecord, input: ResearchInput | DemoInput | VisualInput) => void;
|
||||
spawn: (job: JobRecord, input: ResearchInput | DemoInput | VisualInput | PdfInput) => void;
|
||||
}
|
||||
|
||||
export const researchInputSchema = z.object({
|
||||
@@ -53,6 +53,16 @@ export const visualInputSchema = z.object({
|
||||
),
|
||||
});
|
||||
|
||||
export const pdfInputSchema = z.object({
|
||||
path: z.string().describe("Path to the learner's PDF (relative or absolute), exactly as they gave it."),
|
||||
question: z
|
||||
.string()
|
||||
.describe(
|
||||
"What you need from the document — the specific content, explanation, or answer to extract and brief. " +
|
||||
"The reader sees NOTHING else of the lesson.",
|
||||
),
|
||||
});
|
||||
|
||||
/**
|
||||
* The per-call dispatch: create the job (idempotent by toolCallId), fire the
|
||||
* runner, and return the ack. Shared by all three tools — only kind differs.
|
||||
@@ -62,7 +72,7 @@ function dispatch(
|
||||
kind: JobRecord["kind"],
|
||||
toolCallId: string,
|
||||
ack: string,
|
||||
input: ResearchInput | DemoInput | VisualInput,
|
||||
input: ResearchInput | DemoInput | VisualInput | PdfInput,
|
||||
): string {
|
||||
const existing = ctx.jobStore.findJobByToolCallId(ctx.chatId, toolCallId);
|
||||
const job = existing ?? ctx.jobStore.createJob({ kind, chatId: ctx.chatId, toolCallId });
|
||||
@@ -79,6 +89,9 @@ const DEMO_ACK =
|
||||
const VISUAL_ACK =
|
||||
"This call is fire-and-forget: continue your turn and keep teaching — do not wait, poll, or mention waiting. " +
|
||||
"The verified figure arrives as a new message when ready and is rendered in the lesson; reference it then.";
|
||||
const PDF_ACK =
|
||||
"This call is fire-and-forget: continue your turn and keep teaching — do not wait, poll, or mention waiting. " +
|
||||
"The document brief arrives as a new message when ready; weave it into the lesson and cite its pages.";
|
||||
|
||||
const RESEARCH_DESCRIPTION =
|
||||
"Dispatch a background web-research agent: fact verification, current data, or niche specifics you are not certain about. " +
|
||||
@@ -97,6 +110,12 @@ const VISUAL_DESCRIPTION =
|
||||
"function plots, physical layouts. For flows/relations/taxonomies write mermaid inline instead. " +
|
||||
"The call is ASYNC and fire-and-forget — it resolves immediately and your turn continues; the verified figure arrives later " +
|
||||
"as a new message.";
|
||||
const PDF_DESCRIPTION =
|
||||
"Dispatch a background sub-agent that READS a learner-provided PDF on your behalf (triage, targeted extraction, visual page " +
|
||||
"reading for equations and diagrams) and returns a brief with page citations. Use it when the learner gives you a PDF path " +
|
||||
"and you need its CONTENT for the lesson. The call is ASYNC and fire-and-forget — it resolves immediately and your turn " +
|
||||
"continues; the brief arrives later as a new message. For quick looks at plain text or image files, use the read tool " +
|
||||
"directly instead of dispatching.";
|
||||
|
||||
/**
|
||||
* Per-request job tool registry: each tool closes over the composition root's
|
||||
@@ -123,9 +142,16 @@ export function jobTools(ctx: JobToolContext): Record<string, LhTool<any, any>>
|
||||
schema: visualInputSchema,
|
||||
execute: async (input, { toolCallId }) => dispatch(ctx, "visual", toolCallId, VISUAL_ACK, input),
|
||||
}),
|
||||
pdf: lhTool({
|
||||
name: "pdf",
|
||||
description: PDF_DESCRIPTION,
|
||||
schema: pdfInputSchema,
|
||||
execute: async (input, { toolCallId }) => dispatch(ctx, "pdf", toolCallId, PDF_ACK, input),
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
export type ResearchInput = z.infer<typeof researchInputSchema>;
|
||||
export type DemoInput = z.infer<typeof demoInputSchema>;
|
||||
export type VisualInput = z.infer<typeof visualInputSchema>;
|
||||
export type PdfInput = z.infer<typeof pdfInputSchema>;
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
import * as fs from "node:fs/promises";
|
||||
import * as path from "node:path";
|
||||
import { z } from "zod";
|
||||
import { lhTool, type LhToolImageResult } from "../lh-tool.ts";
|
||||
|
||||
/**
|
||||
* The read tool — sources v0 (2026-09): a Node port of pi's read semantics
|
||||
* for the learner's local files. The flow is learner-owned: he pastes file
|
||||
* paths into the chat, the agent reads on its own terms (nothing is
|
||||
* auto-injected). Unrestricted local reads are the user-decided v0 scope —
|
||||
* this is a personal study harness, not a multi-tenant service.
|
||||
*
|
||||
* Ported behaviors (mirroring pi's dist/core/tools/read.js):
|
||||
* - text files: utf-8, offset (1-indexed) / limit slicing, and the
|
||||
* 2000-line / 50KB truncation ceiling with actionable "use offset=N"
|
||||
* continuation notices — a huge file never silently floods the context.
|
||||
* - image files (jpg/png/gif/webp/bmp): returned as native image content
|
||||
* parts so the vision-capable model actually SEES them (teacher's
|
||||
* glm-5.3-flash accepts image input per pi's zai catalog; the converter
|
||||
* in lh-tool.ts maps LhToolImageResult to pi's ImageContent).
|
||||
* - unreadable/missing files throw — pi turns that into an error tool
|
||||
* result the model sees and recovers from.
|
||||
*
|
||||
* Usage guidance ships in the description (the self-contained-tools
|
||||
* principle, user-decided 2026-09: system prompts reference only
|
||||
* always-on tools — read IS always-on, but its doctrine still lives here).
|
||||
*/
|
||||
|
||||
const MAX_LINES = 2000;
|
||||
const MAX_BYTES = 50 * 1024;
|
||||
|
||||
/** Extension map for v0 (pi sniffs magic bytes; extensions suffice here —
|
||||
* learner files are pasted paths, not adversarial uploads). */
|
||||
const IMAGE_MIME: Record<string, string> = {
|
||||
".jpg": "image/jpeg",
|
||||
".jpeg": "image/jpeg",
|
||||
".png": "image/png",
|
||||
".gif": "image/gif",
|
||||
".webp": "image/webp",
|
||||
".bmp": "image/bmp",
|
||||
};
|
||||
|
||||
const readInputSchema = z.object({
|
||||
path: z.string().min(1).describe("Path to the file to read (relative or absolute)"),
|
||||
offset: z.number().int().positive().optional().describe("Line number to start reading from (1-indexed)"),
|
||||
limit: z.number().int().positive().optional().describe("Maximum number of lines to read"),
|
||||
});
|
||||
|
||||
function formatSize(bytes: number): string {
|
||||
return bytes >= 1024 ? `${(bytes / 1024).toFixed(1)}KB` : `${bytes}B`;
|
||||
}
|
||||
|
||||
/** Slice + truncate the text body, pi's continuation-notice style. */
|
||||
function readTextSlice(text: string, offset: number | undefined, limit: number | undefined): string {
|
||||
const allLines = text.split("\n");
|
||||
const totalLines = allLines.length;
|
||||
const startLine = offset ? Math.max(0, offset - 1) : 0;
|
||||
if (startLine >= totalLines) {
|
||||
throw new Error(`Offset ${offset} is beyond end of file (${totalLines} lines total)`);
|
||||
}
|
||||
// honor an explicit limit first (never beyond EOF)
|
||||
let selected = allLines.slice(startLine, limit !== undefined ? startLine + limit : totalLines);
|
||||
// then the 2000-line ceiling
|
||||
let truncatedBy: "lines" | "bytes" | null = null;
|
||||
if (selected.length > MAX_LINES) {
|
||||
selected = selected.slice(0, MAX_LINES);
|
||||
truncatedBy = "lines";
|
||||
}
|
||||
// then the 50KB ceiling
|
||||
if (Buffer.byteLength(selected.join("\n"), "utf-8") > MAX_BYTES) {
|
||||
while (selected.length > 0 && Buffer.byteLength(selected.join("\n"), "utf-8") > MAX_BYTES) {
|
||||
selected.pop();
|
||||
}
|
||||
truncatedBy = "bytes";
|
||||
}
|
||||
if (truncatedBy === null) {
|
||||
const remaining = totalLines - (startLine + selected.length);
|
||||
if (remaining > 0) {
|
||||
return `${selected.join("\n")}\n\n[${remaining} more lines in file. Use offset=${startLine + selected.length + 1} to continue.]`;
|
||||
}
|
||||
return selected.join("\n");
|
||||
}
|
||||
const endLineDisplay = startLine + selected.length;
|
||||
const reason =
|
||||
truncatedBy === "lines" ? `${MAX_LINES} line limit` : `${formatSize(MAX_BYTES)} limit`;
|
||||
return `${selected.join("\n")}\n\n[Showing lines ${startLine + 1}-${endLineDisplay} of ${totalLines} (${reason}). Use offset=${endLineDisplay + 1} to continue.]`;
|
||||
}
|
||||
|
||||
/** The read tool, shared verbatim by the prober and the teacher. */
|
||||
export const readTool = lhTool({
|
||||
name: "read",
|
||||
description:
|
||||
"Read the contents of a local file — the learner's source material for this lesson " +
|
||||
"(he pastes file paths into the chat; read them on your own terms, never ask him to " +
|
||||
"paste file CONTENTS into the chat). Supports text files and images (jpg, png, gif, " +
|
||||
"webp, bmp) — images are shown to you as attachments. Text output is truncated to " +
|
||||
`2000 lines or 50KB (whichever is hit first); use offset/limit for large files, and ` +
|
||||
"continue with offset until you have what you need.",
|
||||
schema: readInputSchema,
|
||||
execute: async ({ path: rawPath, offset, limit }): Promise<string | LhToolImageResult> => {
|
||||
const absolute = path.resolve(process.cwd(), rawPath);
|
||||
const ext = path.extname(absolute).toLowerCase();
|
||||
const mime = IMAGE_MIME[ext];
|
||||
const buffer = await fs.readFile(absolute); // ENOENT/EACCES → error result the model sees
|
||||
if (mime) {
|
||||
// NOTE v0: no resize — raw bytes as base64. Learner files are study
|
||||
// material (screenshots, figures), not adversarial payloads; a resize
|
||||
// step (sharp) can land later if large images prove wasteful.
|
||||
return {
|
||||
text: `Read image file [${mime}] — ${path.basename(absolute)} (${formatSize(buffer.byteLength)}), attached as an image.`,
|
||||
images: [{ data: buffer.toString("base64"), mimeType: mime }],
|
||||
};
|
||||
}
|
||||
const text = buffer.toString("utf-8");
|
||||
return readTextSlice(text, offset, limit);
|
||||
},
|
||||
});
|
||||
Reference in New Issue
Block a user