@oh-my-pi/pi-coding-agent 15.1.1 → 15.1.3

package/dist/types/goals/tools/goal-tool.d.ts

@@ -0,0 +1,62 @@
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Component } from "@oh-my-pi/pi-tui";
+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 "../../tools";
+import type { Goal, GoalToolDetails } from "../state";
+declare const goalSchema: z.ZodObject<{
+    op: z.ZodEnum<{
+        complete: "complete";
+        create: "create";
+        get: "get";
+    }>;
+    objective: z.ZodOptional<z.ZodString>;
+    token_budget: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type GoalToolInput = z.infer<typeof goalSchema>;
+export interface GoalToolResponse {
+    goal: Goal | null;
+    remainingTokens: number | null;
+    completionBudgetReport: string | null;
+}
+export declare function buildGoalToolResponse(goal: Goal | null | undefined, options?: {
+    includeCompletionReport?: boolean;
+}): GoalToolResponse;
+export declare class GoalTool implements AgentTool<typeof goalSchema, GoalToolDetails> {
+    #private;
+    readonly name = "goal";
+    readonly label = "Goal";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        op: z.ZodEnum<{
+            complete: "complete";
+            create: "create";
+            get: "get";
+        }>;
+        objective: z.ZodOptional<z.ZodString>;
+        token_budget: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly intent: "omit";
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: GoalToolInput, _signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<GoalToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<GoalToolDetails>>;
+}
+interface GoalRenderArgs {
+    op?: GoalToolInput["op"];
+    objective?: string;
+    token_budget?: number;
+}
+export declare const goalToolRenderer: {
+    renderCall(args: GoalRenderArgs, _options: RenderResultOptions, uiTheme: Theme): Component;
+    renderResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: GoalToolDetails;
+        isError?: boolean;
+    }, _options: RenderResultOptions, uiTheme: Theme, args?: GoalRenderArgs): Component;
+    mergeCallAndResult: boolean;
+};
+export {};

package/dist/types/hashline/anchors.d.ts

@@ -0,0 +1,20 @@
+import type { HashMismatch } from "./types";
+export declare function formatFullAnchorRequirement(raw?: string): string;
+export declare function parseTag(ref: string): {
+    line: number;
+    hash: string;
+};
+export declare class HashlineMismatchError extends Error {
+    readonly mismatches: HashMismatch[];
+    readonly fileLines: string[];
+    readonly remaps: ReadonlyMap<string, string>;
+    constructor(mismatches: HashMismatch[], fileLines: string[]);
+    get displayMessage(): string;
+    private static rejectionHeader;
+    static formatDisplayMessage(mismatches: HashMismatch[], fileLines: string[]): string;
+    static formatMessage(mismatches: HashMismatch[], fileLines: string[]): string;
+}
+export declare function validateLineRef(ref: {
+    line: number;
+    hash: string;
+}, fileLines: string[]): void;

package/dist/types/hashline/apply.d.ts

@@ -0,0 +1,14 @@
+import type { HashlineApplyOptions, HashlineEdit } from "./types";
+export interface HashlineApplyResult {
+    lines: string;
+    firstChangedLine?: number;
+    warnings?: string[];
+    noopEdits?: HashlineNoopEdit[];
+}
+export interface HashlineNoopEdit {
+    editIndex: number;
+    loc: string;
+    reason: string;
+    current: string;
+}
+export declare function applyHashlineEdits(text: string, edits: HashlineEdit[], options?: HashlineApplyOptions): HashlineApplyResult;

package/dist/types/hashline/constants.d.ts

