@scotthuang/agent-knock-knock 0.13.3 → 0.13.4

package/dist/src/deferred-foreground-conflict-policy.js

@@ -0,0 +1,52 @@
+import { isFinalDeferredForegroundTransferStatus } from "./deferred-foreground-transfer-policy.js";
+import { listDeferredForegroundTransfers, loadDeferredForegroundTransfer } from "./deferred-foreground-transfer.js";
+import { turnIdForConversation } from "./protocol.js";
+import { terminalControlEvidenceMatches } from "./terminal-control-ref.js";
+import { isRecord, nonBlankString as stringValue } from "./value-guards.js";
+/**
+ * Keep a Turn immutable while it is reserved by a nonterminal deferred
+ * foreground transfer. This guard observes Store state only and never sends
+ * terminal input.
+ */
+export function assertConversationHasNoNonterminalDeferredForegroundTransfer({ storeDir, conversation, action }) {
+    const turnId = turnIdForConversation(conversation);
+    const sourceTransfer = listDeferredForegroundTransfers(storeDir).find((candidate) => candidate.version === 2 &&
+        candidate.source_kind === "candidate_rollout_quiescent" &&
+        !isFinalDeferredForegroundTransferStatus(candidate.status) &&
+        (candidate.source_turn_history ?? []).some((sourceTurn) => sourceTurn.turn_id === turnId));
+    if (sourceTransfer) {
+        throw new Error(`cannot ${action} Turn ${turnId} while deferred foreground transfer ` +
+            `${sourceTransfer.transfer_id} reserves it as immutable source ` +
+            `history in ${sourceTransfer.status}; dedicated transfer recovery ` +
+            "must finish first");
+    }
+    const takeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const transferId = stringValue(takeover?.deferred_foreground_transfer_id);
+    if (!transferId) {
+        return;
+    }
+    const transfer = loadDeferredForegroundTransfer(storeDir, transferId);
+    if (!isFinalDeferredForegroundTransferStatus(transfer.status)) {
+        throw new Error(`cannot ${action} Turn ${turnId} while deferred foreground transfer ` +
+            `${transfer.transfer_id} is ${transfer.status}; dedicated transfer ` +
+            "recovery must finish first");
+    }
+}
+/**
+ * Keep one exact physical terminal immutable while a deferred foreground
+ * transfer still owns its lifecycle boundary.
+ */
+export function assertTerminalHasNoNonterminalDeferredForegroundTransfer({ storeDir, pid, terminalControl, action }) {
+    const transfer = listDeferredForegroundTransfers(storeDir).find((candidate) => !isFinalDeferredForegroundTransferStatus(candidate.status) &&
+        candidate.process_pid === pid &&
+        terminalControlEvidenceMatches(candidate.terminal_endpoint, terminalControl));
+    if (!transfer) {
+        return;
+    }
+    throw new Error(`cannot ${action} terminal ${terminalControl.target} while deferred ` +
+        `foreground transfer ${transfer.transfer_id} is ${transfer.status}; ` +
+        "dedicated transfer recovery must finish first");
+}
+//# sourceMappingURL=deferred-foreground-conflict-policy.js.map

