@sema-agent/core 5.19.0 → 5.21.0

package/dist/tools/fs/notebook.d.ts

@@ -1,9 +1,34 @@
 import type { ImageContent } from "../../internal/llm.js";
+/**
+ * RB-227 ([1937] N1) — the Read tool's Jupyter-notebook projection: `.ipynb` is rendered as cells
+ * with outputs (CC 2.1.220 parity: `Ctd`/`wtd`/`Zx_`/`Qx_`/`eI_`/`tI_`/`Atd`, pretty220.js
+ * :371265-:371426), never as raw JSON text. The raw-JSON rendering let a notebook's base64 outputs
+ * overflow the Read token cap, auto-paginate into an `isPartialView` entry, and thereby lock
+ * NotebookEdit out via the requireRead gate (RB-200 F2) — with the marker's own offset/limit hint
+ * pointing at a range that itself exceeds the cap (the base64 lives on one mega-line).
+ *
+ * Pure module (no I/O, no env): index.ts owns reading/decoding/state; this owns parse + render.
+ */
+/** CC 220 `o3r` (:60226): extname === ".ipynb". */
 export declare function isNotebookPath(p: string): boolean;
+/** CC 220 `Jx_ = 1e4` (:371426): PER-CELL cap on the summed output payload (text chars + image
+ *  base64 chars). A cell over it has its ENTIRE outputs array replaced by one pointer line —
+ *  per cell, never a running global budget (CC's `Xx_` accumulator restarts for every cell). */
 export declare const NOTEBOOK_CELL_OUTPUT_POINTER_CHARS = 10000;
+/** Per-output text clip. CC clips each output at its bash-output limit first (`CCs` → `vtd`) and
+ *  then the per-cell 10K pointer check dominates — in the all-cells projection a cell whose output
+ *  text exceeds 10K is always pointered, so this clip is unreachable insurance kept at the same
+ *  10K yardstick (simplification of CC's two-stage clip, recorded deliberately). */
 export declare const NOTEBOOK_OUTPUT_TEXT_CLIP = 10000;
+/** RB-227 E4 — cumulative image budget across the WHOLE notebook: the 10K per-cell pointer bounds
+ *  one cell, but N cells × ~9KB images is unbounded. CC gets an implicit bound because image data
+ *  counts toward its 256KB projected-JSON cap (`ePi = 262144`, :61029) and then HARD-ERRORS; sema
+ *  reuses that same figure but as a DEGRADATION budget — images past it are dropped with an honest
+ *  marker instead of making the notebook unreadable/uneditable (which is the RB-227 failure mode
+ *  this whole lane exists to remove). Divergence-logged. */
 export declare const NOTEBOOK_IMAGE_BASE64_BUDGET = 262144;
 export interface NotebookOutputImage {
+    /** Whitespace-stripped base64 (magic-validated — never an unverified blob, see `imageFromData`). */
     image_data: string;
     media_type: "image/png" | "image/jpeg";
 }
@@ -13,10 +38,19 @@ export interface NotebookOutput {
     image?: NotebookOutputImage;
 }
 export interface NotebookCell {
+    /** `cell.id`, or the synthesized `cell-${index}` for nbformat<4.5 — index = the UNFILTERED array
+     *  position, because NotebookEdit's `/^cell-(\d+)$/` positional fallback resolves exactly that.
+     *  Deliberate delta (review r2 finding 2): sema synthesizes for any NON-STRING id (`typeof id ===
+     *  "string"` guard in `parseNotebookCells`) where CC's `wtd` uses `e.id ?? cell-${t}` (:371314)
+     *  and would render e.g. a numeric id literally — but NotebookEdit's id match is string-only, so
+     *  CC's literal form would be un-addressable while sema's positional alias resolves; nbformat
+     *  ids are spec-string, so this branch only fires on out-of-spec input. */
     cell_id: string;
     cellType: string;
     source: string;
+    /** Code cells only (CC `wtd`). */
     language?: string;
+    /** Code cells only; CC drops falsy (`e.execution_count || void 0`). */
     execution_count?: number;
     outputs?: NotebookOutput[];
 }
@@ -27,14 +61,36 @@ export type ParsedNotebook = {
     ok: false;
     reason: "json" | "shape";
 };
