@sayknow-cli/coding-agent 0.4.2 → 0.4.3

package/dist/types/harness-control-plane/seams.d.ts

@@ -0,0 +1,21 @@
+/**
+ * v1 seams (M11). The control plane is harness-agnostic by design, but v1 ships ONLY the
+ * sayknow-cli adapter. Other harnesses and transports are explicit, designed-not-built seams
+ * that fail closed with a clear `seam_unsupported_in_v1` signal rather than silently degrading.
+ */
+import type { Harness } from "./types";
+export declare const SUPPORTED_HARNESSES: readonly Harness[];
+export declare const DEFERRED_SEAMS: readonly ["codex-adapter", "omx-adapter", "remote-transport", "global-daemon", "capability-token-auth", "web-viewer", "fleet-control-plane", "rich-tui-coview"];
+export type DeferredSeam = (typeof DEFERRED_SEAMS)[number];
+export declare function isHarnessSupported(harness: string): harness is Harness;
+export interface UnsupportedSeamResult {
+    ok: false;
+    error: string;
+    evidence: {
+        seam: true;
+        name: string;
+        supported: readonly Harness[];
+        deferred: readonly string[];
+    };
+}
+export declare function unsupportedSeam(name: string): UnsupportedSeamResult;

package/dist/types/harness-control-plane/session-lease.d.ts

@@ -0,0 +1,65 @@
+export interface SessionLease {
+    ownerId: string;
+    sessionId: string;
+    pid: number;
+    leaseTokenHash: string;
+    endpoint: {
+        kind: "unix-socket" | "fifo";
+        path: string;
+    } | null;
+    eventsPath: string;
+    heartbeatAt: string;
+    expiresAt: string;
+    leaseEpoch: number;
+    writer: {
+        ownerId: string;
+        leaseEpoch: number;
+    };
+}
+export declare class LeaseError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export type LeaseStatus = "missing" | "live" | "expiredAlive" | "dead" | "epermAlive";
+type PidStatus = "alive" | "dead" | "eperm";
+export declare function readLease(root: string, sessionId: string): Promise<SessionLease | null>;
+export declare function isExpired(lease: SessionLease, clock?: () => number): boolean;
+export declare function classifyLeaseStatus(lease: SessionLease | null, opts?: {
+    clock?: () => number;
+    probe?: (pid: number) => PidStatus;
+}): LeaseStatus;
+/** Liveness probe via signal 0. Defaults to the real process table; injectable for tests. */
+export declare function isOwnerAlive(pid: number, probe?: (pid: number) => boolean): boolean;
+export declare function isStale(lease: SessionLease, opts?: {
+    clock?: () => number;
+    probe?: (pid: number) => boolean;
+}): boolean;
+export interface AcquireOptions {
+    ownerId: string;
+    pid: number;
+    endpoint?: SessionLease["endpoint"];
+    eventsPath: string;
+    ttlMs: number;
+    clock?: () => number;
+    probe?: (pid: number) => boolean | PidStatus;
+}
+export interface AcquiredLease {
+    lease: SessionLease;
+    token: string;
+}
+/**
+ * Acquire (or take over a stale) lease. Fails closed with `lease_held` when a live,
+ * unexpired lease is held by a different owner. Re-acquiring as the current owner refreshes.
+ */
+export declare function acquireLease(root: string, sessionId: string, opts: AcquireOptions): Promise<AcquiredLease>;
+/** Refresh the lease expiry. Only the recorded owner may heartbeat (single-writer). */
+export declare function heartbeat(root: string, sessionId: string, ownerId: string, ttlMs: number, clock?: () => number): Promise<SessionLease>;
+/** Whether `ownerId` is the live, unexpired single writer permitted to append events. */
+export declare function canWriteEvents(lease: SessionLease, ownerId: string, clock?: () => number): boolean;
+/** Release the lease (owner shutdown). Only the holder may release. */
+export declare function releaseLease(root: string, sessionId: string, ownerId: string): Promise<void>;
+export declare function reapDeadOwnerArtifacts(root: string, sessionId: string, expectedOwnerId: string, expectedEpoch: number, opts?: {
+    clock?: () => number;
+    probe?: (pid: number) => PidStatus;
+}): Promise<boolean>;
+export {};

package/dist/types/harness-control-plane/session-transport.d.ts

