theokit 0.11.7 → 0.12.0

package/dist/rate-limit-BdNDZ3vt.d.ts

@@ -1,58 +0,0 @@
-import { IncomingMessage } from 'node:http';
-import { R as RateLimitStore } from './rate-limit-store-BEJnhWdw.js';
-
-/**
- * Rate limit configuration — basic single-bucket shape. Per ADR D2, the
- * per-route + per-user variant is layered on top via T2.2; this base
- * struct is the smallest unit.
- */
-interface RateLimitConfig {
-    windowMs: number;
-    max: number;
-}
-interface RateLimitResult {
-    limited: boolean;
-    headers: Record<string, string>;
-}
-/**
- * Create a rate limiter that consumes a pluggable `RateLimitStore`.
- *
- * Backwards-compatible signature: callers passing only `config` get the
- * default `InMemoryStore`. Distributed deployments pass a Redis adapter
- * (or any other `RateLimitStore` implementation) via `opts.store`.
- *
- * T2.1: synchronous return for back-compat with the current
- * `api-middleware.ts` integration point. The async store contract is
- * exercised lazily — we use a sync fast-path against the in-memory store
- * (single-thread JS makes this safe). External stores remain async and
- * would require a different async wrapper at the middleware layer.
- */
-declare function createRateLimiter(config: RateLimitConfig, opts?: {
-    store?: RateLimitStore;
-}): (req: IncomingMessage) => RateLimitResult;
-/**
- * T5a.2 Phase D slice 2/3 — Web-Standards single-bucket rate limiter.
- *
- * Mirror of `createRateLimiter(config, opts)` returning a checker that
- * accepts `(clientIp: string)` instead of `(req: IncomingMessage)`. Web
- * `Request` has no `req.socket.remoteAddress` — the IP is resolved by
- * the caller per-runtime (Node adapter from socket; CF Workers from
- * `cf-connecting-ip`; etc., same convention as Phase D slice 1/3's
- * `DeriveKeyRequestContext.clientIp`).
- *
- * Same `RateLimitConfig`, same `InMemoryStore` default, same async
- * store rejection (use a dedicated async middleware for external stores).
- * Same `RateLimitResult` return shape.
- *
- * **Signature difference from `createRateLimiter`:** this Web factory's
- * checker takes a raw IP string instead of a Request object. The IP is
- * the ONLY input the bucket needs; passing a Request object would force
- * the caller to populate `request.headers.get('x-forwarded-for')` or
- * similar without giving us any safer extraction. KISS — accept the IP
- * directly, document the per-runtime resolution at the adapter boundary.
- */
-declare function createRateLimiterWeb(config: RateLimitConfig, opts?: {
-    store?: RateLimitStore;
-}): (clientIp: string) => RateLimitResult;
-
-export { type RateLimitConfig as R, type RateLimitResult as a, createRateLimiterWeb as b, createRateLimiter as c };

package/dist/rate-limit-store-BEJnhWdw.d.ts