+/**
+ * CC `Ctd` + `wtd` (:371373 / :371313): parse the notebook JSON into the projected cell list.
+ * Failure is a typed reason, not a throw — the Read lane falls back to raw text on it (sema
+ * divergence from CC's hard error: a corrupt notebook stays readable so the model can see what is
+ * wrong; NotebookEdit still refuses it with its own JSON-validation errors, so nothing is loosened).
+ * `notebookPath` is substituted into the per-cell pointer line (CC ships a literal
+ * `<notebook_path>` placeholder there; the real path makes the recipe directly runnable).
+ */
 export declare function parseNotebookCells(text: string, notebookPath: string): ParsedNotebook;
 export interface NotebookRender {
     blocks: Array<{
         type: "text";
         text: string;
     } | ImageContent>;
+    /** Total chars across the (merged) text blocks — the caller's token-cap yardstick. */
     textChars: number;
+    /** Total base64 chars actually emitted as image blocks (post-budget). */
     imageChars: number;
 }
+/**
+ * CC `eI_`/`tI_`/`Atd` (:371339/:371349/:371399): render projected cells to content blocks.
+ * Tag shape is CC-verbatim, including the deliberately malformed closing tag `</cell id="X">`;
+ * `<cell_type>` only when not code, `<language>` only for code cells whose language !== "python".
+ * Output text rides with a leading "\n" (tI_) and adjacent text blocks merge with "\n" (Atd), so an
+ * all-text notebook collapses to a single text block. Images ride as real image blocks in sema's
+ * `{type:"image", data, mimeType}` shape, bounded by the cumulative `imageBase64Budget` (E4): past
+ * it the image is DROPPED with an honest text marker — a degradation, never an error.
+ */
 export declare function renderNotebookCells(cells: readonly NotebookCell[], imageBase64Budget: number): NotebookRender;
+/** Wire-card projection of a cell: base64 replaced by a length marker so the `details` card never
+ *  carries raw image bytes (they ride the model-facing content blocks; an oversized card would be
+ *  omitted whole by the structuredFrom 4×cap and blind the shell). */
 export declare function stripNotebookImageData(cell: NotebookCell): NotebookCell;

package/dist/tools/fs/pdf.d.ts

@@ -1,29 +1,85 @@
+/**
+ * PDF read pipeline (service [411]② + 审计 [485]⑤ — CC FileReadTool parity).
+ *
+ * CC ground truth (original-source-code, 取证 2026-07-07):
+ * - Whole-PDF path (`FileReadTool.ts:987-1016` + `utils/pdf.ts:88-103`): the file bytes are base64'd and
+ *   sent as a native `{type:"document",source:{type:"base64",media_type:"application/pdf",data}}` content
+ *   block — the model reads the text layer directly (no local text extraction).
+ * - Page-range path (`utils/pdf.ts:179-230`): CC does NOT split the PDF itself — it shells out to
+ *   poppler's `pdftoppm -jpeg -r 100 -f F -l L` and returns the rendered pages as IMAGE blocks.
+ * - Page counting (`utils/pdf.ts:119-135`): poppler's `pdfinfo`, parsing `/^Pages:\s+(\d+)/m`; `null`
+ *   (tool absent/failed) fails OPEN. We add a zero-dependency byte-scan fallback for uncompressed PDFs.
+ * - Limits (`constants/apiLimits.ts:46-84`): 20MB whole-send target, 100MB extraction ceiling, 20 pages
+ *   per request, >10 pages ⇒ the `pages` parameter is REQUIRED.
+ *
+ * sema follows the same shape with the ExecutionEnv seam (works against remote envs too) and honest
+ * degradation when poppler is absent — never a fake success.
+ */
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+/** Max pages a single `pages` request may span (CC `PDF_MAX_PAGES_PER_READ`). */
 export declare const PDF_MAX_PAGES_PER_READ = 20;
+/** Above this page count a whole-PDF read is refused and `pages` is required (CC `PDF_AT_MENTION_INLINE_THRESHOLD`). */
 export declare const PDF_INLINE_PAGE_THRESHOLD = 10;
+/** Max raw size sent whole as a document block (CC `PDF_TARGET_RAW_SIZE`). */
 export declare const PDF_TARGET_RAW_SIZE: number;
+/** Max raw size the page-extraction (pdftoppm) path accepts (CC `PDF_MAX_EXTRACT_SIZE`). */
 export declare const PDF_MAX_EXTRACT_SIZE: number;
