tracelattice 1.2.9 → 1.3.1

package/dist/contracts/strategy.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Reasoning Strategy contract — defines how a strategy observes reasoning state
+ * and decides the next action (continue, branch, terminate, suspend).
+ *
+ * Strategies are pluggable policies that drive higher-level reasoning control
+ * flow on top of the sequential thinking pipeline. They are pure (no I/O) and
+ * receive a snapshot of session state via {@link StrategyContext}.
+ *
+ * @module contracts/strategy
+ */
+import type { ThoughtData } from '../core/thought.js';
+import type { ReasoningStats } from '../core/reasoning.js';
+import type { GraphView } from '../core/graph/GraphView.js';
+/**
+ * Read-only snapshot of session state passed to a reasoning strategy.
+ *
+ * All fields are immutable references. Strategies MUST NOT mutate the
+ * history, graph, or stats — doing so will corrupt downstream consumers.
+ *
+ * @example
+ * ```ts
+ * const ctx: StrategyContext = {
+ *   sessionId: 'sess_42',
+ *   history: hm.getHistory('sess_42'),
+ *   graph: new GraphView(edgeStore, 'sess_42'),
+ *   stats: evaluator.computeStats(history),
+ *   currentThought: latestThought,
+ * };
+ * const decision = strategy.decide(ctx);
+ * ```
+ */
+export interface StrategyContext {
+    /** Session identifier this context belongs to. */
+    readonly sessionId: string;
+    /** Chronological list of thoughts recorded in this session. */
+    readonly history: readonly ThoughtData[];
+    /** Read-only graph view for traversal (ancestors, descendants, etc.). */
+    readonly graph: GraphView;
+    /** Aggregated reasoning analytics for the session. */
+    readonly stats: ReasoningStats;
+    /** The thought that just triggered the strategy decision. */
+    readonly currentThought: ThoughtData;
+}
+/**
+ * Discriminated union describing the action a strategy wants to take.
+ *
+ * - `continue`  — keep the current chain; optionally hint at next direction.
+ * - `branch`    — fork a new branch from a prior thought.
+ * - `terminate` — stop the reasoning chain; reason is required.
+ * - `suspend`   — pause the chain; may be resumed after `resumeAfter` ms.
+ *
+ * @example
+ * ```ts
+ * const d: StrategyDecision = { action: 'branch', branchId: 'alt-1', fromThought: 3 };
+ * if (d.action === 'branch') console.log(d.branchId);
+ * ```
+ */
+export type StrategyDecision = {
+    action: 'continue';
+    reason?: string;
+    nextHint?: string;
+} | {
+    action: 'branch';
+    branchId: string;
+    fromThought: number;
+    reason?: string;
+} | {
+    action: 'terminate';
+    reason: string;
+} | {
+    action: 'suspend';
+    reason: string;
+    resumeAfter?: number;
+};
+/**
+ * Pluggable reasoning strategy interface.
+ *
+ * Implementations are stateless with respect to global state — all input
+ * comes from the {@link StrategyContext}. Strategies are registered via DI
+ * and selected by name (e.g. `tot`, `cot`, `react`).
+ *
+ * @example
+ * ```ts
+ * class GreedyStrategy implements IReasoningStrategy {
+ *   readonly name = 'greedy';
+ *   decide(ctx: StrategyContext): StrategyDecision {
+ *     return { action: 'continue' };
+ *   }
+ *   shouldBranch(_ctx: StrategyContext): boolean { return false; }
+ *   shouldTerminate(ctx: StrategyContext): boolean {
+ *     return ctx.history.length >= 50;
+ *   }
+ * }
+ * ```
+ */
+export interface IReasoningStrategy {
+    /** Stable identifier (used for DI lookup and metrics labels). */
+    readonly name: string;
+    /** Compute the next action given the current state snapshot. */
+    decide(ctx: StrategyContext): StrategyDecision;
+    /** Predicate: should the chain branch right now? */
+    shouldBranch(ctx: StrategyContext): boolean;
+    /** Predicate: should the chain terminate right now? */
+    shouldTerminate(ctx: StrategyContext): boolean;
+}
+//# sourceMappingURL=strategy.d.ts.map

package/dist/contracts/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/contracts/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC;CACrC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB;IAClC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,eAAe,GAAG,gBAAgB,CAAC;IAC/C,oDAAoD;IACpD,YAAY,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;IAC5C,uDAAuD;IACvD,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;CAC/C"}