@@ -0,0 +1,48 @@
+export interface SessionStateSnapshot {
+    isStreaming: boolean;
+    steeringQueueDepth: number;
+    followupQueueDepth: number;
+}
+export interface HarnessSessionTransportCloseContext {
+    /**
+     * Immediate cycle-break acknowledgment for the exact direct close path.
+     *
+     * Invoke this method synchronously before an async close() reaches its first await
+     * (or before a non-async close() returns its promise); the returned promise may be
+     * awaited later. It does NOT signal that RuntimeOwner teardown has completed.
+     */
+    acknowledgeDirectOwnerStopReentry(): Promise<void>;
+}
+/** SDK-backed transport contract for a live harness session. */
+export interface HarnessSessionTransport {
+    getState(): Promise<SessionStateSnapshot>;
+    sendPrompt(prompt: string): Promise<{
+        commandId: string;
+        ack: boolean;
+    }>;
+    eventCursor(): number;
+    waitForAgentStart(afterCursor: number, timeoutMs: number): Promise<{
+        cursor: number;
+    } | null>;
+    /**
+     * Await every transport-owned cleanup step. close() MUST NOT call public
+     * RuntimeOwner.stop(), which would circularly await this close and hang. A transport
+     * that needs that direct cycle break must synchronously invoke
+     * `context.acknowledgeDirectOwnerStopReentry()` before its first await.
+     */
+    close(context?: HarnessSessionTransportCloseContext): Promise<void>;
+    /** Return a synchronous disposer that fully severs this event subscription. */
+    onEventFrame?(listener: (frame: Record<string, unknown>) => void): () => void;
+    isLive?(): boolean;
+    lastFrameAt?(): string | null;
+    getLastAssistantText?(): Promise<string | null>;
+}
+export interface AcceptanceResult {
+    accepted: boolean;
+    reason: string;
+    commandId: string | null;
+    preSubmitCursor: number;
+    agentStartCursor: number | null;
+    preSubmitState: SessionStateSnapshot;
+}
+export declare function singleFlightAccept(transport: HarnessSessionTransport, prompt: string, timeoutMs: number): Promise<AcceptanceResult>;

package/dist/types/harness-control-plane/state-machine.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lifecycle state machine + the universal `{state, evidence, nextAllowedActions}` contract.
+ *
+ * `nextAllowedActions` is the forcing function: it tells the caller exactly which
+ * primitives are currently permitted and, when not, why. Owner-routed verbs
+ * (`submit`) report `owner-not-live` when no `RuntimeOwner` holds the session lease.
+ */
+import type { HarnessLifecycle, NextAllowedAction, PrimitiveResponse, SessionState, SessionStateView } from "./types";
+export declare function isTerminal(lifecycle: HarnessLifecycle): boolean;
+export declare function canTransition(from: HarnessLifecycle, to: HarnessLifecycle): boolean;
+export declare function assertTransition(from: HarnessLifecycle, to: HarnessLifecycle): void;
+export interface NextAllowedActionsOptions {
+    /** Additional live-owner/RPC readiness gate for submit, e.g. rpc-not-idle. */
+    submitUnavailableReason?: string | null;
+}
+export declare function submitUnavailableReason(lifecycle: HarnessLifecycle, ownerLive: boolean, gateReason?: string | null): string | null;
+/**
+ * Derive the permitted next actions for a session given its lifecycle and whether
+ * a live owner currently holds the lease.
+ */
+export declare function nextAllowedActions(lifecycle: HarnessLifecycle, ownerLive: boolean, options?: NextAllowedActionsOptions): NextAllowedAction[];
+export declare function buildStateView(state: SessionState, ownerLive: boolean): SessionStateView;
+/** Build the universal contract response carried by every primitive. */
+export declare function buildResponse<E extends Record<string, unknown>>(state: SessionState, ownerLive: boolean, evidence: E, ok?: boolean): PrimitiveResponse<E>;

package/dist/types/harness-control-plane/storage.d.ts