package/dist/src/deferred-foreground-conflict-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-foreground-conflict-policy.js","sourceRoot":"","sources":["../../src/deferred-foreground-conflict-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uCAAuC,EAAE,MAChD,0CAA0C,CAAC;AAC7C,OAAO,EAAE,+BAA+B,EACtC,8BAA8B,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAqB,MAAM,eAAe,CAAC;AAEzE,OAAO,EAAE,8BAA8B,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,QAAQ,EAAE,cAAc,IAAI,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE5E;;;;GAIG;AACH,MAAM,UAAU,4DAA4D,CAAC,EAC3E,QAAQ,EACR,YAAY,EACZ,MAAM,EAKP;IACC,MAAM,MAAM,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACnD,MAAM,cAAc,GAAG,+BAA+B,CAAC,QAAQ,CAAC,CAAC,IAAI,CACnE,CAAC,SAAS,EAAE,EAAE,CACZ,SAAS,CAAC,OAAO,KAAK,CAAC;QACvB,SAAS,CAAC,WAAW,KAAK,6BAA6B;QACvD,CAAC,uCAAuC,CAAC,SAAS,CAAC,MAAM,CAAC;QAC1D,CAAC,SAAS,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,IAAI,CACxC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,KAAK,MAAM,CAC9C,CACJ,CAAC;IACF,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,UAAU,MAAM,SAAS,MAAM,sCAAsC;YACrE,GAAG,cAAc,CAAC,WAAW,mCAAmC;YAChE,cAAc,cAAc,CAAC,MAAM,gCAAgC;YACnE,mBAAmB,CACpB,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,uBAAuB,CAAC;QAC7D,CAAC,CAAC,YAAY,CAAC,uBAAuB;QACtC,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,EAAE,+BAA+B,CAAC,CAAC;IAC1E,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO;IACT,CAAC;IACD,MAAM,QAAQ,GAAG,8BAA8B,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACtE,IAAI,CAAC,uCAAuC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CACb,UAAU,MAAM,SAAS,MAAM,sCAAsC;YACrE,GAAG,QAAQ,CAAC,WAAW,OAAO,QAAQ,CAAC,MAAM,uBAAuB;YACpE,4BAA4B,CAC7B,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wDAAwD,CAAC,EACvE,QAAQ,EACR,GAAG,EACH,eAAe,EACf,MAAM,EAMP;IACC,MAAM,QAAQ,GAAG,+BAA+B,CAAC,QAAQ,CAAC,CAAC,IAAI,CAC7D,CAAC,SAAS,EAAE,EAAE,CACZ,CAAC,uCAAuC,CAAC,SAAS,CAAC,MAAM,CAAC;QAC1D,SAAS,CAAC,WAAW,KAAK,GAAG;QAC7B,8BAA8B,CAC5B,SAAS,CAAC,iBAAiB,EAC3B,eAAe,CAChB,CACJ,CAAC;IACF,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IACD,MAAM,IAAI,KAAK,CACb,UAAU,MAAM,aAAa,eAAe,CAAC,MAAM,kBAAkB;QACrE,uBAAuB,QAAQ,CAAC,WAAW,OAAO,QAAQ,CAAC,MAAM,IAAI;QACrE,+CAA+C,CAChD,CAAC;AACJ,CAAC"}

package/dist/src/durable-notification-kernel.d.ts

@@ -0,0 +1,94 @@
+import type { CallbackAttemptOutcome } from "./callback-transport.js";
+/**
+ * Store-neutral claim metadata shared by durable callback and Watch outboxes.
+ * Persistence adapters deliberately choose their own status names and fields.
+ */
+export interface DurableNotificationLease {
+    attempt: number;
+    attemptId: string;
+    attemptedAt: string;
+    leaseExpiresAt: string;
+}
+export declare function createDurableNotificationLease(input: {
+    previousAttempts: number;
+    attemptId: string;
+    attemptedAt: string;
+    leaseBaseMs: number;
+    leaseMs: number;
+}): DurableNotificationLease;
+export type DurableNotificationRetryDecision = {
+    state: "retryable";
+    attempt: number;
+} | {
+    state: "waiting";
+    attempt: number;
+    retry_at?: string;
+} | {
+    state: "in_flight";
+    attempt: number;
+    lease_expires_at?: string;
+} | {
+    state: "non_retryable";
+    attempt: number;
+} | {
+    state: "settled";
+    attempt: number;
+} | {
+    state: "exhausted";
+    attempt: number;
+};
+export type DurableNotificationRetryFacts = {
+    phase: "ready";
+    attempt: number;
+    maxAttempts?: number;
+} | {
+    phase: "retry_wait";
+    attempt: number;
+    nowMs: number;
+    retryAt?: string;
+    retryAuthorized: boolean;
+    maxAttempts?: number;
+} | {
+    phase: "leased";
+    attempt: number;
+    nowMs: number;
+    leaseExpiresAt?: string;
+    maxAttempts?: number;
+} | {
+    phase: "settled";
+    attempt: number;
+};
+/**
+ * Decide whether a durable notification attempt may be claimed. The caller
+ * supplies only persisted facts plus its clock observation; no I/O or Store
+ * shape is owned here.
+ */
+export declare function decideDurableNotificationRetry(facts: DurableNotificationRetryFacts): DurableNotificationRetryDecision;
+export type DurableNotificationSettlement = {
+    state: "accepted";
+    outcome: Extract<CallbackAttemptOutcome, {
+        disposition: "accepted";
+    }>;
+} | {
+    state: "superseded";
+    outcome: Exclude<CallbackAttemptOutcome, {
+        disposition: "accepted";
+    }>;
+} | {
+    state: "failed";
+    outcome: Exclude<CallbackAttemptOutcome, {
+        disposition: "accepted";
+    }>;
+    retryAuthorized: boolean;
+};
+/**
+ * Reduce one authoritative transport outcome into a Store-neutral settlement.
+ * Conversation and Watch adapters retain their distinct status/error schemas.
+ */
+export declare function reduceDurableNotificationSettlement(input: {
+    attempt: number;
+    outcome: CallbackAttemptOutcome;
+    retryEnabled: boolean;
+    maxRetryAttempts?: number;
+    supersede?: boolean;
+}): DurableNotificationSettlement;

