@theokit/di-agent 0.2.0 → 0.3.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.
package/dist/index.d.cts CHANGED
@@ -42,70 +42,181 @@ interface CreateAgentProviderOptions<TAgent> {
42
42
  */
43
43
  declare function createAgentProvider<TAgent>(options: CreateAgentProviderOptions<TAgent>): FactoryProvider<TAgent>;
44
44
 
45
+ /**
46
+ * The class a class decorator was applied to, as seen by the reader helpers.
47
+ *
48
+ * Spelled as a constructor signature rather than `Function`. `Function` is the widest callable
49
+ * type there is — it accepts any argument list and returns `any` — so it documents nothing and
50
+ * silently admits things that are not classes at all. The constructor form says what the readers
51
+ * actually receive: something you could have written `new` in front of.
52
+ *
53
+ * `abstract` so an abstract base class is accepted, and `...args: never` because the readers only
54
+ * ever pass the value to `Reflect.getMetadata` and never construct it, so the parameter list is
55
+ * deliberately unusable rather than merely unconstrained.
56
+ */
57
+ type DecoratedClass = abstract new (...args: never) => unknown;
58
+
59
+ /** What {@link Auth} declares: the identity `providers` this agent accepts, and any transport
60
+ * `sessionConfig` they need. */
45
61
  interface AuthOptions {
46
62
  providers?: string[];
47
63
  sessionConfig?: unknown;
48
64
  }
65
+ /**
66
+ * Declare how an agent class authenticates the caller.
67
+ *
68
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
69
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
70
+ */
49
71
  declare function Auth(options?: AuthOptions): ClassDecorator;
50
- declare function readAuthMetadata(target: Function): AuthOptions | undefined;
72
+ /** The `@Auth` of a class, or `undefined` when it has none.
73
+ *
74
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
75
+ * property and method decorators, which accumulate into a map. */
76
+ declare function readAuthMetadata(target: DecoratedClass): AuthOptions | undefined;
51
77
 
78
+ /** What {@link AutoSummarize} declares: the `triggerFraction` of the context window that starts a
79
+ * summarisation, how many recent turns to `keepNewest` verbatim, and optionally which `model`
80
+ * writes the summary. */
52
81
  interface AutoSummarizeOptions {
53
82
  triggerFraction?: number;
54
83
  keepNewest?: number;
55
84
  model?: string;
56
85
  }
86
+ /**
87
+ * Declare that a conversation is summarised automatically as it approaches the context limit, so
88
+ * it can continue past the point where it would otherwise be truncated.
89
+ *
90
+ * Defaults are resolved at decoration time, so a reader of the metadata sees real values rather
91
+ * than having to know them.
92
+ *
93
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
94
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
95
+ */
57
96
  declare function AutoSummarize(options?: AutoSummarizeOptions): ClassDecorator;
58
- declare function readAutoSummarizeMetadata(target: abstract new (...args: never) => unknown): (Required<Omit<AutoSummarizeOptions, "model">> & {
97
+ /** The `@AutoSummarize` of a class with its defaults resolved, or `undefined` when it has none.
98
+ *
99
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
100
+ * property and method decorators, which accumulate into a map. */
101
+ declare function readAutoSummarizeMetadata(target: DecoratedClass): (Required<Omit<AutoSummarizeOptions, "model">> & {
59
102
  model?: string;
60
103
  }) | undefined;
61
104
 
105
+ /** What {@link Cron} declares: the `schedule` as a cron expression and the `timezone` it is read
106
+ * in. The expression is stored verbatim and never parsed here, so a malformed one surfaces
107
+ * wherever it is eventually scheduled. */
62
108
  interface CronOptions {
63
109
  schedule: string;
64
110
  timezone?: string;
65
111
  }
112
+ /** A stored `@Cron`, with the method it was applied to. The map is already keyed by that method;
113
+ * `methodKey` repeats it so an entry read on its own still says what it schedules. */
66
114
  interface CronMetadata extends CronOptions {
67
115
  methodKey: string | symbol;
68
116
  }
117
+ /**
118
+ * `@Cron(options)` — declare a scheduled routine on a method.
119
+ *
120
+ * Accumulates per method, keyed by the method name, so a class may schedule as many
121
+ * routines as it has methods. It used to keep a single object per class, which meant a
122
+ * second `@Cron` on the same class silently discarded the first (#6).
123
+ */
69
124
  declare function Cron(options: CronOptions): MethodDecorator;
70
- declare function readCronMetadata(target: abstract new (...args: never) => unknown): CronMetadata | undefined;
125
+ /** Read `@Cron()` metadata off a class constructor, keyed by method (insertion-ordered). */
126
+ declare function readCronMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, CronMetadata>;
71
127
 
128
+ /** What {@link EvalDecorator} declares: the evaluation's `name`, the `scorers` that judge a run,
129
+ * and the `dataset` it runs against. */
72
130
  interface EvalOptions {
73
131
  name?: string;
74
132
  scorers?: unknown[];
75
133
  dataset?: unknown;
76
134
  }
135
+ /**
136
+ * Declare an agent class as the subject of an evaluation.
137
+ *
138
+ * Named `EvalDecorator` rather than `Eval` because `eval` is a reserved word in strict mode, and
139
+ * an export nobody can import under its own name is worse than a longer one.
140
+ *
141
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
142
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
143
+ */
77
144
  declare function EvalDecorator(options?: EvalOptions): ClassDecorator;
78
- declare function readEvalDecoratorMetadata(target: Function): EvalOptions | undefined;
145
+ /** The `@EvalDecorator` of a class, or `undefined` when it has none.
146
+ *
147
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
148
+ * property and method decorators, which accumulate into a map. */
149
+ declare function readEvalDecoratorMetadata(target: DecoratedClass): EvalOptions | undefined;
79
150
 
151
+ /** What {@link Hitl} declares: the `tools` whose invocation needs a human decision, and the
152
+ * `timeoutMs` after which waiting stops. */
80
153
  interface HitlOptions {
81
154
  tools: string[];
82
155
  timeoutMs?: number;
83
156
  }
157
+ /** A stored `@Hitl`, with the method it was applied to. The map is already keyed by that method;
158
+ * `methodKey` repeats it so an entry read on its own still says what it guards. */
84
159
  interface HitlMetadata extends HitlOptions {
85
160
  methodKey: string | symbol;
86
161
  }
162
+ /**
163
+ * `@Hitl(options)` — declare a human-in-the-loop approval handler on a method.
164
+ *
165
+ * Accumulates per method, keyed by the method name, so a class may declare as many
166
+ * handlers as it has methods. It used to keep a single object per class, which meant a
167
+ * second `@Hitl` on the same class silently discarded the first (#6).
168
+ */
87
169
  declare function Hitl(options: HitlOptions): MethodDecorator;
88
- declare function readHitlMetadata(target: abstract new (...args: never) => unknown): HitlMetadata | undefined;
170
+ /** Read `@Hitl()` metadata off a class constructor, keyed by method (insertion-ordered). */
171
+ declare function readHitlMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, HitlMetadata>;
89
172
 
173
+ /** What {@link MemoryScopeDecorator} declares: the `path` naming this scope's place in the
174
+ * memory hierarchy. */
90
175
  interface MemoryScopeOptions {
91
176
  path: string;
92
177
  }
178
+ /**
179
+ * Declare the memory scope a property reads and writes, so sibling scopes stay isolated from
180
+ * each other while a child can still see its parent.
181
+ *
182
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
183
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
184
+ */
93
185
  declare function MemoryScopeDecorator(options: MemoryScopeOptions): PropertyDecorator;
186
+ /** Every `@MemoryScopeDecorator` on a class, keyed by the property it was applied to. */
94
187
  declare function readMemoryScopeMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, MemoryScopeOptions>;
95
188
 
189
+ /** What {@link Reranker} declares: which provider and model score the candidates, and how many
190
+ * survive (`topN`). */
96
191
  interface RerankerOptions {
97
192
  provider?: string;
98
193
  model?: string;
99
194
  topN?: number;
100
195
  }
196
+ /**
197
+ * Declare a property as the reranking step that reorders what a retriever returned.
198
+ *
199
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
200
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
201
+ */
101
202
  declare function Reranker(options: RerankerOptions): PropertyDecorator;
203
+ /** Every `@Reranker` on a class, keyed by the property it was applied to. */
102
204
  declare function readRerankerMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RerankerOptions>;
103
205
 
206
+ /** What {@link Retriever} declares: how many passages to return (`topK`) and the minimum score
207
+ * a passage needs to be worth returning at all (`threshold`). */
104
208
  interface RetrieverOptions {
105
209
  topK?: number;
106
210
  threshold?: number;
107
211
  }
212
+ /**
213
+ * Declare a property as the retrieval step of a RAG pipeline.
214
+ *
215
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
216
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
217
+ */
108
218
  declare function Retriever(options: RetrieverOptions): PropertyDecorator;
219
+ /** Every `@Retriever` on a class, keyed by the property it was applied to. */
109
220
  declare function readRetrieverMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RetrieverOptions>;
110
221
 
111
222
  /**
@@ -156,6 +267,9 @@ declare function Step(metadata?: StepMetadata): MethodDecorator;
156
267
  /** Read `@Step()` metadata off a class constructor (insertion-ordered). */
157
268
  declare function readStepMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, StepMetadata>;
158
269
 
270
+ /** What {@link SubAgent} declares: how the parent agent describes the delegate when deciding
271
+ * whether to hand work over, and optionally which model it runs on and how deep delegation may
272
+ * nest before it stops. */
159
273
  interface SubAgentOptions {
160
274
  name: string;
161
275
  description: string;
@@ -163,48 +277,109 @@ interface SubAgentOptions {
163
277
  model?: string;
164
278
  maxDelegationDepth?: number;
165
279
  }
280
+ /**
281
+ * Declare a property as a subagent this one may delegate to, exposed to the parent as a tool.
282
+ *
283
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
284
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
285
+ */
166
286
  declare function SubAgent(options: SubAgentOptions): PropertyDecorator;
287
+ /** Every `@SubAgent` on a class, keyed by the property it was applied to. */
167
288
  declare function readSubAgentMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubAgentOptions>;
168
289
 
290
+ /** What {@link Subscription} declares: the event `name` to listen for, and optionally the
291
+ * `transport` it arrives on. */
169
292
  interface SubscriptionOptions {
170
293
  name: string;
171
294
  transport?: string;
172
295
  }
296
+ /**
297
+ * Declare a property as a subscription to an event stream.
298
+ *
299
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
300
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
301
+ */
173
302
  declare function Subscription(options: SubscriptionOptions): PropertyDecorator;
303
+ /** Every `@Subscription` on a class, keyed by the property it was applied to. */
174
304
  declare function readSubscriptionMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubscriptionOptions>;
175
305
 
306
+ /** What {@link TextSplitter} declares: the splitting `strategy`, the target `chunkSize`, and how
307
+ * much `overlap` consecutive chunks share so a passage split mid-sentence is still retrievable
308
+ * from either side. */
176
309
  interface TextSplitterOptions {
177
310
  strategy?: string;
178
311
  chunkSize?: number;
179
312
  overlap?: number;
180
313
  }
314
+ /**
315
+ * Declare a property as the step that breaks documents into indexable chunks.
316
+ *
317
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
318
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
319
+ */
181
320
  declare function TextSplitter(options: TextSplitterOptions): PropertyDecorator;
321
+ /** Every `@TextSplitter` on a class, keyed by the property it was applied to. */
182
322
  declare function readTextSplitterMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, TextSplitterOptions>;
183
323
 
324
+ /** What {@link Tool} declares about one tool: the name and description an agent sees when
325
+ * choosing it, and optionally the schema its input must match. */
184
326
  interface ToolOptions {
185
327
  name: string;
186
328
  description: string;
187
329
  inputSchema?: unknown;
188
330
  }
331
+ /**
332
+ * Declare a property as a tool an agent may call.
333
+ *
334
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
335
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
336
+ */
189
337
  declare function Tool(options: ToolOptions): PropertyDecorator;
338
+ /** Every `@Tool` on a class, keyed by the property it was applied to. Empty map when there are
339
+ * none — a class with no tools is ordinary, not an error. */
190
340
  declare function readToolMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, ToolOptions>;
191
341
 
342
+ /** What {@link UseSandbox} declares: which `backend` isolates the execution, the `workDir` it
343
+ * starts in, and the `timeoutMs` after which it is abandoned. */
192
344
  interface UseSandboxOptions {
193
345
  backend?: "local" | "docker" | string;
194
346
  workDir?: string;
195
347
  timeoutMs?: number;
196
348
  }
349
+ /**
350
+ * Declare that a property's work runs inside a sandbox rather than in this process.
351
+ *
352
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
353
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
354
+ */
197
355
  declare function UseSandbox(options?: UseSandboxOptions): PropertyDecorator;
356
+ /** Every `@UseSandbox` on a class, keyed by the property it was applied to. */
198
357
  declare function readSandboxMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, UseSandboxOptions>;
199
358
 
359
+ /** What {@link Workflow} declares about a workflow class: its `name`, an optional `retryPolicy`,
360
+ * and the schemas its input and output are expected to match. */
200
361
  interface WorkflowOptions {
201
362
  name?: string;
202
363
  retryPolicy?: unknown;
203
364
  inputSchema?: unknown;
204
365
  outputSchema?: unknown;
205
366
  }
367
+ /**
368
+ * Mark a class as a workflow.
369
+ *
370
+ * This is the class-level marker only. The steps are declared with `@Step` on the methods, and
371
+ * `buildWorkflow` compiles the two together into a runnable `@theokit/sdk` Workflow — which makes
372
+ * it the one decorator in this package with a consumer that ships here.
373
+ *
374
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
375
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
376
+ */
206
377
  declare function Workflow(options?: WorkflowOptions): ClassDecorator;
207
- declare function readWorkflowMetadata(target: Function): WorkflowOptions | undefined;
378
+ /** The `@Workflow` of a class, or `undefined` when it has none.
379
+ *
380
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
381
+ * property and method decorators, which accumulate into a map. */
382
+ declare function readWorkflowMetadata(target: DecoratedClass): WorkflowOptions | undefined;
208
383
 
209
384
  /**
210
385
  * Parameter decorator — injects the REQUEST-scoped Agent into a constructor.
@@ -234,7 +409,7 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
234
409
  * `@theokit/sdk` `Workflow`.
235
410
  *
236
411
  * This is the materializer/bridge for the decorator-driven workflow authoring
237
- * surface (cross-val Gap 2). It COMPOSES the existing `Workflow` engine — it
412
+ * surface. It COMPOSES the existing `Workflow` engine — it
238
413
  * adds no orchestration logic of its own (same principle as `createSquad`).
239
414
  * Steps are topologically ordered by their single `after` dependency into a
240
415
  * linear `Workflow.then(...)` chain; each step's return value is threaded into
@@ -253,4 +428,4 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
253
428
  */
254
429
  declare function buildWorkflow(instance: object): Workflow$1;
255
430
 
256
- export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };
431
+ export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, type DecoratedClass, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };
package/dist/index.d.ts CHANGED
@@ -42,70 +42,181 @@ interface CreateAgentProviderOptions<TAgent> {
42
42
  */
43
43
  declare function createAgentProvider<TAgent>(options: CreateAgentProviderOptions<TAgent>): FactoryProvider<TAgent>;
44
44
 
45
+ /**
46
+ * The class a class decorator was applied to, as seen by the reader helpers.
47
+ *
48
+ * Spelled as a constructor signature rather than `Function`. `Function` is the widest callable
49
+ * type there is — it accepts any argument list and returns `any` — so it documents nothing and
50
+ * silently admits things that are not classes at all. The constructor form says what the readers
51
+ * actually receive: something you could have written `new` in front of.
52
+ *
53
+ * `abstract` so an abstract base class is accepted, and `...args: never` because the readers only
54
+ * ever pass the value to `Reflect.getMetadata` and never construct it, so the parameter list is
55
+ * deliberately unusable rather than merely unconstrained.
56
+ */
57
+ type DecoratedClass = abstract new (...args: never) => unknown;
58
+
59
+ /** What {@link Auth} declares: the identity `providers` this agent accepts, and any transport
60
+ * `sessionConfig` they need. */
45
61
  interface AuthOptions {
46
62
  providers?: string[];
47
63
  sessionConfig?: unknown;
48
64
  }
65
+ /**
66
+ * Declare how an agent class authenticates the caller.
67
+ *
68
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
69
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
70
+ */
49
71
  declare function Auth(options?: AuthOptions): ClassDecorator;
50
- declare function readAuthMetadata(target: Function): AuthOptions | undefined;
72
+ /** The `@Auth` of a class, or `undefined` when it has none.
73
+ *
74
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
75
+ * property and method decorators, which accumulate into a map. */
76
+ declare function readAuthMetadata(target: DecoratedClass): AuthOptions | undefined;
51
77
 
78
+ /** What {@link AutoSummarize} declares: the `triggerFraction` of the context window that starts a
79
+ * summarisation, how many recent turns to `keepNewest` verbatim, and optionally which `model`
80
+ * writes the summary. */
52
81
  interface AutoSummarizeOptions {
53
82
  triggerFraction?: number;
54
83
  keepNewest?: number;
55
84
  model?: string;
56
85
  }
86
+ /**
87
+ * Declare that a conversation is summarised automatically as it approaches the context limit, so
88
+ * it can continue past the point where it would otherwise be truncated.
89
+ *
90
+ * Defaults are resolved at decoration time, so a reader of the metadata sees real values rather
91
+ * than having to know them.
92
+ *
93
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
94
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
95
+ */
57
96
  declare function AutoSummarize(options?: AutoSummarizeOptions): ClassDecorator;
58
- declare function readAutoSummarizeMetadata(target: abstract new (...args: never) => unknown): (Required<Omit<AutoSummarizeOptions, "model">> & {
97
+ /** The `@AutoSummarize` of a class with its defaults resolved, or `undefined` when it has none.
98
+ *
99
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
100
+ * property and method decorators, which accumulate into a map. */
101
+ declare function readAutoSummarizeMetadata(target: DecoratedClass): (Required<Omit<AutoSummarizeOptions, "model">> & {
59
102
  model?: string;
60
103
  }) | undefined;
61
104
 
105
+ /** What {@link Cron} declares: the `schedule` as a cron expression and the `timezone` it is read
106
+ * in. The expression is stored verbatim and never parsed here, so a malformed one surfaces
107
+ * wherever it is eventually scheduled. */
62
108
  interface CronOptions {
63
109
  schedule: string;
64
110
  timezone?: string;
65
111
  }
112
+ /** A stored `@Cron`, with the method it was applied to. The map is already keyed by that method;
113
+ * `methodKey` repeats it so an entry read on its own still says what it schedules. */
66
114
  interface CronMetadata extends CronOptions {
67
115
  methodKey: string | symbol;
68
116
  }
117
+ /**
118
+ * `@Cron(options)` — declare a scheduled routine on a method.
119
+ *
120
+ * Accumulates per method, keyed by the method name, so a class may schedule as many
121
+ * routines as it has methods. It used to keep a single object per class, which meant a
122
+ * second `@Cron` on the same class silently discarded the first (#6).
123
+ */
69
124
  declare function Cron(options: CronOptions): MethodDecorator;
70
- declare function readCronMetadata(target: abstract new (...args: never) => unknown): CronMetadata | undefined;
125
+ /** Read `@Cron()` metadata off a class constructor, keyed by method (insertion-ordered). */
126
+ declare function readCronMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, CronMetadata>;
71
127
 
128
+ /** What {@link EvalDecorator} declares: the evaluation's `name`, the `scorers` that judge a run,
129
+ * and the `dataset` it runs against. */
72
130
  interface EvalOptions {
73
131
  name?: string;
74
132
  scorers?: unknown[];
75
133
  dataset?: unknown;
76
134
  }
135
+ /**
136
+ * Declare an agent class as the subject of an evaluation.
137
+ *
138
+ * Named `EvalDecorator` rather than `Eval` because `eval` is a reserved word in strict mode, and
139
+ * an export nobody can import under its own name is worse than a longer one.
140
+ *
141
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
142
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
143
+ */
77
144
  declare function EvalDecorator(options?: EvalOptions): ClassDecorator;
78
- declare function readEvalDecoratorMetadata(target: Function): EvalOptions | undefined;
145
+ /** The `@EvalDecorator` of a class, or `undefined` when it has none.
146
+ *
147
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
148
+ * property and method decorators, which accumulate into a map. */
149
+ declare function readEvalDecoratorMetadata(target: DecoratedClass): EvalOptions | undefined;
79
150
 
151
+ /** What {@link Hitl} declares: the `tools` whose invocation needs a human decision, and the
152
+ * `timeoutMs` after which waiting stops. */
80
153
  interface HitlOptions {
81
154
  tools: string[];
82
155
  timeoutMs?: number;
83
156
  }
157
+ /** A stored `@Hitl`, with the method it was applied to. The map is already keyed by that method;
158
+ * `methodKey` repeats it so an entry read on its own still says what it guards. */
84
159
  interface HitlMetadata extends HitlOptions {
85
160
  methodKey: string | symbol;
86
161
  }
162
+ /**
163
+ * `@Hitl(options)` — declare a human-in-the-loop approval handler on a method.
164
+ *
165
+ * Accumulates per method, keyed by the method name, so a class may declare as many
166
+ * handlers as it has methods. It used to keep a single object per class, which meant a
167
+ * second `@Hitl` on the same class silently discarded the first (#6).
168
+ */
87
169
  declare function Hitl(options: HitlOptions): MethodDecorator;
88
- declare function readHitlMetadata(target: abstract new (...args: never) => unknown): HitlMetadata | undefined;
170
+ /** Read `@Hitl()` metadata off a class constructor, keyed by method (insertion-ordered). */
171
+ declare function readHitlMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, HitlMetadata>;
89
172
 
173
+ /** What {@link MemoryScopeDecorator} declares: the `path` naming this scope's place in the
174
+ * memory hierarchy. */
90
175
  interface MemoryScopeOptions {
91
176
  path: string;
92
177
  }
178
+ /**
179
+ * Declare the memory scope a property reads and writes, so sibling scopes stay isolated from
180
+ * each other while a child can still see its parent.
181
+ *
182
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
183
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
184
+ */
93
185
  declare function MemoryScopeDecorator(options: MemoryScopeOptions): PropertyDecorator;
186
+ /** Every `@MemoryScopeDecorator` on a class, keyed by the property it was applied to. */
94
187
  declare function readMemoryScopeMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, MemoryScopeOptions>;
95
188
 
189
+ /** What {@link Reranker} declares: which provider and model score the candidates, and how many
190
+ * survive (`topN`). */
96
191
  interface RerankerOptions {
97
192
  provider?: string;
98
193
  model?: string;
99
194
  topN?: number;
100
195
  }
196
+ /**
197
+ * Declare a property as the reranking step that reorders what a retriever returned.
198
+ *
199
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
200
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
201
+ */
101
202
  declare function Reranker(options: RerankerOptions): PropertyDecorator;
203
+ /** Every `@Reranker` on a class, keyed by the property it was applied to. */
102
204
  declare function readRerankerMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RerankerOptions>;
103
205
 
206
+ /** What {@link Retriever} declares: how many passages to return (`topK`) and the minimum score
207
+ * a passage needs to be worth returning at all (`threshold`). */
104
208
  interface RetrieverOptions {
105
209
  topK?: number;
106
210
  threshold?: number;
107
211
  }
212
+ /**
213
+ * Declare a property as the retrieval step of a RAG pipeline.
214
+ *
215
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
216
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
217
+ */
108
218
  declare function Retriever(options: RetrieverOptions): PropertyDecorator;
219
+ /** Every `@Retriever` on a class, keyed by the property it was applied to. */
109
220
  declare function readRetrieverMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, RetrieverOptions>;
110
221
 
111
222
  /**
@@ -156,6 +267,9 @@ declare function Step(metadata?: StepMetadata): MethodDecorator;
156
267
  /** Read `@Step()` metadata off a class constructor (insertion-ordered). */
157
268
  declare function readStepMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, StepMetadata>;
158
269
 
270
+ /** What {@link SubAgent} declares: how the parent agent describes the delegate when deciding
271
+ * whether to hand work over, and optionally which model it runs on and how deep delegation may
272
+ * nest before it stops. */
159
273
  interface SubAgentOptions {
160
274
  name: string;
161
275
  description: string;
@@ -163,48 +277,109 @@ interface SubAgentOptions {
163
277
  model?: string;
164
278
  maxDelegationDepth?: number;
165
279
  }
280
+ /**
281
+ * Declare a property as a subagent this one may delegate to, exposed to the parent as a tool.
282
+ *
283
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
284
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
285
+ */
166
286
  declare function SubAgent(options: SubAgentOptions): PropertyDecorator;
287
+ /** Every `@SubAgent` on a class, keyed by the property it was applied to. */
167
288
  declare function readSubAgentMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubAgentOptions>;
168
289
 
290
+ /** What {@link Subscription} declares: the event `name` to listen for, and optionally the
291
+ * `transport` it arrives on. */
169
292
  interface SubscriptionOptions {
170
293
  name: string;
171
294
  transport?: string;
172
295
  }
296
+ /**
297
+ * Declare a property as a subscription to an event stream.
298
+ *
299
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
300
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
301
+ */
173
302
  declare function Subscription(options: SubscriptionOptions): PropertyDecorator;
303
+ /** Every `@Subscription` on a class, keyed by the property it was applied to. */
174
304
  declare function readSubscriptionMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, SubscriptionOptions>;
175
305
 
306
+ /** What {@link TextSplitter} declares: the splitting `strategy`, the target `chunkSize`, and how
307
+ * much `overlap` consecutive chunks share so a passage split mid-sentence is still retrievable
308
+ * from either side. */
176
309
  interface TextSplitterOptions {
177
310
  strategy?: string;
178
311
  chunkSize?: number;
179
312
  overlap?: number;
180
313
  }
314
+ /**
315
+ * Declare a property as the step that breaks documents into indexable chunks.
316
+ *
317
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
318
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
319
+ */
181
320
  declare function TextSplitter(options: TextSplitterOptions): PropertyDecorator;
321
+ /** Every `@TextSplitter` on a class, keyed by the property it was applied to. */
182
322
  declare function readTextSplitterMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, TextSplitterOptions>;
183
323
 
324
+ /** What {@link Tool} declares about one tool: the name and description an agent sees when
325
+ * choosing it, and optionally the schema its input must match. */
184
326
  interface ToolOptions {
185
327
  name: string;
186
328
  description: string;
187
329
  inputSchema?: unknown;
188
330
  }
331
+ /**
332
+ * Declare a property as a tool an agent may call.
333
+ *
334
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
335
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
336
+ */
189
337
  declare function Tool(options: ToolOptions): PropertyDecorator;
338
+ /** Every `@Tool` on a class, keyed by the property it was applied to. Empty map when there are
339
+ * none — a class with no tools is ordinary, not an error. */
190
340
  declare function readToolMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, ToolOptions>;
191
341
 
342
+ /** What {@link UseSandbox} declares: which `backend` isolates the execution, the `workDir` it
343
+ * starts in, and the `timeoutMs` after which it is abandoned. */
192
344
  interface UseSandboxOptions {
193
345
  backend?: "local" | "docker" | string;
194
346
  workDir?: string;
195
347
  timeoutMs?: number;
196
348
  }
349
+ /**
350
+ * Declare that a property's work runs inside a sandbox rather than in this process.
351
+ *
352
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
353
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
354
+ */
197
355
  declare function UseSandbox(options?: UseSandboxOptions): PropertyDecorator;
356
+ /** Every `@UseSandbox` on a class, keyed by the property it was applied to. */
198
357
  declare function readSandboxMetadata(target: abstract new (...args: never) => unknown): ReadonlyMap<string | symbol, UseSandboxOptions>;
199
358
 
359
+ /** What {@link Workflow} declares about a workflow class: its `name`, an optional `retryPolicy`,
360
+ * and the schemas its input and output are expected to match. */
200
361
  interface WorkflowOptions {
201
362
  name?: string;
202
363
  retryPolicy?: unknown;
203
364
  inputSchema?: unknown;
204
365
  outputSchema?: unknown;
205
366
  }
367
+ /**
368
+ * Mark a class as a workflow.
369
+ *
370
+ * This is the class-level marker only. The steps are declared with `@Step` on the methods, and
371
+ * `buildWorkflow` compiles the two together into a runnable `@theokit/sdk` Workflow — which makes
372
+ * it the one decorator in this package with a consumer that ships here.
373
+ *
374
+ * Records metadata only. Nothing in this package acts on it — the runtime that does lives in
375
+ * `@theokit/sdk`, which is what lets the declaration and the execution version independently.
376
+ */
206
377
  declare function Workflow(options?: WorkflowOptions): ClassDecorator;
207
- declare function readWorkflowMetadata(target: Function): WorkflowOptions | undefined;
378
+ /** The `@Workflow` of a class, or `undefined` when it has none.
379
+ *
380
+ * Class decorators are singular by nature, so this returns one object or `undefined` — unlike the
381
+ * property and method decorators, which accumulate into a map. */
382
+ declare function readWorkflowMetadata(target: DecoratedClass): WorkflowOptions | undefined;
208
383
 
209
384
  /**
210
385
  * Parameter decorator — injects the REQUEST-scoped Agent into a constructor.
@@ -234,7 +409,7 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
234
409
  * `@theokit/sdk` `Workflow`.
235
410
  *
236
411
  * This is the materializer/bridge for the decorator-driven workflow authoring
237
- * surface (cross-val Gap 2). It COMPOSES the existing `Workflow` engine — it
412
+ * surface. It COMPOSES the existing `Workflow` engine — it
238
413
  * adds no orchestration logic of its own (same principle as `createSquad`).
239
414
  * Steps are topologically ordered by their single `after` dependency into a
240
415
  * linear `Workflow.then(...)` chain; each step's return value is threaded into
@@ -253,4 +428,4 @@ declare const AGENT_TOKEN = "@theokit/di-agent:Agent";
253
428
  */
254
429
  declare function buildWorkflow(instance: object): Workflow$1;
255
430
 
256
- export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };
431
+ export { AGENT_TOKEN, Auth, type AuthOptions, AutoSummarize, type AutoSummarizeOptions, type CreateAgentProviderOptions, Cron, type CronMetadata, type CronOptions, type DecoratedClass, EvalDecorator, type EvalOptions, Hitl, type HitlMetadata, type HitlOptions, InjectAgent, MemoryScopeDecorator, type MemoryScopeOptions, Reranker, type RerankerOptions, Retriever, type RetrieverOptions, Squad, type SquadMetadata, Step, type StepMetadata, SubAgent, type SubAgentOptions, Subscription, type SubscriptionOptions, TextSplitter, type TextSplitterOptions, Tool, type ToolOptions, UseSandbox, type UseSandboxOptions, Workflow, type WorkflowOptions, buildWorkflow, createAgentProvider, readAuthMetadata, readAutoSummarizeMetadata, readCronMetadata, readEvalDecoratorMetadata, readHitlMetadata, readMemoryScopeMetadata, readRerankerMetadata, readRetrieverMetadata, readSandboxMetadata, readSquadMetadata, readStepMetadata, readSubAgentMetadata, readSubscriptionMetadata, readTextSplitterMetadata, readToolMetadata, readWorkflowMetadata };