@@ -0,0 +1,81 @@
+import type { EventEnvelope, ReceiptFamily, SessionState } from "./types";
+interface HarnessRootRegistryEntry {
+    root: string;
+    updatedAt: string;
+}
+export interface HarnessRootRegistryForGc {
+    sessionId: string;
+    roots: HarnessRootRegistryEntry[];
+}
+export interface HarnessRootRegistryListingForGc {
+    sessionId: string;
+    file: string;
+    roots: HarnessRootRegistryEntry[];
+    error?: string;
+}
+interface ResolveHarnessSessionRootOptions {
+    expectedWorkspace?: string;
+}
+export declare function canonicalWorkspacePath(workspace: string): string;
+/** @internal */
+export declare function listHarnessRootRegistriesForGc(env?: NodeJS.ProcessEnv): Promise<HarnessRootRegistryListingForGc[]>;
+/** @internal */
+export declare function rewriteHarnessRootRegistryForGc(file: string, registry: HarnessRootRegistryForGc): Promise<void>;
+/** @internal */
+export declare function removeHarnessRootRegistryFileForGc(file: string): Promise<void>;
+export declare const MAX_UNIX_SOCKET_PATH_BYTES = 100;
+export declare function controlSocketPath(root: string, sessionId: string, env?: NodeJS.ProcessEnv): string;
+export declare class StorageError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Resolve the harness state root from explicit value, env, or cwd/session default. */
+export declare function resolveHarnessRoot(opts?: {
+    root?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    skcSessionId?: string;
+}): string;
+export declare function assertSafeSessionId(id: string): void;
+export declare function generateSessionId(prefix?: string): string;
+export interface SessionPaths {
+    dir: string;
+    state: string;
+    lease: string;
+    events: string;
+    receiptsIndex: string;
+    receiptsDir: string;
+    artifactsDir: string;
+    controlSock: string;
+    controlFifo: string;
+    skcSessionDir: string;
+}
+export declare function sessionPaths(root: string, sessionId: string): SessionPaths;
+export declare function readSessionState(root: string, sessionId: string): Promise<SessionState | null>;
+export declare function rememberHarnessSessionRoot(root: string, sessionId: string, env?: NodeJS.ProcessEnv): Promise<void>;
+export declare function resolveHarnessSessionRoot(root: string, sessionId: string, env?: NodeJS.ProcessEnv, options?: ResolveHarnessSessionRootOptions): Promise<string>;
+export declare function writeSessionState(root: string, state: SessionState): Promise<void>;
+export declare function sessionExists(root: string, sessionId: string): Promise<boolean>;
+/** Append a single severity envelope to events.jsonl. Single-writer discipline is the owner's job (M3). */
+export declare function appendEvent(root: string, sessionId: string, envelope: EventEnvelope): Promise<void>;
+/** Read events from cursor (exclusive). Tail-only: never mutates the log. */
+export declare function readEvents(root: string, sessionId: string, fromCursor?: number): Promise<EventEnvelope[]>;
+export interface ReceiptIndexEntry {
+    receiptId: string;
+    family: ReceiptFamily;
+    valid: boolean;
+    createdAt: string;
+    path: string;
+}
+/**
+ * Persist a receipt immutably. Fails closed if the receipt id already exists,
+ * then appends an index entry to receipts.jsonl.
+ */
+export declare function writeReceiptImmutable(root: string, sessionId: string, family: ReceiptFamily, receiptId: string, value: {
+    receiptId: string;
+    family: ReceiptFamily;
+    valid: boolean;
+    createdAt: string;
+}): Promise<ReceiptIndexEntry>;
+export declare function readReceiptIndex(root: string, sessionId: string, family?: ReceiptFamily): Promise<ReceiptIndexEntry[]>;
+export {};