package/dist/src/durable-notification-kernel.js

@@ -0,0 +1,68 @@
+export function createDurableNotificationLease(input) {
+    return {
+        attempt: input.previousAttempts + 1,
+        attemptId: input.attemptId,
+        attemptedAt: input.attemptedAt,
+        leaseExpiresAt: new Date(input.leaseBaseMs + input.leaseMs).toISOString()
+    };
+}
+/**
+ * Decide whether a durable notification attempt may be claimed. The caller
+ * supplies only persisted facts plus its clock observation; no I/O or Store
+ * shape is owned here.
+ */
+export function decideDurableNotificationRetry(facts) {
+    if (facts.phase !== "settled" &&
+        facts.maxAttempts !== undefined &&
+        facts.attempt > facts.maxAttempts) {
+        return { state: "exhausted", attempt: facts.attempt };
+    }
+    if (facts.phase === "ready") {
+        return { state: "retryable", attempt: facts.attempt };
+    }
+    if (facts.phase === "retry_wait") {
+        if (!facts.retryAuthorized) {
+            return { state: "non_retryable", attempt: facts.attempt };
+        }
+        const retryAtMs = Date.parse(facts.retryAt ?? "");
+        return retryAtMs <= facts.nowMs
+            ? { state: "retryable", attempt: facts.attempt }
+            : {
+                state: "waiting",
+                attempt: facts.attempt,
+                retry_at: facts.retryAt
+            };
+    }
+    if (facts.phase === "leased") {
+        const leaseExpiresAtMs = Date.parse(facts.leaseExpiresAt ?? "");
+        return leaseExpiresAtMs <= facts.nowMs
+            ? { state: "retryable", attempt: facts.attempt }
+            : {
+                state: "in_flight",
+                attempt: facts.attempt,
+                lease_expires_at: facts.leaseExpiresAt
+            };
+    }
+    return { state: "settled", attempt: facts.attempt };
+}
+/**
+ * Reduce one authoritative transport outcome into a Store-neutral settlement.
+ * Conversation and Watch adapters retain their distinct status/error schemas.
+ */
+export function reduceDurableNotificationSettlement(input) {
+    if (input.outcome.disposition === "accepted") {
+        return { state: "accepted", outcome: input.outcome };
+    }
+    if (input.supersede === true) {
+        return { state: "superseded", outcome: input.outcome };
+    }
+    return {
+        state: "failed",
+        outcome: input.outcome,
+        retryAuthorized: input.outcome.disposition === "retryable_failure" &&
+            input.retryEnabled &&
+            (input.maxRetryAttempts === undefined ||
+                input.attempt <= input.maxRetryAttempts)
+    };
+}
+//# sourceMappingURL=durable-notification-kernel.js.map

