@xandout/libra-harness 0.1.131 → 0.1.133

package/dist/extensions/disk-session/extension.d.ts

@@ -1,215 +1,41 @@
-import type { Extension, Model } from '@xandout/libra-harness';
-import type { Message, MessageContent, ToolCall } from '@xandout/libra-harness';
-/**
- * A single record in a session's JSONL log.
- *
- * Maps directly to a Message plus correlation metadata. The system
- * prompt that was active for a turn is captured on the user record's
- * `systemPrompt` field. Background channel messages (observed but not
- * directed at the agent) are stored as `system` records so the agent
- * sees them as context, not as messages to respond to.
- */
-export interface SessionRecord {
-    role: 'user' | 'assistant' | 'tool' | 'control' | 'system';
-    content: MessageContent;
-    toolCalls?: ToolCall[];
-    toolCallId?: string;
-    name?: string;
-    /** Message correlation id (e.g. a Slack message timestamp, a Discord message id). */
-    ts: string;
-    /** Thread parent correlation id — undefined for top-level messages. */
-    threadTs?: string;
-    /** ISO timestamp for internal tracking. */
-    recordedAt: string;
-    /**
-     * The system prompt that was active for this turn. Persisted on the
-     * user record (the first record of each turn) so every turn's JSONL
-     * entry shows exactly what instructions the model was operating under.
-     * Absent on assistant, tool, and control records. Lets you audit
-     * "why did the model respond this way?" without replaying config +
-     * extension state.
-     */
-    systemPrompt?: string;
-    /** Token usage from the LLM provider (accumulated across iterations). */
-    usage?: {
-        promptTokens: number;
-        completionTokens: number;
-        iterations: number;
-        /** Prompt tokens served from provider cache (accumulated). */
-        cachedPromptTokens?: number;
-        /** Reasoning/thinking tokens (accumulated). */
-        reasoningTokens?: number;
-    };
-    /**
-     * Generic enrichment bag. Populated opaquely from
-     * `ctx.turn.metadata.sessionMeta` — any extension may write into
-     * that metadata key during `beforeTurn`/`afterLLM` and disk-session
-     * persists it here without inspecting the contents. Keys are owned
-     * by the extension that writes them (e.g. `keywords`, `sentiment`).
-     */
-    meta?: Record<string, unknown>;
-}
-/**
- * Identifies which session a turn belongs to.
- *
- * The host (or a resolver) produces this from turn metadata — the
- * disk-session extension never reads host-specific types directly.
- */
+import type { Extension } from '../../extension.js';
+import type { Model } from '../../model.js';
+import { type LedgerUsage, type MessageLedgerRecord, type SessionRecord } from './ledger.js';
 export interface SessionIdentity {
-    /** Stable session key — used as the JSONL filename and in-memory cache key. e.g. 'slack_C1', 'dm_U1', 'issue_42'.
-     * Should be filesystem-safe (alphanumeric, underscore, hyphen). Characters outside [a-zA-Z0-9_-] are replaced with '_' for the filename, so keys with colons or dots won't round-trip identically through a restart. */
     key: string;
-    /** Correlation id for the incoming message (persisted as `record.ts`). */
     messageTs: string;
-    /** Parent correlation id — when set, this message is a reply in a thread/sub-conversation. Persisted as `record.threadTs` and used as the context fork point. */
     threadTs?: string;
-    /** True for 1:1 conversations (DMs) — disables thread forking, uses simple last-N history. */
     isDirect?: boolean;
 }
-/**
- * Extracts a {@link SessionIdentity} from turn metadata.
- *
- * The host supplies a resolver so disk-session doesn't need to know
- * about Slack channels, Discord channels, or any other host concept.
- * Return `undefined` to skip session handling for a turn.
- */
 export interface SessionResolver {
     resolve(metadata: Record<string, unknown>): SessionIdentity | undefined;
 }
 export interface DiskSessionConfig {
-    /** Directory for session JSONL files. Default: ./sessions */
     sessionDir?: string;
-    /**
-     * Max records to keep in memory per session. Older records are
-     * evicted from the cache but remain in the JSONL file.
-     * Default: 1000.
-     */
-    maxRecords?: number;
-    /**
-     * Max messages to include in the agent's context per turn.
-     * When history reaches this threshold, auto-summarization is triggered.
-     * Default: 50.
-     */
     maxContextMessages?: number;
-    /**
-     * Number of messages to evict or compact at once when exceeding maxContextMessages.
-     * By evicting in discrete chunks rather than 1-by-1 per turn, the prompt prefix
-     * stays stable for consecutive turns, maximizing LLM prompt cache hits.
-     * Default: Math.max(1, Math.floor(maxContextMessages / 2)).
-     */
-    contextEvictionStep?: number;
-    /**
-     * Fallback message limits to back off to if a context length error occurs
-     * (e.g. [100, 50, 25]). If the model provider rejects a request due to
-     * context length, the extension steps down to the next fallback limit.
-     * Default: [maxContextMessages, Math.floor(maxContextMessages / 2), Math.floor(maxContextMessages / 4)].
-     */
-    fallbackThresholds?: number[];
-    /**
-     * Whether to automatically summarize older conversation messages when history
-     * reaches maxContextMessages.
-     * Default: true.
-     */
     autoSummarize?: boolean;
-    /**
-     * Model to use for generating auto-summaries.
-     * Defaults to the agent's configured model if not explicitly provided.
-     */
     model?: Model;
-    /**
-     * Number of top-level (non-thread) messages to include as channel
-     * context when forking a thread. These are messages that came BEFORE
-     * the thread parent — what the channel was discussing when the thread
-     * started. Default: 10.
-     */
     channelContextMessages?: number;
-    /**
-     * Number of recent top-level messages to include after the last thread
-     * reply. This gives the agent awareness of what's happened in the
-     * channel since the thread was last active (e.g. if someone comes back
-     * to a thread a week later, the agent sees recent channel activity).
-     * Default: 5.
-     */
     recentChannelMessages?: number;
-    /** Load existing JSONL files into memory on startup. Default: true. */
+    toolCallRetention?: number;
     loadOnStartup?: boolean;
-    /**
-     * Print a summary line when sessions are loaded from disk.
-     * Default: true.
-     */
     verbose?: boolean;
-    /**
-     * Resolve a {@link SessionIdentity} from turn metadata. Default:
-     * reads `metadata.session` as a `SessionIdentity`, falls back to
-     * `metadata.sessionId` as a plain key, then to `'default'`.
-     */
     resolver?: SessionResolver;
 }