@@ -0,0 +1,21 @@
+/** Lines of context shown either side of a hash mismatch. */
+export declare const MISMATCH_CONTEXT = 2;
+/** Filler hash used for the interior of a multi-line range; not validated. */
+export declare const RANGE_INTERIOR_HASH = "**";
+/** Header marker introducing a new file section in multi-section input. */
+export declare const FILE_HEADER_PREFIX = "@";
+/** Optional patch envelope start marker; silently consumed when present. */
+export declare const BEGIN_PATCH_MARKER = "*** Begin Patch";
+/** Optional patch envelope end marker; terminates parsing when encountered. */
+export declare const END_PATCH_MARKER = "*** End Patch";
+/**
+ * Recovery sentinel emitted by the agent loop when a contaminated
+ * `to=functions.edit` stream is truncated mid-call (see
+ * `docs/ERRATA-GPT5-HARMONY.md`). Behaves like `END_PATCH_MARKER` for
+ * parsing — terminates the line loop — and additionally surfaces a
+ * warning in the tool result so the model knows to re-issue any
+ * remaining edits.
+ */
+export declare const ABORT_MARKER = "*** Abort";
+/** Warning text appended to the tool result when ABORT_MARKER terminates parsing. */
+export declare const ABORT_WARNING = "Tool stream truncated mid-call due to detected output corruption. Applied ops above are valid. Re-issue any remaining edits.";

package/dist/types/hashline/diff-preview.d.ts

@@ -0,0 +1,2 @@
+import type { CompactHashlineDiffOptions, CompactHashlineDiffPreview } from "./types";
+export declare function buildCompactHashlineDiffPreview(diff: string, _options?: CompactHashlineDiffOptions): CompactHashlineDiffPreview;

package/dist/types/hashline/diff.d.ts

@@ -0,0 +1,17 @@
+import { type HashlineInputSection } from "./input";
+import type { HashlineApplyOptions } from "./types";
+export declare function computeHashlineSectionDiff(section: HashlineInputSection, cwd: string, options?: HashlineApplyOptions): Promise<{
+    diff: string;
+    firstChangedLine: number | undefined;
+} | {
+    error: string;
+}>;
+export declare function computeHashlineDiff(input: {
+    input: string;
+    path?: string;
+}, cwd: string, options?: HashlineApplyOptions): Promise<{
+    diff: string;
+    firstChangedLine: number | undefined;
+} | {
+    error: string;
+}>;

package/dist/types/hashline/execute.d.ts

@@ -0,0 +1,4 @@
+import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import type { EditToolDetails } from "../edit/renderer";
+import type { ExecuteHashlineSingleOptions, hashlineEditParamsSchema } from "./types";
+export declare function executeHashlineSingle(options: ExecuteHashlineSingleOptions): Promise<AgentToolResult<EditToolDetails, typeof hashlineEditParamsSchema>>;