package/dist/src/durable-notification-kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-notification-kernel.js","sourceRoot":"","sources":["../../src/durable-notification-kernel.ts"],"names":[],"mappings":"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"}

package/dist/src/herdr-socket-transport.d.ts

@@ -0,0 +1,43 @@
+export declare const HERDR_DEFAULT_TIMEOUT_MS = 5000;
+export interface HerdrWireRequest {
+    id: string;
+    method: string;
+    params: Record<string, unknown>;
+}
+export interface HerdrSocketIdentity {
+    device: string;
+    inode: string;
+    ctimeNs: string;
+    ownerUid?: number;
+}
+export interface HerdrRequestOptions {
+    expectedSocketIdentity?: HerdrSocketIdentity;
+}
+export type HerdrRequestFunction = (socketPath: string, request: HerdrWireRequest, options?: HerdrRequestOptions) => Promise<unknown>;
+/** A structured Herdr API rejection received after a complete request. */
+export declare class HerdrApiError extends Error {
+    readonly code: string;
+    readonly requestId: string;
+    constructor(code: string, message: string, requestId: string);
+}
+/**
+ * Raw socket failure with an explicit dispatch boundary.
+ *
+ * `definitelyNotSent` is true only when the Unix socket never connected or
+ * the request was rejected locally before any socket write was attempted.
+ */
+export declare class HerdrTransportError extends Error {
+    readonly definitelyNotSent: boolean;
+    constructor(message: string, definitelyNotSent: boolean, options?: {
+        cause?: unknown;
+    });
+}
+/** Send one newline-delimited JSON request over a Herdr Unix-domain socket. */
+export declare function requestHerdrUnixSocket(socketPath: string, request: HerdrWireRequest, options?: {
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    expectedSocketIdentity?: HerdrSocketIdentity;
+}): Promise<unknown>;
+/** Resolve immutable filesystem identity for one owner-local Herdr socket. */
+export declare function readHerdrSocketIdentity(socketPath: string): HerdrSocketIdentity;
+export declare function sameHerdrSocketIdentity(left: HerdrSocketIdentity, right: HerdrSocketIdentity): boolean;