-/**
- * Sanitizes a message sequence to strictly conform to LLM tool-call schemas:
- * 1. Every message with role 'tool' MUST directly follow an assistant message
- *    with a matching tool call id (or follow valid sibling tool messages for that same assistant).
- *    Any orphan or duplicate tool messages are dropped.
- * 2. If an assistant message has toolCalls, but some or all tool calls were never
- *    fulfilled (e.g. session interrupted mid-turn or tool execution halted), its
- *    toolCalls array is pruned to only the fulfilled tool calls.
- * 3. If an assistant message has toolCalls but none were fulfilled:
- *    - If the assistant message has non-empty text content, toolCalls is stripped.
- *    - If the assistant message has no text content, it is removed entirely.
- */
-export declare function sanitizeConversationMessages(messages: Message[]): Message[];
-export declare function isContextLengthError(err: unknown): boolean;
-export declare function generateSessionSummary(model: Model, records: SessionRecord[]): Promise<string>;
-/**
- * Disk-backed session extension.
- *
- * ## Architecture
- *
- * **One JSONL file per session** (`<sessionKey>.jsonl`). Append-only —
- * every message the agent sees (human or bot, top-level or threaded) is
- * appended. This log is the source of truth.
- *
- * **Snapshot at beforeTurn**: when a turn starts, the extension takes a
- * read-only snapshot of the session log at that moment. The turn runs
- * against the snapshot. Concurrent turns each take their own snapshot
- * and don't see each other's in-progress work.
- *
- * **Fork for threads**: when a thread reply comes in (identity has
- * `threadTs`), the snapshot is filtered to include only:
- *   1. Top-level messages before the thread parent (channel context)
- *   2. All messages in that thread (parent + replies)
- *   3. Recent top-level messages after the last thread reply
- *
- * **Append after turn**: when the turn finishes, new messages (user +
- * assistant + tool calls) are appended to the session log. No data is
- * ever rewritten or reordered.
- *
- * **Stable prefix for LLM caching**: the messages array is built as
- *   [system prompt] + [stable session history] + [new user message]
- * The session history grows monotonically (append-only), so earlier
- * tokens stay cached upstream. Per-turn metadata is injected at the end
- * of the context (by a host-side `beforeContext` hook), not the
- * beginning, to preserve the cache prefix.
- *
- * ## Host integration
- *
- * The host supplies a {@link SessionResolver} (or writes
- * `metadata.session`) so the extension knows which session a turn
- * belongs to. The extension itself is host-agnostic — it doesn't know
- * about Slack, Discord, or any other platform.
- */
-export default function createDiskSessionExtension(config?: DiskSessionConfig): Extension & {
+export interface DiskSessionExtension extends Extension {
     getRecords(sessionKey?: string): SessionRecord[];
     getSessions(): string[];
-    clear(sessionKey?: string): void;
-    clearAll(): void;
     appendControl(sessionKey: string, content: string, ts?: string, threadTs?: string): void;
     appendMessage(sessionKey: string, content: string, opts?: {
         ts?: string;
         threadTs?: string;
         meta?: Record<string, unknown>;
     }): void;
-    getEffectiveLimit(sessionKey?: string): number;
-    setEffectiveLimit(sessionKey: string, limit: number): void;
-};
+}
+export declare function generateSessionSummary(model: Model, records: MessageLedgerRecord[]): Promise<{
+    content: string;
+    usage?: LedgerUsage;
+}>;
+export default function createDiskSessionExtension(config?: DiskSessionConfig): DiskSessionExtension;
+export type { SessionRecord } from './ledger.js';
 //# sourceMappingURL=extension.d.ts.map

package/dist/extensions/disk-session/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../src/extensions/disk-session/extension.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../src/extensions/disk-session/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAG5C,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAYrB,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,GAAG,SAAS,CAAC;CACzE;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAqB,SAAQ,SAAS;IACrD,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAAC;IACjD,WAAW,IAAI,MAAM,EAAE,CAAC;IACxB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzF,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QACxD,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,GAAG,IAAI,CAAC;CACV;AAYD,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,mBAAmB,EAAE,GAC7B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC,CAenD;AAED,MAAM,CAAC,OAAO,UAAU,0BAA0B,CAAC,MAAM,GAAE,iBAAsB,GAAG,oBAAoB,CAgOvG;AAED,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}