+/** True when the bytes start with the `%PDF-` magic. Magic outranks extension both ways: a mis-named
+ *  `.pdf` without it is refused, and a non-`.pdf` file carrying it is read AS a PDF. */
 export declare function pdfMagicMatches(bytes: Uint8Array): boolean;
+/** A parsed 1-indexed inclusive page range. `last === Infinity` for an open range ("10-"). */
 export interface PdfPageRange {
     first: number;
     last: number;
 }
+/** Parse the CC `pages` formats — "3", "1-5", "10-" (open range). `undefined` = invalid. */
 export declare function parsePdfPageRange(pages: string): PdfPageRange | undefined;
+/**
+ * Zero-dependency page-count estimate: count `/Type /Page` leaf objects in the raw bytes. Exact for
+ * classically-serialized PDFs (incl. linearized — objects stay uncompressed); returns `undefined` when
+ * nothing matches (page tree inside compressed object streams — modern writers), NEVER a guess.
+ */
 export declare function countPdfPagesFromBytes(bytes: Uint8Array): number | undefined;
+/** Max chars of a failed poppler call's stderr/stdout kept in the reported error (A-005.15). */
+export declare const PDF_EXEC_ERROR_PREVIEW_CHARS = 400;
+/** Bound a poppler exec failure's captured stream to {@link PDF_EXEC_ERROR_PREVIEW_CHARS}, marking the cut
+ *  (a bare slice reads identical to a short capture that just happened to end there — the model has no way
+ *  to tell "that's everything" from "that's all we kept"). Exactly-at-the-cap text is unmarked. */
+export declare function previewExecStream(s: string): string;
+/**
+ * Total page count via poppler `pdfinfo` (CC parity), falling back to {@link countPdfPagesFromBytes}
+ * when the tool is absent/fails and the bytes were already read. `undefined` = unknown (fail-open,
+ * matching CC's `getPDFPageCount → null`).
+ */
 export declare function getPdfPageCount(env: ExecutionEnv, absPath: string, bytes: Uint8Array | undefined, signal?: AbortSignal): Promise<number | undefined>;
+/** How many leading pages the vision fallback (level 2) renders for a whole-PDF read on a model without
+ *  document input — conservative per-request budget; the note directs the model to `pages` for more. */
 export declare const PDF_FALLBACK_RENDER_PAGES = 5;
+/**
+ * PDF capability profile of the SERVING model, consumed by the Read tool's degradation chain (v2):
+ * - `document` — the brain path can forward a native `{type:"document"}` block (today: anthropic-messages
+ *   WITH vision — anthropic.ts drops document blocks for no-vision models — or an explicit `input`
+ *   declaration containing "document" for a future capability bit).
+ * - `vision` — `Model.input` contains "image" (absent metadata fails open = today's behavior).
+ * Structural parameter (no deep Model import): `prepare-task` passes the task's resolved Model.
+ */
 export interface PdfModelCapabilities {
     document: boolean;
     vision: boolean;
 }
+/** Derive {@link PdfModelCapabilities} from a Model-shaped object. `undefined` model = fully capable
+ *  (fail-open: no metadata ⇒ preserve the native document-block behavior, brain-level placeholder guards). */
 export declare function pdfModelCapabilitiesOf(model?: {
     api?: string;
     input?: readonly string[];
 }): PdfModelCapabilities;