package/dist/src/herdr-socket-transport.js

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import { createConnection } from "node:net";
+const HERDR_MAX_REQUEST_BYTES = 1024 * 1024;
+const HERDR_MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+export const HERDR_DEFAULT_TIMEOUT_MS = 5_000;
+/** A structured Herdr API rejection received after a complete request. */
+export class HerdrApiError extends Error {
+    code;
+    requestId;
+    constructor(code, message, requestId) {
+        super(message);
+        this.code = code;
+        this.requestId = requestId;
+        this.name = "HerdrApiError";
+    }
+}
+/**
+ * Raw socket failure with an explicit dispatch boundary.
+ *
+ * `definitelyNotSent` is true only when the Unix socket never connected or
+ * the request was rejected locally before any socket write was attempted.
+ */
+export class HerdrTransportError extends Error {
+    definitelyNotSent;
+    constructor(message, definitelyNotSent, options = {}) {
+        super(message, options);
+        this.definitelyNotSent = definitelyNotSent;
+        this.name = "HerdrTransportError";
+    }
+}
+/** Send one newline-delimited JSON request over a Herdr Unix-domain socket. */
+export function requestHerdrUnixSocket(socketPath, request, options = {}) {
+    let encoded;
+    try {
+        encoded = `${JSON.stringify(request)}\n`;
+    }
+    catch (error) {
+        return Promise.reject(new HerdrTransportError(`failed to encode Herdr request: ${describeError(error)}`, true, { cause: error }));
+    }
+    if (Buffer.byteLength(encoded) > HERDR_MAX_REQUEST_BYTES) {
+        return Promise.reject(new HerdrTransportError(`Herdr request exceeds ${HERDR_MAX_REQUEST_BYTES} bytes`, true));
+    }
+    const timeoutMs = positiveInteger(options.timeoutMs) ?? HERDR_DEFAULT_TIMEOUT_MS;
+    const maxResponseBytes = positiveInteger(options.maxResponseBytes) ??
+        HERDR_MAX_RESPONSE_BYTES;
+    return new Promise((resolve, reject) => {
+        let connected = false;
+        let settled = false;
+        let response = "";
+        const socket = createConnection({ path: socketPath });
+        socket.setEncoding("utf8");
+        socket.setTimeout(timeoutMs);
+        const fail = (message, definitelyNotSent, cause) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            reject(new HerdrTransportError(message, definitelyNotSent, { cause }));
+        };
+        socket.once("connect", () => {
+            if (settled)
+                return;
+            connected = true;
+            if (options.expectedSocketIdentity) {
+                let liveSocketIdentity;
+                try {
+                    liveSocketIdentity = readHerdrSocketIdentity(socketPath);
+                }
+                catch (error) {
+                    fail(`failed to revalidate Herdr socket ${socketPath}: ${describeError(error)}`, true, error);
+                    return;
+                }
+                if (!sameHerdrSocketIdentity(options.expectedSocketIdentity, liveSocketIdentity)) {
+                    fail(`Herdr socket ${socketPath} changed before request dispatch`, true);
+                    return;
+                }
+            }
+            try {
+                socket.write(encoded, (error) => {
+                    if (error) {
+                        fail(`failed to write Herdr request: ${error.message}`, false, error);
+                    }
+                });
+            }
+            catch (error) {
+                fail(`failed to write Herdr request: ${describeError(error)}`, false, error);
+            }
+        });
+        socket.on("data", (chunk) => {
+            if (settled)
+                return;
+            response += String(chunk);
+            if (Buffer.byteLength(response) > maxResponseBytes) {
+                fail(`Herdr response exceeds ${maxResponseBytes} bytes`, false);
+                return;
+            }
+            const newline = response.indexOf("\n");
+            if (newline < 0)
+                return;
+            const line = response.slice(0, newline).trim();
+            if (!line) {
+                fail("Herdr returned an empty response", false);
+                return;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch (error) {
+                fail(`Herdr returned invalid JSON: ${describeError(error)}`, false, error);
+                return;
+            }
+            settled = true;
+            socket.destroy();
+            resolve(parsed);
+        });
+        socket.once("timeout", () => {
+            fail(`timed out waiting for Herdr socket ${socketPath}`, !connected);
+        });
+        socket.once("error", (error) => {
+            fail(`Herdr socket ${socketPath} failed: ${error.message}`, !connected, error);
+        });
+        socket.once("end", () => {
+            if (!settled)
+                fail("Herdr closed the socket without a response", false);
+        });
+        socket.once("close", () => {
+            if (!settled)
+                fail("Herdr closed the socket without a response", !connected);
+        });
+    });
+}
+/** Resolve immutable filesystem identity for one owner-local Herdr socket. */
+export function readHerdrSocketIdentity(socketPath) {
+    const stats = fs.lstatSync(socketPath, { bigint: true });
+    if (stats.isSymbolicLink()) {
+        throw new Error(`Herdr endpoint must not be a symbolic link: ${socketPath}`);
+    }
+    if (!stats.isSocket()) {
+        throw new Error(`Herdr endpoint is not a Unix socket: ${socketPath}`);
+    }
+    const ownerUid = Number(stats.uid);
+    const currentUid = typeof process.getuid === "function"
+        ? process.getuid()
+        : undefined;
+    if (currentUid !== undefined && ownerUid !== currentUid) {
+        throw new Error(`Herdr socket ${socketPath} is owned by uid ${ownerUid}, expected ${currentUid}`);
+    }
+    return {
+        device: stats.dev.toString(),
+        inode: stats.ino.toString(),
+        ctimeNs: stats.ctimeNs.toString(),
+        ownerUid
+    };
+}
+export function sameHerdrSocketIdentity(left, right) {
+    return left.device === right.device &&
+        left.inode === right.inode &&
+        left.ctimeNs === right.ctimeNs &&
+        left.ownerUid === right.ownerUid;
+}
+function positiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : undefined;
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=herdr-socket-transport.js.map

