theokit 0.11.6 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/LICENSE +201 -0
  2. package/dist/actions-virtual-module-SQDY3V5X.js +0 -0
  3. package/dist/add-W6FNTAFS.js +0 -0
  4. package/dist/app-typed-client-QG7BVZYW.js +0 -0
  5. package/dist/aws-lambda-7GSCNLPY.js +0 -0
  6. package/dist/broadcast-LUMOJIJT.js +0 -0
  7. package/dist/build-QFRLSEZ4.js +0 -0
  8. package/dist/build-request-body-preview-QMWD2IXK.js +0 -0
  9. package/dist/bun-KP2KES6S.js +0 -0
  10. package/dist/check-PD2FTKMM.js +0 -0
  11. package/dist/chunk-3LVRAGAZ.js +0 -0
  12. package/dist/chunk-43D6XNDR.js +0 -0
  13. package/dist/chunk-45C3WUQ7.js +0 -0
  14. package/dist/chunk-5ODOE6EF.js +0 -0
  15. package/dist/chunk-6FYD34NX.js +0 -0
  16. package/dist/chunk-7YZHAQU7.js +0 -0
  17. package/dist/{chunk-GEEMNDPH.js → chunk-AD74EAK3.js} +30 -1
  18. package/dist/chunk-AD74EAK3.js.map +1 -0
  19. package/dist/chunk-FOZIR3TG.js +0 -0
  20. package/dist/chunk-GFMQJHXX.js +0 -0
  21. package/dist/chunk-HGZL5EOI.js +0 -0
  22. package/dist/chunk-HNBWZKIQ.js +0 -0
  23. package/dist/chunk-IEES3CHD.js +0 -0
  24. package/dist/chunk-JAIKGP3Q.js +0 -0
  25. package/dist/chunk-JQSFBJR5.js +0 -0
  26. package/dist/chunk-NAZ4E2GT.js +0 -0
  27. package/dist/chunk-PBEH6NXR.js +0 -0
  28. package/dist/chunk-YJAUJXZS.js +0 -0
  29. package/dist/cloudflare-C6E5SPAE.js +0 -0
  30. package/dist/configure-agent-registry-ZOBVU3MV.js +0 -0
  31. package/dist/db-3UNAMSFK.js +0 -0
  32. package/dist/deno-deploy-RFZN56X4.js +0 -0
  33. package/dist/dev-GBXOTXUP.js +0 -0
  34. package/dist/dev-emit-FEFEDLZF.js +0 -0
  35. package/dist/dispatcher-EJHL6JMJ.js +0 -0
  36. package/dist/docker-LZZB4D5E.js +0 -0
  37. package/dist/generate-OMKHQ7OM.js +0 -0
  38. package/dist/info-OUEUZOT7.js +0 -0
  39. package/dist/netlify-PMLHVPN4.js +0 -0
  40. package/dist/node-BPJ3Z4DT.js +0 -0
  41. package/dist/openapi-VR6AFBLJ.js +0 -0
  42. package/dist/registry-Q2TZQLUH.js +0 -0
  43. package/dist/router-TLEAOFID.js +0 -0
  44. package/dist/routes-LRYOIIAI.js +0 -0
  45. package/dist/scan-7MJC6PYU.js +0 -0
  46. package/dist/schema-7CAY6IZR.js +0 -0
  47. package/dist/server/define/index.js +5 -3
  48. package/dist/server/index.js +4 -2
  49. package/dist/server/index.js.map +1 -1
  50. package/dist/server-error-to-envelope-UUXDSLAZ.js +0 -0
  51. package/dist/server-routes-hmr-VZXOP5YT.js +0 -0
  52. package/dist/services-json-Y3XODNB5.js +0 -0
  53. package/dist/services-typed-client-32KMTTXR.js +0 -0
  54. package/dist/start-3ZHAXSJE.js +0 -0
  55. package/dist/static-55G3LX2I.js +0 -0
  56. package/dist/storage-manager-ZSQFLEYT.js +0 -0
  57. package/dist/theo-cloud-DQRP6S6M.js +0 -0
  58. package/dist/upgrade-readiness-ACGW44JC.js +0 -0
  59. package/dist/vercel-J6G7ZHYQ.js +0 -0
  60. package/dist/vite-plugin-WO72VLYR.js +0 -0
  61. package/package.json +13 -9
  62. package/dist/adapters/web-shim.d.ts +0 -67
  63. package/dist/adapters/ws-shim.d.ts +0 -55
  64. package/dist/agent-events-DosDXkSV.d.ts +0 -94
  65. package/dist/audit-log-BQWM5YLG.d.ts +0 -60
  66. package/dist/boot/index.d.ts +0 -39
  67. package/dist/chunk-GEEMNDPH.js.map +0 -1
  68. package/dist/client/index.d.ts +0 -362
  69. package/dist/csrf-BBrEZSBW.d.ts +0 -107
  70. package/dist/csrf-readiness-store-CjIoub3U.d.ts +0 -43
  71. package/dist/define-websocket-CdK94O-D.d.ts +0 -64
  72. package/dist/devtools/entry.d.ts +0 -5
  73. package/dist/error-envelope-BsNzzAV5.d.ts +0 -62
  74. package/dist/health-route-C0hk64_U.d.ts +0 -57
  75. package/dist/index-B40qUSrQ.d.ts +0 -575
  76. package/dist/index.d.ts +0 -361
  77. package/dist/job-backend-CgC8Xf33.d.ts +0 -68
  78. package/dist/match-CfbEFRG4.d.ts +0 -26
  79. package/dist/plugin-runner-BGBkzgi0.d.ts +0 -95
  80. package/dist/plugin-types-DNJGxr4Z.d.ts +0 -79
  81. package/dist/rate-limit-BdNDZ3vt.d.ts +0 -58
  82. package/dist/rate-limit-store-BEJnhWdw.d.ts +0 -72
  83. package/dist/react-query/index.d.ts +0 -33
  84. package/dist/schema-BpH6ivDY.d.ts +0 -74
  85. package/dist/server/agent/index.d.ts +0 -229
  86. package/dist/server/auth/index.d.ts +0 -419
  87. package/dist/server/cost/index.d.ts +0 -177
  88. package/dist/server/cron/index.d.ts +0 -208
  89. package/dist/server/define/index.d.ts +0 -310
  90. package/dist/server/http/index.d.ts +0 -11
  91. package/dist/server/index.d.ts +0 -847
  92. package/dist/server/jobs/index.d.ts +0 -348
  93. package/dist/server/observability/index.d.ts +0 -324
  94. package/dist/server/plugins/index.d.ts +0 -17
  95. package/dist/server/rate-limit/index.d.ts +0 -105
  96. package/dist/server/realtime/index.d.ts +0 -15
  97. package/dist/server/scan/index.d.ts +0 -106
  98. package/dist/server/security/index.d.ts +0 -193
  99. package/dist/server/storage/index.d.ts +0 -22
  100. package/dist/server/webhook/index.d.ts +0 -148
  101. package/dist/storage-manager-C4jsO0Tp.d.ts +0 -89
  102. package/dist/storage-types-DsDTCPbp.d.ts +0 -96
  103. package/dist/vite-plugin/index.d.ts +0 -115