package/dist/contracts/strategy.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/summary.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Summary store contract — defines the interface for persisting and querying
+ * compressed thought summaries produced by the compression subsystem.
+ *
+ * Implementations must provide per-session isolation: summaries from one
+ * session must never appear in queries scoped to another session.
+ *
+ * @module contracts/summary
+ */
+import type { Summary } from '../core/compression/Summary.js';
+export type { Summary };
+/**
+ * Storage and query contract for {@link Summary} records.
+ *
+ * Implementations are expected to be in-process (no I/O) and synchronous.
+ * Persistence backends may wrap this interface in async adapters.
+ *
+ * @example
+ * ```ts
+ * const store: ISummaryStore = new InMemorySummaryStore();
+ * store.add(summary);
+ * const all = store.forSession('sess_42');
+ * const branch = store.forBranch('sess_42', 'alt-1');
+ * ```
+ */
+export interface ISummaryStore {
+    /**
+     * Add a summary to the store.
+     *
+     * @param summary - The summary record to add
+     *
+     * @example
+     * ```ts
+     * store.add({ id: '01HX...', sessionId: 's1', rootThoughtId: 't5', ... });
+     * ```
+     */
+    add(summary: Summary): void;
+    /**
+     * Retrieve a summary by its unique id.
+     *
+     * @param id - The summary's unique identifier
+     * @returns The summary, or `undefined` if not found
+     *
+     * @example
+     * ```ts
+     * const s = store.get('01HX...');
+     * if (s) console.log(s.topics);
+     * ```
+     */
+    get(id: string): Summary | undefined;
+    /**
+     * Get all summaries for a session, in insertion order.
+     *
+     * @param sessionId - Session to query
+     * @returns Read-only array of summaries (may be empty)
+     *
+     * @example
+     * ```ts
+     * for (const s of store.forSession('sess_42')) {
+     *   console.log(s.coveredRange);
+     * }
+     * ```
+     */
+    forSession(sessionId: string): readonly Summary[];
+    /**
+     * Get all summaries for a specific branch within a session.
+     *
+     * @param sessionId - Session to query
+     * @param branchId - Branch identifier to filter by
+     * @returns Read-only array of summaries on that branch (may be empty)
+     *
+     * @example
+     * ```ts
+     * const altSummaries = store.forBranch('sess_42', 'alt-1');
+     * ```
+     */
+    forBranch(sessionId: string, branchId: string): readonly Summary[];
+    /**
+     * Remove all summaries for a session. Other sessions are unaffected.
+     *
+     * @param sessionId - Session to clear
+     *
+     * @example
+     * ```ts
+     * store.clearSession('sess_42');
+     * ```
+     */
+    clearSession(sessionId: string): void;
+    /**
+     * Count summaries.
+     *
+     * @param sessionId - If provided, count for that session only;
+     *   otherwise return the total across all sessions
+     * @returns The number of summaries
+     *
+     * @example
+     * ```ts
+     * const total = store.size();
+     * const perSession = store.size('sess_42');
+     * ```
+     */
+    size(sessionId?: string): number;
+}
+//# sourceMappingURL=summary.d.ts.map

package/dist/contracts/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../src/contracts/summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAE9D,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;;;;;;OASG;IACH,GAAG,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAErC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAAC;IAElD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAAC;IAEnE;;;;;;;;;OASG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC"}

