@sayknow-cli/agent-core 0.3.13 → 0.3.15

package/dist/types/compaction/pruning.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Tool output pruning utilities for compaction.
+ *
+ * Candidate selection is staleness-aware: tool results that have been
+ * superseded by a later result for the same target (same file read again,
+ * same search re-run) or invalidated by a later successful edit/write to a
+ * covered file are pruned in preference to merely-old results. Protect-window
+ * and minimum-savings hysteresis semantics are unchanged.
+ */
+import type { SessionEntry, SessionMessageEntry } from "./entries";
+export interface PruneConfig {
+    /** Keep the most recent tool output tokens intact. */
+    protectTokens: number;
+    /** Only prune if total savings meets this threshold. */
+    minimumSavings: number;
+    /** Tool names that should never be pruned. */
+    protectedTools: string[];
+    /**
+     * Tools in `protectedTools` whose protection is waived once the result is
+     * superseded (a later result for the same target, or a later successful
+     * edit/write to the covered file). The most recent result per target is
+     * never considered superseded. Optional; defaults to none.
+     */
+    staleOverridableTools?: string[];
+}
+export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+export interface PruneResult {
+    prunedCount: number;
+    tokensSaved: number;
+    /**
+     * The mutated message entries. Callers whose entry source returns
+     * materialized copies (not live references) must write these back into
+     * their canonical store by id.
+     */
+    prunedEntries: SessionMessageEntry[];
+}
+export interface AssistantArgumentPruneResult {
+    argumentPrunedCount: number;
+    argumentTokensSaved: number;
+    /**
+     * The mutated assistant message entries. Callers whose entry source returns
+     * materialized copies must write these back into their canonical store by id.
+     */
+    prunedEntries: SessionMessageEntry[];
+}
+export declare function pruneAssistantToolArguments(entries: SessionEntry[], config?: PruneConfig): AssistantArgumentPruneResult;
+/**
+ * Estimate the token savings {@link pruneToolOutputs} would achieve, without
+ * mutating any entry. Returns 0 savings when below the configured minimum so the
+ * caller sees the same gate the real prune enforces.
+ */
+export declare function estimateToolOutputPruneSavings(entries: SessionEntry[], config?: PruneConfig): {
+    prunableCount: number;
+    tokensSaved: number;
+};
+/**
+ * Evidence gate for below-threshold maintenance pruning (Finding 13). Pruning
+ * forces a prompt-cache-epoch reset, so it only runs when opted in AND the
+ * estimated stale savings clear a high minimum AND exceed the one-time reset
+ * cost (so the reclaim pays the reset back). Default-off/blocked until live
+ * evidence justifies enabling.
+ */
+export declare function shouldRunMaintenancePrune(args: {
+    enabled: boolean;
+    estimatedSavings: number;
+    minSavings: number;
+    cacheEpochResetCost: number;
+}): boolean;
+export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;

package/dist/types/compaction/utils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+import type { Message } from "@sayknow-cli/ai";
+import type { AgentMessage } from "../types";
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export declare function createFileOps(): FileOperations;
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export declare function computeFileLists(fileOps: FileOperations): {
+    readFiles: string[];
+    modifiedFiles: string[];
+};
+export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
+export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[]): string;
+/**
+ * Serialize LLM messages to text for summarization.
+ * This prevents the model from treating it as a conversation to continue.
+ * Call convertToLlm() first to handle custom message types.
+ */
+export declare function serializeConversation(messages: Message[]): string;
+export declare const SUMMARIZATION_SYSTEM_PROMPT: string;

package/dist/types/compaction.d.ts

@@ -0,0 +1 @@
+export * from "./compaction/index";

package/dist/types/harmony-leak.d.ts

