theokit 0.12.0 → 0.13.0

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

@@ -0,0 +1,177 @@
+import { d as StorageAdapter } from '../../storage-types-DsDTCPbp.js';
+
+/**
+ * Cost tracking types (R0.5.11).
+ *
+ * @see docs/adr/0002-job-backend-interface-neutral-contract.md (mirror pattern)
+ *
+ * Phase 5 — Production-Readiness #4: adds `ToolUsageRecord` for per-tool
+ * latency / error tracking via SDK's onToolStart/onToolEnd/onToolError hooks.
+ * Same UsageStorageAdapter handles both via discriminated union.
+ *
+ * EC-9 (SHOULD TEST): backward compat — record() input without `kind` is
+ * normalized to 'llm' by the framework so external adapters from older
+ * versions keep working.
+ */
+/**
+ * Per-LLM-call cost record (existing — gains optional `kind` discriminator).
+ */
+interface UsageRecord {
+    /** Discriminator. Optional for backward-compat; defaults to 'llm'. */
+    kind?: 'llm';
+    /** User identifier (e.g., session userId, tenantId, apiKey hash). */
+    userId: string;
+    /** Model id (e.g., 'claude-sonnet-4-5-20250929'). */
+    model: string;
+    /** Token counts per direction. */
+    tokens: {
+        input: number;
+        output: number;
+    };
+    /** USD cost in fractional dollars. */
+    costUsd: number;
+    /** When the run happened. */
+    timestamp: Date;
+}
+/**
+ * Per-tool-invocation record (Phase 5 — Production-Readiness #4).
+ *
+ * Emitted by `trackAgentTools` on every `onToolEnd` / `onToolError`. The same
+ * `UsageStorageAdapter.record` accepts both record kinds via union.
+ */
+interface ToolUsageRecord {
+    kind: 'tool';
+    userId: string;
+    conversationId: string;
+    toolName: string;
+    /**
+     * Unique per invocation; correlates onToolStart with onToolEnd / onToolError.
+     * EC-16 (DOCUMENT): callId uniqueness is SDK contract — if SDK ever reuses
+     * a callId, `trackAgentTools`'s Map uses last-write-wins (defensive).
+     */
+    callId: string;
+    /** True when the tool handler returned; false when it threw. */
+    success: boolean;
+    /** Milliseconds from onToolStart to onToolEnd / onToolError. */
+    durationMs: number;
+    /** Populated only when success === false. */
+    errorMessage?: string;
+    timestamp: Date;
+}
+interface UsageQuery {
+    userId: string;
+    period: {
+        from: Date;
+        to: Date;
+    };
+}
+interface UsageResult {
+    totalTokens: number;
+    totalCostUsd: number;
+    runs: number;
+}
+interface UsageStorageAdapter {
+    readonly name: string;
+    /**
+     * Record a usage event. Accepts both kinds; framework normalizes input
+     * without `kind` to 'llm' before calling adapter (EC-9 backward compat).
+     */
+    record(input: UsageRecord | ToolUsageRecord): Promise<void>;
+    getUsage(query: UsageQuery): Promise<UsageResult>;
+}
+
+interface TrackAgentRunInput {
+    userId: string;
+    model: string;
+    tokens: {
+        input: number;
+        output: number;
+    };
+    costUsd: number;
+    /** Defaults to `new Date()`. */
+    timestamp?: Date;
+    /** Optional execution status surfaced to devtools (default 'finished'). */
+    status?: 'finished' | 'error' | 'aborted';
+}
+interface TrackAgentRunOptions {
+    /** Adapter resolved from `theo.config.ts > cost.storage`. */
+    storage: UsageStorageAdapter | undefined;
+}
+/**
+ * Record a single agent run's usage + cost. Companion to the client-side
+ * `<CostMeter>` from `@theokit/ui`.
+ *
+ * EC-14: this function NEVER bubbles errors back to the caller. Adapter
+ * failures (network outage, DB down, etc.) are logged via `console.warn`
+ * and swallowed. The agent response MUST NOT fail because cost tracking
+ * is degraded.
+ *
+ * No-op when `storage` is undefined (cost tracking unconfigured).
+ *
+ * In dev mode (Vite OR tsup-built with NODE_ENV != 'production'), fires a
+ * `theokit-evolution-ci-and-dx` Phase 3 dispatcher event so the devtools
+ * Agents tab can render the run. Prod tree-shakes the entire dispatcher
+ * import via the `__IS_DEV` IIFE guard.
+ *
+ * @see docs/concepts/cost-tracking.md (when implemented in T6.3)
+ */
+declare function trackAgentRun(input: TrackAgentRunInput, opts: TrackAgentRunOptions): Promise<void>;
+
+/**
+ * In-memory usage storage for dev/tests. Unbounded — production
+ * deployments MUST plug in a durable adapter (Postgres/Redis recipes
+ * land with R0.6.7; documented in EC-114).
+ *
+ * Phase 5 — Production-Readiness #4: accepts both `UsageRecord` (LLM call,
+ * kind='llm' or omitted) AND `ToolUsageRecord` (tool call, kind='tool').
+ * `getUsage` only sums LLM records (tools have no token/cost dimension).
+ *
+ * EC-9 (backward compat): input without `kind` is normalized to `kind:'llm'`
+ * — adapters from older versions stay working.
+ *
+ * Concurrency: Node's single-threaded event loop guarantees that
+ * `Array.push` is atomic, so concurrent record() calls cannot lose data.
+ */
+declare class InMemoryUsageStorage implements UsageStorageAdapter, StorageAdapter {
+    #private;
+    readonly name = "memory";
+    /**
+     * T2.3 — `StorageAdapter` lifecycle hook (ADR-0007 D6). In-memory storage
+     * has no real cleanup to perform — this is intentionally a noop so the
+     * adapter can be registered with `StorageManager.register()` and
+     * participate in graceful shutdown without changing behavior.
+     *
+     * Does NOT clear stored records (dispose ≠ reset). For test reset use
+     * a fresh instance.
+     */
+    dispose(): Promise<void>;
+    record(input: UsageRecord | ToolUsageRecord): Promise<void>;
+    getUsage(query: UsageQuery): Promise<UsageResult>;
+}
+
+interface TrackAgentToolsOptions {
+    storage: UsageStorageAdapter;
+    /** Defaults to () => new Date() — overridable for deterministic testing. */
+    now?: () => Date;
+    /** Identifier for the user — passed through to ToolUsageRecord.userId. */
+    userId?: string;
+    /** Identifier for the conversation — passed through to ToolUsageRecord.conversationId. */
+    conversationId?: string;
+}
+interface ToolHookEvent {
+    callId: string;
+    name: string;
+    [key: string]: unknown;
+}
+interface TrackAgentToolsHooks {
+    onToolStart: (event: ToolHookEvent) => void;
+    onToolEnd: (event: ToolHookEvent) => void;
+    onToolError: (event: ToolHookEvent) => void;
+}
+/**
+ * Create the three tool-lifecycle callbacks. Hand the returned object's
+ * methods to `Agent.create({ tools, onToolStart, onToolEnd, onToolError })`.
+ */
+declare function trackAgentTools(opts: TrackAgentToolsOptions): TrackAgentToolsHooks;
+
+export { InMemoryUsageStorage, type ToolHookEvent, type ToolUsageRecord, type TrackAgentRunInput, type TrackAgentRunOptions, type TrackAgentToolsHooks, type TrackAgentToolsOptions, type UsageQuery, type UsageRecord, type UsageResult, type UsageStorageAdapter, trackAgentRun, trackAgentTools };

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