package/dist/contracts/summary.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/suspension.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Suspension store contract for tool interleave.
+ *
+ * Manages pending tool_call thoughts that are awaiting tool execution
+ * results. Each suspension is identified by a unique token, has a TTL,
+ * and can be resumed (consumed) or peeked (non-destructive lookup).
+ *
+ * @module contracts/suspension
+ */
+/**
+ * A single pending tool-call suspension record.
+ *
+ * Created when a `tool_call` thought is processed and the system is
+ * waiting for the corresponding tool result to be supplied via a
+ * follow-up `tool_result` thought.
+ */
+export interface SuspensionRecord {
+    /** Opaque token used to resume this suspension. */
+    readonly token: string;
+    /** Session that owns this suspension. */
+    readonly sessionId: string;
+    /** Thought number of the originating `tool_call` thought. */
+    readonly toolCallThoughtNumber: number;
+    /** Name of the tool to invoke. */
+    readonly toolName: string;
+    /** Arguments supplied to the tool. */
+    readonly toolArguments: Record<string, unknown>;
+    /** Wall-clock millisecond timestamp when the record was created. */
+    readonly createdAt: number;
+    /** Wall-clock millisecond timestamp after which the record is expired. */
+    readonly expiresAt: number;
+}
+/**
+ * Store of pending tool-call suspensions with TTL expiry.
+ *
+ * Implementations are expected to expire records lazily on access and
+ * (optionally) eagerly via a background sweeper started by `start()`.
+ *
+ * @example
+ * ```typescript
+ * const store: ISuspensionStore = new InMemorySuspensionStore();
+ * store.start();
+ * const rec = store.suspend({
+ *   sessionId: 's1',
+ *   toolCallThoughtNumber: 3,
+ *   toolName: 'search',
+ *   toolArguments: { q: 'foo' },
+ *   expiresAt: Date.now() + 60_000,
+ * });
+ * const resumed = store.resume(rec.token);
+ * store.stop();
+ * ```
+ */
+export interface ISuspensionStore {
+    /**
+     * Create and store a new suspension record.
+     *
+     * The implementation generates a unique `token` and `createdAt`
+     * timestamp. If `ttlMs` is supplied, `expiresAt` is computed as
+     * `Date.now() + ttlMs` and overrides any caller-supplied
+     * `expiresAt` value.
+     *
+     * @param record - Record fields excluding `token` and `createdAt`,
+     * with optional `ttlMs` to derive `expiresAt`.
+     * @returns The fully-populated stored record.
+     *
+     * @example
+     * ```typescript
+     * const rec = store.suspend({
+     *   sessionId: 's1',
+     *   toolCallThoughtNumber: 2,
+     *   toolName: 'search',
+     *   toolArguments: {},
+     *   ttlMs: 30_000,
+     *   expiresAt: 0,
+     * });
+     * ```
+     */
+    suspend(record: Omit<SuspensionRecord, 'token' | 'createdAt'> & {
+        ttlMs?: number;
+    }): SuspensionRecord;
+    /**
+     * Consume a suspension by token.
+     *
+     * Returns `null` for both unknown tokens and expired records;
+     * expired records are removed as a side-effect. The caller
+     * (typically `ThoughtProcessor`) is expected to distinguish the
+     * two cases (e.g. via a prior `peek()`) and throw
+     * `SuspensionNotFoundError` or `SuspensionExpiredError`
+     * accordingly.
+     *
+     * @param token - Token returned from {@link suspend}.
+     * @returns The record on success, `null` if missing or expired.
+     *
+     * @example
+     * ```typescript
+     * const rec = store.resume(token);
+     * if (!rec) throw new SuspensionNotFoundError(token);
+     * ```
+     */
+    resume(token: string): SuspensionRecord | null;
+    /**
+     * Non-destructive lookup of a suspension by token.
+     *
+     * Does not remove expired records. Returns `null` if the token is
+     * unknown.
+     *
+     * @param token - Token to inspect.
+     * @returns The record if present (even when expired), else `null`.
+     *
+     * @example
+     * ```typescript
+     * const rec = store.peek(token);
+     * if (rec && rec.expiresAt < Date.now()) {
+     *   throw new SuspensionExpiredError(token);
+     * }
+     * ```
+     */
+    peek(token: string): SuspensionRecord | null;
+    /**
+     * Remove all records whose `expiresAt` is at or before `now`.
+     *
+     * @param now - Wall-clock millisecond timestamp to compare against.
+     * @returns Number of records removed.
+     *
+     * @example
+     * ```typescript
+     * const removed = store.expireOlderThan(Date.now());
+     * ```
+     */
+    expireOlderThan(now: number): number;
+    /**
+     * Remove all records belonging to a session.
+     *
+     * @param sessionId - Session whose records should be cleared.
+     *
+     * @example
+     * ```typescript
+     * store.clearSession('session-a');
+     * ```
+     */
+    clearSession(sessionId: string): void;
+    /**
+     * Count stored records.
+     *
+     * @param sessionId - Optional session filter; when omitted, returns
+     * the total count across all sessions.
+     * @returns Number of currently stored records (expired-but-not-yet-swept
+     * records are included).
+     *
+     * @example
+     * ```typescript
+     * const total = store.size();
+     * const perSession = store.size('session-a');
+     * ```
+     */
+    size(sessionId?: string): number;
+    /**
+     * Start the background sweeper, if any.
+     *
+     * Idempotent — repeated calls have no additional effect.
+     *
+     * @example
+     * ```typescript
+     * store.start();
+     * ```
+     */
+    start(): void;
+    /**
+     * Stop the background sweeper, if any.
+     *
+     * Idempotent — repeated calls have no additional effect.
+     *
+     * @example
+     * ```typescript
+     * store.stop();
+     * ```
+     */
+    stop(): void;
+}
+//# sourceMappingURL=suspension.d.ts.map

package/dist/contracts/suspension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspension.d.ts","sourceRoot":"","sources":["../../src/contracts/suspension.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAChC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,gBAAgB;IAChC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CACN,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,WAAW,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxE,gBAAgB,CAAC;IAEpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAE/C;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAErC;;;;;;;;;OASG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEjC;;;;;;;;;OASG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;;;;;;;OASG;IACH,IAAI,IAAI,IAAI,CAAC;CACb"}

package/dist/contracts/suspension.js

@@ -0,0 +1 @@
+export { };