package/dist/src/herdr-socket-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-socket-transport.js","sourceRoot":"","sources":["../../src/herdr-socket-transport.ts"],"names":[],"mappings":"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"}

package/dist/src/herdr-terminal-control-provider.d.ts

@@ -1,20 +1,10 @@
 import { type CommandResult, type TerminalDiscoveryDiagnosticLog, type TerminalControlProvider, type TerminalViewport } from "./terminal-control-provider.js";
 import { type TerminalControlCapability, type TerminalControlRef, type TerminalEndpointRef, type TerminalProviderCapability } from "./terminal-control-ref.js";
 import type { TerminalProcessSnapshot } from "./terminal-agent-adapter.js";
+import { type HerdrRequestFunction, type HerdrSocketIdentity } from "./herdr-socket-transport.js";
+export { HerdrApiError, HerdrTransportError, readHerdrSocketIdentity, requestHerdrUnixSocket, type HerdrRequestFunction, type HerdrRequestOptions, type HerdrSocketIdentity, type HerdrWireRequest } from "./herdr-socket-transport.js";
 export declare const HERDR_EXACT_VERSION = "0.8.0";
 export declare const HERDR_EXACT_PROTOCOL = 19;
-type JsonRecord = Record<string, unknown>;
-export interface HerdrWireRequest {
-    id: string;
-    method: string;
-    params: JsonRecord;
-}
-export interface HerdrSocketIdentity {
-    device: string;
-    inode: string;
-    ctimeNs: string;
-    ownerUid?: number;
-}
 export interface HerdrTtyDeviceIdentity {
     device: string;
     inode: string;
@@ -31,10 +21,6 @@ export interface HerdrTtyViewportInspectionOptions {
     currentUid?: number;
 }
 export type HerdrTtyViewportInspector = (shellPid: number) => TerminalViewport | undefined | Promise<TerminalViewport | undefined>;
-export interface HerdrRequestOptions {
-    expectedSocketIdentity?: HerdrSocketIdentity;
-}
-export type HerdrRequestFunction = (socketPath: string, request: HerdrWireRequest, options?: HerdrRequestOptions) => Promise<unknown>;
 export interface HerdrSessionInfo {
     name: string;
     default: boolean;
@@ -58,33 +44,6 @@ export interface HerdrTerminalControlDiagnostics {
     }>;
     terminalCount: number;
 }
-/** A structured Herdr API rejection received after a complete request. */
-export declare class HerdrApiError extends Error {
-    readonly code: string;
-    readonly requestId: string;
-    constructor(code: string, message: string, requestId: string);
-}
-/**
- * Raw socket failure with an explicit dispatch boundary.
- *
- * `definitelyNotSent` is true only when the Unix socket never connected or
- * the request was rejected locally before any socket write was attempted.
- */
-export declare class HerdrTransportError extends Error {
-    readonly definitelyNotSent: boolean;
-    constructor(message: string, definitelyNotSent: boolean, options?: {
-        cause?: unknown;
-    });
-}
-/**
- * Send one newline-delimited JSON request over a Herdr Unix-domain socket.
- * Normal Herdr requests receive exactly one newline-delimited JSON response.
- */
-export declare function requestHerdrUnixSocket(socketPath: string, request: HerdrWireRequest, options?: {
-    timeoutMs?: number;
-    maxResponseBytes?: number;
-    expectedSocketIdentity?: HerdrSocketIdentity;
-}): Promise<unknown>;
 export declare class HerdrTerminalControlProvider implements TerminalControlProvider {
     readonly kind = "herdr";
     readonly supportedCapabilities: readonly TerminalControlCapability[];
@@ -139,5 +98,3 @@ export declare function translateHerdrKey(value: string): string;
  * resize the PTY without updating the layout rectangle that owns the pane.
  */
 export declare function inspectHerdrTtyViewport(shellPid: number, options?: HerdrTtyViewportInspectionOptions): TerminalViewport | undefined;
-export declare function readHerdrSocketIdentity(socketPath: string): HerdrSocketIdentity;
-export {};