@@ -1,72 +0,0 @@
-/**
- * T2.1 — RateLimitStore interface.
- *
- * Pluggable backend for the rate limiter. The default `InMemoryStore`
- * preserves current single-instance behavior. Multi-instance deployments
- * (TheoCloud canary, K8s replicas) opt in to a distributed adapter
- * (Redis, Cloudflare KV) without bloating single-instance apps.
- *
- * Contract per ADR D1:
- *   - `incr` is atomic — concurrent calls for the same key both observe
- *     the same `resetAt` and increment count by 1.
- *   - `get` returns `null` for expired entries (not just absent — checks
- *     `now > resetAt`).
- *   - `reset` removes the key entirely; next `incr` creates fresh.
- *
- * Async signature is honest about Redis adapters even though in-memory
- * implementation is synchronous. Callers MUST await.
- */
-interface RateLimitState {
-    /** Number of requests counted in the current window. */
-    count: number;
-    /** Absolute timestamp (ms since epoch) when this window expires. */
-    resetAt: number;
-}
-interface RateLimitStore {
-    /**
-     * Atomic increment-and-get. If the key is missing OR the previous
-     * window expired (`now >= resetAt`), create with `count=1, resetAt=now+windowMs`.
-     * Otherwise increment count by 1, preserving the original resetAt.
-     */
-    incr(key: string, windowMs: number): Promise<RateLimitState>;
-    /** Read current state. Returns `null` for missing or expired entries. */
-    get(key: string): Promise<RateLimitState | null>;
-    /** Remove a key. Used by login throttling on success (T6.1). */
-    reset(key: string): Promise<void>;
-}
-/**
- * Default in-memory store. Backed by `Map<string, RateLimitState>`.
- *
- * GC: every 1000 `incr` calls, expired entries are removed. Pathological
- * key explosion is bounded by `MAX_ENTRIES` (LRU-evict oldest insertion).
- *
- * Single-thread by virtue of Node's event loop — `incr` is atomic at the
- * JavaScript level (no preemption between Map.get and Map.set).
- */
-declare class InMemoryStore implements RateLimitStore {
-    private store;
-    /** Bound the map to prevent unbounded growth from pathological inputs. */
-    static readonly MAX_ENTRIES = 100000;
-    /** GC sweep interval, milliseconds. */
-    static readonly GC_INTERVAL_MS = 30000;
-    private gcTimer;
-    constructor();
-    /**
-     * Synchronous fast-path used by the legacy sync `createRateLimiter`
-     * surface (`api-middleware.ts` is sync). The async `incr` delegates to
-     * this for in-memory; external adapters override `incr` directly.
-     */
-    incrSync(key: string, windowMs: number): RateLimitState;
-    /** Sweep expired entries. Called by the GC timer; safe to call manually. */
-    sweepExpired(): void;
-    /**
-     * Stop the GC timer. Call from tests or when discarding the store. After
-     * `dispose`, the store still works but no longer auto-sweeps.
-     */
-    dispose(): void;
-    incr(key: string, windowMs: number): Promise<RateLimitState>;
-    get(key: string): Promise<RateLimitState | null>;
-    reset(key: string): Promise<void>;
-}
-
-export { InMemoryStore as I, type RateLimitStore as R, type RateLimitState as a };

package/dist/react-query/index.d.ts

@@ -1,33 +0,0 @@
-/**
- * T5.3 — React Query adapter primitives.
- *
- * Exposes:
- *  - `stableQueryKey(path, options)` — produces a deterministic queryKey
- *    that is equal across calls when the logical content of query/body is
- *    equal, regardless of property order or inline-object identity. Solves
- *    EC-10 (inline-object → infinite refetch).
- *  - `buildUseTheoQueryConfig(path, options, fetcher)` — produces the
- *    `{ queryKey, queryFn }` pair that consumers pass to `useQuery` from
- *    `@tanstack/react-query`.
- *
- * The canonical implementation lives here in `theokit/client`. The
- * dedicated subpath `theokit/react-query` re-exports this surface so
- * consumers who only need the React Query bridge can import from a
- * clearly named entry point — same shape as `theokit/server`,
- * `theokit/vite-plugin`, etc. No separate npm package.
- */
-interface FetchOptionsLike {
-    query?: unknown;
-    body?: unknown;
-    params?: unknown;
-}
-type QueryKey = readonly unknown[];
-declare function stableQueryKey(path: string, options: FetchOptionsLike): QueryKey;
-type Fetcher<TResult = unknown> = (path: string, options: FetchOptionsLike) => Promise<TResult>;
-interface UseTheoQueryConfig<TResult = unknown> {
-    queryKey: QueryKey;
-    queryFn: () => Promise<TResult>;
-}
-declare function buildUseTheoQueryConfig<TResult = unknown>(path: string, options: FetchOptionsLike, fetcher: Fetcher<TResult>): UseTheoQueryConfig<TResult>;
-
-export { type FetchOptionsLike, type Fetcher, type Fetcher as FetcherFn, type QueryKey, type UseTheoQueryConfig, type UseTheoQueryConfig as UseTheoQueryInternals, buildUseTheoQueryConfig, buildUseTheoQueryConfig as buildUseTheoQueryInternals, stableQueryKey };

package/dist/schema-BpH6ivDY.d.ts

