maka-agent 0.2.0-dev.12.20260901 → 0.2.0-dev.14.20260902

package/node_modules/@maka/runtime/dist/session-event-runtime-mapper.js

@@ -481,6 +481,9 @@ function mapBackendSessionEvent(event, ctx, memory) {
                             : {}),
                         ...(event.promptSegments !== undefined ? { promptSegments: event.promptSegments } : {}),
                         ...(event.contextBudget !== undefined ? { contextBudget: event.contextBudget } : {}),
+                        ...(event.lastRequestAnchor !== undefined
+                            ? { lastRequestAnchor: event.lastRequestAnchor }
+                            : {}),
                     },
                 },
                 ...(event.providerRequestTraceId !== undefined
@@ -552,12 +555,6 @@ function completeRuntimeEvent(base, event, memory) {
         stateDelta.failureClass =
             memory.failureClass ?? failureClassFromCompleteStopReason(stopReason) ?? 'runtime_error';
     }
-    // The context_budget_exhausted outcome carries which invariant made the turn
-    // unrecoverable; the durable terminal state must not collapse it to a bare
-    // failure class.
-    if (event.contextBudgetExhaustedDetail !== undefined) {
-        stateDelta.contextBudgetExhaustedDetail = event.contextBudgetExhaustedDetail;
-    }
     if (event.contextCompactionOutcome !== undefined) {
         stateDelta.contextCompactionOutcome = event.contextCompactionOutcome;
     }

package/node_modules/@maka/runtime/dist/shell-tools.js

@@ -220,7 +220,78 @@ export function buildStopBackgroundTaskTool(backgroundTasks) {
         impl: ({ ref }, ctx) => backgroundTasks.stopBackgroundTask(ctx.sessionId, ref, ctx.abortSignal),
     };
 }
