@theokit/sdk 1.6.1 → 1.7.0

package/dist/internal/agent-loop/loop-context-init.d.ts

@@ -0,0 +1,2 @@
+import type { AgentLoopInputs } from "./loop-types.js";
+export declare function initLoopContext(inputs: AgentLoopInputs): Promise<LoopContext>;

package/dist/internal/agent-loop/tool-dispatch.d.ts

@@ -1,4 +1,25 @@
 import type { SDKMessage } from "../../types/messages.js";
 import type { LlmContentPart, LlmToolCallPart } from "../llm/types.js";
-import type { AgentLoopInputs } from "./loop-types.js";
+import type { AgentLoopInputs, ResolvedTool } from "./loop-types.js";
+export type { ResolvedTool } from "./loop-types.js";
+/**
+ * T2.4 — Parallel tool dispatch with bounded concurrency (DR2 finding #4).
+ *
+ * Pre-T2.4 this was a serial `for...of` loop — each tool call awaited
+ * before the next. With N independent tools each taking Tms, total
+ * wall-clock was N×Tms. T2.4 switches to `Promise.all` with bounded
+ * concurrency via an inline semaphore (ADR D135 — in-house, no
+ * `p-limit` dep). Default cap is 4 concurrent tools; consumer
+ * overrides via `AgentLoopInputs.maxConcurrentTools`.
+ *
+ * Order preservation: `Promise.all` preserves input order in the
+ * resolved array regardless of which promise settles first — the
+ * LLM expects tool results in call order and this contract holds.
+ *
+ * Event array safety: `events` is append-only. In single-threaded
+ * JS (Node event loop), concurrent `.push()` calls from different
+ * microtask continuations do NOT interleave — each push is atomic.
+ * The order of events across tools becomes non-deterministic, but
+ * each individual tool's events are internally ordered.
+ */
 export declare function dispatchTools(inputs: AgentLoopInputs, tools: ResolvedTool[], toolCalls: LlmToolCallPart[], events: SDKMessage[]): Promise<LlmContentPart[]>;

package/dist/internal/auth/api-key-validator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * T1.3 — API key boundary validation.
+ *
+ * `validateApiKeyShape(key, provider?)` runs at the create-agent boundary
+ * and rejects malformed inputs early (whitespace-only strings, sub-16-char
+ * fragments, embedded whitespace, missing-prefix shapes for providers that
+ * stamp a known prefix). The check is shape-only — it does NOT make a
+ * round-trip to the provider; live validation still happens at the first
+ * `fetch` against the provider URL.
+ *
+ * Exempted from shape validation:
+ * - fixture keys (prefix `theo_test_`) — used by SDK consumers' fixture-mode tests.
+ * - local-runtime mock key `"local"` — used by Ollama / LMStudio / llama.cpp
+ *   sibling profiles (ADRs D182/D188/D189) whose `authType` is `"none"`.
+ *
+ * @internal
+ */
+export interface ApiKeyValidationFailure {
+    readonly malformed: true;
+    readonly reason: "empty" | "whitespace_only" | "too_short" | "embedded_whitespace" | "missing_known_prefix";
+    readonly message: string;
+}
+export interface ApiKeyValidationOk {
+    readonly malformed: false;
+}
+export type ApiKeyValidationResult = ApiKeyValidationOk | ApiKeyValidationFailure;
+export interface ValidateApiKeyOptions {
+    /** Provider name (lowercase) for prefix sanity check. */
+    provider?: string;
+    /**
+     * When `false`, only OBVIOUSLY-malformed inputs (empty, whitespace-only,
+     * < 4 chars) are rejected. Set when the caller knows the value is just an
+     * identifier (e.g., `shouldUseRealLocalRuntime` mode where the real HTTP
+     * call uses an env credential instead of this `apiKey`).
+     *
+     * When `true` (default), the full shape check applies: 16-char minimum,
+     * provider-prefix sanity, no embedded whitespace.
+     */
+    strict?: boolean;
+}
+/**
+ * Validate the shape of an API key. Returns a discriminated result; the
+ * boundary caller (`agent.ts createLocalAgent` / `createCloudAgent`) throws
+ * `AuthenticationError({code:"malformed_api_key"})` on failure.
+ */
+export declare function validateApiKeyShape(key: string | undefined, options?: ValidateApiKeyOptions | string): ApiKeyValidationResult;