package/dist/types/hashline/hash.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Core hash utilities shared by hashline edit mode, read/search output,
+ * and prompt helpers.
+ */
+/**
+ * 647 single-token BPE bigrams for hashline anchors. Every entry tokenizes as
+ * exactly one token in modern BPE vocabularies (cl100k / o200k / Claude family),
+ * so a hashline anchor built from one bigram is exactly 1 token.
+ *
+ * This is the complete set of 2-letter lowercase combinations that are single
+ * tokens — the 29 missing combinations are rare-letter pairs (q/x/z heavy)
+ * that no major BPE vocabulary merges into a single token.
+ *
+ * Order is stable forever — changing it would invalidate every saved
+ * `LINE+ID` reference in transcripts and prompts.
+ */
+export declare const HL_BIGRAMS: readonly string[];
+export declare const HL_BIGRAMS_COUNT: number;
+/**
+ * Decoration prefix that may precede a `LINE+HASH` anchor in tool output:
+ * `>` (context line in grep), `+` (added line in diff), `-` (removed line),
+ * `*` (match line). Any combination, in any order, surrounded by optional
+ * whitespace. Output formatters emit at most one decoration per anchor; the
+ * regex stays liberal because anchor-ref parsers accept whatever the model
+ * echoes back.
+ */
+export declare const HL_ANCHOR_DECORATION_RE_RAW = "\\s*[>+\\-*]*\\s*";
+/**
+ * Capture-group regex source for a decorated `LINE+HASH` anchor. Group 1
+ * captures the line number (digits only); group 2 captures the hash. The
+ * source is intentionally unanchored — anchoring with `^` (or composing into a
+ * larger pattern) is the caller's responsibility.
+ */
+export declare const HL_ANCHOR_RE_RAW = "\\s*[>+\\-*]*\\s*(\\d+)([a-z]{2})";
+/**
+ * Bare `LINE+HASH` Lid (no decorations, no captures, no anchors). Use for
+ * embedding inside larger patterns where the line+hash unit appears as a
+ * literal (e.g. range bounds, alternation arms, op-line heuristics).
+ */
+export declare const HL_HASH_RE_RAW = "[1-9]\\d*[a-z]{2}";
+/**
+ * Capture-group form of {@link HL_HASH_RE_RAW}: group 1 captures the
+ * line number, group 2 captures the hash.
+ */
+export declare const HL_HASH_CAPTURE_RE_RAW = "([1-9]\\d*)([a-z]{2})";
+/** Width of a hash in display characters. */
+export declare const HL_HASH_WIDTH = 2;
+/**
+ * Representative hash suffixes for use in user-facing error messages and
+ * prompt examples.
+ */
+export declare const HL_HASH_EXAMPLES: readonly ["sr", "ab", "th"];
+/**
+ * Format a comma-separated list of example anchors with an optional line-number
+ * prefix, quoted for inclusion in error messages: `"160sr", "160ab", "160th"`.
+ */
+export declare function describeAnchorExamples(linePrefix?: string): string;
+/**
+ * Substitute every grammar placeholder with the value derived from its
+ * TypeScript counterpart. Grammars that don't reference these placeholders
+ * pass through unchanged.
+ */
+export declare function resolveHashlineGrammarPlaceholders(grammar: string): string;
+/** @deprecated Use {@link resolveHashlineGrammarPlaceholders}. */
+export declare const resolveLarkLidPlaceholders: typeof resolveHashlineGrammarPlaceholders;
+/**
+ * Single source of truth for the hashline edit payload separator. This is the
+ * configured separator that starts inserted/replacement payload lines in
+ * hashline edit input (`<separator>TEXT`) and separates inline modify ops from
+ * their appended/prepended text.
+ *
+ * Override at runtime with the `PI_HL_SEP` env var (e.g.
+ * `PI_HL_SEP=">"`, `PI_HL_SEP="\\"`). The value is read once at module load;
+ * the edit grammar, prompt helper, and edit parser derive from it.
+ *
+ * Default is `~`, chosen empirically. Benchmark across 8 candidate separators
+ * x 3 models (glm-4.7:nitro, gpt-5.4-nano, claude-sonnet-4-6), 24-48 runs per
+ * cell, hashline variant, 12 sampled tasks per run:
+ *
+ *   sep | task ✓ | edit ✓ | patch fail      | tok/run
+ *   ----|--------|--------|-----------------|--------
+ *    +  | 70.8%  | 78.0%  | 27/125 (21.6%)  | 32,127
+ *    ÷  | 70.7%  | 90.6%  | 22/211 (10.4%)  | 31,666
+ *    ~  | 69.4%  | 94.9%  |  6/107 ( 5.6%)  | 30,529   <-- default
+ *    >  | 69.2%  | 91.5%  | 21/219 ( 9.6%)  | 30,777
+ *    :  | 66.7%  | 86.4%  | 20/126 (15.9%)  | 33,900
+ *    |  | 65.9%  | 86.9%  | 20/127 (15.7%)  | 34,589
+ *    \  | 65.5%  | 89.8%  | 16/124 (12.9%)  | 36,010
+ *    %  | 63.9%  | 92.8%  | 11/125 ( 8.8%)  | 36,530
+ *
+ * `~` wins because:
+ *   - highest edit-tool success rate (94.9%) of any tested separator
+ *   - lowest patch-failure rate (5.6%) — model rarely emits a malformed payload
+ *   - cheapest in tokens alongside `>` (no retry overhead from format collisions)
+ *   - no line-leading role in any mainstream language, markdown, diff, regex,
+ *     or shell, so payload lines are unambiguous to both the parser and models
+ *   - task-success is statistically tied with `>` and `÷` (within run-to-run
+ *     noise), so the edit-reliability win is free
+ *
+ * `+` and `÷` lead on raw task-success but at the cost of ~2-4x more patch
+ * failures (the model retries until it lands a valid edit). `:`, `|`, `\`
+ * collide with line-leading syntax (label/object-key, body separator, escape)
+ * and degrade both edit reliability and intent-match.
+ */
+export declare const HL_EDIT_SEP: string;
+/** Regex-escaped form of {@link HL_EDIT_SEP}, safe for regexes. */
+export declare const HL_EDIT_SEP_RE_RAW: string;
+/** Stable separator for read/search/hashline display output. Intentionally not configurable. */
+export declare const HL_BODY_SEP = "|";
+/** Regex-escaped form of {@link HL_BODY_SEP}, safe for embedding inside a regex. */
+export declare const HL_BODY_SEP_RE_RAW: string;
+/**
+ * Compute a 2-character hash of a single line via xxHash32 mod 647 over
+ * {@link HL_BIGRAMS}. Lines with no letter or digit mix the line number
+ * into the seed so adjacent identical punctuation-only lines (e.g. brace-only
+ * lines) get distinct hashes; lines with significant content stay
+ * line-number-independent so a line is identifiable across small shifts.
+ *
+ * The line input should not include a trailing newline.
+ */
+export declare function computeLineHash(idx: number, line: string): string;
+/**
+ * Formats an anchor reference given a line number and its text.
+ * Returns `LINE+ID` (e.g., `42sr`) — no separator between
+ * number and hash.
+ */
+export declare function formatLineHash(line: number, lines: string): string;
+/**
+ * Formats a single line with a hashline anchor.
+ * Returns `LINE+ID|TEXT` (e.g., `42sr|function hi() {`, `3ab|}`).
+ */
+export declare function formatHashLine(lineNumber: number, line: string): string;
+/**
+ * Format file text with hashline prefixes for display.
+ *
+ * Each line becomes `LINE+ID|TEXT` where LINENUM is 1-indexed.
+ * No padding on line numbers; pipe separator between anchor and content.
+ *
+ * @param text - Raw file text string
+ * @param startLine - First line number (1-indexed, defaults to 1)
+ * @returns Formatted string with one hashline-prefixed line per input line
+ *
+ * @example
+ * ```
+ * formatHashLines("function hi() {\n  return;\n}")
+ * // "1bm|function hi() {\n2er|  return;\n3ab|}"
+ * ```
+ */
+export declare function formatHashLines(text: string, startLine?: number): string;

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