-export function buildWriteStdinTool(ptyControls) {
+/** A syntactically valid PTY ref used only in the documented WriteStdin examples. */
+export const WRITE_STDIN_EXAMPLE_REF = 'maka://runtime/background-tasks/sr_example';
+/**
+ * One minimal legal payload per WriteStdin action type (plus a resize-only
+ * call). Each entry is valid under the loose provider schema AND passes strict
+ * validation after normalization — the WriteStdin contract conformance test
+ * asserts both, so the documented shape can never drift from what the runtime
+ * actually accepts. The `key (chord)` entry shows the ctrl-modified printable
+ * form the description points at.
+ */
+export const WRITE_STDIN_MINIMAL_EXAMPLES = [
+    {
+        label: 'text',
+        payload: { ref: WRITE_STDIN_EXAMPLE_REF, actions: [{ type: 'text', text: 'hello' }] },
+    },
+    {
+        label: 'key (named)',
+        payload: { ref: WRITE_STDIN_EXAMPLE_REF, actions: [{ type: 'key', key: 'enter' }] },
+    },
+    {
+        label: 'key (chord)',
+        payload: {
+            ref: WRITE_STDIN_EXAMPLE_REF,
+            actions: [{ type: 'key', key: 'c', modifiers: ['ctrl'] }],
+        },
+    },
+    {
+        label: 'mouse click',
+        payload: {
+            ref: WRITE_STDIN_EXAMPLE_REF,
+            actions: [{ type: 'mouse', event: 'click', x: 0, y: 0, button: 'left' }],
+        },
+    },
+    {
+        label: 'mouse press',
+        payload: {
+            ref: WRITE_STDIN_EXAMPLE_REF,
+            actions: [{ type: 'mouse', event: 'press', x: 0, y: 0, button: 'left' }],
+        },
+    },
+    {
+        label: 'mouse release',
+        payload: {
+            ref: WRITE_STDIN_EXAMPLE_REF,
+            actions: [{ type: 'mouse', event: 'release', x: 0, y: 0, button: 'left' }],
+        },
+    },
+    {
+        label: 'mouse move',
+        payload: {
+            ref: WRITE_STDIN_EXAMPLE_REF,
+            actions: [{ type: 'mouse', event: 'move', x: 1, y: 1 }],
+        },
+    },
+    {
+        label: 'mouse scroll',
+        payload: {
+            ref: WRITE_STDIN_EXAMPLE_REF,
+            actions: [{ type: 'mouse', event: 'scroll', x: 0, y: 0, direction: 'up' }],
+        },
+    },
+    { label: 'resize only', payload: { ref: WRITE_STDIN_EXAMPLE_REF, size: { cols: 80, rows: 24 } } },
+];
+/**
+ * The concrete minimal example embedded in the WriteStdin tool description,
+ * derived from the pinned {@link WRITE_STDIN_MINIMAL_EXAMPLES} `key (named)`
+ * entry so the documented shape can never drift from what conformance tests
+ * exercise. The example ref id is templated to `<id>` for human readers.
+ */
+export const WRITE_STDIN_DESCRIPTION_EXAMPLE_JSON = JSON.stringify((WRITE_STDIN_MINIMAL_EXAMPLES.find((example) => example.label === 'key (named)') ??
+    WRITE_STDIN_MINIMAL_EXAMPLES[0]).payload).replace('sr_example', '<id>');
+export function createWriteStdinSchemas() {
     const terminalAction = z.unknown().transform((value, context) => {
         try {
             return parseTerminalInputAction(value);
@@ -339,6 +410,10 @@ export function buildWriteStdinTool(ptyControls) {
     })
         .strict()
         .describe('Send ordered terminal actions and/or resize a background PTY');
+    return { providerParameters, strictParameters };
+}
+export function buildWriteStdinTool(ptyControls) {
+    const { providerParameters, strictParameters } = createWriteStdinSchemas();
     const providerSchema = zodSchema(providerParameters);
     const parameters = jsonSchema(async () => await providerSchema.jsonSchema, {
         validate: async (value) => {
@@ -356,6 +431,7 @@ export function buildWriteStdinTool(ptyControls) {
             `Named keys are ${TERMINAL_INPUT_NAMED_KEYS.join(', ')}. Use a printable ASCII key with ctrl or alt for chords such as Ctrl-B; use text for ordinary typing. ` +
             'Mouse coordinates are zero-based terminal cells and work only while the application has enabled SGR cell mouse reporting. ' +
             'Actions are written atomically in their listed order. Text is ordinary audited tool-call data, not a secure secret channel. ' +
+            `Minimal example: ${WRITE_STDIN_DESCRIPTION_EXAMPLE_JSON}. ` +
             'The returned output is the terminal state at that cut, not output attributed to this input; use Read on the ref to observe later output.',
         parameters,
         permissionArgs: (input) => parseInput(input),

package/node_modules/@maka/runtime/dist/tool-availability.js

@@ -45,6 +45,37 @@ const DIRECT_TOOL_NAMES = new Set([
     // Provider-routed equivalent of the direct Write/Edit surface.
     'apply_patch',
 ]);
+/**
+ * Discovery capability-family derived from a tool's permission `categoryHint`.
+ *
+ * This reuses the existing permission taxonomy (`ToolCategory`) purely for
+ * *presentation* in the deferred-tool search inventory: it never loads a tool
+ * schema and never affects permission classification. Several permission
+ * categories intentionally collapse into one browsing family (e.g. every shell
+ * bucket → `shell`). `custom_tool` is deliberately `null` so our own
+ * session-scoped tools without a stronger hint keep falling back to `other`.
+ *
+ * The map is TOTAL over `ToolCategory` on purpose: adding a new category to the
+ * union forces an explicit decision here (family or `null`) at compile time,
+ * instead of silently collapsing the new category into `other`.
+ */
+const CATEGORY_FAMILY = {
+    read: { id: 'filesystem', label: 'Filesystem & search' },
+    file_write: { id: 'filesystem', label: 'Filesystem & search' },
+    fs_destructive: { id: 'filesystem', label: 'Filesystem & search' },
+    shell_safe: { id: 'shell', label: 'Shell & processes' },
+    shell_unsafe: { id: 'shell', label: 'Shell & processes' },
+    privileged: { id: 'shell', label: 'Shell & processes' },
+    git_destructive: { id: 'shell', label: 'Shell & processes' },
+    web_read: { id: 'web', label: 'Web & network' },
+    network_send: { id: 'web', label: 'Web & network' },
+    browser: { id: 'browser', label: 'Browser automation' },
+    computer_use: { id: 'computer_use', label: 'Computer use' },
+    client_capability: { id: 'client_capability', label: 'Client capabilities' },
+    subagent: { id: 'agents', label: 'Agent orchestration' },
+    // null = intentionally ungrouped; falls back to the `other` bucket.
+    custom_tool: null,
+};
 export function toolAvailabilityHash(config) {
     return stableHash({
         mode: config === undefined ? 'full' : 'search',
@@ -113,12 +144,50 @@ export class ToolAvailabilityRuntime {
         }
         const ungrouped = [...searchable].filter((name) => !claimed.has(name)).sort(compareExactString);
         if (ungrouped.length > 0) {
-            const fallback = groups.find((group) => group.id === 'other');
-            if (fallback) {
-                fallback.toolNames = [...fallback.toolNames, ...ungrouped].sort(compareExactString);
+            // Bucket ungrouped native tools by their permission `categoryHint` so the
+            // search inventory advertises a compact capability-family map instead of a
+            // single opaque `other` group. This reads metadata already on the bound
+            // tool (no schema is loaded) and never affects permission classification.
+            // A caller-supplied group with a colliding id keeps precedence: family
+            // members merge into it. Tools with no hint (or `custom_tool`) still fall
+            // back to `other`.
+            const familyMembers = new Map();
+            const otherNames = [];
+            for (const name of ungrouped) {
+                const hint = this.toolsByName.get(name)?.categoryHint;
+                // A mapped-but-`null` entry (e.g. custom_tool) and an absent hint both
+                // route to `other`; only a non-null family is bucketed.
+                const family = hint ? CATEGORY_FAMILY[hint] : null;
+                if (!family) {
+                    otherNames.push(name);
+                    continue;
+                }
+                const bucket = familyMembers.get(family.id) ?? { label: family.label, names: [] };
+                bucket.names.push(name);
+                familyMembers.set(family.id, bucket);
             }
-            else {
-                groups.push({ id: 'other', toolNames: ungrouped });
+            for (const id of [...familyMembers.keys()].sort(compareExactString)) {
+                const bucket = familyMembers.get(id);
+                const existing = groups.find((group) => group.id === id);
+                if (existing) {
+                    existing.toolNames = [...existing.toolNames, ...bucket.names].sort(compareExactString);
+                }
+                else {
+                    groups.push({
+                        id,
+                        toolNames: [...bucket.names].sort(compareExactString),
+                        ...(bucket.label !== undefined ? { label: bucket.label } : {}),
+                    });
+                }
+            }
+            if (otherNames.length > 0) {
+                const fallback = groups.find((group) => group.id === 'other');
+                if (fallback) {
+                    fallback.toolNames = [...fallback.toolNames, ...otherNames].sort(compareExactString);
+                }
+                else {
+                    groups.push({ id: 'other', toolNames: otherNames.sort(compareExactString) });
+                }
             }
         }
         this.groups = groups;

package/node_modules/@maka/runtime/dist/tool-result-archive-resource.js

@@ -25,7 +25,16 @@ export const TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS = 7_500;
 const ARCHIVE_ARTIFACT_ID_PATTERN = /^[A-Za-z0-9._-]{1,160}$/;
 const MAX_MANIFEST_ITEMS = 100;
 const MAX_METADATA_STRING_CHARS = 160;
-const MANIFEST_RESPONSE_RESERVE_CHARS = 600;
+/** Upper bound on matches returned by a single search page. */
+export const TOOL_RESULT_ARCHIVE_MAX_SEARCH_MATCHES = 50;
+/** Characters of surrounding context kept on each side of a search match. */
+const SEARCH_SNIPPET_RADIUS = 80;
+/** Longest search snippet retained, so many matches still fit one response. */
+const MAX_SEARCH_SNIPPET_CHARS = 240;
+/** Maximum pattern length accepted by the ArchiveRead tool schema. */
+const MAX_SEARCH_PATTERN_CHARS = 256;
+/** Preview length surfaced by inspect for text/object payloads. */
+const INSPECT_PREVIEW_CHARS = 600;
 export function buildToolResultArchiveResourceRef(input) {
     const artifactId = encodeURIComponent(input.artifactId);
     const sha256 = encodeURIComponent(input.bodySha256);
@@ -95,23 +104,59 @@ export async function readToolResultArchiveResource(reader, sessionId, request,
     const operation = request.operation ?? 'inspect';
     const limit = normalizeLimit(request.limit);
     const offset = normalizeOffset(request.offset);
+    const parsed = deserializeArchive(read.serializedResult);
+    if (operation === 'search') {
+        const text = resolveArchiveText(parsed, read.serializedResult);
+        return searchArchive(request.ref, text, request.pattern, offset);
+    }
     if (operation === 'read') {
-        return pagedContent({
-            ref: request.ref,
-            operation,
-            content: read.serializedResult,
-            offset,
-            limit,
-        });
+        // Page the decoded text for string payloads so offsets land on real
+        // characters, not JSON escape bytes; structured payloads still page their
+        // canonical JSON serialization.
+        const text = resolveArchiveText(parsed, read.serializedResult);
+        if (request.unit === 'line') {
+            return pagedLines(request.ref, text, offset, limit);
+        }
+        return pagedContent({ ref: request.ref, operation, content: text, offset, limit });
     }
-    const parsed = deserializeArchive(read.serializedResult);
     if (operation === 'query') {
         return queryArchiveItem(request.ref, parsed, request.itemId, offset, limit);
     }
-    return inspectArchive(request.ref, identity, parsed);
+    return inspectArchive(request.ref, identity, parsed, read.serializedResult);
+}
+/**
+ * The text an archive should page/search over. String payloads decode to their
+ * raw content, and terminal/shell-run payloads project their stdout/stderr;
+ * everything else pages its canonical JSON serialization.
+ */
+function resolveArchiveText(parsed, serializedResult) {
+    if (typeof parsed === 'string')
+        return parsed;
+    if (!isTerminalArchivePayload(parsed))
+        return serializedResult;
+    // Bash archives retain the canonical terminal/shell-run object. Search and
+    // line reads should operate on the human-readable streams, not JSON-escaped
+    // `\\n` sequences in that object.
+    const output = isRecord(parsed.output) ? parsed.output : undefined;
+    if (output?.mode === 'pty') {
+        const ptyParts = [output.scrollback, output.screen, output.lastAlternateScreen].filter((part) => typeof part === 'string' && part.length > 0);
+        return ptyParts.join('\n');
+    }
+    const stdout = output && typeof output.stdout === 'string' ? output.stdout : undefined;
+    const stderr = output && typeof output.stderr === 'string' ? output.stderr : undefined;
+    if (stdout !== undefined || stderr !== undefined) {
+        const parts = [stdout, stderr].filter((s) => typeof s === 'string' && s.length > 0);
+        return parts.join('\n');
+    }
+    return serializedResult;
+}
+function isTerminalArchivePayload(value) {
+    return (isRecord(value) &&
+        (value.kind === 'terminal' || value.kind === 'shell_run') &&
+        isRecord(value.output));
 }
 export const TOOL_RESULT_ARCHIVE_READ_INSTRUCTIONS = 'This result is archived but still readable. Call ArchiveRead with the provided ref and operation "inspect"; use operation "query" with itemId for one structured item, or operation "read" with offset/limit for a bounded page. Do not use Glob to find the archive.';
-function inspectArchive(ref, identity, value) {
+function inspectArchive(ref, identity, value, serializedResult) {
     const base = {
         ok: true,
         kind: 'tool_result_archive',
@@ -120,45 +165,111 @@ function inspectArchive(ref, identity, value) {
         artifactId: identity.artifactId,
         originalBytes: identity.originalBytes,
     };
+    const readHint = 'Call ArchiveRead with operation "read" (unit "char" or "line"), offset, and limit for bounded pages, or operation "search" with a pattern to locate text.';
+    if (isTerminalArchivePayload(value)) {
+        const text = resolveArchiveText(value, serializedResult);
+        return {
+            ...base,
+            valueType: 'terminal',
+            totalChars: text.length,
+            totalLines: countLines(text),
+            preview: boundedString(text, INSPECT_PREVIEW_CHARS),
+            readHint,
+        };
+    }
+    if (typeof value === 'string') {
+        // A plain-text/terminal payload: report the char/line coordinate space plus
+        // a short preview so the model can page or search without a blind first read.
+        return {
+            ...base,
+            valueType: 'text',
+            totalChars: value.length,
+            totalLines: countLines(value),
+            preview: boundedString(value, INSPECT_PREVIEW_CHARS),
+            readHint,
+        };
+    }
     if (isRecord(value)) {
         const items = Array.isArray(value.items) ? value.items : undefined;
-        const manifestItems = items ? fitManifestItems(base, items) : undefined;
-        const result = {
+        let objectKeys = Object.keys(value)
+            .slice(0, 25)
+            .map((key) => boundedString(key));
+        const buildObjectBase = () => ({
             ...base,
             valueType: 'object',
-            keys: Object.keys(value)
-                .slice(0, 25)
-                .map((key) => boundedString(key)),
+            totalChars: serializedResult.length,
+            keys: objectKeys,
             ...(typeof value.kind === 'string' ? { archivedKind: boundedString(value.kind) } : {}),
             ...(typeof value.status === 'string' ? { status: boundedString(value.status) } : {}),
-            ...(items
-                ? {
-                    itemCount: items.length,
-                    items: manifestItems,
-                    queryHint: 'Call ArchiveRead with operation "query" and one of the listed itemId values.',
+        });
+        if (items) {
+            const queryHint = 'Call ArchiveRead with operation "query" and one of the listed itemId values.';
+            const projectedItems = items.slice(0, MAX_MANIFEST_ITEMS).map(inspectItem);
+            let manifestItems = projectedItems;
+            const buildManifest = () => ({
+                ...buildObjectBase(),
+                itemCount: items.length,
+                items: manifestItems,
+                queryHint,
+                readHint,
+                ...(manifestItems.length < items.length
+                    ? { itemsTruncated: true, listedItemCount: manifestItems.length }
+                    : {}),
+            });
+            // Keep one actionable itemId when it can fit, then trade keys for more
+            // manifest entries and re-add entries against the complete envelope.
+            while (JSON.stringify(buildManifest()).length > TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS) {
+                if (manifestItems.length > 1) {
+                    manifestItems = manifestItems.slice(0, -1);
+                    continue;
                 }
-                : {}),
-            readHint: 'Call ArchiveRead with operation "read", offset, and limit for raw JSON pages.',
-        };
-        return {
-            ...result,
-            ...(items && manifestItems && manifestItems.length < items.length
-                ? { itemsTruncated: true, listedItemCount: manifestItems.length }
-                : {}),
-        };
+                if (objectKeys.length > 0) {
+                    objectKeys = objectKeys.slice(0, -1);
+                    continue;
+                }
+                if (manifestItems.length > 0) {
+                    manifestItems = [];
+                    continue;
+                }
+                break;
+            }
+            for (const projectedItem of projectedItems.slice(manifestItems.length)) {
+                const next = [...manifestItems, projectedItem];
+                manifestItems = next;
+                if (JSON.stringify(buildManifest()).length > TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS) {
+                    manifestItems = next.slice(0, -1);
+                    break;
+                }
+            }
+            return buildManifest();
+        }
+        const buildObject = () => ({
+            ...buildObjectBase(),
+            preview: boundedString(serializedResult, INSPECT_PREVIEW_CHARS),
+            readHint,
+        });
+        while (objectKeys.length > 0 &&
+            JSON.stringify(buildObject()).length > TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS) {
+            objectKeys = objectKeys.slice(0, -1);
+        }
+        return buildObject();
     }
     if (Array.isArray(value)) {
         return {
             ...base,
             valueType: 'array',
             itemCount: value.length,
-            readHint: 'Call ArchiveRead with operation "read", offset, and limit for raw JSON pages.',
+            totalChars: serializedResult.length,
+            preview: boundedString(serializedResult, INSPECT_PREVIEW_CHARS),
+            readHint,
         };
     }
     return {
         ...base,
         valueType: value === null ? 'null' : typeof value,
-        readHint: 'Call ArchiveRead with operation "read", offset, and limit for content pages.',
+        totalChars: serializedResult.length,
+        preview: boundedString(serializedResult, INSPECT_PREVIEW_CHARS),
+        readHint,
     };
 }
 function queryArchiveItem(ref, value, itemId, offset, limit) {
@@ -225,6 +336,194 @@ function pagedContent(input) {
     }
     return buildPage(low);
 }
+/**
+ * Locate a literal (case-insensitive) substring inside the archived text and
+ * return matched offsets with bounded context snippets. The pattern is escaped
+ * before using a Unicode-aware literal regex, so it cannot inject regex syntax
+ * or introduce pathological backtracking. Matches accumulate only while the
+ * envelope stays within
+ * TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS, and `nextOffset` resumes the scan.
+ */
+function searchArchive(ref, text, pattern, offset) {
+    if (!pattern)
+        return archiveFailure(ref, 'pattern_required');
+    // Escape the user pattern before using a Unicode-aware literal regex. This
+    // preserves original source indices while retaining contextual case folding
+    // (for example, Greek final sigma), and remains safe from regex injection or
+    // pathological backtracking because the pattern is literal.
+    const matcher = new RegExp(escapeRegExp(pattern), 'giu');
+    const base = {
+        ok: true,
+        kind: 'tool_result_archive',
+        operation: 'search',
+        ref,
+        pattern: boundedString(pattern, MAX_SEARCH_PATTERN_CHARS),
+        totalChars: text.length,
+    };
+    const buildResponse = (matches, nextOffset) => ({
+        ...base,
+        matchCount: matches.length,
+        matches,
+        nextOffset,
+        hasMore: nextOffset !== null,
+    });
+    const matches = [];
+    // Line numbers are assigned by a single forward scan; match offsets only
+    // increase, so total work stays linear in the text length.
+    let scanChar = 0;
+    let scanLine = 1;
+    const lineAt = (index) => {
+        while (scanChar < index && scanChar < text.length) {
+            if (text.charCodeAt(scanChar) === 10)
+                scanLine++;
+            scanChar++;
+        }
+        return scanLine;
+    };
+    let from = normalizeSearchOffset(text, offset);
+    while (matches.length < TOOL_RESULT_ARCHIVE_MAX_SEARCH_MATCHES) {
+        matcher.lastIndex = from;
+        const match = matcher.exec(text);
+        if (!match)
+            return buildResponse(matches, null);
+        const index = match.index;
+        const matchEnd = index + match[0].length;
+        // Keep the complete match representable when the accepted pattern is
+        // longer than the normal snippet budget; trim surrounding context first.
+        const snippetLimit = Math.min(MAX_SEARCH_PATTERN_CHARS + SEARCH_SNIPPET_RADIUS * 2, Math.max(MAX_SEARCH_SNIPPET_CHARS, matchEnd - index));
+        const contextBudget = Math.max(0, snippetLimit - (matchEnd - index));
+        const before = Math.min(SEARCH_SNIPPET_RADIUS, Math.floor(contextBudget / 2));
+        const after = Math.min(SEARCH_SNIPPET_RADIUS, contextBudget - before);
+        const snippetStart = Math.max(0, index - before);
+        const snippetEnd = Math.min(text.length, matchEnd + after);
+        const candidate = {
+            offset: index,
+            line: lineAt(index),
+            snippetStart,
+            snippet: text.slice(snippetStart, snippetEnd),
+        };
+        if (JSON.stringify(buildResponse([...matches, candidate], index)).length >
+            TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS) {
+            // This match would overflow the budget; resume here next call.
+            return buildResponse(matches, index);
+        }
+        matches.push(candidate);
+        from = index + Math.max(1, match[0].length);
+    }
+    // Hit the per-page match cap; report where an unread match still waits.
+    matcher.lastIndex = from;
+    const more = matcher.exec(text);
+    return buildResponse(matches, more === null ? null : more.index);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function normalizeSearchOffset(text, offset) {
+    const clamped = Math.min(Math.max(0, offset), text.length);
+    if (clamped > 0 &&
+        clamped < text.length &&
+        isLowSurrogate(text.charCodeAt(clamped)) &&
+        isHighSurrogate(text.charCodeAt(clamped - 1))) {
+        return clamped + 1;
+    }
+    return clamped;
+}
+function isHighSurrogate(value) {
+    return value >= 0xd800 && value <= 0xdbff;
+}
+function isLowSurrogate(value) {
+    return value >= 0xdc00 && value <= 0xdfff;
+}
+/** Count 1-based lines in text (an empty string has zero lines). */
+function countLines(text) {
+    if (text.length === 0)
+        return 0;
+    let count = 1;
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            count++;
+    }
+    return count;
+}
+/**
+ * Collect up to `maxLines` lines starting at the zero-based `lineOffset` without
+ * materializing the whole text as an array — the scan stops after the window,
+ * so cost is bounded by the requested window, not the archive size.
+ */
+function collectLineWindow(text, lineOffset, maxLines) {
+    if (text.length === 0)
+        return { lines: [], startChar: 0 };
+    let cursor = 0;
+    let line = 0;
+    while (line < lineOffset && cursor <= text.length) {
+        const nl = text.indexOf('\n', cursor);
+        if (nl === -1)
+            return { lines: [], startChar: text.length };
+        cursor = nl + 1;
+        line++;
+    }
+    const startChar = cursor;
+    const lines = [];
+    while (lines.length < maxLines && cursor <= text.length) {
+        const nl = text.indexOf('\n', cursor);
+        if (nl === -1) {
+            lines.push(text.slice(cursor));
+            break;
+        }
+        lines.push(text.slice(cursor, nl));
+        cursor = nl + 1;
+        if (cursor > text.length)
+            break;
+    }
+    return { lines, startChar };
+}
+/**
+ * Read a bounded window of whole lines. offset/limit count lines; the returned
+ * line count is trimmed by binary search so the response never exceeds
+ * TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS, and `nextLineOffset` resumes paging.
+ */
+function pagedLines(ref, text, lineOffset, lineLimit) {
+    const totalLines = countLines(text);
+    const { lines } = collectLineWindow(text, lineOffset, lineLimit);
+    const buildPage = (count) => {
+        const endLine = lineOffset + count;
+        const hasMore = endLine < totalLines;
+        return {
+            ok: true,
+            kind: 'tool_result_archive',
+            operation: 'read',
+            ref,
+            unit: 'line',
+            lineOffset,
+            lineLimit: count,
+            totalLines,
+            nextLineOffset: hasMore ? endLine : null,
+            hasMore,
+            content: lines.slice(0, count).join('\n'),
+        };
+    };
+    let low = 0;
+    let high = lines.length;
+    while (low < high) {
+        const candidate = Math.ceil((low + high) / 2);
+        if (JSON.stringify(buildPage(candidate)).length <= TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS) {
+            low = candidate;
+        }
+        else {
+            high = candidate - 1;
+        }
+    }
+    if (low === 0 && lines.length > 0) {
+        return archiveFailure(ref, 'line_too_large', {
+            unit: 'line',
+            lineOffset,
+            totalLines,
+            lineChars: lines[0].length,
+            readHint: 'Retry with operation "read" and unit "char" to page this oversized line.',
+        });
+    }
+    return buildPage(low);
+}
 function inspectItem(value) {
     if (!isRecord(value))
         return { valueType: value === null ? 'null' : typeof value };
@@ -264,26 +563,8 @@ function inspectItem(value) {
         ...(typeof value.result === 'string' ? { resultChars: value.result.length } : {}),
     };
 }
-function fitManifestItems(base, items) {
-    const fitted = [];
-    for (const candidate of items.slice(0, MAX_MANIFEST_ITEMS)) {
-        const projected = inspectItem(candidate);
-        const next = [...fitted, projected];
-        if (JSON.stringify({
-            ...base,
-            items: next,
-        }).length >
-            TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS - MANIFEST_RESPONSE_RESERVE_CHARS) {
-            break;
-        }
-        fitted.push(projected);
-    }
-    return fitted;
-}
-function boundedString(value) {
-    return value.length <= MAX_METADATA_STRING_CHARS
-        ? value
-        : `${value.slice(0, MAX_METADATA_STRING_CHARS - 1)}…`;
+function boundedString(value, max = MAX_METADATA_STRING_CHARS) {
+    return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
 }
 function deserializeArchive(serialized) {
     if (serialized === 'undefined')