@sayknow-cli/coding-agent 0.4.7 → 0.5.1

package/dist/types/task/receipt.d.ts

@@ -59,6 +59,8 @@ export interface TaskResultReceipt {
     extractedToolCounts?: Record<string, number>;
     forkContext?: SingleResult["forkContext"];
     forkContextAdvisory?: SingleResult["forkContextAdvisory"];
+    /** Resolved repository identity for this delegated lane (#2901). */
+    repositoryBinding?: SingleResult["repositoryBinding"];
     roi?: TaskRoi;
 }
 /**

package/dist/types/task/types.d.ts

@@ -45,6 +45,10 @@ export declare const taskItemSchema: z.ZodObject<{
     id: z.ZodString;
     description: z.ZodString;
     assignment: z.ZodString;
+    executionMode: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        "ultragoal-red-team": "ultragoal-red-team";
+    }>>;
     inheritContext: z.ZodOptional<z.ZodEnum<{
         none: "none";
         receipt: "receipt";
@@ -52,6 +56,15 @@ export declare const taskItemSchema: z.ZodObject<{
         bounded: "bounded";
         full: "full";
     }>>;
+    repositoryBinding: z.ZodOptional<z.ZodObject<{
+        schema: z.ZodLiteral<"skc.repository_binding.v1">;
+        worktreeRoot: z.ZodString;
+        commonDir: z.ZodNullable<z.ZodString>;
+        relativeSubdir: z.ZodOptional<z.ZodString>;
+        displayPath: z.ZodOptional<z.ZodString>;
+        head: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export type TaskItem = z.infer<typeof taskItemSchema>;
 export declare const taskSchema: z.ZodObject<{
@@ -60,6 +73,10 @@ export declare const taskSchema: z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -67,6 +84,15 @@ export declare const taskSchema: z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -82,6 +108,10 @@ export declare const taskSchemaNoIsolation: z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -89,6 +119,15 @@ export declare const taskSchemaNoIsolation: z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -104,6 +143,10 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -111,6 +154,15 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -125,6 +177,10 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -132,6 +188,15 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -146,6 +211,10 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -153,6 +222,15 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -167,6 +245,10 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -174,6 +256,15 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -188,6 +279,10 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -195,6 +290,15 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -209,6 +313,10 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        executionMode: z.ZodOptional<z.ZodEnum<{
+            default: "default";
+            "ultragoal-red-team": "ultragoal-red-team";
+        }>>;
         inheritContext: z.ZodOptional<z.ZodEnum<{
             none: "none";
             receipt: "receipt";
@@ -216,6 +324,15 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
             bounded: "bounded";
             full: "full";
         }>>;
+        repositoryBinding: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodLiteral<"skc.repository_binding.v1">;
+            worktreeRoot: z.ZodString;
+            commonDir: z.ZodNullable<z.ZodString>;
+            relativeSubdir: z.ZodOptional<z.ZodString>;
+            displayPath: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            branch: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strip>>;
     spawnPlan: z.ZodOptional<z.ZodObject<{
         whyParallel: z.ZodString;
@@ -335,6 +452,9 @@ export interface AgentProgress {
         attempt: number;
         maxAttempts: number;
         unbounded?: boolean;
+        kind: "first_event_timeout" | "idle_stream_stall" | "provider_error";
+        provider?: string;
+        lastProviderProgressAtMs?: number;
         delayMs: number;
         errorMessage: string;
         startedAtMs: number;
@@ -431,6 +551,19 @@ export interface SingleResult {
         recommendedMode: ForkContextMode;
         reasons: string[];
     };
+    /**
+     * Resolved repository identity used for this task after pre-discovery stamping
+     * and fail-closed validation (#2901).
+     */
+    repositoryBinding?: {
+        schema: "skc.repository_binding.v1";
+        worktreeRoot: string;
+        commonDir: string | null;
+        relativeSubdir?: string;
+        displayPath?: string;
+        head?: string;
+        branch?: string;
+    };
 }
 /** True only for complete, factual five-bucket cost accounting. */
 export declare function hasCompleteUsageCostBreakdown(usage: unknown): boolean;

