Setting the file. One moment.
Types · Swarm · langchain-ai/langchain-skills · Skills Docs
Back to the top of the page
Position
7 of 8 scripts/ types.ts
TypeScript · 323 lines · 7 KB
15 * Number of rows in the table at creation time.
16 */
17 count : number ;
18
19 /**
20 * Column names present in the first row (e.g. `["id", "file"]`).
21 */
22 columns : string [];
23 }
24
25 /**
26 * Source specification for `create()`.
27 *
28 * Exactly one of `glob`, `filePaths`, or `tasks` must be set.
29 * Providing zero or more than one source throws an error.
30 */
31 export interface CreateSource {
32 /**
33 * Glob pattern(s) to match files. Each match becomes a row with
34 * `{ id: <basename>, file: <full path> }` columns. Requires a
35 * `glob` tool in the PTC configuration.
36 */
37 glob ?: string | string [];
38
39 /**
40 * Explicit list of file paths. Same row structure as `glob`
41 * (`{ id, file }`) but skips pattern resolution.
42 */
43 filePaths ?: string [];
44
45 /**
46 * Custom row data. Each object must include a string `id` field.
47 * All other fields become table columns.
48 */
49 tasks ?: Array < Record < string , unknown >>;
50 }
51
52 /**
53 * Per-row batch size function.
54 *
55 * Returns the desired batch size for a given row. Rows that return
56 * the same batch size are grouped together, then chunked into
57 * batches of that size.
58 */
59 export type BatchFn = (
60 row : Record < string , unknown >,
61 rowCount : number ,
62 ) => number ;
63
64 /**
65 * Options for `run()`.
66 *
67 * Controls how rows are selected, how instructions are templated,
68 * and how subagent dispatch is configured.
69 */
70 export interface RunOptions {
71 /**
72 * Instruction template with `{column}` placeholders that are
73 * interpolated per-row (e.g. `"Review {file} for security issues"`).
74 */
75 instruction : string ;
76
77 /**
78 * Context prose prepended to every subagent prompt. Use for shared
79 * background that applies to all rows (e.g. project description).
80 */
81 context ?: string ;
82
83 /**
84 * Filter clause to select a subset of rows. Rows that don't match
85 * are skipped (counted in `RunResult.skipped`).
86 */
87 filter ?: SwarmFilter ;
88
89 /**
90 * Name of the subagent type to dispatch to. When set, each dispatch
91 * runs a full agentic loop with tools. When omitted, each dispatch
92 * is a direct model call with structured output (no tools, no iteration).
93 */
94 subagentType ?: string ;
95
96 /**
97 * JSON Schema (type: "object") for structured output. Each property
98 * in the schema becomes a top-level column on the row.
99 */
100 responseSchema : Record < string , unknown >;
101
102 /**
103 * Controls how rows are grouped into subagent calls.
104 *
105 * - **Number**: uniform batch size for all rows.
106 * - **Function**: called per-row, returns desired batch size. Rows with
107 * the same batch size are grouped together, then chunked.
108 *
109 * Batch sizes are clamped to [1, MAX_BATCH_SIZE] after evaluation.
110 *
111 * @default auto-batch based on table size to cap total dispatches.
112 */
113 batchSize ?: number | BatchFn ;
114
115 /**
116 * Maximum concurrent subagent dispatches. Clamped to [1, MAX_SUBAGENTS].
117 * Defaults to MAX_SUBAGENTS (10) when omitted.
118 */
119 concurrency ?: number ;
120 }
121
122 /**
123 * Summary returned by `run()`.
124 *
125 * Contains counts and deduplicated failure groups. The agent uses
126 * this to decide whether to retry, inspect, or proceed.
127 */
128 export interface RunResult {
129 /**
130 * Number of rows where the subagent succeeded and a result was merged.
131 */
132 completed : number ;
133
134 /**
135 * Number of rows where the subagent failed or interpolation failed.
136 */
137 failed : number ;
138
139 /**
140 * Number of rows excluded by the filter (not dispatched).
141 */
142 skipped : number ;
143
144 /**
145 * Failures grouped by error message, sorted by count descending.
146 */
147 failures : FailureGroup [];
148 }
149
150 /**
151 * A group of rows that failed with the same error message.
152 *
153 * Deduplication keeps the failure list compact even when hundreds of
154 * rows hit the same error (e.g. rate limiting).
155 */
156 export interface FailureGroup {
157 /**
158 * The error message shared by all rows in this group.
159 */
160 error : string ;
161
162 /**
163 * Number of rows that hit this error.
164 */
165 count : number ;
166
167 /**
168 * IDs of all rows that hit this error.
169 */
170 ids : string [];
171 }
172
173 /**
174 * Options for `rows()`.
175 *
176 * Controls filtering, column projection, and row limiting when
177 * retrieving table data for inspection or aggregation.
178 */
179 export interface RowsOptions {
180 /**
181 * Filter clause — only rows matching the filter are returned.
182 */
183 filter ?: SwarmFilter ;
184
185 /**
186 * Project to specific columns. Omit to return all columns.
187 */
188 columns ?: string [];
189
190 /**
191 * Maximum number of rows to return. Omit for no limit.
192 */
193 limit ?: number ;
194 }
195
196 /**
197 * Filter clause for selecting rows. Can be a leaf predicate or a
198 * combinator (`and`/`or`) composing multiple clauses.
199 *
200 * Leaf predicates operate on a single column (supports dot-paths
201 * for nested access, e.g. `"meta.score"`).
202 */
203 export type SwarmFilter =
204 | {
205 /**
206 * Column path to compare.
207 */
208 column : string ;
209
210 /**
211 * Row matches if column value deeply equals this value.
212 */
213 equals : unknown ;
214 }
215 | {
216 /**
217 * Column path to compare.
218 */
219 column : string ;
220
221 /**
222 * Row matches if column value does NOT deeply equal this value.
223 */
224 notEquals : unknown ;
225 }
226 | {
227 /** Column path to compare. */
228 column : string ;
229
230 /**
231 * Row matches if column value deeply equals any item in this array.
232 */
233 in : unknown [];
234 }
235 | {
236 /**
237 * Column path to compare.
238 */
239 column : string ;
240
241 /**
242 * When true, matches non-null/non-undefined. When false, matches null/undefined.
243 */
244 exists : boolean ;
245 }
246 | {
247 /**
248 * All sub-filters must match for the row to match.
249 */
250 and : SwarmFilter [];
251 }
252 | {
253 /**
254 * At least one sub-filter must match for the row to match.
255 */
256 or : SwarmFilter [];
257 };
258
259 /**
260 * A single dispatch unit for the executor.
261 *
262 * Represents one subagent call — either a single row's interpolated
263 * prompt or a batch prompt covering multiple rows.
264 */
265 export interface TaskSpec {
266 /**
267 * Row ID (single dispatch) or batch ID (batched dispatch).
268 */
269 id : string ;
270
271 /**
272 * Fully interpolated prompt to send to the subagent.
273 */
274 prompt : string ;
275
276 /**
277 * Name of the subagent type to dispatch to. When omitted, the
278 * dispatch is a direct model call (invoke mode).
279 */
280 subagentType ?: string ;
281
282 /**
283 * Optional JSON Schema to constrain the subagent's response.
284 */
285 responseSchema ?: Record < string , unknown >;
286
287 /**
288 * Dispatch mode for this task.
289 *
290 * - `"agent"` — Full agentic loop with tools and middleware.
291 * - `"invoke"` — Direct model call, no tools or iteration.
292 *
293 * @default " agent "
294 */
295 mode ?: "agent" | "invoke" ;
296 }
297
298 /**
299 * Result of a single subagent dispatch.
300 *
301 * Returned by the executor in the same order as the input `TaskSpec[]`.
302 */
303 export interface TaskResult {
304 /**
305 * Row ID or batch ID that this result corresponds to.
306 */
307 id : string ;
308
309 /**
310 * Whether the dispatch succeeded or failed.
311 */
312 status : "completed" | "failed" ;
313
314 /**
315 * The subagent's response string (present when `status` is `"completed"`).
316 */
317 result ?: string ;
318
319 /**
320 * Error message (present when `status` is `"failed"`).
321 */
322 error ?: string ;
323 }