@relayflows/sdk 2.0.21 → 2.0.22

package/dist/agent-transcript.d.ts

@@ -0,0 +1,186 @@
+import { type SidechannelContext } from './pty-sidechannel.js';
+/**
+ * Per-attempt agent transcript: the redacted, capped `stream-json` file the
+ * worker writes beside the PTY socket, and the ≤ 8 KiB digest of it that rides
+ * in `trajectory_tail` on every completion.
+ *
+ * Every bound below is enforced here and stated in what it produces — a
+ * marker line at a seam, a suffix on a cut string, a boolean on the digest —
+ * so a reader is told what was dropped rather than left to guess.
+ */
+/** Cap on one attempt's transcript file: the first 128 KiB whole, then a rolling tail. */
+export declare const TRANSCRIPT_FILE_MAX_BYTES: number;
+export declare const TRANSCRIPT_HEAD_BYTES: number;
+export declare const TRANSCRIPT_TAIL_BYTES: number;
+/** Cap on any one string leaf inside a frame (tool results, thinking, text). */
+export declare const TRANSCRIPT_STRING_MAX_BYTES: number;
+/**
+ * Cap on the serialized digest. Half the kernel's 16 KiB `trajectory_tail`
+ * boundary (relayflowd/src/server.rs), leaving room for the `relay_task`
+ * sibling the worker already journals.
+ */
+export declare const TRANSCRIPT_DIGEST_MAX_BYTES: number;
+/** Cap on an llm step's `trajectory_tail.error`; over 16 KiB the kernel refuses the completion. */
+export declare const LLM_ERROR_MAX_BYTES: number;
+export declare const FINAL_TEXT_MAX_BYTES: number;
+export declare const FAILURE_EXCERPT_MAX_BYTES = 1024;
+export declare const TOOL_INPUT_EXCERPT_MAX_CHARS = 120;
+/**
+ * Cap on any single provider-supplied identifier copied into `result`
+ * (`model`, `session_id`, `stop_reason`, `subtype`, `claude_code_version`) and
+ * on a tool name. These are attacker-influenceable strings that no reduction
+ * step in `boundTranscriptDigest` trims, so they are bounded where they enter.
+ */
+export declare const DIGEST_LABEL_MAX_BYTES = 256;
+/**
+ * Bytes reserved inside `TRANSCRIPT_FILE_MAX_BYTES` for the
+ * `relayflow.truncated` marker, so a full head plus a full tail plus the
+ * marker still fits the stated per-attempt cap. The marker serializes to
+ * well under this even with 20-digit counters.
+ */
+export declare const TRUNCATION_MARKER_RESERVE = 256;
+export declare const TOOL_COUNTS_MAX = 32;
+export declare const TOOL_LAST_CALLS_MAX = 20;
+export declare const ARTIFACT_PATHS_MAX = 50;
+export interface TranscriptFile {
+    path: string;
+    /** Bytes the redacted transcript would have occupied without the file cap. */
+    bytes_total: number;
+    bytes_kept: number;
+    frames_total: number;
+    frames_kept: number;
+    truncated: boolean;
+    sha256: string;
+}
+export interface TranscriptToolCall {
+    seq: number;
+    name: string;
+    input_excerpt: string;
+    result_bytes?: number;
+    is_error?: boolean;
+}
+export interface TranscriptDigest {
+    attempt?: number;
+    exit_code?: number | null;
+    file?: TranscriptFile;
+    result?: {
+        provider: 'claude' | 'codex';
+        model?: string;
+        claude_code_version?: string;
+        session_id?: string;
+        subtype?: string;
+        is_error?: boolean;
+        stop_reason?: string;
+        num_turns?: number;
+        duration_ms?: number;
+        duration_api_ms?: number;
+        total_cost_usd?: number;
+        usage?: {
+            input?: number;
+            output?: number;
+            cache_read?: number;
+            cache_creation?: number;
+            thinking?: number;
+        };
+        permission_denials?: number;
+    };
+    tools?: {
+        counts: Array<{
+            name: string;
+            calls: number;
+            errors: number;
+        }>;
+        last_calls: TranscriptToolCall[];
+        total_calls: number;
+        shown_calls: number;
+        /** False when the provider's frames are only counted, not paired (Codex). */
+        complete: boolean;
+    };
+    final_text?: string;
+    final_text_truncated?: boolean;
+    failure?: {
+        kind: 'result' | 'tool_result' | 'stderr';
+        excerpt: string;
+        truncated?: boolean;
+    };
+    artifacts?: {
+        count: number;
+        paths: string[];
+    };
+    /**
+     * Set when even the ordered reductions left the digest over its cap and it
+     * was cut back to fixed-size fields — every provider-supplied string but a
+     * bounded file path is gone. A reader is told rather than left guessing.
+     */
+    core_only?: boolean;
+}
+type RecordValue = Record<string, unknown>;
+/** `…/runs/<runId>/steps/<stepId>/attempt-<n>.transcript.jsonl`, beside the PTY socket. */
+export declare function transcriptPath(context: Pick<SidechannelContext, 'dataDir' | 'runId' | 'stepId'>, attempt: number): string;
+/**
+ * Relay-issued token prefixes, shared with `redactRelayError` (worker-cli.ts).
+ * The tail must be at least 8 characters so journal keys such as `at_ms` are
+ * not mistaken for tokens.
+ */
+export declare const RELAY_TOKEN_PATTERN: RegExp;
+export type Redactor = (text: string) => string;
+/**
+ * One redactor for one environment: the values of secret-named variables are
+ * resolved once, so a writer redacting thousands of strings does not rescan
+ * `process.env` for each.
+ */
+export declare function createRedactor(env?: NodeJS.ProcessEnv): Redactor;
+/** Redact one string against `env` (D6 rules 2–4). */
+export declare function redactText(text: string, env?: NodeJS.ProcessEnv): string;
+/** Cut `text` to at most `maxBytes` of UTF-8 on a code-point boundary. */
+export declare function utf8Head(text: string, maxBytes: number): string;
+/** The last `maxBytes` of `text`, on a code-point boundary. */
+export declare function utf8Tail(text: string, maxBytes: number): string;
+/** Head-cut with the truncation stated in the value itself. */
+export declare function boundedText(text: string, maxBytes: number, label?: string): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Redact and bound every string leaf of a parsed frame, and reduce the
+ * `system/init` frame to its whitelist. Unknown frame types are kept as they
+ * are, minus the same string treatment.
+ */
+export declare function reduceFrame(frame: unknown, redact: Redactor): unknown;
+export interface TranscriptWriter {
+    /** One stdout line, without its newline. Never throws; a failed file is reported by `close`. */
+    write(line: string): void;
+    /** Flush the tail, finish the file, and describe it — `undefined` when the file could not be written. */
+    close(): Promise<TranscriptFile | undefined>;
+}
+/**
+ * Open the per-attempt transcript file. The first `TRANSCRIPT_HEAD_BYTES` are
+ * written as they arrive, so a crash mid-run still leaves the start of the
+ * transcript on disk; past that a ring of the last `TRANSCRIPT_TAIL_BYTES`
+ * is kept and flushed on close, behind one `relayflow.truncated` marker line
+ * that says how much fell between them.
+ */
+export declare function openTranscriptWriter(path: string, env?: NodeJS.ProcessEnv): Promise<TranscriptWriter | undefined>;
+/**
+ * Build the digest from the frames `decodeProviderResult` already parsed.
+ * Claude: `tool_use` blocks are paired with `tool_result` blocks by
+ * `tool_use_id`; `init` supplies model and version. Codex: `item.completed`
+ * items are counted by `item.type` only, so `tools.complete` is false.
+ * `failure` is filled only when the attempt did not succeed.
+ */
+export declare function buildTranscriptDigest(frames: RecordValue[], kind: 'claude' | 'codex', outcome: {
+    exit_code: number | null;
+    stderr_tail: string;
+}, env?: NodeJS.ProcessEnv): Pick<TranscriptDigest, 'result' | 'tools' | 'final_text' | 'final_text_truncated' | 'failure'>;
+/** Serialized size of the digest as it will be journaled. */
+export declare function digestBytes(digest: TranscriptDigest): number;
+/**
+ * Shrink the digest until it serializes to at most `TRANSCRIPT_DIGEST_MAX_BYTES`,
+ * in a fixed order: recent tool calls, artifact paths, final text, failure
+ * excerpt, tool counts. Each cut leaves its mark — `shown_calls` under
+ * `total_calls`, `artifacts.count` above `paths.length`, `final_text_truncated`,
+ * `failure.truncated` — so a reader knows the digest is not the whole account.
+ */
+export declare function boundTranscriptDigest(digest: TranscriptDigest): TranscriptDigest;
+export {};
+//# sourceMappingURL=agent-transcript.d.ts.map

package/dist/agent-transcript.d.ts.map

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