theokit 0.12.0 → 0.12.1

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

@@ -0,0 +1,58 @@
+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

@@ -0,0 +1,72 @@
+/**
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * 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

@@ -0,0 +1,74 @@
+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

@@ -0,0 +1,229 @@
+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 };