@@ -0,0 +1,100 @@
+/**
+ * GPT-5 Harmony-header leakage detection and recovery.
+ *
+ * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
+ * implements §3 of that document: detection by signal fusion, plus a
+ * truncate-and-resume primitive for the `edit` tool when its input is in
+ * hashline DSL form. Other tools and surfaces fall through to
+ * abort-and-retry handled by the agent loop.
+ */
+import type { AssistantMessage, Model } from "@sayknow-cli/ai";
+declare const SIGNAL_ORDER: readonly ["M", "C", "G", "S", "B", "R", "T"];
+export type HarmonySignalClass = "H" | "I" | (typeof SIGNAL_ORDER)[number];
+export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";
+export interface HarmonySignal {
+    classes: HarmonySignalClass[];
+    start: number;
+    end: number;
+    text: string;
+}
+export interface HarmonyDetection {
+    surface: HarmonySurface;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+    signals: HarmonySignal[];
+}
+export interface HarmonyAuditEvent {
+    action: "truncate_resume" | "abort_retry" | "escalated";
+    surface: HarmonySurface;
+    signal: string;
+    retryN: number;
+    model: string;
+    provider: string;
+    toolName?: string;
+    removedLen: number;
+    removedSha8: string;
+    removedPreview: string;
+    removedBlob?: string;
+}
+export interface HarmonyRecoveredToolCall {
+    message: AssistantMessage;
+    removed: string;
+}
+/**
+ * Whether to run leak detection on responses from this model. We default-on
+ * for every OpenAI code provider model rather than enumerating ids, so a future
+ * gpt-5.6 (or whatever) doesn't silently bypass the mitigation. Detection
+ * itself is cheap; the cost of missing a leak on a new model is not.
+ */
+export declare function isHarmonyLeakMitigationTarget(model: Model): boolean;
+export declare function shouldMitigateHarmonyLeak(model: Model, detection: HarmonyDetection): boolean;
+export declare function signalListLabel(signals: readonly HarmonySignal[]): string;
+/**
+ * Detect harmony-protocol leakage in `text`. Returns undefined if clean.
+ *
+ * Trip rule: `H` alone, or `M` paired with at least one co-signal
+ * (`C`/`G`/`S`/`B`/`R`/`T`). Bare `M` does not trip — this document, its
+ * tests, and bug reports legitimately carry the marker.
+ *
+ * `parsedEnd`, when supplied, marks the byte at which a structurally valid
+ * tool-argument parse ends; markers strictly after it set the `T` co-signal.
+ * `contentIndex`/`toolName`/`toolCallId` flow through to the returned
+ * detection for downstream auditing.
+ */
+export declare function detectHarmonyLeak(text: string, surface: HarmonySurface, options?: {
+    parsedEnd?: number;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+}): HarmonyDetection | undefined;
+/** Scan an assistant message's content blocks; return the first detection. */
+export declare function detectHarmonyLeakInAssistantMessage(message: AssistantMessage): HarmonyDetection | undefined;
+/**
+ * Truncate a contaminated tool call at the start of the contaminated line and
+ * append the tool's recovery sentinel. Returns a recovered AssistantMessage
+ * (containing only the cleaned tool call), a synthetic continuation user
+ * message asking the model to re-issue the rest, and the removed substring
+ * for auditing. Returns undefined when the tool is not recovery-eligible or
+ * the truncation would leave nothing meaningful to dispatch.
+ *
+ * `providerPayload` is dropped from the recovered message: for OpenAI code backend the
+ * encrypted reasoning blob is opaque/signed and we cannot validate that it is
+ * uncontaminated. The model re-reasons on the next turn.
+ */
+export declare function recoverHarmonyToolCall(message: AssistantMessage, detection: HarmonyDetection): HarmonyRecoveredToolCall | undefined;
+/**
+ * Return the contaminated substring from `message` for audit purposes when
+ * recovery is not applicable (abort path). Walks from the first detected
+ * signal to end-of-content within the relevant block. Returns "" if the
+ * detection cannot be resolved against the message.
+ */
+export declare function extractHarmonyRemoved(message: AssistantMessage, detection: HarmonyDetection): string;
+export declare function createHarmonyAuditEvent(params: {
+    action: HarmonyAuditEvent["action"];
+    detection: HarmonyDetection;
+    model: Model;
+    retryN: number;
+    removed: string;
+}): HarmonyAuditEvent;
+export {};

package/dist/types/image-placeholder-guard.d.ts

@@ -0,0 +1,4 @@
+import type { ImageContent, TextContent } from "@sayknow-cli/ai";
+export declare const IMAGE_PLACEHOLDER_ATTACHMENT_GUIDANCE = "Image placeholder text was submitted without an image payload. Paste the image with #paste-image, attach it with @path/to/image.png, or save the image and provide the saved file path.";
+export declare function isImagePlaceholderOnlyText(text: string): boolean;
+export declare function assertImagePlaceholdersHavePayload(text: string, content: readonly (TextContent | ImageContent)[] | undefined): void;

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./agent";
+export * from "./agent-loop";
+export * from "./append-only-context";
+export * from "./compaction";
+export * from "./harmony-leak";
+export * from "./image-placeholder-guard";
+export * from "./proxy";
+export * from "./run-collector";
+export * from "./telemetry";
+export * from "./thinking";
+export * from "./types";

