@xiaoso/dsh-tool-plus 0.1.6 → 0.1.7-beta.1

package/lib/types/tools/omp/session/streaming-output.d.ts

@@ -0,0 +1,244 @@
+import type { AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+export declare const DEFAULT_MAX_LINES = 3000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const DEFAULT_MAX_COLUMN = 512;
+/**
+ * Default artifact-on-disk cap for {@link OutputSink}.
+ *
+ * `0` means unbounded: by default, `artifact://<id>` references preserve the
+ * complete raw stream instead of a capped head/tail sample.
+ */
+export declare const ARTIFACT_DEFAULT_MAX_BYTES = 0;
+/** Default head budget; the remainder becomes the rolling tail window. */
+export declare const ARTIFACT_DEFAULT_HEAD_BYTES: number;
+export interface OutputSummary {
+    output: string;
+    truncated: boolean;
+    totalLines: number;
+    totalBytes: number;
+    outputLines: number;
+    outputBytes: number;
+    /** Bytes elided from the middle when head-retain mode is active. */
+    elidedBytes?: number;
+    /** Lines elided from the middle when head-retain mode is active. */
+    elidedLines?: number;
+    /** Bytes dropped by the per-line column cap (sum across all lines). */
+    columnDroppedBytes?: number;
+    /** Number of distinct lines that hit the per-line column cap. */
+    columnTruncatedLines?: number;
+    /** Configured per-line column cap in effect (chars), when > 0. */
+    columnMax?: number;
+    /** Artifact ID for internal URL access (artifact://<id>) when truncated */
+    artifactId?: string;
+}
+export interface OutputSinkOptions {
+    artifactPath?: string;
+    artifactId?: string;
+    /**
+     * Total inline body budget (bytes). Default DEFAULT_MAX_BYTES. The head
+     * window and rolling tail window share this budget, so a composed
+     * `dump()` body never exceeds it (plus the elision marker).
+     */
+    spillThreshold?: number;
+    /**
+     * When > 0, the sink keeps the first `headBytes` of output in addition to
+     * the rolling tail window. Output between the two windows is elided
+     * (middle elision). Clamped to `spillThreshold / 2` so the tail keeps at
+     * least half the inline budget. Default 0 = tail-only behavior.
+     */
+    headBytes?: number;
+    /**
+     * Per-line byte cap. When > 0, lines wider than `maxColumns` bytes are
+     * truncated with an ellipsis at write time; remaining bytes up to the next
+     * `\n` are dropped. Cap state persists across chunks so split-mid-line
+     * writes still respect the budget. Default 0 = no per-line cap.
+     */
+    maxColumns?: number;
+    onChunk?: (chunk: string) => void;
+    /** Minimum ms between onChunk calls. 0 = every chunk (default). */
+    chunkThrottleMs?: number;
+    /**
+     * Optional cap on bytes written to the artifact-on-disk file. When the cap
+     * is hit, the head window is preserved verbatim and subsequent output feeds
+     * a rolling tail window; on close, the sink writes a single
+     * `[ARTIFACT TRUNCATED: …]` notice between them. Default
+     * {@link ARTIFACT_DEFAULT_MAX_BYTES} (unbounded).
+     */
+    artifactMaxBytes?: number;
+    /**
+     * Bytes reserved for the head window of the capped artifact file. The
+     * tail window receives `artifactMaxBytes - artifactHeadBytes`. Default
+     * {@link ARTIFACT_DEFAULT_HEAD_BYTES}; clamped to `[0, artifactMaxBytes]`.
+     */
+    artifactHeadBytes?: number;
+}
+export interface TruncationResult {
+    content: string;
+    truncated?: boolean;
+    truncatedBy?: "lines" | "bytes" | "middle";
+    totalLines: number;
+    totalBytes: number;
+    outputLines?: number;
+    outputBytes?: number;
+    /** Bytes elided from the middle (truncateMiddle only). */
+    elidedBytes?: number;
+    /** Lines elided from the middle (truncateMiddle only). */
+    elidedLines?: number;
+    lastLinePartial?: boolean;
+    firstLineExceedsLimit?: boolean;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 3000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+    /**
+     * For `truncateMiddle`: bytes reserved for the head window. The tail
+     * window receives `maxBytes - maxHeadBytes`. Default `floor(maxBytes/2)`.
+     */
+    maxHeadBytes?: number;
+    /**
+     * For `truncateMiddle`: lines reserved for the head window. The tail
+     * window receives `maxLines - maxHeadLines`. Default `floor(maxLines/2)`.
+     */
+    maxHeadLines?: number;
+}
+/** Result from byte-level truncation helpers. */
+export interface ByteTruncationResult {
+    text: string;
+    bytes: number;
+}
+export interface TailTruncationNoticeOptions {
+    fullOutputPath?: string;
+    originalContent?: string;
+    suffix?: string;
+}
+export interface HeadTruncationNoticeOptions {
+    startLine?: number;
+    totalFileLines?: number;
+}
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the tail.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateTailBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a string/buffer to fit within a byte limit, keeping the head.
+ * Handles multi-byte UTF-8 boundaries correctly.
+ */
+export declare function truncateHeadBytes(data: string | Uint8Array, maxBytes: number): ByteTruncationResult;
+/**
+ * Truncate a single line to max characters, appending '…' if truncated.
+ */
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+/** Shared helper to build a no-truncation result. */
+export declare function noTruncResult(content: string, totalLines?: number, totalBytes?: number): TruncationResult;
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Never returns partial lines. If the first line exceeds the byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ *
+ * This implementation avoids Buffer.from(content) for the whole input.
+ * It only computes UTF-8 byteLength for candidate lines that can still fit.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * May return a partial first line if the last line exceeds the byte limit.
+ *
+ * Also avoids Buffer.from(content) for the whole input.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Format the inline marker substituted for the elided middle region.
+ * Returned without surrounding newlines so callers can position it freely.
+ */
+export declare function formatMiddleElisionMarker(elidedLines: number, elidedBytes: number): string;
+/**
+ * Truncate content keeping a head window and a tail window, eliding the middle.
+ *
+ * The combined output is `<head>\n<marker>\n<tail>` when truncation is needed.
+ * `maxHeadBytes` defaults to `floor(maxBytes / 2)`; the tail receives the
+ * remainder. Falls back to `truncateTail` / `truncateHead` if either side's
+ * budget is empty or the content already fits.
+ */
+export declare function truncateMiddle(content: string, options?: TruncationOptions): TruncationResult;
+/** Options for {@link enforceInlineByteCap}. */
+export interface InlineByteCapOptions {
+    /** Inline byte budget. Defaults to {@link DEFAULT_MAX_BYTES}. */
+    maxBytes?: number;
+    /**
+     * Persist the full text as a session artifact. When an artifact id is
+     * returned, a `[raw output: artifact://<id>]` footer is appended so the
+     * elided bytes stay recoverable.
+     */
+    saveArtifact?: (full: string) => string | undefined | Promise<string | undefined>;
+}
+/**
+ * Final-defense inline size guard for tool results.
+ *
+ * No-op when `text` fits within `maxBytes` (the common path). Otherwise keeps
+ * ~60% of the budget from the head and ~25% from the tail — cut on line
+ * boundaries, never splitting a multi-byte UTF-8 sequence — with an elision
+ * marker between. The remaining ~15% is slack for the marker and the optional
+ * `[raw output: artifact://<id>]` footer, so the result stays under `maxBytes`.
+ */
+export declare function enforceInlineByteCap(text: string, options: InlineByteCapOptions): Promise<string>;
+export declare class TailBuffer {
+    #private;
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+    append(text: string): void;
+    text(): string;
+    bytes(): number;
+}
+export declare class OutputSink {
+    #private;
+    constructor(options?: OutputSinkOptions);
+    /**
+     * Push a chunk of output. The buffer management and onChunk callback run
+     * synchronously. File sink writes are deferred and serialized internally.
+     */
+    push(chunk: string): void;
+    createInput(): WritableStream<Uint8Array | string>;
+    /**
+     * Replace the in-memory buffer with the given text. Used when an upstream
+     * minimizer rewrites the captured output after the raw bytes have already
+     * been streamed.
+     *
+     * After this call the buffer is authoritative: streaming counters realign
+     * to the replacement, the retained head window is cleared, and head
+     * retention is disabled so subsequent `push()` calls append directly to the
+     * tail buffer instead of repopulating the (now meaningless) head window
+     * — which would otherwise reorder content and trip the middle-elision
+     * branch in `dump()` against stale totals.
+     */
+    replace(text: string): void;
+    dump(notice?: string): Promise<OutputSummary>;
+    /**
+     * Release the artifact spill descriptor on an exit path that skips
+     * {@link dump} — a thrown error or abort. Idempotent and safe in a
+     * `finally`: if {@link dump} already ran this is a no-op, otherwise it
+     * flushes the capped tail and closes the sink so the descriptor is not
+     * leaked until a later unrelated read hits `EMFILE` (issue #6463).
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Format a truncation notice for tail-truncated output (bash, python, ssh).
+ * Returns empty string if not truncated.
+ */
+export declare function formatTailTruncationNotice(truncation: TruncationResult, options?: TailTruncationNoticeOptions): string;
+/**
+ * Format a truncation notice for head-truncated output (read tool).
+ * Returns empty string if not truncated.
+ */
+export declare function formatHeadTruncationNotice(truncation: TruncationResult, options?: HeadTruncationNoticeOptions): string;
+/**
+ * Build an onChunk handler that appends to a TailBuffer and emits a streaming
+ * update (when `onUpdate` is defined) with the buffer's current text.
+ */
+export declare function streamTailUpdates<TDetails, TInput = unknown>(tailBuffer: TailBuffer, onUpdate: AgentToolUpdateCallback<TDetails, TInput> | undefined): (chunk: string) => void;

package/lib/types/tools/omp/task/spawn-policy.d.ts

@@ -0,0 +1,22 @@
+/** Default agent used when a session has unrestricted spawning. */
+export declare const DEFAULT_SPAWN_AGENT = "task";
+/** Spawn policy derived from a parent agent's `spawns` frontmatter. */
+export interface ResolvedSpawnPolicy {
+    /** True when at least one subagent may be spawned. */
+    enabled: boolean;
+    /** Agent used when the caller omits the agent field. */
+    defaultAgent: string;
+    /** Explicitly allowed agents, or `null` when the policy is unrestricted. */
+    allowedAgents: readonly string[] | null;
+    /** Text used in spawn rejection messages. */
+    allowedErrorText: string;
+    /** Backtick-quoted explicit agents for prompt descriptions. */
+    allowedPromptText?: string;
+}
+/** Resolves spawn frontmatter into the default and prompt/error surfaces. */
+export declare function resolveSpawnPolicy(parentSpawns: string | boolean | null | undefined): ResolvedSpawnPolicy;
+/**
+ * Whether the `scout` agent is spawnable in a session: not disabled via
+ * `task.disabledAgents`, and permitted by the session spawn policy.
+ */
+export declare function isScoutSpawnable(disabledAgents: readonly string[] | undefined, spawns: string | boolean | null | undefined): boolean;

package/lib/types/tools/omp/tools/approval.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool approval resolution.
+ *
+ * Approval policy is declared by each tool. This module only knows how to:
+ * - normalize user `tools.approval.<tool>: allow | deny | prompt` overrides,
+ * - compare a tool capability tier against the active approval mode,
+ * - format the generic approval prompt body.
+ */
+import type { AgentTool, ToolTier } from "@oh-my-pi/pi-agent-core";
+export type { ToolApproval, ToolApprovalDecision, ToolTier } from "@oh-my-pi/pi-agent-core";
+export type ApprovalPolicy = "allow" | "deny" | "prompt";
+export type ApprovalMode = "always-ask" | "write" | "yolo";
+type ApprovalSubject = Pick<AgentTool, "name" | "approval" | "formatApprovalDetails">;
+export interface ResolvedApproval {
+    policy: ApprovalPolicy;
+    tier: ToolTier;
+    reason?: string;
+    override: boolean;
+    source?: "tool" | "user" | "mode";
+    /** User-policy key that produced `source: "user"` (defaults to the tool name). */
+    policyKey?: string;
+}
+/**
+ * Evaluate a tool's own approval declaration against `args` and return the
+ * resulting capability tier, defaulting to `exec` when the tool omits an
+ * approval. Unlike reading `tool.approval` directly, this runs function-valued
+ * approvals — the write tool's `xd://` gate uses it to take a mounted device's
+ * argument-dependent tier instead of falling back to `exec`.
+ */
+export declare function resolveToolTier(tool: ApprovalSubject, args: unknown): ToolTier;
+/**
+ * Resolve approval policy for a tool call.
+ *
+ * Resolution order:
+ *  1. Tool `approval(args)` decision, defaulting to tier "exec" when omitted.
+ *     A decision may carry a `policyKey` — `tools.approval.<policyKey>` is then
+ *     the user override consulted instead of `tools.approval.<tool.name>`, with
+ *     the invoking tool's own policy as the fallback when the user set none for
+ *     the keyed sub-tool (e.g. an `xd://` device dispatch without a device
+ *     policy still honors `tools.approval.write`).
+ *  2. User per-tool override, if set and valid.
+ *  3. Active mode tier comparison.
+ *
+ * In yolo mode, override-based tool prompts are ignored; user `tools.approval`
+ * settings remain authoritative.
+ */
+export declare function resolveApproval(tool: ApprovalSubject, args: unknown, mode: ApprovalMode, userConfig?: Record<string, unknown>): ResolvedApproval;
+/**
+ * Check if a tool call requires user approval.
+ *
+ * @throws Error if policy is 'deny'
+ * @returns Object with required flag and optional reason for the prompt
+ */
+export declare function requiresApproval(tool: ApprovalSubject, args: unknown, mode: ApprovalMode, userConfig?: Record<string, unknown>): {
+    required: boolean;
+    reason?: string;
+};
+export declare function truncateForPrompt(value: string, maxChars?: number): string;
+/**
+ * Format the approval prompt body shown to the user.
+ */
+export declare function formatApprovalPrompt(tool: ApprovalSubject, args: unknown, reason?: string): string;

package/lib/types/tools/omp/tools/ast-edit.d.ts

@@ -0,0 +1,73 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
+import type { ToolSession } from "../sdk";
+import type { OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const astEditSchema: import("@oh-my-pi/omptype").FluentType<{
+    paths: string[];
+    ops: {
+        out: string;
+        pat: string;
+    }[];
+}, {
+    paths: string[];
+    ops: {
+        out: string;
+        pat: string;
+    }[];
+}>;
+export interface AstEditToolDetails {
+    totalReplacements: number;
+    filesTouched: number;
+    filesSearched: number;
+    applied: boolean;
+    limitReached: boolean;
+    parseErrors?: string[];
+    /** Total parse error count before {@link PARSE_ERRORS_LIMIT} capping. Omitted when no errors. */
+    parseErrorsTotal?: number;
+    scopePath?: string;
+    files?: string[];
+    fileReplacements?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter (no model-only hashline anchors). The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+    /** Absolute base directory used during the edit. Used by the renderer to resolve
+     * display-relative paths to absolute paths for OSC 8 hyperlinks. */
+    searchPath?: string;
+    /** Session cwd at edit time. Display header paths are cwd-relative, so the
+     * renderer resolves them against this; `searchPath` is the scope target. */
+    cwd?: string;
+}
+type AstEditSchemaInfer = typeof astEditSchema.infer;
+export declare class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolDetails> {
+    private readonly session;
+    readonly name = "ast_edit";
+    readonly approval: (args: unknown) => "read" | "write";
+    readonly formatApprovalDetails: (args: unknown) => string[];
+    readonly label = "AST Edit";
+    readonly summary = "Perform AST-aware code edits (structural refactoring)";
+    readonly description: string;
+    readonly parameters: import("@oh-my-pi/omptype").FluentType<{
+        paths: string[];
+        ops: {
+            out: string;
+            pat: string;
+        }[];
+    }, {
+        paths: string[];
+        ops: {
+            out: string;
+            pat: string;
+        }[];
+    }>;
+    readonly strict = true;
+    readonly examples: readonly ToolExample<AstEditSchemaInfer>[];
+    readonly deferrable = true;
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: AstEditSchemaInfer, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AstEditToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<AstEditToolDetails>>;
+}
+export {};

package/lib/types/tools/omp/tools/ast-grep.d.ts

@@ -0,0 +1,61 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ToolExample } from "@oh-my-pi/pi-ai";
+import type { ToolSession } from "../sdk";
+import type { OutputMeta } from "../../omp/tools/output-meta.ts";
+declare const astGrepSchema: import("@oh-my-pi/omptype").FluentType<{
+    pat: string;
+    path?: string | undefined;
+    skip?: number | undefined;
+}, {
+    pat: string;
+    path?: string | undefined;
+    skip?: number | undefined;
+}>;
+export interface AstGrepToolDetails {
+    matchCount: number;
+    fileCount: number;
+    filesSearched: number;
+    limitReached: boolean;
+    parseErrors?: string[];
+    /** Total parse error count before {@link PARSE_ERRORS_LIMIT} capping. Omitted when no errors. */
+    parseErrorsTotal?: number;
+    scopePath?: string;
+    files?: string[];
+    fileMatches?: Array<{
+        path: string;
+        count: number;
+    }>;
+    meta?: OutputMeta;
+    /** Pre-formatted text for the user-visible TUI render. Mirrors `result.text` lines but uses
+     * a `│` gutter and `*` to mark match lines. The TUI uses this directly so it never parses model-facing text. */
+    displayContent?: string;
+    /** Absolute base directory used during search. Used by the renderer to resolve
+     * display-relative paths to absolute paths for OSC 8 hyperlinks. */
+    searchPath?: string;
+    /** Session cwd at search time. Display header/match paths are cwd-relative, so
+     * the renderer resolves them against this; `searchPath` is the scope target. */
+    cwd?: string;
+}
+export declare class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolDetails> {
+    private readonly session;
+    readonly name = "ast_grep";
+    readonly approval: "read";
+    readonly label = "AST Grep";
+    readonly summary = "Search code with AST patterns (structural grep)";
+    get description(): string;
+    readonly parameters: import("@oh-my-pi/omptype").FluentType<{
+        pat: string;
+        path?: string | undefined;
+        skip?: number | undefined;
+    }, {
+        pat: string;
+        path?: string | undefined;
+        skip?: number | undefined;
+    }>;
+    readonly strict = true;
+    readonly examples: readonly ToolExample<typeof astGrepSchema.inferIn>[];
+    readonly loadMode = "discoverable";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: typeof astGrepSchema.infer, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AstGrepToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<AstGrepToolDetails>>;
+}
+export {};

package/lib/types/tools/omp/tools/auto-generated-guard.d.ts

@@ -0,0 +1,20 @@
+import { type Settings } from "../config/settings.ts";
+/**
+ * Check if a file is auto-generated by examining its content.
+ * Throws ToolError if the file appears to be auto-generated.
+ *
+ * @param absolutePath - Absolute path to the file
+ * @param displayPath - Path to show in error messages (relative or as provided)
+ * @param activeSettings - Session settings; falls back to global settings or the schema default
+ */
+export declare function assertEditableFile(absolutePath: string, displayPath?: string, activeSettings?: Settings): Promise<void>;
+/**
+ * Check if file content is auto-generated.
+ * Uses only the first CHECK_BYTE_COUNT characters of the content.
+ * Throws ToolError if the content appears to be auto-generated.
+ *
+ * @param content - File content to check (can be full content or prefix)
+ * @param displayPath - Path to show in error messages
+ * @param activeSettings - Session settings; falls back to global settings or the schema default
+ */
+export declare function assertEditableFileContent(content: string, displayPath: string, activeSettings?: Settings): void;