@@ -1,74 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Wave 2 — Polyglot Services Orchestration (T1.1).
- *
- * Declarative `services: {}` primitive for `theo.config.ts`. Each entry
- * declares an external sidecar process (Python FastAPI / Node Hono) that
- * boots alongside the TheoKit TS app. Empty `services: {}` is the default
- * and preserves Wave 1 behavior (no impact on TS-only apps).
- *
- * See ADRs 0012-0015 + plan: docs/plans/wave-2-polyglot-services-plan.md
- */
-
-/**
- * Single service definition. All commands run from `services/<name>/` cwd.
- *
- * EC-4 fix: `proxy` regex requires NON-EMPTY path after `/` (the `+` quantifier)
- * to reject `/` which would catch-all and conflict with TheoKit's own routing.
- */
-declare const ServiceDefinitionSchema: z.ZodObject<{
-    runtime: z.ZodEnum<{
-        python: "python";
-        node: "node";
-    }>;
-    type: z.ZodOptional<z.ZodEnum<{
-        server: "server";
-        worker: "worker";
-    }>>;
-    port: z.ZodNumber;
-    proxy: z.ZodString;
-    dev: z.ZodString;
-    build: z.ZodOptional<z.ZodString>;
-    start: z.ZodString;
-    openapi: z.ZodOptional<z.ZodURL>;
-    healthcheck: z.ZodDefault<z.ZodString>;
-    cors: z.ZodDefault<z.ZodBoolean>;
-    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    passSetCookie: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
-type ServiceDefinition = z.infer<typeof ServiceDefinitionSchema>;
-type ServicesConfig = Record<string, ServiceDefinition>;
-/**
- * Full services config schema with cross-service refines.
- *
- * EC-1 fix: detect duplicate ports across services.
- * EC-13: empty `dependsOn: []` accepted as no-deps.
- * Self-dep, missing-ref, and cycles rejected via topological check.
- */
-declare const servicesConfigSchema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-    runtime: z.ZodEnum<{
-        python: "python";
-        node: "node";
-    }>;
-    type: z.ZodOptional<z.ZodEnum<{
-        server: "server";
-        worker: "worker";
-    }>>;
-    port: z.ZodNumber;
-    proxy: z.ZodString;
-    dev: z.ZodString;
-    build: z.ZodOptional<z.ZodString>;
-    start: z.ZodString;
-    openapi: z.ZodOptional<z.ZodURL>;
-    healthcheck: z.ZodDefault<z.ZodString>;
-    cors: z.ZodDefault<z.ZodBoolean>;
-    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-    dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    passSetCookie: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>>>;
-type ServicesConfigInput = z.input<typeof servicesConfigSchema>;
-type ServicesConfigOutput = z.output<typeof servicesConfigSchema>;
-
-export type { ServicesConfig as S, ServiceDefinition as a, ServicesConfigInput as b, ServicesConfigOutput as c };

package/dist/server/agent/index.d.ts

@@ -1,229 +0,0 @@
-import { a as AgentErrorEvent, A as AgentEvent } from '../../agent-events-DosDXkSV.js';
-export { b as AgentMessageEvent, f as AgentRunErrorCode, c as AgentThinkingEvent, d as AgentToolCallEvent, e as AgentToolResultEvent } from '../../agent-events-DosDXkSV.js';
-
-/**
- * Item #4 — `streamAgentRun`
- *
- * Adapter that consumes the `@theokit/sdk` `Run.stream()` async generator
- * (SDKMessage variants) and yields TheoKit `AgentEvent`s suitable for SSE
- * via `defineAgentEndpoint`. One line at the consumer side:
- *
- *   ```ts
- *   const run = await agent.send(message)
- *   yield* streamAgentRun(run)
- *   ```
- *
- * Mapping table (SDK → AgentEvent):
- *
- * | SDK message                          | AgentEvent yielded                     |
- * |---|---|
- * | assistant.content[].type==='text'    | { type: 'message', content }           |
- * | assistant.content[].type==='tool_use'| (none — covered by tool_call below)    |
- * | tool_call(status='running')          | { type: 'tool_call', name, args, id }  |
- * | tool_call(status='completed')        | { type: 'tool_result', name, data, id }|
- * | tool_call(status='error')            | { type: 'error', message, id }         |
- * | run.wait() status==='error'          | { type: 'error', message }             |
- * | run.wait() status==='cancelled'      | (none — cancel ≠ error)                |
- * | system / user / thinking / status /  | (none — internal SDK telemetry)        |
- * |   task / request / object_delta      |                                        |
- *
- * Abort semantics: when the consumer calls `generator.return()` on the
- * outer `defineAgentEndpoint` generator, `streamAgentRun` exits the
- * `for await` loop and does NOT call `run.wait()`. Cleanup of in-flight
- * SDK resources is the SDK consumer's responsibility (`run.cancel()`).
- */
-/**
- * Local mirror of the SDK's `Run` interface — only the surfaces we consume.
- * The message contract is minimal (just `{ type: string }`) so the SDK's
- * `SDKMessage` discriminated union IS structurally assignable without any
- * cast at the consumer site (covariant — TS accepts the SDK's typed message
- * as the wider `{ type: string }`). Property access inside `streamAgentRun`
- * narrows via runtime type guards.
- *
- * `import type` from `@theokit/sdk` would couple TheoKit to the SDK at type-
- * resolution time even for consumers who never use the agent surface.
- */
-interface AgentRunLike {
-    stream: () => AsyncIterable<{
-        type: string;
-    }>;
-    wait: () => Promise<AgentRunResult>;
-}
-/**
- * Re-exported as a convenience for test fixtures. Production code typically
- * passes an SDK `Run` directly (structural match via `{ type: string }`).
- */
-type AgentRunStreamMessage = {
-    type: 'assistant';
-    message: {
-        role: 'assistant';
-        content: {
-            type: string;
-            text?: string;
-        }[];
-    };
-} | {
-    type: 'tool_call';
-    name: string;
-    status: 'running' | 'completed' | 'error';
-    args?: unknown;
-    result?: unknown;
-    call_id: string;
-} | {
-    type: string;
-    [k: string]: unknown;
-};
-/** Subset of the SDK `RunResult` we consume. */
-interface AgentRunResult {
-    status: 'finished' | 'error' | 'cancelled';
-    error?: {
-        message: string;
-        code?: string;
-        cause?: unknown;
-    };
-}
-/**
- * Map an SDK error to the AgentErrorEvent shape. Pure function — easy to test.
- *
- * Backward compat (D4): non-AgentRunError throws yield only `message` field
- * (legacy shape); discriminated fields stay `undefined`.
- *
- * Return type is the specific `AgentErrorEvent` (not the union) for ergonomic
- * call-site access — `errorToEvent(err).code` works without narrowing.
- */
-declare function errorToEvent(err: unknown, id?: string): AgentErrorEvent;
-declare function streamAgentRun(run: AgentRunLike): AsyncGenerator<AgentEvent, void, unknown>;
-
-/**
- * Item #5 — `createConversationHistory`
- *
- * Orchestrator that resolves a stable `agentId` from (explicit → session →
- * cookie → fresh UUID), then returns an `@theokit/sdk` `Agent` via
- * `Agent.getOrCreate(agentId, options)`. Conversation turns auto-persist in
- * `<cwd>/.theokit/agents/<agentId>/messages.jsonl` — SDK owns the storage
- * (ADR D1). `MemorySettings` (facts recall layer) is opt-in passthrough via
- * `options.memory` (ADR D2).
- *
- * Security: agentId from cookie/explicit is attacker-controlled. The SDK
- * uses it as a filesystem path component AND we serialize it into Set-Cookie.
- * EC-1 enforces a strict regex `^[a-zA-Z0-9_-]{1,128}$` at every entry point;
- * invalid values fall through (treated as "missing") rather than throw.
- */
-/**
- * Minimum surface of an SDK Agent that consumers care about post-creation.
- * Structural match — any object with `send` + `dispose` of compatible
- * shape works. `send` returns a `SdkRunLike` (a Run-shaped object) that
- * `streamAgentRun` can consume. Permissive `unknown` for now; consumers
- * who want stricter types can cast to the SDK's own types.
- *
- * **T5.2 (architecture-cleanup) — DP-7 decision: KEEP (Opt B).** The 5 duck-typed
- * mirrors below were flagged as "over-engineered" by the 2026-05-27 architecture
- * review. Decision: KEEP them because `@theokit/sdk` is `devDependency` (not
- * required at runtime for consumers that don't use agent features). Removing
- * the mirrors would force a hard runtime dep on the SDK, breaking consumers
- * who build TheoKit apps without the agent layer.
- *
- * @kept Defensive duck-type. Do NOT replace with direct SDK type imports unless
- *   `@theokit/sdk` is promoted from devDependency to dependency. If promoting,
- *   ALSO drop the mirrors (Opt A from the architecture-cleanup plan T5.2).
- */
-interface SdkRunLike {
-    stream: () => AsyncIterable<{
-        type: string;
-    }>;
-    wait: () => Promise<{
-        status: 'finished' | 'error' | 'cancelled';
-        error?: {
-            message: string;
-        };
-    }>;
-}
-interface SdkAgent {
-    send: (message: string, options?: unknown) => Promise<SdkRunLike>;
-    dispose: () => Promise<void>;
-}
-/**
- * Phase 2 — structural duck-type of `@theokit/sdk`'s `ConversationStorageAdapter`.
- *
- * D2 (decoupling): we mirror the SDK's shape locally rather than hard-import
- * the SDK type. This lets consumers pass any object matching the structural
- * contract (own implementation, SDK's `FileSystemConversationStorage`,
- * `InMemoryConversationStorage`, or a Postgres/Redis recipe).
- *
- * EC-5 (SHOULD TEST — sync drift detection): the SDK type MUST be assignable
- * to this interface AND vice-versa. A contract test asserts both directions.
- *
- * `unknown` for the message payload avoids coupling to the SDK's `SDKMessage`
- * shape. Real consumers cast at the call site if they need stricter types.
- */
-interface ConversationStorageLike {
-    getMessages(conversationId: string): Promise<readonly unknown[]>;
-    appendMessage(conversationId: string, message: unknown): Promise<void>;
-    deleteConversation(conversationId: string): Promise<void>;
-    listConversationIds?(opts?: {
-        limit?: number;
-    }): Promise<readonly string[] | undefined>;
-    dispose?(): Promise<void>;
-}
-/**
- * Minimum surface of `AgentOptions` accepted by `Agent.getOrCreate`. Forward-
- * compatible: callers pass whatever the SDK supports (memory, tools, etc.).
- *
- * Phase 2 adds typed `conversationStorage` slot. The index signature still
- * passes everything else opaquely.
- */
-interface SdkAgentOptions {
-    apiKey?: string;
-    model?: {
-        id: string;
-    };
-    tools?: readonly unknown[];
-    memory?: Record<string, unknown>;
-    /**
-     * Phase 2 (Production-Readiness #1) — pluggable conversation persistence.
-     * Default (when omitted): SDK falls back to `FileSystemConversationStorage`.
-     * Required for serverless / multi-host deploys.
-     */
-    conversationStorage?: ConversationStorageLike;
-    [key: string]: unknown;
-}
-interface ConversationHistoryArgs {
-    /** Request — for reading the conversation cookie. */
-    request: Request | {
-        headers?: {
-            cookie?: string;
-        } | Headers;
-    };
-    /**
-     * Response-like surface that accepts a `Set-Cookie` header. The primitive
-     * appends a Set-Cookie line when issuing a new conversation id. If absent,
-     * the primitive still reads the existing cookie but cannot issue a new
-     * one — useful for read-only contexts.
-     */
-    response?: {
-        headers: Headers;
-    };
-    /** Explicit override — wins over session/cookie/uuid (ADR D3 step 1). */
-    agentId?: string;
-    /** Auth session containing a `conversationId` field — ADR D3 step 2. */
-    session?: {
-        conversationId?: string;
-    } | null;
-    /** SDK AgentOptions forwarded to Agent.getOrCreate. apiKey + model required. */
-    options: SdkAgentOptions;
-    /** Cookie name override. Default: 'theo_conversation'. */
-    cookieName?: string;
-    /** Cookie max-age in seconds. Default + min: 30 days. Non-positive coerced to default (EC-4). */
-    cookieMaxAge?: number;
-}
-interface ConversationHistoryResult {
-    /** The SDK Agent, ready to receive `agent.send(message)`. */
-    agent: SdkAgent;
-    /** The resolved conversation id (useful for logging / debugging). */
-    conversationId: string;
-    /** True when the id was newly generated (no prior cookie / session). */
-    isNew: boolean;
-}
-declare function createConversationHistory(args: ConversationHistoryArgs): Promise<ConversationHistoryResult>;
-
-export { AgentErrorEvent, AgentEvent, type AgentRunLike, type AgentRunResult, type AgentRunStreamMessage, type ConversationHistoryArgs, type ConversationHistoryResult, type ConversationStorageLike, type SdkAgent, type SdkAgentOptions, type SdkRunLike, createConversationHistory, errorToEvent, streamAgentRun };