@threahq/remote-session 0.1.0

package/session.test-support.d.ts

@@ -0,0 +1,6 @@
+import type { RemoteSession } from "./session.js";
+export declare function fireIdleTimeout(session: RemoteSession, invocationId: string): Promise<void>;
+export declare function gate(): {
+    promise: Promise<void>;
+    open: () => void;
+};

package/tool-trace.d.ts

@@ -0,0 +1,14 @@
+export type ToolTraceSectionLabel = "Arguments" | "Output" | "Error output" | "Details";
+export interface ToolTraceSection {
+    label: ToolTraceSectionLabel;
+    body: string;
+    lang: string | null;
+}
+/**
+ * Serialize a structured tool trace under the step content limit, trimming the
+ * largest section first (the same algorithm as pi-remote and claude-code-remote).
+ */
+export declare function toolTraceContent(params: {
+    headline: string;
+    sections: ToolTraceSection[];
+}): string;

package/turn-route.d.ts

@@ -0,0 +1,149 @@
+import type { SealedReplyBody } from "@threahq/bot-runtime-client";
+import type { ClaimedInvocation } from "./client.js";
+/** Exact failed POST bytes and id, retained because an ambiguous failure may have committed. */
+export type PreparedPost = {
+    kind: "plaintext";
+    seq: number;
+    text: string;
+    retryKey?: string;
+    body: {
+        instanceId: string;
+        claimToken: string;
+        content: string;
+        clientMessageId: string;
+        metadata: Record<string, unknown>;
+    };
+} | {
+    kind: "sealed";
+    seq: number;
+    text: string;
+    retryKey?: string;
+    body: SealedReplyBody;
+    attachmentIds: string[];
+};
+export interface PostIntent {
+    text: string;
+    retryKey?: string;
+    retry?: PreparedPost;
+}
+export type PlaintextCompletionBody = {
+    instanceId: string;
+    claimToken: string;
+    sourceRevision: number;
+    metadata: Record<string, unknown>;
+} & ({
+    finalMessageMarkdown: string;
+} | {
+    noResponse: true;
+});
+export type SealedCompletionBody = ({
+    reply: SealedReplyBody & {
+        attachmentIds?: string[];
+    };
+} | {
+    noResponse: true;
+}) & {
+    sourceRevision: number;
+};
+export type PreparedCompletionWire = {
+    kind: "plaintext";
+    body: PlaintextCompletionBody;
+} | {
+    kind: "sealed";
+    callbackToken: string;
+    body: SealedCompletionBody;
+};
+export type PreparedClose = {
+    reason: "reply";
+    sourceText: string;
+    wire: PreparedCompletionWire;
+} | {
+    reason: "timeout";
+    wire: PreparedCompletionWire;
+};
+export type CloseRequest = {
+    kind: "reply";
+    text: string;
+} | {
+    kind: "timeout";
+};
+export type RouteState = "open" | "closing" | "closed";
+export declare class RouteRevokedError extends Error {
+}
+/**
+ * One claimed invocation's delivery route. The session's maps and queued posts
+ * share this object so reserved ids survive state transitions. Route death has
+ * three private signals with distinct meanings — `state` (turn protocol
+ * progress), `revoked` (this session stopped speaking for the stream), and
+ * `terminal` (the server refused the route for good) — mutated only through
+ * the named transitions below; `generation` fences a route created before a
+ * session teardown (`isFenced`).
+ */
+export declare class TurnRoute {
+    readonly invocation: ClaimedInvocation;
+    /** Registration order distinguishes an older route from a newer owner of the same stream. */
+    readonly order: number;
+    /** The session lifecycle this route belongs to; a bump fences it out for good. */
+    readonly generation: number;
+    sentCount: number;
+    /** The accepted final reply's exact text, for idempotent reply retries. */
+    replyText?: string;
+    /** Exact close body retained after an ambiguous completion. */
+    prepared?: PreparedClose;
+    /** The completion currently on the wire, so shutdown can settle it instead of racing it. */
+    closing?: Promise<unknown>;
+    deadline?: ReturnType<typeof setTimeout>;
+    readonly pending: Map<number, PreparedPost>;
+    /** Source-backed inputs folded into this turn; they close with it and fail with it. */
+    contributors: ClaimedInvocation[];
+    /** Aborts the completion on the wire when any folded source changes underneath it. */
+    readonly execution: AbortController;
+    /** FIFO tail: every post on this route runs behind it, in call order. */
+    private tail;
+    /** Highest sequence handed out. Reserved before the write, so a failure spends it. */
+    private reservedSeq;
+    /** Bumped on every (re-)arm, so a fired timeout queued behind a post can tell it is stale. */
+    private deadlineGeneration;
+    private stateValue;
+    private revokedFlag;
+    private terminalFlag;
+    private readonly idleTimeoutMs;
+    private readonly onIdleDeadline;
+    constructor(options: {
+        invocation: ClaimedInvocation;
+        order: number;
+        generation: number;
+        idleTimeoutMs: number;
+        onIdleDeadline: (route: TurnRoute, deadlineGeneration: number) => void;
+        contributors?: ClaimedInvocation[];
+    });
+    get state(): RouteState;
+    get revoked(): boolean;
+    get terminal(): boolean;
+    isFenced(lifecycle: number): boolean;
+    /** FIFO allocation keeps concurrent posts on distinct ids and orders them against completion. */
+    enqueue<T>(task: () => Promise<T>): Promise<T>;
+    /** Snapshot retry intent before queueing so concurrent callers cannot adopt each other's failure. */
+    snapshotIntent(text: string, retryKey?: string): PostIntent;
+    /** An ambiguous failure reserves its id and exact bytes; changed text takes the next id. */
+    claimSeq(retry: PreparedPost | undefined): number;
+    rememberFailedPost(seq: number, prepared: PreparedPost, lifecycle: number): void;
+    recordLandedPost(seq: number, prepared: PreparedPost): void;
+    /** The source changed under a prepared body: never replay bytes sealed or revisioned against the old input. */
+    discardPrepared(): void;
+    /** This session stopped speaking for the route's stream; pending retries and the deadline die with it. */
+    revoke(): void;
+    /** The server refused the route for good: drop write credentials and every pending payload. */
+    markTerminal(): void;
+    beginClosing(): void;
+    markClosed(): void;
+    settleClosed(replyText: string | undefined): void;
+    reopen(prepared: PreparedClose | undefined): void;
+    /** Track the completion on the wire so shutdown can settle it instead of racing it. */
+    trackClosing<T>(task: Promise<T>): Promise<T>;
+    armIdleTimeout(): void;
+    /** Reset the idle timeout after a sign of life. */
+    touchIdleTimeout(): void;
+    isCurrentDeadline(deadlineGeneration: number): boolean;
+    private clearDeadline;
+}