package/dist/types/proxy.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Proxy stream function for apps that route LLM calls through a server.
+ * The server manages auth and proxies requests to LLM providers.
+ */
+import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream, type Model, type SimpleStreamOptions, type StopReason } from "@sayknow-cli/ai";
+declare class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+    constructor();
+}
+/**
+ * Proxy event types - server sends these with partial field stripped to reduce bandwidth.
+ */
+export type ProxyAssistantMessageEvent = {
+    type: "start";
+} | {
+    type: "text_start";
+    contentIndex: number;
+} | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    contentSignature?: string;
+} | {
+    type: "thinking_start";
+    contentIndex: number;
+} | {
+    type: "thinking_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "thinking_end";
+    contentIndex: number;
+    contentSignature?: string;
+} | {
+    type: "toolcall_start";
+    contentIndex: number;
+    id: string;
+    toolName: string;
+} | {
+    type: "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+} | {
+    type: "done";
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    usage: AssistantMessage["usage"];
+} | {
+    type: "error";
+    reason: Extract<StopReason, "aborted" | "error">;
+    errorMessage?: string;
+    usage: AssistantMessage["usage"];
+};
+export interface ProxyStreamOptions extends SimpleStreamOptions {
+    /** Auth token for the proxy server */
+    authToken: string;
+    /** Proxy server URL (e.g., "https://genai.example.com") */
+    proxyUrl: string;
+}
+/**
+ * Stream function that proxies through a server instead of calling LLM providers directly.
+ * The server strips the partial field from delta events to reduce bandwidth.
+ * We reconstruct the partial message client-side.
+ *
+ * Use this as the `streamFn` option when creating an Agent that needs to go through a proxy.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   streamFn: (model, context, options) =>
+ *     streamProxy(model, context, {
+ *       ...options,
+ *       authToken: await getAuthToken(),
+ *       proxyUrl: "https://genai.example.com",
+ *     }),
+ * });
+ * ```
+ */
+export declare function streamProxy(model: Model, context: Context, options: ProxyStreamOptions): ProxyMessageEventStream;
+export {};