package/dist/types/task/ultragoal-redteam-activation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Decide whether an executor assignment should inject the ultragoal red-team
+ * prompt fragment.
+ *
+ * Preference order (parse, don't re-validate later):
+ * 1. Explicit typed `executionMode` on the task / ExecutorOptions — authoritative.
+ * 2. Assignment text heuristics — only explicit Ultragoal QA/red-team phrasing.
+ *
+ * Bare mentions of `executorQa` (docs, quality-gate field names, negative
+ * instructions) must not flip the mode (#2698 / #2456).
+ *
+ * Mirrors `executor.md`:
+ * "activates only when the assignment explicitly labels Executor as Ultragoal
+ * completion QA/red-team or asks for `executorQa` red-team evidence."
+ */
+export declare const EXECUTOR_EXECUTION_MODES: readonly ["default", "ultragoal-red-team"];
+export type ExecutorExecutionMode = (typeof EXECUTOR_EXECUTION_MODES)[number];
+export declare function isExecutorExecutionMode(value: unknown): value is ExecutorExecutionMode;
+/**
+ * Parse a caller-supplied mode. Unknown values fail closed to `undefined`
+ * so the assignment heuristic (or default off) still applies — never invent on.
+ */
+export declare function parseExecutorExecutionMode(value: unknown): ExecutorExecutionMode | undefined;
+export declare function assignmentRequestsUltragoalRedTeam(assignment: string | undefined): boolean;
+export interface ResolveUltragoalRedTeamArgs {
+    readonly executionMode?: unknown;
+    readonly assignment?: string;
+}
+/**
+ * Final activation decision for the executor prompt fragment.
+ * Typed mode wins; assignment text is a compatibility fallback only.
+ */
+export declare function resolveUltragoalRedTeamActivation(args: ResolveUltragoalRedTeamArgs): boolean;

package/dist/types/tools/browser/launch.d.ts

@@ -13,6 +13,13 @@ export declare const DEFAULT_VIEWPORT: {
 export declare const BROWSER_PROTOCOL_TIMEOUT_MS = 60000;
 export declare function loadPuppeteer(): Promise<typeof Puppeteer>;
 export declare function loadPuppeteerInWorker(safeDir: string): Promise<typeof Puppeteer>;
+/** Test seam: the browser launch overrides as resolved from trusted env. */
+export declare function resolveBrowserEnvOverridesForTest(): {
+    executablePath: string | undefined;
+    proxy: string | undefined;
+    proxyBypassLoopback: boolean;
+    ignoreCertErrors: boolean;
+};
 export interface LaunchHeadlessOptions {
     headless: boolean;
     viewport?: {

package/dist/types/tools/fetch.d.ts

@@ -4,6 +4,7 @@ import type { Settings } from "../config/settings";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
+import { type TruncationDirection } from "../session/streaming-output";
 import type { RenderResult } from "../web/scrapers/types";
 import { type OutputMeta } from "./output-meta";
 export declare function isReadableUrlPath(value: string): boolean;
@@ -14,6 +15,11 @@ export interface ParsedReadUrlTarget {
     limit?: number;
 }
 export declare function parseReadUrlTarget(readPath: string): ParsedReadUrlTarget | null;
+export declare function renderHtmlToText(html: string, signal?: AbortSignal): Promise<{
+    content: string;
+    ok: boolean;
+    method: string;
+}>;
 interface FetchImagePayload {
     data: string;
     mimeType: string;
@@ -21,14 +27,6 @@ interface FetchImagePayload {
 type FetchRenderResult = RenderResult & {
     image?: FetchImagePayload;
 };
-/**
- * Opt-in insane-search fallback for blocked / degraded public URL reads.
- *
- * Returns a finalized `method: "insane"` result on success, or null (so the
- * caller continues with its normal degraded behavior). Fail-closed: no note,
- * guard DNS, dependency probe, or subprocess when raw mode or the opt-in
- * setting is off. The public-URL guard runs BEFORE any probe/spawn.
- */
 export declare function tryInsaneFallback(args: {
     url: string;
     finalUrl: string;
@@ -53,7 +51,12 @@ interface ReadUrlCacheEntry {
     artifactId?: string;
     details: ReadUrlToolDetails;
     image?: FetchImagePayload;
+    /** Complete URL output, including its preamble and body. */
     output: string;
+    /** UTF-16 code-unit offset of the preamble in `output`. */
+    preambleChars: number;
+    /** Offset of the preamble after `wrapUntrustedContent(output)` is persisted. */
+    wrappedPreambleChars?: number;
 }
 export declare function loadReadUrlCacheEntry(session: ToolSession, params: {
     path: string;
@@ -62,11 +65,21 @@ export declare function loadReadUrlCacheEntry(session: ToolSession, params: {
     ensureArtifact?: boolean;
     preferCached?: boolean;
 }): Promise<ReadUrlCacheEntry>;
+export declare const WRAP_PREFIX_CHARS: number;
+export declare function escapeUntrustedContent(content: string): string;
 export declare function wrapUntrustedContent(content: string): string;
+/**
+ * Remove only the outer URL-output wrapper before line pagination. The content
+ * remains escaped exactly as persisted; it is deliberately never unescaped.
+ */
+export declare function prepareReadUrlSelectorInput(output: string, preambleChars: number, wrappedPreambleChars?: number): {
+    text: string;
+    preambleChars: number;
+};
 export declare function executeReadUrl(session: ToolSession, params: {
     path: string;
     raw?: boolean;
-}, signal?: AbortSignal): Promise<AgentToolResult<ReadUrlToolDetails>>;
+}, signal?: AbortSignal, direction?: TruncationDirection): Promise<AgentToolResult<ReadUrlToolDetails>>;
 /** Render URL read call (URL preview) */
 export declare function renderReadUrlCall(args: {
     path?: string;

package/dist/types/tools/image-gen.d.ts

@@ -2,7 +2,7 @@ import { type Model } from "@sayknow-cli/ai";
 import * as z from "zod/v4";
 import { type ModelRegistry } from "../config/model-registry";
 import type { CustomTool } from "../extensibility/custom-tools/types";
-type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter";
+type ImageProvider = "alibaba" | "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter";
 declare const responseModalitySchema: z.ZodEnum<{
     IMAGE: "IMAGE";
     TEXT: "TEXT";
@@ -55,6 +55,52 @@ interface OpenAIResponsesUsage {
     total_tokens?: number;
 }
 type ImageUsageMetadata = GeminiUsageMetadata | OpenAIResponsesUsage;
+interface AlibabaImageContentPart {
+    type?: string;
+    text?: string;
+    image?: string;
+}
+interface AlibabaImageResponse {
+    code?: string;
+    message?: string;
+    output?: {
+        choices?: Array<{
+            message?: {
+                content?: AlibabaImageContentPart[];
+            };
+        }>;
+    };
+}
+/** Map the tool's image_size values onto wan2.7's 1K/2K size classes. */
+export declare function resolveAlibabaImageSize(imageSize: string | undefined): string | undefined;
+/**
+ * Build the Bailian multimodal-generation request body for wan2.7 image
+ * generation/editing. Input images ride along as data URLs; generation-only
+ * calls send just the prompt text. The sync endpoint returns OSS URLs inline.
+ */
+export declare function buildAlibabaImageRequest(model: string, promptText: string, inputImages: InlineImageData[], imageSize: string | undefined): {
+    model: string;
+    input: {
+        messages: Array<{
+            role: "user";
+            content: Array<{
+                text: string;
+            } | {
+                image: string;
+            }>;
+        }>;
+    };
+    parameters: {
+        n: number;
+        watermark: boolean;
+        size?: string;
+    };
+};
+/** Collect OSS image URLs and any text parts from a Bailian image response. */
+export declare function collectAlibabaImageResult(response: AlibabaImageResponse): {
+    imageUrls: string[];
+    responseText?: string;
+};
 interface ImageGenToolDetails {
     provider: ImageProvider;
     model: string;
@@ -72,6 +118,22 @@ interface InlineImageData {
 }
 /** Set the preferred image provider from settings */
 export declare function setPreferredImageProvider(provider: ImageProvider | "auto"): void;
+/** Provider → default image model mapping for auto-binding */
+export declare const IMAGE_PROVIDER_DEFAULTS: Record<string, string>;
+/** Resolved image generation configuration from settings */
+export interface ImageProviderConfig {
+    provider: ImageProvider | "auto" | "custom";
+    model: string | null;
+    customUrl?: string;
+    customKey?: string;
+    customKeyEnv?: string;
+}
+/** Set the configured image provider + model from settings */
+export declare function setConfiguredImageModel(config: ImageProviderConfig | null): void;
+/** Get the current configured image model (for UI display) */
+export declare function getConfiguredImageModel(): ImageProviderConfig | null;
+/** Resolve the effective image model for a configured provider */
+export declare function resolveImageModel(provider: string, modelOverride: string | null): string;
 export declare function isOpenAIHostedImageModel(model: Model | undefined): model is Model;
 export declare const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails>;
 export declare function getImageGenTools(modelRegistry?: ModelRegistry, activeModel?: Model): Promise<Array<CustomTool<typeof imageGenSchema, ImageGenToolDetails>>>;

package/dist/types/tools/index.d.ts

@@ -82,6 +82,8 @@ export interface AskAnswerRequest {
     options: string[];
     interaction: "selector" | "custom_editor" | "clarification_editor";
     controls: readonly AskRemoteControl[];
+    /** Optional zero-based recommendation into the authoritative raw options. */
+    recommendedIndex?: number;
 }
 export type AskRemoteInteraction = {
     kind: "value";
@@ -155,6 +157,8 @@ export interface ToolSession {
      *  its terminal-phase chain guard. Returns the raw phase string or undefined
      *  when no active skill (or accessor) is available. */
     getActiveSkillPhase?: () => string | undefined;
+    /** Restrict provider-facing deep-interview ask metadata to the active workflow stage. */
+    getDeepInterviewAskStage?: () => "topology" | "post-topology" | undefined;
     /** Pre-loaded prompt templates */
     promptTemplates?: PromptTemplate[];
     /** Whether LSP integrations are enabled */
@@ -194,9 +198,11 @@ export interface ToolSession {
     /** Agent identity used for IRC routing. Returns the registry id (e.g. "0-Main", "0-AuthLoader"). */
     getAgentId?: () => string | null;
     /** Look up a registered tool by name (used by the eval js backend's tool bridge). */
+    getToolByName?: (name: string) => AgentTool | undefined;
+    /** Look up a registered tool with the session's execution guards applied. */
+    getToolForExecution?: (name: string) => AgentTool | undefined;
     /** Purge undelivered queued custom messages matching the predicate. Returns counts. */
     purgeQueuedCustomMessages?: (predicate: (message: CustomMessage) => boolean) => PurgeQueuedCustomMessagesResult;
-    getToolByName?: (name: string) => AgentTool | undefined;
     /** Agent registry for IRC routing across live sessions. */
     agentRegistry?: AgentRegistry;
     /** Optional restricted bash command prefixes for read-only role agents and constrained modes. */

package/dist/types/tools/output-meta.d.ts

@@ -7,12 +7,15 @@
 import type { AgentTool } from "@sayknow-cli/agent-core";
 import { type Settings } from "../config/settings";
 import type { Theme } from "../modes/theme/theme";
-import { type OutputSummary, type TruncationResult } from "../session/streaming-output";
+import { type OutputSummary, type ReadWindow, type TruncationResult } from "../session/streaming-output";
 /**
  * Truncation metadata for the output notice.
  */
 export interface TruncationMeta {
     direction: "head" | "tail" | "middle";
+    /** Coordinate basis for shown/head/tail ranges. Omitted means file coordinates; "window" is the selected-range coordinate system. */
+    rangeBase?: "file" | "window";
+    noticeOwner?: "body";
     truncatedBy: "lines" | "bytes" | "middle";
     totalLines: number;
     totalBytes: number;
@@ -33,6 +36,12 @@ export interface TruncationMeta {
         start: number;
         end: number;
     };
+    /** Partial source-line preview retained by a directional window. */
+    partialLine?: {
+        line: number;
+        bytes: number;
+        sourceBytes: number;
+    };
     /** Bytes elided from the middle. */
     elidedBytes?: number;
     /** Lines elided from the middle. */
@@ -96,11 +105,14 @@ export interface TruncationOptions {
     startLine?: number;
     totalFileLines?: number;
     artifactId?: string;
+    maxBytes?: number;
+    noticeOwner?: "body";
 }
 export interface TruncationSummaryOptions {
     direction: "head" | "tail" | "middle";
     startLine?: number;
     totalFileLines?: number;
+    noticeOwner?: "body";
 }
 export interface TruncationTextOptions {
     direction: "head" | "tail" | "middle";
@@ -108,6 +120,7 @@ export interface TruncationTextOptions {
     totalBytes?: number;
     maxBytes?: number;
     artifactId?: string;
+    noticeOwner?: "body";
 }
 /**
  * Fluent builder for OutputMeta.
@@ -125,6 +138,13 @@ export declare class OutputMetaBuilder {
     #private;
     /** Add truncation info from TruncationResult. No-op if not truncated. */
     truncation(result: TruncationResult, options: TruncationOptions): this;
+    /** Add metadata from the actual head/tail windows retained by middle truncation. */
+    truncationWindows(windows: ReadWindow, options?: {
+        artifactId?: string;
+        noticeOwner?: "body";
+        maxBytes?: number;
+        rangeBase?: "file" | "window";
+    }): this;
     /** Add truncation info from OutputSummary. No-op if not truncated. */
     truncationFromSummary(summary: OutputSummary, options: TruncationSummaryOptions): this;
     /** Add truncation info from truncated output text. No-op if truncation not detected. */

package/dist/types/tools/read-internals.d.ts

@@ -0,0 +1,12 @@
+import type { Settings } from "../config/settings";
+import type { TruncationDirection } from "../session/streaming-output";
+/**
+ * Read execution routes that have distinct truncation-default contracts.
+ * Routes that share the same default are grouped only when their truncation
+ * policy is identical; selection and rendering remain owned by read.ts.
+ */
+export type ReadRoute = "local-bare-stream" | "local-bare-acp" | "archive-member-bare" | "local-range" | "local-multi-range" | "local-raw" | "local-summary" | "url-reader" | "url-cache-page" | "dir-local" | "dir-archive" | "sqlite-list" | "sqlite-rows" | "converted";
+/** Resolve the configured default for a route; explicit parameters bypass it. */
+export declare function pathDefault(route: ReadRoute, settings: Settings): TruncationDirection;
+/** Resolve the effective caller-facing direction with explicit precedence. */
+export declare function resolveEffectiveDirection(explicitParam: TruncationDirection | undefined, route: ReadRoute, settings: Settings): TruncationDirection;

package/dist/types/tools/read.d.ts

@@ -4,10 +4,49 @@ import * as z from "zod/v4";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { type Theme } from "../modes/theme/theme";
 import type { ToolSession } from "../sdk";
-import { type TruncationResult } from "../session/streaming-output";
+import type { ReadWindow, TruncationResult } from "../session/streaming-output";
 import { type OutputMeta } from "./output-meta";
+export declare function streamLinesFromFile(filePath: string, startLine: number, maxLinesToCollect: number, maxBytes: number, selectedLineLimit: number | null, signal?: AbortSignal, collect?: "head" | "tail" | "both", collectEndExclusive?: number | null): Promise<{
+    lines: string[];
+    totalFileLines: number;
+    collectedBytes: number;
+    stoppedByByteLimit: boolean;
+    firstLinePreview?: {
+        text: string;
+        bytes: number;
+    };
+    firstLineByteLength?: number;
+    selectedBytesTotal: number;
+    windowBytesTotal: number;
+    windowLinesTotal: number;
+    windowStartIndex: number;
+    tailPartial?: {
+        text: string;
+        bytes: number;
+        sourceIndex: number;
+        sourceLineBytes: number;
+    };
+    maxBytes: number;
+    headLines?: string[];
+    headBytes?: number;
+    headStartIndex?: number;
+    degenerateTailBudget: boolean;
+    degenerateHeadBudget: boolean;
+    headStoppedByBytes: boolean;
+    headStoppedByLines: boolean;
+    ringBudgetLines: number;
+    ringEvictedForBytes: boolean;
+    ringEvictedForLines: boolean;
+    tailDroppedForBytes: boolean;
+}>;
+export declare function streamResultWindow(result: Awaited<ReturnType<typeof streamLinesFromFile>>, collect: "tail" | "both", startLine: number, collectEndExclusive: number | null): ReadWindow;
 declare const readSchema: z.ZodObject<{
     path: z.ZodString;
+    truncation: z.ZodOptional<z.ZodEnum<{
+        head: "head";
+        last: "last";
+        both: "both";
+    }>>;
 }, z.core.$strict>;
 export type ReadToolInput = z.infer<typeof readSchema>;
 /** Project paths and output sizes without exposing read content or remote URLs. */
@@ -60,6 +99,11 @@ export declare class ReadTool implements AgentTool<typeof readSchema, ReadToolDe
     readonly description: string;
     readonly parameters: z.ZodObject<{
         path: z.ZodString;
+        truncation: z.ZodOptional<z.ZodEnum<{
+            head: "head";
+            last: "last";
+            both: "both";
+        }>>;
     }, z.core.$strict>;
     readonly nonAbortable = true;
     readonly strict = true;