package/dist/types/harness-control-plane/types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Core types for the sayknow-cli-native coding-harness operations control plane (v1).
+ *
+ * See the approved consensus plan at
+ * `.skc/plans/ralplan/2026-06-02-0853-3e33/stage-02-revision.md` and the spec at
+ * `.skc/specs/deep-interview-harness-control-plane.md`.
+ *
+ * v1 implements the sayknow-cli adapter only. omx/codex/remote/auth are deferred seams.
+ */
+import type { AgentWireObservedSignal } from "../modes/shared/agent-wire/event-contract";
+/** Harnesses the control plane can operate. v1 implements `sayknow-cli` only. */
+export type Harness = "sayknow-cli" | "codex" | "omx";
+/** Operating mode of a session. `implement` builds/changes code; `review` produces a read-only verdict. */
+export type SessionMode = "implement" | "review";
+/** Closed vocabulary of terminal review verdicts a review-only session may emit. */
+export type ReviewVerdict = "APPROVE_MERGE_READY" | "REQUEST_CHANGES" | "OWNER_CONFIRMATION_REQUIRED";
+export declare const REVIEW_VERDICTS: readonly ReviewVerdict[];
+export declare function isReviewVerdict(value: unknown): value is ReviewVerdict;
+/**
+ * Extract a single closed-vocabulary review verdict from free-form assistant text.
+ *
+ * Scans for canonical verdict tokens (and accepted aliases) as whole words and returns the
+ * LAST occurrence — the agent's final stated decision wins over any earlier mention. Returns
+ * null when no allowed token is present, so the finalizer fails closed on a missing verdict.
+ */
+export declare function extractReviewVerdict(text: string | null | undefined): ReviewVerdict | null;
+/** Lifecycle states of an operated session. */
+export type HarnessLifecycle = "new" | "started" | "submitted" | "observing" | "recovering" | "validating" | "finalizing" | "completed" | "blocked" | "retired";
+/** Event severities emitted by the owner. */
+export type Severity = "info" | "warn" | "critical";
+/** Bounded git delta classification surfaced by `observe`. */
+export type GitDelta = "clean" | "dirty" | "zero-delta" | "unknown";
+/** Risk classification surfaced by `observe`. */
+export type RiskKind = "normal" | "prompt-not-accepted" | "deleted-worktree" | "vanished-dirty";
+/** Deterministic recovery classifications. */
+export type RecoveryClassification = "continue" | "send-enter" | "reinject-prompt" | "restart-clean" | "restart-preserve-delta" | "fallback-codex-exec" | "human-check";
+/** Receipt families persisted under the session storage dir. */
+export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion" | "review-verdict" | "review-failure" | "phase-rollup";
+/** The CLI verbs / primitives exposed by `skc harness <verb>`. */
+export type HarnessVerb = "start" | "submit" | "observe" | "classify" | "recover" | "validate" | "finalize" | "retire" | "events" | "monitor" | "operate";
+/** Submission transports. */
+export type SubmitMode = "paste-buffer" | "stdin" | "file";
+/** A single entry in the forcing-function `nextAllowedActions` list. */
+export interface NextAllowedAction {
+    verb: HarnessVerb;
+    available: boolean;
+    /** Present when `available` is false; explains why the verb is currently disallowed. */
+    reason?: string;
+}
+/** Compact, model-facing view of session state included in every response. */
+export interface SessionStateView {
+    sessionId: string;
+    lifecycle: HarnessLifecycle;
+    harness: Harness;
+    ownerLive: boolean;
+    blockers: string[];
+}
+/**
+ * The universal contract: EVERY primitive response carries `{state, evidence, nextAllowedActions}`.
+ * `ok` is a transport-level convenience; semantic blocking is expressed via state + nextAllowedActions.
+ */
+export interface PrimitiveResponse<E = Record<string, unknown>> {
+    ok: boolean;
+    state: SessionStateView;
+    evidence: E;
+    nextAllowedActions: NextAllowedAction[];
+}
+/** Re-grabbable session handle returned by `start` / `operate`. */
+export interface SessionHandle {
+    sessionId: string;
+    harness: Harness;
+    /** Operating mode; absent on legacy records means `implement`. */
+    mode?: SessionMode;
+    repo: string | null;
+    workspace: string;
+    branch: string | null;
+    base: string | null;
+    issueOrPr: string | null;
+    processHandle: {
+        kind: "runtime-owner";
+        ownerId: string | null;
+        pid: number | null;
+    };
+    sdkHandle: {
+        kind: "sdk-session-endpoint";
+        sessionId: string;
+    };
+    ownerHandle: {
+        leasePath: string;
+        endpoint: string | null;
+        heartbeatAt: string | null;
+    };
+    routerHandle: {
+        kind: "default-in-owner";
+        policy: string;
+        eventsPath: string;
+    };
+    viewportHandle: {
+        kind: "event-monitor";
+        tmuxSessionName: string | null;
+        viewOnly: true;
+    };
+    startedAt: string;
+    updatedAt: string;
+}
+/** Persisted per-session record (state.json). */
+export interface SessionState {
+    schemaVersion: number;
+    sessionId: string;
+    lifecycle: HarnessLifecycle;
+    harness: Harness;
+    handle: SessionHandle;
+    /** Per-classification retry counters consumed by the recovery policy. */
+    retries: Record<string, number>;
+    blockers: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Bounded observed-signal vocabulary surfaced by `observe` (the owner only ever
+ * emits these). Aliased to the canonical agent-wire signal vocabulary so there
+ * is a single source of truth shared with the observation core.
+ */
+export type ObservedSignal = AgentWireObservedSignal;
+export declare const OBSERVED_SIGNALS: readonly ObservedSignal[];
+/** Bounded observation surfaced by `observe` — never a raw pane/transcript dump. */
+export interface Observation {
+    lifecycle: HarnessLifecycle;
+    ownerLive: boolean;
+    cwd: string;
+    branch: string | null;
+    gitDelta: GitDelta;
+    lastActivityAt: string | null;
+    observedSignals: string[];
+    risk: RiskKind;
+    /** RPC subprocess liveness, distinct from owner-process/lease liveness. Optional for back-compat. */
+    rpcLive?: boolean;
+    /** ISO timestamp of the most recent RPC frame the owner observed, if any. */
+    rpcLastFrameAt?: string | null;
+    /** True only when owner/rpc/lifecycle gates indicate a prompt can be submitted now. */
+    readyForSubmit?: boolean;
+    /** Present when readyForSubmit is false; mirrors submit's nextAllowedActions reason. */
+    submitUnavailableReason?: string | null;
+}
+/** Input to the deterministic recovery classifier. */
+export interface ClassifyInput {
+    observation: Observation;
+    /** Remaining retry budget per classification family. */
+    retryBudget: RetryBudget;
+    /** Whether an accepted prompt was in flight when the owner/RPC was last seen. */
+    acceptedPromptActive?: boolean;
+}
+/** Default and supplied retry budgets. */
+export interface RetryBudget {
+    reinjectPrompt: number;
+    zeroDeltaVanish: number;
+    dirtyVanishPreserve: number;
+    validationRepair: number;
+}
+/** Result of the deterministic recovery classifier. */
+export interface RecoveryDecision {
+    classification: RecoveryClassification;
+    reason: string;
+    severity: Severity;
+    /** Whether executing the recommended action requires a live owner. */
+    ownerRequired: boolean;
+    /** Receipt family that MUST be valid before the action may proceed (e.g. `vanish`). */
+    requiredReceiptFamily: ReceiptFamily | null;
+}
+/** Severity-tagged event envelope written exclusively by the owner. */
+export interface EventEnvelope<E = Record<string, unknown>> {
+    eventId: string;
+    cursor: number;
+    createdAt: string;
+    severity: Severity;
+    kind: string;
+    state: SessionStateView;
+    evidence: E;
+    nextAllowedActions: NextAllowedAction[];
+    writer: {
+        ownerId: string;
+        leaseEpoch: number;
+    };
+}
+export declare const SESSION_SCHEMA_VERSION: 1;
+export declare const DEFAULT_RETRY_BUDGET: RetryBudget;

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,19 @@
+/** 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 = "**";
+/** 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 "@sayknow-cli/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,123 @@
+/**
+ * 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 / Anthropic model 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;
+/**
+ * Hashline edit input markers. File section headers start with {@link HL_FILE_PREFIX};
+ * op lines start with a direction/action sigil: {@link HL_OP_INSERT_BEFORE},
+ * {@link HL_OP_INSERT_AFTER}, or {@link HL_OP_REPLACE}. Payload lines are
+ * verbatim file content and have no per-line marker.
+ *
+ * These constants are the single source of truth for the edit parser, grammar,
+ * renderer, and prompt.
+ */
+export declare const HL_OP_INSERT_BEFORE = "\u00AB";
+export declare const HL_OP_INSERT_AFTER = "\u00BB";
+export declare const HL_OP_REPLACE = "\u2254";
+/** All hashline edit op sigils, concatenated for fast membership tests. */
+export declare const HL_OP_CHARS = "\u00AB\u00BB\u2254";
+/** Hashline edit file section header marker. */
+export declare const HL_FILE_PREFIX = "\u00A7";
+/** 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}. The hash depends only on the line's content (after
+ * stripping CR and trailing whitespace); the `idx` parameter is accepted
+ * for call-site symmetry with line numbers but is intentionally unused so
+ * that anchors remain stable across line shifts caused by sibling edits.
+ *
+ * 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[];