@@ -0,0 +1,208 @@
+/**
+ * Cron primitive types (R0.5.4).
+ *
+ * @see docs/adr/0004-cron-schedule-5-field-utc-strict.md
+ */
+type CronConcurrencyPolicy = 'forbid' | 'allow';
+interface CronContext {
+    /** W3C trace_id propagated from the scheduler invocation. */
+    readonly traceId: string;
+    /** UTC instant the cron was scheduled to fire. */
+    readonly scheduledAt: Date;
+    /** Abort signal triggered when the scheduler stops or shuts down. */
+    readonly signal: AbortSignal;
+}
+interface CronOptions {
+    /** 5-field UTC cron expression (ADR-0004). */
+    schedule: string;
+    /** Handler invoked on each fire. May return Promise. */
+    handler: (ctx: CronContext) => unknown;
+    /**
+     * Concurrency policy when previous handler is still running:
+     * - 'forbid' (default) — skip the next fire + log a warning
+     * - 'allow'            — run concurrently
+     */
+    concurrency?: CronConcurrencyPolicy;
+}
+interface CronDefinition {
+    readonly name: string;
+    readonly schedule: string;
+    readonly handler: (ctx: CronContext) => unknown;
+    readonly concurrency: CronConcurrencyPolicy;
+}
+
+/**
+ * Declare a time-triggered handler. Pure identity helper — no
+ * registration side effect; the build-time scanner (T1.3) discovers
+ * definitions by walking `server/crons/` and emits a manifest the
+ * adapters translate at deploy.
+ *
+ * @example
+ * ```ts
+ * // server/crons/morning-summary.ts
+ * export default defineCron('morning-summary', {
+ *   schedule: '0 9 * * *',  // 09:00 UTC
+ *   async handler({ traceId, scheduledAt, signal }) {
+ *     // ...
+ *   },
+ * })
+ * ```
+ */
+declare function defineCron(name: string, options: CronOptions): CronDefinition;
+
+/**
+ * Validate a cron schedule string per ADR-0004 — 5-field UTC strict.
+ *
+ * Accepts:
+ *   - Standard 5-field expressions: `minute hour dayOfMonth month dayOfWeek`
+ *   - Step (`*\/15`), range (`1-5`), list (`MON,TUE,FRI`), wildcards
+ *
+ * Rejects:
+ *   - 6-field with seconds (`* * * * * *`)
+ *   - 7-field with year
+ *   - Shorthand (`@daily`, `@hourly`, `@yearly`, `@reboot`)
+ *   - Timezone suffix
+ *   - Empty / whitespace-only
+ *   - Malformed grammar
+ *
+ * Throws on every invalid input. Every error message includes the
+ * original input and the fix.
+ *
+ * @see docs/adr/0004-cron-schedule-5-field-utc-strict.md
+ */
+declare function validateCronSchedule(schedule: string): void;
+
+/**
+ * One discovered cron from build-time scan. The handler is intentionally
+ * NOT included — manifest is platform-neutral and consumed by adapters
+ * that emit static config. Runtime dispatch loads the handler at fire time.
+ */
+interface CronNode {
+    readonly name: string;
+    readonly filePath: string;
+    readonly schedule: string;
+    readonly concurrency: CronConcurrencyPolicy;
+}
+declare class DuplicateCronNameError extends Error {
+    readonly cronName: string;
+    readonly filePaths: readonly string[];
+    readonly code = "DUPLICATE_CRON_NAME";
+    constructor(cronName: string, filePaths: readonly string[]);
+}
+/**
+ * Scan a directory for cron definition files and return the discovered
+ * `CronNode[]` sorted by name. Throws `DuplicateCronNameError` on name
+ * collision and `Error` on missing default export.
+ *
+ * Sequential by design — module imports are awaited one-by-one to keep
+ * error messages anchored to the file that failed.
+ */
+declare function scanCrons(cronsDir: string): Promise<CronNode[]>;
+
+declare const CRON_MANIFEST_SCHEMA_VERSION: 1;
+interface CronManifestEntry {
+    readonly name: string;
+    readonly filePath: string;
+    readonly schedule: string;
+    readonly concurrency: 'forbid' | 'allow';
+}
+interface CronManifest {
+    readonly schemaVersion: typeof CRON_MANIFEST_SCHEMA_VERSION;
+    readonly generatedAt: string;
+    readonly crons: readonly CronManifestEntry[];
+}
+/**
+ * Build a `CronManifest` from scanned `CronNode[]`. Filepaths are kept
+ * relative to the caller's project root for portability.
+ */
+declare function buildCronManifest(nodes: readonly CronNode[], projectRoot?: string): CronManifest;
+/**
+ * Write the cron manifest to `path` atomically (EC-106).
+ *
+ * Accepts either a pre-built `CronManifest` OR an array of `CronNode[]`
+ * (which gets converted via `buildCronManifest`). The atomic-write
+ * helper guarantees `path` always contains valid JSON, even under
+ * concurrent writes (e.g., dev-server rescan + build).
+ */
+declare function writeCronManifest(path: string, input: readonly CronNode[] | CronManifest, projectRoot?: string): void;
+
+/**
+ * Thrown when an existing platform-config file (vercel.json, wrangler.toml,
+ * serverless.yml) cannot be parsed. Caller must fix the file before
+ * re-running `theokit build`. We NEVER silently overwrite a user's config.
+ */
+declare class ExistingConfigUnparseableError extends Error {
+    readonly filePath: string;
+    readonly parseError: string;
+    readonly code = "EXISTING_CONFIG_UNPARSEABLE";
+    constructor(filePath: string, parseError: string);
+}
+/**
+ * Translate a TheoKit cron manifest into `vercel.json crons[]`.
+ *
+ * EC-105: existing fields (functions, headers, redirects, rewrites, env,
+ * etc.) are preserved verbatim — ONLY the `crons[]` slice is replaced.
+ */
+declare function translateCronToVercel(vercelJsonPath: string, crons: readonly CronManifestEntry[]): void;
+/**
+ * Translate a TheoKit cron manifest into `wrangler.toml [triggers] crons`.
+ *
+ * EC-105: regex-based mutation that preserves comments + other sections
+ * verbatim. Replaces only the `[triggers]` block (or appends if absent).
+ */
+declare function translateCronToCloudflare(wranglerTomlPath: string, crons: readonly CronManifestEntry[]): void;
+/**
+ * Convert TheoKit's 5-field UTC cron to AWS EventBridge's 6-field format.
+ * EventBridge requires `?` in EITHER day-of-month OR day-of-week (not both `*`).
+ *
+ * Algorithm:
+ *   - If DOM is "*" and DOW is "*" → insert ? in DOW (default)
+ *   - If DOM is "*" and DOW is specific → insert ? in DOM
+ *   - If DOM is specific and DOW is "*" → insert ? in DOW
+ *   - Append "*" year field at end.
+ */
+declare function convertToAwsCron(schedule: string): string;
+/**
+ * Translate a TheoKit cron manifest into a `serverless.yml` functions
+ * map with `events: - schedule: cron(...)` entries.
+ *
+ * EC-105: appends to `functions:` block, preserving all existing
+ * functions/sections. Cron functions are named `cron_<name>` to avoid
+ * collision with user-declared functions.
+ */
+declare function translateCronToAws(serverlessYmlPath: string, crons: readonly CronManifestEntry[]): void;
+/**
+ * Emit a Deno entry file that registers each cron via `Deno.cron`.
+ *
+ * Unlike Vercel/CF/AWS, Deno.cron is an in-process runtime API — the
+ * entry file is a managed artifact (overwritten each build), not a user
+ * config (so EC-105 doesn't apply here).
+ */
+declare function translateCronToDeno(entryPath: string, crons: readonly CronManifestEntry[]): void;
+
+/**
+ * In-memory cron scheduler for `theokit dev` (T1.4).
+ *
+ * Algorithm:
+ *   - For each cron, compute `nextFireAt = cron-parser.next()`.
+ *   - Schedule a `setTimeout(handler, nextFireAt - now)`.
+ *   - After handler invocation (sync return or Promise scheduled), recompute
+ *     next fire from CURRENT time (drift-free vs scheduled time).
+ *
+ * Per-cron isolation (EC-109):
+ *   - Each cron's handler invocation is fire-and-forget (`void` scheduled).
+ *     A hanging handler does NOT block the scheduler loop nor other crons.
+ *   - `concurrency: 'forbid'` (default) tracks an in-flight flag per-cron;
+ *     subsequent ticks skip + warn while the in-flight flag is set.
+ *   - `concurrency: 'allow'` runs handlers concurrently — caller's responsibility.
+ *
+ * Production deploys use platform-native triggers (T1.5 adapter translators);
+ * this scheduler exists only for local dev iteration.
+ */
+interface CronScheduler {
+    start(): void;
+    stop(): void;
+}
+declare function createCronScheduler(definitions: readonly CronDefinition[]): CronScheduler;
+
+export { CRON_MANIFEST_SCHEMA_VERSION, type CronConcurrencyPolicy, type CronContext, type CronDefinition, type CronManifest, type CronManifestEntry, type CronNode, type CronOptions, type CronScheduler, DuplicateCronNameError, ExistingConfigUnparseableError, buildCronManifest, convertToAwsCron, createCronScheduler, defineCron, scanCrons, translateCronToAws, translateCronToCloudflare, translateCronToDeno, translateCronToVercel, validateCronSchedule, writeCronManifest };