@@ -1,208 +0,0 @@
1
- /**
2
- * Cron primitive types (R0.5.4).
3
- *
4
- * @see docs/adr/0004-cron-schedule-5-field-utc-strict.md
5
- */
6
- type CronConcurrencyPolicy = 'forbid' | 'allow';
7
- interface CronContext {
8
- /** W3C trace_id propagated from the scheduler invocation. */
9
- readonly traceId: string;
10
- /** UTC instant the cron was scheduled to fire. */
11
- readonly scheduledAt: Date;
12
- /** Abort signal triggered when the scheduler stops or shuts down. */
13
- readonly signal: AbortSignal;
14
- }
15
- interface CronOptions {
16
- /** 5-field UTC cron expression (ADR-0004). */
17
- schedule: string;
18
- /** Handler invoked on each fire. May return Promise. */
19
- handler: (ctx: CronContext) => unknown;
20
- /**
21
- * Concurrency policy when previous handler is still running:
22
- * - 'forbid' (default) — skip the next fire + log a warning
23
- * - 'allow' — run concurrently
24
- */
25
- concurrency?: CronConcurrencyPolicy;
26
- }
27
- interface CronDefinition {
28
- readonly name: string;
29
- readonly schedule: string;
30
- readonly handler: (ctx: CronContext) => unknown;
31
- readonly concurrency: CronConcurrencyPolicy;
32
- }
33
-
34
- /**
35
- * Declare a time-triggered handler. Pure identity helper — no
36
- * registration side effect; the build-time scanner (T1.3) discovers
37
- * definitions by walking `server/crons/` and emits a manifest the
38
- * adapters translate at deploy.
39
- *
40
- * @example
41
- * ```ts
42
- * // server/crons/morning-summary.ts
43
- * export default defineCron('morning-summary', {
44
- * schedule: '0 9 * * *', // 09:00 UTC
45
- * async handler({ traceId, scheduledAt, signal }) {
46
- * // ...
47
- * },
48
- * })
49
- * ```
50
- */
51
- declare function defineCron(name: string, options: CronOptions): CronDefinition;
52
-
53
- /**
54
- * Validate a cron schedule string per ADR-0004 — 5-field UTC strict.
55
- *
56
- * Accepts:
57
- * - Standard 5-field expressions: `minute hour dayOfMonth month dayOfWeek`
58
- * - Step (`*\/15`), range (`1-5`), list (`MON,TUE,FRI`), wildcards
59
- *
60
- * Rejects:
61
- * - 6-field with seconds (`* * * * * *`)
62
- * - 7-field with year
63
- * - Shorthand (`@daily`, `@hourly`, `@yearly`, `@reboot`)
64
- * - Timezone suffix
65
- * - Empty / whitespace-only
66
- * - Malformed grammar
67
- *
68
- * Throws on every invalid input. Every error message includes the
69
- * original input and the fix.
70
- *
71
- * @see docs/adr/0004-cron-schedule-5-field-utc-strict.md
72
- */
73
- declare function validateCronSchedule(schedule: string): void;
74
-
75
- /**
76
- * One discovered cron from build-time scan. The handler is intentionally
77
- * NOT included — manifest is platform-neutral and consumed by adapters
78
- * that emit static config. Runtime dispatch loads the handler at fire time.
79
- */
80
- interface CronNode {
81
- readonly name: string;
82
- readonly filePath: string;
83
- readonly schedule: string;
84
- readonly concurrency: CronConcurrencyPolicy;
85
- }
86
- declare class DuplicateCronNameError extends Error {
87
- readonly cronName: string;
88
- readonly filePaths: readonly string[];
89
- readonly code = "DUPLICATE_CRON_NAME";
90
- constructor(cronName: string, filePaths: readonly string[]);
91
- }
92
- /**
93
- * Scan a directory for cron definition files and return the discovered
94
- * `CronNode[]` sorted by name. Throws `DuplicateCronNameError` on name
95
- * collision and `Error` on missing default export.
96
- *
97
- * Sequential by design — module imports are awaited one-by-one to keep
98
- * error messages anchored to the file that failed.
99
- */
100
- declare function scanCrons(cronsDir: string): Promise<CronNode[]>;
101
-
102
- declare const CRON_MANIFEST_SCHEMA_VERSION: 1;
103
- interface CronManifestEntry {
104
- readonly name: string;
105
- readonly filePath: string;
106
- readonly schedule: string;
107
- readonly concurrency: 'forbid' | 'allow';
108
- }
109
- interface CronManifest {
110
- readonly schemaVersion: typeof CRON_MANIFEST_SCHEMA_VERSION;
111
- readonly generatedAt: string;
112
- readonly crons: readonly CronManifestEntry[];
113
- }
114
- /**
115
- * Build a `CronManifest` from scanned `CronNode[]`. Filepaths are kept
116
- * relative to the caller's project root for portability.
117
- */
118
- declare function buildCronManifest(nodes: readonly CronNode[], projectRoot?: string): CronManifest;
119
- /**
120
- * Write the cron manifest to `path` atomically (EC-106).
121
- *
122
- * Accepts either a pre-built `CronManifest` OR an array of `CronNode[]`
123
- * (which gets converted via `buildCronManifest`). The atomic-write
124
- * helper guarantees `path` always contains valid JSON, even under
125
- * concurrent writes (e.g., dev-server rescan + build).
126
- */
127
- declare function writeCronManifest(path: string, input: readonly CronNode[] | CronManifest, projectRoot?: string): void;
128
-
129
- /**
130
- * Thrown when an existing platform-config file (vercel.json, wrangler.toml,
131
- * serverless.yml) cannot be parsed. Caller must fix the file before
132
- * re-running `theokit build`. We NEVER silently overwrite a user's config.
133
- */
134
- declare class ExistingConfigUnparseableError extends Error {
135
- readonly filePath: string;
136
- readonly parseError: string;
137
- readonly code = "EXISTING_CONFIG_UNPARSEABLE";
138
- constructor(filePath: string, parseError: string);
139
- }
140
- /**
141
- * Translate a TheoKit cron manifest into `vercel.json crons[]`.
142
- *
143
- * EC-105: existing fields (functions, headers, redirects, rewrites, env,
144
- * etc.) are preserved verbatim — ONLY the `crons[]` slice is replaced.
145
- */
146
- declare function translateCronToVercel(vercelJsonPath: string, crons: readonly CronManifestEntry[]): void;
147
- /**
148
- * Translate a TheoKit cron manifest into `wrangler.toml [triggers] crons`.
149
- *
150
- * EC-105: regex-based mutation that preserves comments + other sections
151
- * verbatim. Replaces only the `[triggers]` block (or appends if absent).
152
- */
153
- declare function translateCronToCloudflare(wranglerTomlPath: string, crons: readonly CronManifestEntry[]): void;
154
- /**
155
- * Convert TheoKit's 5-field UTC cron to AWS EventBridge's 6-field format.
156
- * EventBridge requires `?` in EITHER day-of-month OR day-of-week (not both `*`).
157
- *
158
- * Algorithm:
159
- * - If DOM is "*" and DOW is "*" → insert ? in DOW (default)
160
- * - If DOM is "*" and DOW is specific → insert ? in DOM
161
- * - If DOM is specific and DOW is "*" → insert ? in DOW
162
- * - Append "*" year field at end.
163
- */
164
- declare function convertToAwsCron(schedule: string): string;
165
- /**
166
- * Translate a TheoKit cron manifest into a `serverless.yml` functions
167
- * map with `events: - schedule: cron(...)` entries.
168
- *
169
- * EC-105: appends to `functions:` block, preserving all existing
170
- * functions/sections. Cron functions are named `cron_<name>` to avoid
171
- * collision with user-declared functions.
172
- */
173
- declare function translateCronToAws(serverlessYmlPath: string, crons: readonly CronManifestEntry[]): void;
174
- /**
175
- * Emit a Deno entry file that registers each cron via `Deno.cron`.
176
- *
177
- * Unlike Vercel/CF/AWS, Deno.cron is an in-process runtime API — the
178
- * entry file is a managed artifact (overwritten each build), not a user
179
- * config (so EC-105 doesn't apply here).
180
- */
181
- declare function translateCronToDeno(entryPath: string, crons: readonly CronManifestEntry[]): void;
182
-
183
- /**
184
- * In-memory cron scheduler for `theokit dev` (T1.4).
185
- *
186
- * Algorithm:
187
- * - For each cron, compute `nextFireAt = cron-parser.next()`.
188
- * - Schedule a `setTimeout(handler, nextFireAt - now)`.
189
- * - After handler invocation (sync return or Promise scheduled), recompute
190
- * next fire from CURRENT time (drift-free vs scheduled time).
191
- *
192
- * Per-cron isolation (EC-109):
193
- * - Each cron's handler invocation is fire-and-forget (`void` scheduled).
194
- * A hanging handler does NOT block the scheduler loop nor other crons.
195
- * - `concurrency: 'forbid'` (default) tracks an in-flight flag per-cron;
196
- * subsequent ticks skip + warn while the in-flight flag is set.
197
- * - `concurrency: 'allow'` runs handlers concurrently — caller's responsibility.
198
- *
199
- * Production deploys use platform-native triggers (T1.5 adapter translators);
200
- * this scheduler exists only for local dev iteration.
201
- */
202
- interface CronScheduler {
203
- start(): void;
204
- stop(): void;
205
- }
206
- declare function createCronScheduler(definitions: readonly CronDefinition[]): CronScheduler;
207
-
208
- 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 };
@@ -1,310 +0,0 @@
1
- import { z } from 'zod';
2
- import { A as AgentEvent } from '../../agent-events-DosDXkSV.js';
3
- import { b as WebSocketLike } from '../../define-websocket-CdK94O-D.js';
4
- export { W as WebSocketHandler, a as WebSocketHandlerWeb, d as defineWebSocket, c as defineWebSocketWeb } from '../../define-websocket-CdK94O-D.js';
5
- import { IncomingMessage } from 'node:http';
6
- import { T as TheoPlugin } from '../../plugin-types-DNJGxr4Z.js';
7
- export { H as HEALTH_PATH, a as HealthRouteConfig, b as READY_PATH, c as ReadyRouteConfig, d as ReservedResponse, R as ReservedRoutes, e as defineHealthRoute, f as defineReadyRoute, s as serveReservedRoute } from '../../health-route-C0hk64_U.js';
8
-
9
- /**
10
- * core/contracts/route-config.ts
11
- *
12
- * Canonical home for `RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>` —
13
- * the contract shape consumed by `defineRoute()` (server) and
14
- * `defineCachedRoute()` (cache).
15
- *
16
- * Moved here in T2.2 of architecture-cleanup so `cache → core/contracts`
17
- * is the legal edge (replacing the prior `cache → server` violation).
18
- *
19
- * GAP-4 (plan v1.1): the 5-arity generic shape `<TQuery, TBody, TParams, TCtx, TResponse>`
20
- * MUST be preserved byte-by-byte. Type tests assert this in
21
- * `tests/unit/route-config-generic-arity.test.ts`.
22
- */
23
-
24
- interface RouteConfig<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown> {
25
- query?: TQuery;
26
- body?: TBody;
27
- params?: TParams;
28
- status?: number;
29
- /**
30
- * Optional Zod schema for the handler's plain-object return value. When
31
- * present, BOTH runtimes (Node `executeRoute` + Web `executeWebRequest`)
32
- * validate the handler's plain-object return against it BEFORE serializing.
33
- *
34
- * A mismatch is a SERVER fault (the handler violated its own declared
35
- * contract) → 500 `INTERNAL_SERVER_ERROR`, distinct from the 400 used for
36
- * input (`query`/`body`/`params`) validation failures.
37
- *
38
- * `Response`-instance returns (and `undefined`/`null` → 204) are NOT
39
- * validated. This is a plain optional field — runtime validation only; the
40
- * handler return type is NOT statically inferred from `response` (YAGNI).
41
- */
42
- response?: z.ZodType;
43
- /**
44
- * Opt out of CSRF enforcement for this route. Use for endpoints that
45
- * legitimately receive third-party POSTs (Stripe webhooks, GitHub
46
- * webhooks, OAuth callbacks). Defaults to enforced per `config.security.csrf`.
47
- *
48
- * Setting `csrf: false` only disables the per-route check — it does NOT
49
- * disable the global mode setting for other routes.
50
- */
51
- csrf?: false;
52
- handler: (ctx: {
53
- query: z.infer<TQuery>;
54
- body: z.infer<TBody>;
55
- params: z.infer<TParams>;
56
- request: Request;
57
- ctx: TCtx;
58
- }) => TResponse | Promise<TResponse>;
59
- }
60
-
61
- /**
62
- * Define a typed HTTP route.
63
- * Identity function — provides type inference for route handlers.
64
- */
65
- declare function defineRoute<TQuery extends z.ZodType = z.ZodUndefined, TBody extends z.ZodType = z.ZodUndefined, TParams extends z.ZodType = z.ZodUndefined, TCtx = unknown, TResponse = unknown>(config: RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>): RouteConfig<TQuery, TBody, TParams, TCtx, TResponse>;
66
-
67
- /**
68
- * Action wire-protocol accept mode per plan g3-server-actions-and-useaction
69
- * v1.2 ADR D1. Default behavior (when omitted) is `'json'`. `'form'` opts the
70
- * action into FormData multipart parsing for progressive-enhancement forms;
71
- * the runtime in `server/http/action-execute.ts` will coerce FormData entries
72
- * against the `input` schema via `formDataToObject` (Astro pattern).
73
- */
74
- type ActionAccept = 'form' | 'json';
75
- interface ActionConfig<TInput extends z.ZodType, TCtx = unknown> {
76
- /**
77
- * Zod input schema. Required: every action declares its input contract via
78
- * Zod (architecture rule: zod-is-SSOT). The shape becomes the handler's
79
- * typed `input` parameter via `z.infer<TInput>`.
80
- */
81
- input: TInput;
82
- /**
83
- * Wire-protocol accept mode. Defaults to `'json'` when omitted. Setting
84
- * `'form'` switches the runtime to FormData multipart parsing — the input
85
- * schema MUST be `z.object(...)` so field-by-field coercion can drive
86
- * boolean string / number / array coercion (Astro pattern).
87
- */
88
- accept?: ActionAccept;
89
- /**
90
- * Opt OUT of CSRF enforcement for this action. Default (omitted) keeps the
91
- * multi-header CSRF gate active. Set `false` for endpoints intentionally
92
- * callable without the `X-Theo-Action` header (e.g. public webhooks). The
93
- * runtime in `server/http/action-execute.ts` reads this flag.
94
- */
95
- csrf?: false;
96
- handler: (ctx: {
97
- input: z.infer<TInput>;
98
- ctx: TCtx;
99
- }) => unknown;
100
- }
101
- /**
102
- * Define a typed server action.
103
- *
104
- * Identity function — provides type inference for action handlers. The
105
- * runtime that consumes the config (validation + invocation + serialization)
106
- * lives in `server/http/action-execute.ts`.
107
- *
108
- * Per plan g3-server-actions-and-useaction v1.2 § Phase 1 / T1.2: the new
109
- * `accept?: 'form' | 'json'` field is the only contract change vs the
110
- * pre-G3 identity. Existing callsites (`defineAction({input, handler})`)
111
- * continue to compile — `accept` is opt-in.
112
- */
113
- declare function defineAction<TInput extends z.ZodType, TCtx = unknown>(config: ActionConfig<TInput, TCtx>): ActionConfig<TInput, TCtx>;
114
-
115
- type MiddlewareHandler = (request: Request, next: (request: Request) => Promise<Response>) => Response | Promise<Response>;
116
- /**
117
- * Define a middleware handler.
118
- * Identity function — provides type annotation for middleware.
119
- */
120
- declare function defineMiddleware(handler: MiddlewareHandler): MiddlewareHandler;
121
-
122
- /**
123
- * T5.1 — defineAgentEndpoint
124
- *
125
- * Sugar over defineRoute (ADR D4). Accepts an async generator that yields
126
- * AgentEvents and produces a RouteConfig whose handler returns a Response
127
- * streaming Server-Sent Events (SSE).
128
- *
129
- * Wire format: `data: <JSON>\n\n` per event. Standards-compliant.
130
- *
131
- * The generator may throw — the wrapper catches and emits a final
132
- * `{ type: 'error', message }` event before closing the stream.
133
- *
134
- * The wrapper observes `request.signal` (EC-7) — when aborted, the
135
- * underlying generator is told to `return()` and the stream closes
136
- * promptly.
137
- *
138
- * Note (EC-12, Out of Scope): SSE backpressure (slow consumer) is not
139
- * handled here. For high-frequency token streaming consider a different
140
- * transport (WS) or a buffer policy. This MVP enqueues each event
141
- * immediately.
142
- */
143
- interface AgentEndpointHandlerArgs<TCtx = unknown, TBody = unknown, TParams extends z.ZodType = z.ZodUndefined> {
144
- query: undefined;
145
- body: TBody;
146
- params: z.infer<TParams>;
147
- request: Request;
148
- ctx: TCtx;
149
- /**
150
- * Mutable headers bag that the wrapper merges into the SSE response BEFORE
151
- * the stream starts. Used by `createConversationHistory` to issue a
152
- * conversation-id cookie on first request. Append entries via
153
- * `cookieHeaders.append('set-cookie', '<cookie-string>')`.
154
- *
155
- * Cookies appended AFTER the first yield are NOT applied — the response
156
- * headers commit when the wrapper constructs the Response, before the
157
- * async generator runs. This is per HTTP semantics, not a wrapper choice.
158
- */
159
- cookieHeaders: Headers;
160
- /**
161
- * Phase 3 (Production-Readiness #5) — request abort signal.
162
- *
163
- * Fires when the SSE client disconnects (browser closes tab, abort fetch,
164
- * etc.). Thread this to `agent.send(msg, { signal })` so the SDK cancels
165
- * the in-flight provider call — STOPS TOKENS FROM CHARGING for output
166
- * the user will never receive.
167
- *
168
- * EC-1 (MUST FIX): the signal is derived via duck-type detection
169
- * (`'aborted' in r.signal && typeof r.signal.addEventListener === 'function'`)
170
- * to survive cross-realm scenarios (Node 18 polyfills, undici, Edge
171
- * runtimes with their own AbortSignal globals). `instanceof AbortSignal`
172
- * would fail in those cases.
173
- */
174
- signal: AbortSignal;
175
- }
176
- interface AgentEndpointConfig<TCtx = unknown, TBody = unknown, TParams extends z.ZodType = z.ZodUndefined> {
177
- /**
178
- * Optional Zod schema for path params (e.g. `z.object({ id: z.string() })`).
179
- * When present, the runner validates path params and returns 400 on mismatch
180
- * BEFORE the generator runs; the validated params are threaded to the
181
- * generator typed as `z.infer<TParams>` (D4).
182
- */
183
- params?: TParams;
184
- handler: (args: AgentEndpointHandlerArgs<TCtx, TBody, TParams>) => AsyncGenerator<AgentEvent, void, unknown>;
185
- }
186
- declare function defineAgentEndpoint<TBody = unknown, TCtx = unknown, TParams extends z.ZodType = z.ZodUndefined>(config: AgentEndpointConfig<TCtx, TBody, TParams>): RouteConfig<z.ZodUndefined, z.ZodUndefined, TParams, TCtx, Response>;
187
-
188
- /**
189
- * Item #4 — `defineAgentTool`
190
- *
191
- * Sugar over the `@theokit/sdk` `CustomTool` contract. Takes a Zod schema +
192
- * handler and produces a structurally-compatible `CustomTool` that
193
- * `Agent.create({ tools: [...] })` accepts.
194
- *
195
- * Uses Zod v4's native `z.toJSONSchema()` to convert the input schema to
196
- * JSON Schema for LLM providers.
197
- *
198
- * Handler error propagation:
199
- * `defineAgentTool` parses the input via the Zod schema BEFORE calling the
200
- * user handler. Invalid input throws a `ZodError`, which the SDK's tool-
201
- * dispatcher (or the `streamAgentRun` adapter) sees as a tool failure and
202
- * surfaces as an `error` AgentEvent on the SSE wire (ADR D3).
203
- */
204
- /**
205
- * Local mirror of the SDK's `CustomTool` interface. We don't `import type`
206
- * from `@theokit/sdk` because the SDK is an optional peer (consumers who
207
- * never call `defineAgentTool` shouldn't need it installed). The shape is
208
- * the wire contract; any structurally-matching object is accepted by
209
- * `Agent.create({ tools })`.
210
- *
211
- * @public
212
- */
213
- interface CustomTool {
214
- name: string;
215
- description: string;
216
- inputSchema: Record<string, unknown>;
217
- handler: (input: Record<string, unknown>) => string | Promise<string>;
218
- }
219
- /**
220
- * Spec accepted by {@link defineAgentTool}. `inputSchema` is a Zod 3 schema
221
- * rooted in `z.object(...)`. The `handler` argument type is inferred via
222
- * `z.infer<T>`.
223
- *
224
- * @public
225
- */
226
- interface DefineAgentToolSpec<T extends z.ZodType> {
227
- /** Tool name surfaced to the LLM. Must match `^[a-zA-Z][a-zA-Z0-9_-]{0,63}$`. */
228
- name: string;
229
- /** Description surfaced to the LLM. Required — drives tool-selection accuracy. */
230
- description: string;
231
- /** Zod schema describing the input. Must be `z.object(...)` at the root. */
232
- inputSchema: T;
233
- /** Handler invoked with the parsed input. */
234
- handler: (input: z.infer<T>) => string | Promise<string>;
235
- }
236
- /**
237
- * Build a {@link CustomTool} from a Zod 3 schema + handler.
238
- *
239
- * Behavior:
240
- * - Validates `name` matches the LLM tool-name regex.
241
- * - Requires `inputSchema` to be a `ZodObject` (Anthropic + SDK contract).
242
- * - Warns (not throws) if `description` is empty — empty descriptions
243
- * degrade LLM tool selection.
244
- * - Converts the Zod schema to JSON Schema 7 inline (no `$ref`s — LLMs handle
245
- * inline schemas more reliably).
246
- * - Strips the top-level `$schema` field (Anthropic rejects schemas with
247
- * `$schema` at root in some provider modes).
248
- * - Wraps the handler to parse the input via the Zod schema BEFORE invoking
249
- * the user code — bad LLM-supplied input throws `ZodError`, which the SDK
250
- * converts to `tool_result(isError)`.
251
- *
252
- * @public
253
- */
254
- declare function defineAgentTool<T extends z.ZodType>(spec: DefineAgentToolSpec<T>): CustomTool;
255
-
256
- interface ChannelHandler<TMessage = unknown> {
257
- onSubscribe?: (ws: WebSocketLike, room: string, req: IncomingMessage) => void;
258
- onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void;
259
- onUnsubscribe?: (ws: WebSocketLike, room: string) => void;
260
- }
261
- /**
262
- * Define a channel handler for WebSocket rooms.
263
- * Identity function — provides type inference for channel handlers.
264
- */
265
- declare function defineChannel<TMessage = unknown>(handler: ChannelHandler<TMessage>): ChannelHandler<TMessage>;
266
- /**
267
- * T5a.2 Phase F slice 2/3 — Web-Standards channel handler.
268
- *
269
- * Mirror of `ChannelHandler<TMessage>` for the Web `Request` shape.
270
- * `onSubscribe` receives `request: Request` instead of `req: IncomingMessage`
271
- * — the rest of the surface (onMessage, onUnsubscribe) is shape-agnostic
272
- * (WebSocketLike is already Web-standards-compatible per `define-websocket.ts`).
273
- *
274
- * Per `docs/plans/t5a2-incoming-message-to-request-shape-refactor-plan.md`
275
- * v1.0 § Phase F.
276
- *
277
- * **Architectural note:** WebSocket upgrade semantics differ across
278
- * runtimes:
279
- * - Node: `WebSocketServer.handleUpgrade(req, socket, head, cb)` —
280
- * hands you `req: IncomingMessage` at the upgrade handshake.
281
- * - CF Workers: `new WebSocketPair()` + `request.headers` (the upgrade
282
- * handshake IS a Web Request) — hands you `request: Request`.
283
- * - Bun: `server.upgrade(request, { data })` — same Web Request shape.
284
- * - Deno: `Deno.upgradeWebSocket(request)` — same Web Request shape.
285
- *
286
- * Channel handlers targeting CF/Bun/Deno use `WebChannelHandler`; legacy
287
- * Node consumers stay on `ChannelHandler`. Cross-runtime channels ship
288
- * both shapes.
289
- */
290
- interface WebChannelHandler<TMessage = unknown> {
291
- onSubscribe?: (ws: WebSocketLike, room: string, request: Request) => void;
292
- onMessage?: (ws: WebSocketLike, room: string, data: TMessage) => void;
293
- onUnsubscribe?: (ws: WebSocketLike, room: string) => void;
294
- }
295
- /**
296
- * Web-Standards `defineChannel` sibling. Identity function — provides
297
- * type inference for Web channel handlers.
298
- */
299
- declare function defineWebChannel<TMessage = unknown>(handler: WebChannelHandler<TMessage>): WebChannelHandler<TMessage>;
300
-
301
- /**
302
- * Identity function for defining a Theo plugin.
303
- *
304
- * **Note:** Prefer `definePlugin` (shorter, canonical name per ADR-0008 D6).
305
- * Both functions are identical — `defineTheoPlugin` is kept as an alias for
306
- * existing in-tree consumers without forcing a migration sweep.
307
- */
308
- declare function defineTheoPlugin(plugin: TheoPlugin): TheoPlugin;
309
-
310
- export { type ActionAccept, type ActionConfig, type AgentEndpointConfig, type AgentEndpointHandlerArgs, type ChannelHandler, type CustomTool, type DefineAgentToolSpec, type MiddlewareHandler, type RouteConfig, type WebChannelHandler, WebSocketLike, defineAction, defineAgentEndpoint, defineAgentTool, defineChannel, defineMiddleware, defineRoute, defineTheoPlugin, defineWebChannel };
@@ -1,11 +0,0 @@
1
- export { B as BATCH_PATH, a as BatchExecuteFn, b as BatchPathConflictError, c as BatchPayload, d as BatchRequestItem, e as BatchResponse, f as BatchResultItem, C as CookieOptions, g as CorsConfig, h as CorsHandler, i as CorsOrigin, j as CorsWebHandler, k as CustomErrorPages, E as ExecuteActionOptions, l as ExecuteRouteContext, H as HandleBatchOptions, M as MAX_ERROR_HTML_BYTES, m as MiddlewareResult, N as NotFoundError, S as STRIPPED_HEADERS, n as SendErrorInput, o as SendErrorOptions, T as TRACE_HEADER, p as TRACE_PARENT_HEADER, q as TheoError, _ as _resetMiddlewareCacheForTests, s as appendCookieToHeaders, t as appendDeleteCookieToHeaders, u as createCorsHandler, v as createCorsWebHandler, w as deleteCookie, x as envelopeCodeToStatus, y as executeAction, z as executeRoute, A as extractTraceId, D as extractTraceIdFromRequest, F as fromUnknown, G as getCookie, I as getCookieFromRequest, J as handleBatchRequest, K as handleRequestError, L as handleWebRequestError, P as loadCustomErrorPages, Q as matchesOrigin, R as parseCookieHeader, U as parseTraceparent, W as runMiddlewareAndContext, X as sendError, Y as sendJson, Z as serializeCookie, $ as serveStaticFile, a0 as serverErrorToEnvelope, a1 as setCookie } from '../../index-B40qUSrQ.js';
2
- import '../../error-envelope-BsNzzAV5.js';
3
- import 'node:http';
4
- import '../../plugin-types-DNJGxr4Z.js';
5
- import '../../plugin-runner-BGBkzgi0.js';
6
- import '../../job-backend-CgC8Xf33.js';
7
- import '../../match-CfbEFRG4.js';
8
- import 'vite';
9
- import '../../csrf-BBrEZSBW.js';
10
- import '../../audit-log-BQWM5YLG.js';
11
- import 'zod';