package/dist/types/run-collector.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Per-invocation run aggregator. Buffers per-chat and per-tool records as the
+ * loop executes and folds them into a single {@link AgentRunSummary} +
+ * {@link AgentRunCoverage} value at the end.
+ *
+ * One collector lives on each {@link AgentTelemetry} handle, which is
+ * constructed once per `agentLoop` invocation in {@link resolveTelemetry}.
+ * Collector lookups use the live `Span` as a `WeakMap` key — bounded memory,
+ * no cross-invoke leakage.
+ *
+ * The collector is fed exclusively by helpers in `./telemetry.ts`. Loop
+ * authors do not interact with it directly except via the public
+ * `recordSkippedTool` helper used for the two skip paths that bypass spans
+ * entirely (pre-run interrupt and the tail-sweep for tool calls that never
+ * produced a result message).
+ */
+import type { Span } from "@opentelemetry/api";
+import type { AssistantMessage, Model, StopReason } from "@sayknow-cli/ai";
+/** Terminal status reported by an `execute_tool` span. */
+export type ToolStatus = "ok" | "error" | "skipped" | "blocked" | "timeout" | "aborted";
+/** Raw record for a single `chat` step, finalized by `finishChatSpan`. */
+export interface ChatRecord {
+    readonly stepNumber: number;
+    readonly model: string;
+    readonly provider: string;
+    readonly stopReason: StopReason | undefined;
+    readonly latencyMs: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly reasoningOutputTokens: number;
+    readonly totalTokens: number;
+    readonly costUsd: number | undefined;
+    readonly costUnavailableReason: string | undefined;
+    readonly errorType: string | undefined;
+}
+/** Raw record for a single `execute_tool` invocation. */
+export interface ToolRecord {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly status: ToolStatus;
+    readonly latencyMs: number;
+    readonly errorType: string | undefined;
+}
+/** Per-tool counters surfaced under {@link AgentRunSummary.tools.byName}. */
+export interface ToolCounters {
+    readonly total: number;
+    readonly ok: number;
+    readonly error: number;
+    readonly skipped: number;
+    readonly blocked: number;
+    readonly timeout: number;
+    readonly aborted: number;
+    readonly totalLatencyMs: number;
+}
+/**
+ * Run-level rollup returned in the `agent_end` event and passed to
+ * {@link AgentTelemetryConfig.onRunEnd}. Pure aggregation — no references to
+ * spans, no callbacks, no live state. Safe to persist / diff / assert.
+ */
+export interface AgentRunSummary {
+    readonly chats: {
+        readonly total: number;
+        /** Bucketed by raw {@link StopReason}; absent reasons omitted. */
+        readonly byStopReason: Readonly<Record<string, number>>;
+        readonly totalLatencyMs: number;
+    };
+    readonly tools: {
+        readonly total: number;
+        readonly ok: number;
+        readonly error: number;
+        readonly skipped: number;
+        readonly blocked: number;
+        readonly timeout: number;
+        readonly aborted: number;
+        readonly totalLatencyMs: number;
+        /** Per-tool-name counters; keys sorted by name on snapshot. */
+        readonly byName: Readonly<Record<string, ToolCounters>>;
+    };
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly cachedInputTokens: number;
+        readonly cacheWriteTokens: number;
+        readonly reasoningOutputTokens: number;
+        readonly totalTokens: number;
+    };
+    readonly cost: {
+        readonly estimatedUsd: number;
+        /** Sorted, deduped. */
+        readonly unavailableReasons: readonly string[];
+    };
+    readonly errors: {
+        readonly total: number;
+        readonly byType: Readonly<Record<string, number>>;
+    };
+    readonly stepCount: number;
+}
+/**
+ * Coverage rollup: registered-vs-invoked across the run. All arrays are
+ * sorted ascending and deduped so the value is stable for diffing.
+ */
+export interface AgentRunCoverage {
+    readonly toolsAvailable: readonly string[];
+    readonly toolsInvoked: readonly string[];
+    readonly toolsUnused: readonly string[];
+    readonly modelsUsed: readonly string[];
+    readonly providersUsed: readonly string[];
+}
+export declare class AgentRunCollector {
+    #private;
+    /** True once `markRunEnded()` has been called for this invocation. */
+    get runEnded(): boolean;
+    /**
+     * Mark this run as logically ended. Callers use this to coordinate the
+     * `onRunEnd` hook between the success path (fires inside
+     * `buildAgentEndEvent`, before `stream.end()`) and the error path (fires
+     * inside `finishInvokeAgentSpan`'s finally). Idempotent — returns `true`
+     * the first time, `false` on subsequent calls.
+     */
+    markRunEnded(): boolean;
+    /** Record the tool names exposed on a single chat step. */
+    noteAvailableTools(tools: readonly {
+        readonly name: string;
+    }[] | undefined): void;
+    beginChat(span: Span, init: {
+        readonly stepNumber: number;
+        readonly model: Model;
+        readonly provider?: string;
+    }): void;
+    endChat(span: Span, message: AssistantMessage, fields: {
+        readonly costUsd: number | undefined;
+        readonly costUnavailableReason: string | undefined;
+    }): void;
+    /**
+     * Stamp the chat span as failed without a finalized AssistantMessage. Used
+     * by the `catch` arm of `streamAssistantResponse` so error chats still
+     * appear in the run summary.
+     */
+    failChat(span: Span, fields: {
+        readonly errorType: string;
+    }): void;
+    beginTool(span: Span, init: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+    }): void;
+    endTool(span: Span, fields: {
+        readonly status: ToolStatus;
+        readonly errorType: string | undefined;
+    }): void;
+    /**
+     * Record a tool that never produced a span — pre-run interrupt or tail
+     * sweep. The LLM still asked for it, so it counts toward
+     * {@link AgentRunCoverage.toolsInvoked}.
+     */
+    recordOrphanTool(record: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+        readonly status: ToolStatus;
+    }): void;
+    /** Build the immutable summary value from buffered records. */
+    snapshot(opts: {
+        readonly stepCount: number;
+    }): {
+        readonly summary: AgentRunSummary;
+        readonly coverage: AgentRunCoverage;
+    };
+}
+/**
+ * Fold multiple per-run summaries into one. Pure aggregation — useful when a
+ * caller (verify pass, benchmark harness) drives the agent loop N times and
+ * needs a single rollup across all invocations.
+ *
+ * Counters sum element-wise. Sets (cost reasons, error types, per-tool
+ * counters) merge by key. Numeric totals sum. The output is in the same
+ * shape as a single `AgentRunSummary`, so all dashboards and persistence
+ * layers handle it uniformly.
+ */
+export declare function aggregateAgentRunSummaries(summaries: readonly AgentRunSummary[]): AgentRunSummary;
+/** Union-merge multiple coverage values, preserving the sorted+deduped invariant. */
+export declare function aggregateAgentRunCoverage(coverages: readonly AgentRunCoverage[]): AgentRunCoverage;
+/** Empty `AgentRunSummary` constant. Exported for tests and default-initializers. */
+export declare function emptyAgentRunSummary(): AgentRunSummary;
+/** Empty `AgentRunCoverage` constant. Exported for tests and default-initializers. */
+export declare function emptyAgentRunCoverage(): AgentRunCoverage;
+/**
+ * Distinguishable error class thrown when `beforeToolCall` returns
+ * `{ block: true }`. Lets the catch arm of `runTool` set the terminal status
+ * on the execute_tool span to `"blocked"` instead of conflating with a real
+ * tool exception.
+ */
+export declare class ToolCallBlockedError extends Error {
+    readonly name = "ToolCallBlockedError";
+    constructor(reason?: string);
+}