@@ -0,0 +1,13 @@
+export * from "./anchors";
+export * from "./apply";
+export * from "./constants";
+export * from "./diff";
+export * from "./diff-preview";
+export * from "./execute";
+export * from "./hash";
+export * from "./input";
+export * from "./parser";
+export * from "./prefixes";
+export * from "./recovery";
+export * from "./stream";
+export * from "./types";

package/dist/types/hashline/input.d.ts

@@ -0,0 +1,11 @@
+import type { SplitHashlineOptions } from "./types";
+export interface HashlineInputSection {
+    path: string;
+    diff: string;
+}
+export declare function containsRecognizableHashlineOperations(input: string): boolean;
+export declare function splitHashlineInput(input: string, options?: SplitHashlineOptions): {
+    path: string;
+    diff: string;
+};
+export declare function splitHashlineInputs(input: string, options?: SplitHashlineOptions): HashlineInputSection[];

package/dist/types/hashline/parser.d.ts

@@ -0,0 +1,7 @@
+import type { HashlineCursor, HashlineEdit } from "./types";
+export declare function cloneCursor(cursor: HashlineCursor): HashlineCursor;
+export declare function parseHashline(diff: string): HashlineEdit[];
+export declare function parseHashlineWithWarnings(diff: string): {
+    edits: HashlineEdit[];
+    warnings: string[];
+};