+/** Timeout for the poppler extraction commands (pdftotext / pdftoppm), in seconds. */
 export declare const PDF_EXEC_TIMEOUT_SEC = 120;
 export type PdfTextResult = {
     ok: true;
     text: string;
+    /** Set when pdftotext hit its exec timeout but had already written partial text: the extraction is
+     *  INCOMPLETE (covers only the leading part of the requested range) and the caller must say so. */
     timedOutAfterSec?: number;
 } | {
     ok: false;
@@ -31,6 +87,13 @@ export type PdfTextResult = {
     timedOut?: boolean;
     error: string;
 };
+/**
+ * Extract the PDF text layer via poppler `pdftotext -layout` (degradation-chain level 1: models without
+ * native document input get the text instead of a placeholder). Optional 1-indexed inclusive page range
+ * (`-f`/`-l`). Output goes through a temp FILE (not exec stdout — env exec seams may cap/mangle stdout),
+ * read back over the env seam so it works against remote envs too. `toolMissing` distinguishes
+ * "install poppler" from a real extraction failure.
+ */
 export declare function extractPdfTextLayer(env: ExecutionEnv, absPath: string, range?: {
     first: number;
     last: number;
@@ -41,6 +104,8 @@ export type PdfExtractResult = {
         pageNumber: number;
         jpeg: Uint8Array;
     }>;
+    /** Set when pdftoppm hit its exec timeout but had already rendered complete leading pages: `pages`
+     *  covers only a PREFIX of the requested range and the caller must label the delivery as partial. */
     timedOutAfterSec?: number;
 } | {
     ok: false;
@@ -48,4 +113,9 @@ export type PdfExtractResult = {
     timedOut?: boolean;
     error: string;
 };
+/**
+ * Render pages [first..last] to JPEGs via poppler `pdftoppm` (CC `extractPDFPages` parity: `-jpeg -r 100`,
+ * 120s timeout). Runs through the ExecutionEnv seam (temp dir + exec + readBinaryFile), so it works
+ * wherever the env does. `toolMissing` distinguishes "install poppler" from a real extraction failure.
+ */
 export declare function extractPdfPagesAsImages(env: ExecutionEnv, absPath: string, first: number, last: number, signal?: AbortSignal): Promise<PdfExtractResult>;

package/dist/tools/fs/pdf.js

@@ -29,6 +29,12 @@ export function countPdfPagesFromBytes(bytes) {
 function shellQuote(arg) {
     return `'${arg.replaceAll("'", `'\\''`)}'`;
 }
+export const PDF_EXEC_ERROR_PREVIEW_CHARS = 400;
+export function previewExecStream(s) {
+    return s.length > PDF_EXEC_ERROR_PREVIEW_CHARS
+        ? `${s.slice(0, PDF_EXEC_ERROR_PREVIEW_CHARS)} …[${s.length - PDF_EXEC_ERROR_PREVIEW_CHARS} chars truncated]`
+        : s;
+}
 export async function getPdfPageCount(env, absPath, bytes, signal) {
     try {
         const r = await env.exec(`pdfinfo ${shellQuote(absPath)}`, { timeout: 10, abortSignal: signal });
@@ -82,7 +88,7 @@ export async function extractPdfTextLayer(env, absPath, range, signal) {
             return { ok: false, toolMissing: false, error: r.error.message };
         }
         if (r.value.exitCode !== 0) {
-            const stderr = (r.value.stderr || r.value.stdout || "").trim().slice(0, 400);
+            const stderr = previewExecStream((r.value.stderr || r.value.stdout || "").trim());
             const missing = r.value.exitCode === 127 || /not found|command not found/i.test(stderr);
             return { ok: false, toolMissing: missing, error: stderr || `pdftotext exited with code ${r.value.exitCode}` };
         }
@@ -145,7 +151,7 @@ export async function extractPdfPagesAsImages(env, absPath, first, last, signal)
             return { ok: false, toolMissing: false, error: r.error.message };
         }
         if (r.value.exitCode !== 0) {
-            const stderr = (r.value.stderr || r.value.stdout || "").trim().slice(0, 400);
+            const stderr = previewExecStream((r.value.stderr || r.value.stdout || "").trim());
             const missing = r.value.exitCode === 127 || /not found|No such file or directory: pdftoppm|command not found/i.test(stderr);
             return { ok: false, toolMissing: missing, error: stderr || `pdftoppm exited with code ${r.value.exitCode}` };
         }

package/dist/tools/fs/repo-map.d.ts

@@ -1,4 +1,14 @@
 import type { AgentTool } from "../../internal/harness-types.js";
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+/** Extract top-level symbol names (deduped, in first-seen order) from source text. A lightweight
+ *  comment/docstring state machine (council #4) skips column-0 declaration-like lines that are really
+ *  inside a `/* … *​/` block comment or a Python `"""`/`'''` docstring — otherwise e.g. a module
+ *  docstring containing `def foo():` at column 0 produces a phantom symbol. Not a full parser (v1
+ *  heuristic): it tracks whole-line block/docstring regions, the common false-positive source.
+ *
+ *  ⚠️ **Exported ONLY as a v1 heuristic, NOT a containment proof** (design/79 §3): it is column-0 /
+ *  source-only and skips indented lines, so it CANNOT enumerate everything an artifact can call. The
+ *  auto-promote tripwire (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan
+ *  contributes nothing; it can only ever raise an escalation, never clear one. */
 export declare function extractSymbols(text: string): string[];
 export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[]): AgentTool;