package/dist/internal/llm/anthropic-shared.d.ts

@@ -76,10 +76,17 @@ export declare function consumeAnthropicResponse(response: Response): Promise<{
     outputTokens?: number;
 }>;
 export declare function parseHttpErrorBody(response: Response): Promise<unknown>;
+export interface AnthropicTextBlock {
+    type: "text";
+    text: string;
+    cache_control?: {
+        type: "ephemeral";
+    };
+}
 export declare function buildAnthropicCommonBody(request: LlmRequest): {
     max_tokens: number;
     messages: Array<Record<string, unknown>>;
-    system?: string;
+    system?: string | AnthropicTextBlock[];
     temperature?: number;
     tools?: Array<{
         name: string;

package/dist/internal/llm/retry.d.ts

@@ -0,0 +1,22 @@
+/**
+ * T3.4 — exponential backoff with full jitter for credential-pool retry.
+ *
+ * Why we need this: pre-T3.4 `pool-aware-client.ts:79-83` retried the
+ * SAME credential immediately on the first 429 without any wait. When
+ * every credential in the pool returned 429 (thundering herd against a
+ * shared quota), the client burned through all 5 retry attempts in <1ms,
+ * tripped `CredentialPoolExhaustedError`, and surfaced to the agent loop
+ * as a hard failure. The user-visible symptom was "all my keys are
+ * exhausted!" when in reality a 1-2s wait would have cleared the rate
+ * limit.
+ *
+ * AWS Architecture Blog "Exponential Backoff And Jitter" (Marc Brooker,
+ * 2015) demonstrates full jitter as the canonical pattern: `sleep =
+ * random_between(0, base * 2^attempt)`. We extend it with a hard cap
+ * (so a 32s sleep never blocks an interactive agent) and honor the
+ * provider's `Retry-After` hint when present — the hint always wins over
+ * the computed value when it falls within `[base, cap]`.
+ *
+ * @internal
+ */
+export {};

package/dist/internal/llm/types.d.ts

@@ -27,13 +27,59 @@ export interface LlmMessage {
     role: "system" | "user" | "assistant";
     content: LlmContentPart[];
 }
+/**
+ * T3.5 — a single system-prompt block. Used by `LlmRequest.system` when the
+ * caller wants to opt into Anthropic prompt caching: each block whose
+ * `cacheable` is `true` gets the `cache_control: {type: 'ephemeral'}`
+ * annotation in the Anthropic wire body, which lets Anthropic bill
+ * subsequent same-content requests at the cache-read rate (1-3x discount).
+ *
+ * For providers that don't support prompt caching (OpenAI, OpenRouter, etc),
+ * the array is joined into a single string at the wire boundary so the
+ * upstream contract stays unchanged. Back-compat: `LlmRequest.system` still
+ * accepts a plain `string` (pre-T3.5 callers compile unchanged).
+ */
+export interface LlmSystemBlock {
+    text: string;
+    /** When `true`, ask the provider to cache this block (Anthropic only). */
+    cacheable?: boolean;
+}
+/**
+ * T3.6 — `LlmRequest.responseFormat` opt-in for OpenAI native structured
+ * outputs. When set, providers that support it emit the response strictly
+ * matching the schema (no parse retries; lower latency than the
+ * synthetic-tool fallback path).
+ *
+ * Two shapes:
+ *  - `{ type: "json_schema", jsonSchema: { name, schema, strict? } }` —
+ *    the canonical structured-outputs shape (`gpt-4o-2024-08-06+`).
+ *    `strict` defaults to `true` (provider guarantees match).
+ *  - `{ type: "json_object" }` — the legacy "JSON mode" hint (older
+ *    OpenAI models). Returns JSON but does NOT guarantee schema match.
+ *
+ * Providers that don't support the field (Anthropic, Ollama) silently
+ * ignore it at the wire layer (`buildAnthropicCommonBody`,
+ * `buildOllamaChatBody`).
+ */
+export type LlmResponseFormat = {
+    type: "json_object";
+} | {
+    type: "json_schema";
+    jsonSchema: {
+        name: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+};
 export interface LlmRequest {
     model: string;
-    system?: string;
+    system?: string | LlmSystemBlock[];
     messages: LlmMessage[];
     tools?: LlmTool[];
     maxTokens?: number;
     temperature?: number;
+    /** T3.6 — opt into native structured outputs (OpenAI-compat providers). */
+    responseFormat?: LlmResponseFormat;
 }
 export type LlmEvent = {
     type: "text_delta";

package/dist/internal/memory/active-memory-cache.d.ts

@@ -1,10 +1,10 @@
-import type { ActiveMemoryResult } from "./active-memory.js";
+import type { ActiveMemoryResult } from "./active-memory-types.js";
 export declare class ActiveMemoryCache {
     private readonly opts;
     private readonly map;
     constructor(opts?: ActiveMemoryCacheOptions);
-    get(userText: string, queryMode: string): ActiveMemoryResult | undefined;
-    set(userText: string, queryMode: string, result: ActiveMemoryResult): void;
+    get(userText: string, queryMode: string, tenantCtx?: TenantContext): ActiveMemoryResult | undefined;
+    set(userText: string, queryMode: string, result: ActiveMemoryResult, tenantCtx?: TenantContext): void;
     size(): number;
     private now;
 }

package/dist/internal/memory/active-memory-types.d.ts

@@ -0,0 +1,8 @@
+import type { MemorySearchHit } from "./index-manager-contract.js";
+export type ActiveMemoryStatus = "ok" | "timeout" | "skipped" | "no-recall" | "error";
+export interface ActiveMemoryResult {
+    summary: string | undefined;
+    durationMs: number;
+    status: ActiveMemoryStatus;
+    hits: ReadonlyArray<MemorySearchHit>;
+}

package/dist/internal/memory/active-memory.d.ts

@@ -1,26 +1,9 @@
+import { type TelemetryHandle } from "../telemetry/tracer.js";
 import type { ActiveMemoryCache } from "./active-memory-cache.js";
+import type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus } from "./active-memory-types.js";
 import type { CircuitBreaker } from "./circuit-breaker.js";
-import type { MemorySearchHit } from "./index-manager.js";
 import type { MemoryIndex } from "./memory-index.js";
-export type ActiveMemoryStatus = "ok" | "timeout" | "skipped" | "no-recall" | "error";
-export interface ActiveMemoryResult {
-    summary: string | undefined;
-    durationMs: number;
-    status: ActiveMemoryStatus;
-    hits: ReadonlyArray<MemorySearchHit>;
-}
-export interface ActiveMemoryOptions {
-    /** Whether active recall is enabled. Default `false`. */
-    enabled?: boolean;
-    /** Query construction strategy. Default `"recent"`. */
-    queryMode?: ActiveMemoryQueryMode;
-    /** Hard timeout in ms. Default `15000`. */
-    timeoutMs?: number;
-    /** Max chars in the summary. Default `220`. */
-    maxSummaryChars?: number;
-    /** Number of recent user turns to include in `queryMode === "recent"`. Default `2`. */
-    recentUserTurns?: number;
-}
+export type { ActiveMemoryQueryMode, ActiveMemoryResult, ActiveMemoryStatus };
 export interface RunActiveMemoryArgs {
     userText: string;
     priorMessages: ReadonlyArray<{
@@ -41,5 +24,26 @@ export interface RunActiveMemoryArgs {
     agentKey?: string;
     /** Run id for transcript file naming. */
     runId?: string;
+    /**
+     * T0.1 — optional telemetry handle. When provided AND telemetry is enabled,
+     * `memory.recall` span is emitted with `{ userId, namespace, scope, queryMode,
+     * hits, status }` attrs and `theokit_memory_recall_duration_ms` histogram is
+     * recorded with the same dimension keys. T4.9 will pin `userId/namespace/scope`
+     * to the cache-key invariant (cross-tenant leak fix).
+     */
+    telemetry?: TelemetryHandle;
+    /** User id surfaced as a memory.recall span attr for cross-tenant tracing. */
+    userId?: string;
+    /** Memory namespace (e.g. `default`, `<orgId>`) for span/histogram dimensions. */
+    namespace?: string;
+    /** Memory scope (`session` / `user` / `global`) for span/histogram dimensions. */
+    scope?: string;
+    /**
+     * T4.7 — AbortSignal propagation. When the caller's signal aborts,
+     * the active-memory recall exits early with `status: "skipped"` and
+     * summary `undefined`. Prevents long-running embedding calls from
+     * blocking agent.dispose() or user-initiated cancellation.
+     */
+    signal?: AbortSignal;
 }
 export declare function runActiveMemory(args: RunActiveMemoryArgs): Promise<ActiveMemoryResult>;

package/dist/internal/memory/adapters/azure-openai-embedding.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const azureOpenAiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/cohere-embedding.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const cohereMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/gemini-embedding.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const geminiMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/adapters/jina-embedding.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryEmbeddingProviderAdapter } from "../embedding-adapter.js";
+export declare const jinaMemoryEmbeddingProviderAdapter: MemoryEmbeddingProviderAdapter;

package/dist/internal/memory/index-manager-contract.d.ts

@@ -0,0 +1,26 @@
+import type { EmbeddingRuntime } from "./embedding-adapter.js";
+export interface IndexStatus {
+    backend: "fts-only" | "hybrid";
+    filesIndexed: number;
+    chunksIndexed: number;
+    lastSyncMs?: number;
+}
+export interface SearchOptions {
+    maxResults?: number;
+    minScore?: number;
+    sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
+    /** 0..1 — vector vs text weight in hybrid scoring (D4). Default 0.6. */
+    vectorWeight?: number;
+    /** 0..1 — text weight in hybrid scoring. Default 0.4. */
+    textWeight?: number;
+}
+/** Vector backend selector. SQLite default; Lance opt-in (ADR D43). */
+export type MemoryBackend = "sqlite-vec" | "lance";
+export interface OpenIndexOptions {
+    cwd: string;
+    filePath?: string;
+    /** When provided, vector index is enabled in hybrid mode. */
+    embedding?: EmbeddingRuntime;
+    /** Vector backend. Default and only value today: `"sqlite-vec"`. */
+    backend?: MemoryBackend;
+}

package/dist/internal/memory/index-manager-dispatch.d.ts

@@ -4,7 +4,7 @@
  *
  * @internal
  */
-import type { MemoryBackend, OpenIndexOptions } from "./index-manager.js";
+import type { MemoryBackend, OpenIndexOptions } from "./index-manager-contract.js";
 import type { MemoryIndex } from "./memory-index.js";
 /** Valid backend identifiers — runtime guard against TS-narrowing escapes (EC-1). */
 export declare const VALID_BACKENDS: readonly MemoryBackend[];

package/dist/internal/memory/index-manager.d.ts

@@ -1,30 +1,5 @@
-import type { EmbeddingRuntime } from "./embedding-adapter.js";
 import { type MemoryIndex } from "./memory-index.js";
-export interface IndexStatus {
-    backend: "fts-only" | "hybrid";
-    filesIndexed: number;
-    chunksIndexed: number;
-    lastSyncMs?: number;
-}
-export interface SearchOptions {
-    maxResults?: number;
-    minScore?: number;
-    sources?: ReadonlyArray<"memory" | "sessions" | "wiki">;
-    /** 0..1 — vector vs text weight in hybrid scoring (D4). Default 0.6. */
-    vectorWeight?: number;
-    /** 0..1 — text weight in hybrid scoring. Default 0.4. */
-    textWeight?: number;
-}
-/** Vector backend selector. SQLite default; Lance opt-in (ADR D43). */
-export type MemoryBackend = "sqlite-vec" | "lance";
-export interface OpenIndexOptions {
-    cwd: string;
-    filePath?: string;
-    /** When provided, vector index is enabled in hybrid mode. */
-    embedding?: EmbeddingRuntime;
-    /** Vector backend. Default and only value today: `"sqlite-vec"`. */
-    backend?: MemoryBackend;
-}
+import type { IndexStatus, MemorySearchHit, OpenIndexOptions, SearchOptions } from "./index-manager-contract.js";
 export declare class IndexManager implements MemoryIndex {
     private readonly cwd;
     private readonly db;
@@ -56,6 +31,13 @@ export declare class IndexManager implements MemoryIndex {
     search(query: string, options?: SearchOptions): Promise<MemorySearchHit[]>;
     status(): IndexStatus;
     private ftsSearch;
+    /**
+     * T4.8 — LIKE-based fallback for CJK and other scripts that FTS5's
+     * default tokenizer cannot segment. Slower than FTS5 (full table scan)
+     * but correct for any Unicode input. Returns the same shape as
+     * `ftsSearch` so callers are unaware of the fallback.
+     */
+    private likeSearchFallback;
     private vectorSearchById;
     private combineHybridScores;
     private mergeHits;

package/dist/internal/memory/{chunk-markdown.d.ts → storage/chunk-markdown.d.ts}

@@ -1,2 +1,2 @@
-import type { MemoryChunk } from "./types.js";
+import type { MemoryChunk } from "../types.js";
 export declare function chunkMarkdown(text: string, options?: ChunkMarkdownOptions): MemoryChunk[];

package/dist/internal/memory/{markdown-store.d.ts → storage/markdown-store.d.ts}

@@ -1,4 +1,4 @@
-import { type MemoryConfig, type MemoryFact } from "./types.js";
+import { type MemoryConfig, type MemoryFact } from "../types.js";
 export declare function memoryDir(cwd: string): string;
 export declare function memoryMdPath(cwd: string): string;
 export declare function notesDir(cwd: string): string;

package/dist/internal/memory/{reader.d.ts → storage/reader.d.ts}

@@ -1,4 +1,4 @@
-import type { MemoryReadResult } from "./types.js";
+import type { MemoryReadResult } from "../types.js";
 export interface ReadFileOptions {
     cwd: string;
     relPath: string;

package/dist/internal/observability/context.d.cts

@@ -0,0 +1,23 @@
+/**
+ * ObservabilityContext — public type for structured observability
+ * across agent runtime, memory, and tool dispatch (T10.2, ADR D449).
+ *
+ * Consumers use this type to thread tracing/logging context through
+ * custom tools and plugins.
+ *
+ * @public
+ */
+export interface ObservabilityContext {
+    /** Current trace ID (W3C Trace Context format). */
+    traceId: string;
+    /** Current span ID. */
+    spanId: string;
+    /** Parent span ID (undefined for root spans). */
+    parentSpanId?: string;
+    /** Structured log emitter. */
+    log: (level: "debug" | "info" | "warn" | "error", message: string, attrs?: Record<string, unknown>) => void;
+    /** Record a counter metric. */
+    counter: (name: string, value?: number, attrs?: Record<string, unknown>) => void;
+    /** Record a histogram metric. */
+    histogram: (name: string, value: number, attrs?: Record<string, unknown>) => void;
+}

package/dist/internal/observability/context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ObservabilityContext — public type for structured observability
+ * across agent runtime, memory, and tool dispatch (T10.2, ADR D449).
+ *
+ * Consumers use this type to thread tracing/logging context through
+ * custom tools and plugins.
+ *
+ * @public
+ */
+export interface ObservabilityContext {
+    /** Current trace ID (W3C Trace Context format). */
+    traceId: string;
+    /** Current span ID. */
+    spanId: string;
+    /** Parent span ID (undefined for root spans). */
+    parentSpanId?: string;
+    /** Structured log emitter. */
+    log: (level: "debug" | "info" | "warn" | "error", message: string, attrs?: Record<string, unknown>) => void;
+    /** Record a counter metric. */
+    counter: (name: string, value?: number, attrs?: Record<string, unknown>) => void;
+    /** Record a histogram metric. */
+    histogram: (name: string, value: number, attrs?: Record<string, unknown>) => void;
+}

package/dist/internal/observability/index.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+var module$1 = require('module');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// src/internal/observability/tracer-loader.ts
+var noopSpan = {
+  setAttribute: () => noopSpan,
+  end: () => void 0
+};
+var tracerCache = /* @__PURE__ */ new Map();
+function getTracer(name, version = "1.0.0") {
+  const cached = tracerCache.get(name);
+  if (cached !== void 0) return cached.tracer ?? void 0;
+  try {
+    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+    const otel = r("@opentelemetry/api");
+    if (otel.trace?.getTracer === void 0) {
+      tracerCache.set(name, { tracer: null });
+      return void 0;
+    }
+    const tracer = otel.trace.getTracer(name, version);
+    tracerCache.set(name, { tracer });
+    return tracer;
+  } catch {
+    tracerCache.set(name, { tracer: null });
+    return void 0;
+  }
+}
+function resetTracerCacheForTests() {
+  tracerCache.clear();
+}
+
+exports.getTracer = getTracer;
+exports.noopSpan = noopSpan;
+exports.resetTracerCacheForTests = resetTracerCacheForTests;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/internal/observability/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/internal/observability/tracer-loader.ts"],"names":["createRequire"],"mappings":";;;;;;AAgBO,IAAM,QAAA,GAAqB;AAAA,EAChC,cAAc,MAAM,QAAA;AAAA,EACpB,KAAK,MAAM;AACb;AAaA,IAAM,WAAA,uBAAkB,GAAA,EAAwB;AAEzC,SAAS,SAAA,CAAU,IAAA,EAAc,OAAA,GAAU,OAAA,EAAiC;AACjF,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,GAAA,CAAI,IAAI,CAAA;AACnC,EAAA,IAAI,MAAA,KAAW,MAAA,EAAW,OAAO,MAAA,CAAO,MAAA,IAAU,MAAA;AAClD,EAAA,IAAI;AACF,IAAA,MAAM,CAAA,GAAIA,sBAAA,CAAc,2PAAe,CAAA;AACvC,IAAA,MAAM,IAAA,GAAO,EAAE,oBAAoB,CAAA;AAGnC,IAAA,IAAI,IAAA,CAAK,KAAA,EAAO,SAAA,KAAc,KAAA,CAAA,EAAW;AACvC,MAAA,WAAA,CAAY,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,MAAM,CAAA;AACtC,MAAA,OAAO,KAAA,CAAA;AAAA,IACT;AACA,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,KAAA,CAAM,SAAA,CAAU,MAAM,OAAO,CAAA;AACjD,IAAA,WAAA,CAAY,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,CAAA;AAChC,IAAA,OAAO,MAAA;AAAA,EACT,CAAA,CAAA,MAAQ;AACN,IAAA,WAAA,CAAY,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,MAAM,CAAA;AACtC,IAAA,OAAO,MAAA;AAAA,EACT;AACF;AAEO,SAAS,wBAAA,GAAiC;AAC/C,EAAA,WAAA,CAAY,KAAA,EAAM;AACpB","file":"index.cjs","sourcesContent":["/**\n * Shared OTel tracer loader (extracted to eliminate cross-module clones —\n * was previously inlined in cache/, workflow/, eval/, handoff/ telemetry\n * modules). Lazy-loads `@opentelemetry/api` via `createRequire`; users\n * without OTel installed pay zero cost.\n *\n * @internal\n */\n\nimport { createRequire } from \"node:module\";\n\nexport interface SpanLike {\n  setAttribute(key: string, value: string | number | boolean): SpanLike;\n  end(): void;\n}\n\nexport const noopSpan: SpanLike = {\n  setAttribute: () => noopSpan,\n  end: () => undefined,\n};\n\nexport interface TracerLike {\n  startSpan(\n    name: string,\n    options?: { attributes?: Record<string, string | number | boolean> },\n  ): SpanLike;\n}\n\ninterface CacheEntry {\n  tracer: TracerLike | null;\n}\n\nconst tracerCache = new Map<string, CacheEntry>();\n\nexport function getTracer(name: string, version = \"1.0.0\"): TracerLike | undefined {\n  const cached = tracerCache.get(name);\n  if (cached !== undefined) return cached.tracer ?? undefined;\n  try {\n    const r = createRequire(import.meta.url);\n    const otel = r(\"@opentelemetry/api\") as {\n      trace?: { getTracer: (n: string, v?: string) => TracerLike };\n    };\n    if (otel.trace?.getTracer === undefined) {\n      tracerCache.set(name, { tracer: null });\n      return undefined;\n    }\n    const tracer = otel.trace.getTracer(name, version);\n    tracerCache.set(name, { tracer });\n    return tracer;\n  } catch {\n    tracerCache.set(name, { tracer: null });\n    return undefined;\n  }\n}\n\nexport function resetTracerCacheForTests(): void {\n  tracerCache.clear();\n}\n"]}

package/dist/internal/observability/index.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Barrel for observability primitives shared across subsystems
+ * (cache, memory, etc.) — exposed via `@theokit/sdk/internal/observability`
+ * sub-path (SDK 2.0 Phase 3 prep).
+ *
+ * @internal — semver-exempt; surface may change in patch releases.
+ */
+export * from "./tracer-loader.js";

package/dist/internal/observability/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Barrel for observability primitives shared across subsystems
+ * (cache, memory, etc.) — exposed via `@theokit/sdk/internal/observability`
+ * sub-path (SDK 2.0 Phase 3 prep).
+ *
+ * @internal — semver-exempt; surface may change in patch releases.
+ */
+export * from "./tracer-loader.js";

package/dist/internal/observability/index.js

@@ -0,0 +1,33 @@
+import { createRequire } from 'module';
+
+// src/internal/observability/tracer-loader.ts
+var noopSpan = {
+  setAttribute: () => noopSpan,
+  end: () => void 0
+};
+var tracerCache = /* @__PURE__ */ new Map();
+function getTracer(name, version = "1.0.0") {
+  const cached = tracerCache.get(name);
+  if (cached !== void 0) return cached.tracer ?? void 0;
+  try {
+    const r = createRequire(import.meta.url);
+    const otel = r("@opentelemetry/api");
+    if (otel.trace?.getTracer === void 0) {
+      tracerCache.set(name, { tracer: null });
+      return void 0;
+    }
+    const tracer = otel.trace.getTracer(name, version);
+    tracerCache.set(name, { tracer });
+    return tracer;
+  } catch {
+    tracerCache.set(name, { tracer: null });
+    return void 0;
+  }
+}
+function resetTracerCacheForTests() {
+  tracerCache.clear();
+}
+
+export { getTracer, noopSpan, resetTracerCacheForTests };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/internal/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/internal/observability/tracer-loader.ts"],"names":[],"mappings":";;;AAgBO,IAAM,QAAA,GAAqB;AAAA,EAChC,cAAc,MAAM,QAAA;AAAA,EACpB,KAAK,MAAM;AACb;AAaA,IAAM,WAAA,uBAAkB,GAAA,EAAwB;AAEzC,SAAS,SAAA,CAAU,IAAA,EAAc,OAAA,GAAU,OAAA,EAAiC;AACjF,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,GAAA,CAAI,IAAI,CAAA;AACnC,EAAA,IAAI,MAAA,KAAW,MAAA,EAAW,OAAO,MAAA,CAAO,MAAA,IAAU,MAAA;AAClD,EAAA,IAAI;AACF,IAAA,MAAM,CAAA,GAAI,aAAA,CAAc,MAAA,CAAA,IAAA,CAAY,GAAG,CAAA;AACvC,IAAA,MAAM,IAAA,GAAO,EAAE,oBAAoB,CAAA;AAGnC,IAAA,IAAI,IAAA,CAAK,KAAA,EAAO,SAAA,KAAc,KAAA,CAAA,EAAW;AACvC,MAAA,WAAA,CAAY,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,MAAM,CAAA;AACtC,MAAA,OAAO,KAAA,CAAA;AAAA,IACT;AACA,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,KAAA,CAAM,SAAA,CAAU,MAAM,OAAO,CAAA;AACjD,IAAA,WAAA,CAAY,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,CAAA;AAChC,IAAA,OAAO,MAAA;AAAA,EACT,CAAA,CAAA,MAAQ;AACN,IAAA,WAAA,CAAY,GAAA,CAAI,IAAA,EAAM,EAAE,MAAA,EAAQ,MAAM,CAAA;AACtC,IAAA,OAAO,MAAA;AAAA,EACT;AACF;AAEO,SAAS,wBAAA,GAAiC;AAC/C,EAAA,WAAA,CAAY,KAAA,EAAM;AACpB","file":"index.js","sourcesContent":["/**\n * Shared OTel tracer loader (extracted to eliminate cross-module clones —\n * was previously inlined in cache/, workflow/, eval/, handoff/ telemetry\n * modules). Lazy-loads `@opentelemetry/api` via `createRequire`; users\n * without OTel installed pay zero cost.\n *\n * @internal\n */\n\nimport { createRequire } from \"node:module\";\n\nexport interface SpanLike {\n  setAttribute(key: string, value: string | number | boolean): SpanLike;\n  end(): void;\n}\n\nexport const noopSpan: SpanLike = {\n  setAttribute: () => noopSpan,\n  end: () => undefined,\n};\n\nexport interface TracerLike {\n  startSpan(\n    name: string,\n    options?: { attributes?: Record<string, string | number | boolean> },\n  ): SpanLike;\n}\n\ninterface CacheEntry {\n  tracer: TracerLike | null;\n}\n\nconst tracerCache = new Map<string, CacheEntry>();\n\nexport function getTracer(name: string, version = \"1.0.0\"): TracerLike | undefined {\n  const cached = tracerCache.get(name);\n  if (cached !== undefined) return cached.tracer ?? undefined;\n  try {\n    const r = createRequire(import.meta.url);\n    const otel = r(\"@opentelemetry/api\") as {\n      trace?: { getTracer: (n: string, v?: string) => TracerLike };\n    };\n    if (otel.trace?.getTracer === undefined) {\n      tracerCache.set(name, { tracer: null });\n      return undefined;\n    }\n    const tracer = otel.trace.getTracer(name, version);\n    tracerCache.set(name, { tracer });\n    return tracer;\n  } catch {\n    tracerCache.set(name, { tracer: null });\n    return undefined;\n  }\n}\n\nexport function resetTracerCacheForTests(): void {\n  tracerCache.clear();\n}\n"]}

package/dist/internal/observability/tracer-loader.d.cts

@@ -0,0 +1,20 @@
+/**
+ * Shared OTel tracer loader (extracted to eliminate cross-module clones —
+ * was previously inlined in cache/, workflow/, eval/, handoff/ telemetry
+ * modules). Lazy-loads `@opentelemetry/api` via `createRequire`; users
+ * without OTel installed pay zero cost.
+ *
+ * @internal
+ */
+export interface SpanLike {
+    setAttribute(key: string, value: string | number | boolean): SpanLike;
+    end(): void;
+}
+export declare const noopSpan: SpanLike;
+export interface TracerLike {
+    startSpan(name: string, options?: {
+        attributes?: Record<string, string | number | boolean>;
+    }): SpanLike;
+}
+export declare function getTracer(name: string, version?: string): TracerLike | undefined;
+export declare function resetTracerCacheForTests(): void;

package/dist/internal/persistence/conversation-storage-fs.d.cts

@@ -0,0 +1,37 @@
+/**
+ * Filesystem-backed implementation of {@link ConversationStorageAdapter}
+ * (Production-Readiness #1, ADR D304).
+ *
+ * Default adapter when `AgentOptions.conversationStorage` is not provided.
+ * Writes append-only JSONL to `<root>/.theokit/agents/<safeId>/messages.jsonl`,
+ * preserving the pre-D303 byte-identical behavior (redaction D68 + JSONL
+ * line granularity).
+ *
+ * Path safety: every conversationId flows through `sanitizeIdentifier` +
+ * `safePathJoin` before touching disk. `deleteConversation` re-applies the
+ * guard (EC-1) — without this the new `rm -rf` would escape via traversal.
+ *
+ * Listing: `listConversationIds` catches ENOENT (EC-2) so first-run deploys
+ * without any `.theokit/agents/` directory return `[]` instead of crashing.
+ *
+ * @public
+ */
+import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+export interface FileSystemConversationStorageOptions {
+    /** Root directory under which `.theokit/agents/<id>/` lives. Defaults to `process.cwd()`. */
+    root?: string;
+}
+export declare class FileSystemConversationStorage implements ConversationStorageAdapter {
+    #private;
+    constructor(opts?: FileSystemConversationStorageOptions);
+    /** Exposed for tests + diagnostics. The path is sanitized at use sites. */
+    get root(): string;
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds(opts?: {
+        limit?: number;
+    }): Promise<readonly string[]>;
+    compact(conversationId: string, maxTurns: number): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/internal/persistence/conversation-storage-memory.d.cts

@@ -0,0 +1,24 @@
+/**
+ * In-memory implementation of {@link ConversationStorageAdapter} (Production-Readiness #1, ADR D304).
+ *
+ * Intended for tests + ephemeral single-process dev/CLI usage. Holds messages
+ * in a `Map<conversationId, StoredMessage[]>`. JavaScript's single-threaded
+ * runtime makes per-conversation appends naturally atomic; no external mutex
+ * needed.
+ *
+ * The adapter returns defensive copies from `getMessages` so callers cannot
+ * mutate internal state by holding a reference to the returned array.
+ *
+ * @public
+ */
+import type { ConversationStorageAdapter, StoredMessage } from "../../types/conversation-storage.js";
+export declare class InMemoryConversationStorage implements ConversationStorageAdapter {
+    #private;
+    getMessages(conversationId: string): Promise<readonly StoredMessage[]>;
+    appendMessage(conversationId: string, message: StoredMessage): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    listConversationIds(opts?: {
+        limit?: number;
+    }): Promise<readonly string[]>;
+    dispose(): Promise<void>;
+}