package/dist/types/hashline/prefixes.d.ts

@@ -0,0 +1,7 @@
+export declare function stripNewLinePrefixes(lines: string[]): string[];
+export declare function stripHashlinePrefixes(lines: string[]): string[];
+/**
+ * Normalize line payloads by stripping read/search line prefixes. `null` /
+ * `undefined` yield `[]`; a single multiline string is split on `\n`.
+ */
+export declare function hashlineParseText(edit: string[] | string | null | undefined): string[];

package/dist/types/hashline/recovery.d.ts

@@ -0,0 +1,22 @@
+import type { FileReadCache } from "../edit/file-read-cache";
+import type { HashlineApplyOptions, HashlineEdit } from "./types";
+export interface HashlineRecoveryArgs {
+    cache: FileReadCache;
+    absolutePath: string;
+    currentText: string;
+    edits: HashlineEdit[];
+    options: HashlineApplyOptions;
+}
+export interface HashlineRecoveryResult {
+    lines: string;
+    firstChangedLine: number | undefined;
+    warnings: string[];
+}
+/**
+ * Attempt to recover from a `HashlineMismatchError` by replaying the edits
+ * against a cached pre-edit snapshot of the file and 3-way-merging the result
+ * onto the current on-disk content. Returns `null` when no recovery is
+ * possible — callers should propagate the original mismatch error in that
+ * case.
+ */
+export declare function tryRecoverHashlineWithCache(args: HashlineRecoveryArgs): HashlineRecoveryResult | null;

package/dist/types/hashline/stream.d.ts

@@ -0,0 +1,2 @@
+import type { HashlineStreamOptions } from "./types";
+export declare function streamHashLinesFromUtf8(source: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, options?: HashlineStreamOptions): AsyncGenerator<string>;

package/dist/types/hashline/types.d.ts

@@ -0,0 +1,77 @@
+import * as z from "zod/v4";
+import type { LspBatchRequest } from "../edit/renderer";
+import type { WritethroughCallback, WritethroughDeferredHandle } from "../lsp";
+import type { ToolSession } from "../tools";
+export interface HashMismatch {
+    line: number;
+    expected: string;
+    actual: string;
+}
+export type Anchor = {
+    line: number;
+    hash: string;
+    contentHint?: string;
+};
+export type HashlineCursor = {
+    kind: "bof";
+} | {
+    kind: "eof";
+} | {
+    kind: "before_anchor";
+    anchor: Anchor;
+} | {
+    kind: "after_anchor";
+    anchor: Anchor;
+};
+export type HashlineEdit = {
+    kind: "insert";
+    cursor: HashlineCursor;
+    text: string;
+    lineNum: number;
+    index: number;
+} | {
+    kind: "delete";
+    anchor: Anchor;
+    lineNum: number;
+    index: number;
+    oldAssertion?: string;
+};
+/** `path` is accepted by the edit tool runtime; other extra keys are preserved. */
+export declare const hashlineEditParamsSchema: z.ZodObject<{
+    input: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type HashlineParams = z.infer<typeof hashlineEditParamsSchema>;
+export interface HashlineStreamOptions {
+    /** First line number to use when formatting (1-indexed). */
+    startLine?: number;
+    /** Maximum formatted lines per yielded chunk (default: 200). */
+    maxChunkLines?: number;
+    /** Maximum UTF-8 bytes per yielded chunk (default: 64 KiB). */
+    maxChunkBytes?: number;
+}
+export interface CompactHashlineDiffPreview {
+    preview: string;
+    addedLines: number;
+    removedLines: number;
+}
+export interface CompactHashlineDiffOptions {
+    /** Maximum entries kept on each side of an unchanged-context truncation (default: 2). */
+    maxUnchangedRun?: number;
+}
+export interface HashlineApplyOptions {
+    autoDropPureInsertDuplicates?: boolean;
+}
+export interface SplitHashlineOptions {
+    cwd?: string;
+    path?: string;
+}
+export interface ExecuteHashlineSingleOptions {
+    session: ToolSession;
+    input: string;
+    path?: string;
+    signal?: AbortSignal;
+    batchRequest?: LspBatchRequest;
+    writethrough: WritethroughCallback;
+    beginDeferredDiagnosticsForPath: (path: string) => WritethroughDeferredHandle;
+}

package/dist/types/hindsight/backend.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Hindsight memory backend.
+ *
+ * Wires the per-session lifecycle (recall on first turn, retain every Nth
+ * agent_end, etc.) on top of the AgentSession event stream. Hindsight runtime
+ * state is owned by the AgentSession so lifetime follows the actual domain
+ * owner instead of a parallel session-id registry.
+ */
+import type { MemoryBackend } from "../memory-backend/types";
+import type { AgentSession } from "../session/agent-session";
+/** Reload the active session's mental-model cache and prompt. */
+export declare function reloadMentalModelsForSession(session: AgentSession): Promise<boolean>;
+export declare const hindsightBackend: MemoryBackend;

package/dist/types/hindsight/bank.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Bank ID derivation, project-tag scoping, and first-use mission setup.
+ *
+ * Three scoping modes (`HindsightConfig.scoping`):
+ *   - `global`              — single shared bank, no per-project filter.
+ *   - `per-project`         — one bank per cwd basename, hard isolation.
+ *   - `per-project-tagged`  — single shared bank, retains carry a `project:<name>`
+ *                              tag and recall filters on it but still surfaces
+ *                              untagged ("global") memories alongside.
+ *
+ * The base bank id is `bankIdPrefix-bankId` (default `omp`). Per-project mode
+ * appends `-<project>`; tagged mode leaves the bank untouched and uses tags.
+ *
+ * Mission setup is idempotent at module level — a missionsSet keeps track of
+ * banks we've already POSTed to so each session boundary doesn't fire a fresh
+ * `createBank` call. Failures are swallowed: missions are an optimisation, not
+ * a precondition for retain/recall.
+ */
+import type { HindsightApi } from "./client";
+import type { HindsightConfig } from "./config";
+export type RecallTagsMatch = "any" | "all" | "any_strict" | "all_strict";
+/**
+ * Resolved bank target for a session: which bank to talk to, plus optional
+ * tags to attach to retains and to filter recalls by.
+ */
+export interface BankScope {
+    bankId: string;
+    /** Tags applied to every retain. Undefined when scoping does not use tags. */
+    retainTags?: string[];
+    /** Tags filter for recall/reflect. Undefined when scoping does not use tags. */
+    recallTags?: string[];
+    /** Match mode for `recallTags`. Defaults to `any` so untagged ("global") memories surface too. */
+    recallTagsMatch?: RecallTagsMatch;
+}
+/**
+ * Resolve the active bank target plus optional tag scoping.
+ *
+ * Always returns a non-empty `bankId`. Tag fields are populated only for
+ * `per-project-tagged`.
+ */
+export declare function computeBankScope(config: HindsightConfig, directory: string): BankScope;
+/**
+ * Backwards-compatible thin wrapper: just return the bank id portion of the
+ * scope. New code should prefer `computeBankScope` directly so it can also
+ * apply the tag fields.
+ */
+export declare function deriveBankId(config: HindsightConfig, directory: string): string;
+/**
+ * Ensure a bank's reflect/retain mission is set, exactly once per process.
+ *
+ * Tracked via the supplied set; on overflow we drop the oldest half so the set
+ * cannot grow unboundedly across long-lived processes.
+ */
+export declare function ensureBankMission(client: HindsightApi, bankId: string, config: HindsightConfig, missionsSet: Set<string>): Promise<void>;