clanka 0.8.6 → 0.10.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 (96) hide show
  1. package/dist/Acp.d.ts +6 -1
  2. package/dist/Acp.d.ts.map +1 -1
  3. package/dist/Acp.js +34 -3
  4. package/dist/Acp.js.map +1 -1
  5. package/dist/Acp.test.js +178 -2
  6. package/dist/Acp.test.js.map +1 -1
  7. package/dist/AcpImage.test.js +7 -1
  8. package/dist/AcpImage.test.js.map +1 -1
  9. package/dist/Agent.d.ts +82 -8
  10. package/dist/Agent.d.ts.map +1 -1
  11. package/dist/Agent.js +556 -113
  12. package/dist/Agent.js.map +1 -1
  13. package/dist/Agent.test.js +86 -5
  14. package/dist/Agent.test.js.map +1 -1
  15. package/dist/AgentCallerConfig.test.d.ts +2 -0
  16. package/dist/AgentCallerConfig.test.d.ts.map +1 -0
  17. package/dist/AgentCallerConfig.test.js +335 -0
  18. package/dist/AgentCallerConfig.test.js.map +1 -0
  19. package/dist/AgentEnvironment.d.ts +76 -0
  20. package/dist/AgentEnvironment.d.ts.map +1 -0
  21. package/dist/AgentEnvironment.js +119 -0
  22. package/dist/AgentEnvironment.js.map +1 -0
  23. package/dist/AgentEnvironment.test.d.ts +2 -0
  24. package/dist/AgentEnvironment.test.d.ts.map +1 -0
  25. package/dist/AgentEnvironment.test.js +304 -0
  26. package/dist/AgentEnvironment.test.js.map +1 -0
  27. package/dist/AgentExecutor.d.ts +342 -183
  28. package/dist/AgentExecutor.d.ts.map +1 -1
  29. package/dist/AgentExecutor.js +607 -127
  30. package/dist/AgentExecutor.js.map +1 -1
  31. package/dist/AgentExecutor.test.js +287 -31
  32. package/dist/AgentExecutor.test.js.map +1 -1
  33. package/dist/AgentExecutorImage.test.js +5 -1
  34. package/dist/AgentExecutorImage.test.js.map +1 -1
  35. package/dist/AgentImage.test.js +15 -2
  36. package/dist/AgentImage.test.js.map +1 -1
  37. package/dist/AgentOutput.d.ts +70 -5
  38. package/dist/AgentOutput.d.ts.map +1 -1
  39. package/dist/AgentOutput.js +65 -0
  40. package/dist/AgentOutput.js.map +1 -1
  41. package/dist/AgentSkills.d.ts +37 -0
  42. package/dist/AgentSkills.d.ts.map +1 -1
  43. package/dist/AgentSkills.js +96 -32
  44. package/dist/AgentSkills.js.map +1 -1
  45. package/dist/AgentSkills.test.js +14 -2
  46. package/dist/AgentSkills.test.js.map +1 -1
  47. package/dist/AgentSubagents.test.d.ts +2 -0
  48. package/dist/AgentSubagents.test.d.ts.map +1 -0
  49. package/dist/AgentSubagents.test.js +494 -0
  50. package/dist/AgentSubagents.test.js.map +1 -0
  51. package/dist/AgentTools.d.ts +356 -14
  52. package/dist/AgentTools.d.ts.map +1 -1
  53. package/dist/AgentTools.js +214 -35
  54. package/dist/AgentTools.js.map +1 -1
  55. package/dist/OutputFormatter.d.ts.map +1 -1
  56. package/dist/OutputFormatter.js +19 -2
  57. package/dist/OutputFormatter.js.map +1 -1
  58. package/dist/ToolkitRenderer.d.ts.map +1 -1
  59. package/dist/ToolkitRenderer.js +6 -1
  60. package/dist/ToolkitRenderer.js.map +1 -1
  61. package/dist/bin/{Effect-rADALOOD.mjs → Effect-2jPlJ8eu.mjs} +43 -38
  62. package/dist/bin/Effect-2jPlJ8eu.mjs.map +1 -0
  63. package/dist/bin/{McpClient-NazR2OwL.mjs → McpClient-1W508adc.mjs} +3 -3
  64. package/dist/bin/{McpClient-NazR2OwL.mjs.map → McpClient-1W508adc.mjs.map} +1 -1
  65. package/dist/bin/{OutputFormatter-BVHbgF2b.mjs → OutputFormatter-BFAv48k9.mjs} +17 -5
  66. package/dist/bin/{OutputFormatter-BVHbgF2b.mjs.map → OutputFormatter-BFAv48k9.mjs.map} +1 -1
  67. package/dist/bin/{Schema-C7NXAOWA.mjs → Schema-D-7VuCiC.mjs} +2 -2
  68. package/dist/bin/{Schema-C7NXAOWA.mjs.map → Schema-D-7VuCiC.mjs.map} +1 -1
  69. package/dist/bin/{SemanticSearch-4Jes3jCl.mjs → SemanticSearch-Cb8aqvGv.mjs} +4 -4
  70. package/dist/bin/{SemanticSearch-4Jes3jCl.mjs.map → SemanticSearch-Cb8aqvGv.mjs.map} +1 -1
  71. package/dist/bin/{Stream-CSLA1_GD.mjs → Stream-DEu2tfCV.mjs} +12 -3
  72. package/dist/bin/Stream-DEu2tfCV.mjs.map +1 -0
  73. package/dist/bin/cli.mjs +13333 -12470
  74. package/dist/bin/cli.mjs.map +1 -1
  75. package/package.json +1 -1
  76. package/src/Acp.test.ts +279 -3
  77. package/src/Acp.ts +34 -4
  78. package/src/AcpImage.test.ts +7 -1
  79. package/src/Agent.test.ts +109 -4
  80. package/src/Agent.ts +874 -140
  81. package/src/AgentCallerConfig.test.ts +522 -0
  82. package/src/AgentEnvironment.test.ts +504 -0
  83. package/src/AgentEnvironment.ts +161 -0
  84. package/src/AgentExecutor.test.ts +414 -37
  85. package/src/AgentExecutor.ts +1028 -191
  86. package/src/AgentExecutorImage.test.ts +5 -1
  87. package/src/AgentImage.test.ts +21 -3
  88. package/src/AgentOutput.ts +91 -1
  89. package/src/AgentSkills.test.ts +14 -2
  90. package/src/AgentSkills.ts +117 -34
  91. package/src/AgentSubagents.test.ts +824 -0
  92. package/src/AgentTools.ts +377 -53
  93. package/src/OutputFormatter.ts +19 -2
  94. package/src/ToolkitRenderer.ts +7 -1
  95. package/dist/bin/Effect-rADALOOD.mjs.map +0 -1
  96. package/dist/bin/Stream-CSLA1_GD.mjs.map +0 -1
@@ -12,6 +12,7 @@ import * as RpcClient from "effect/rpc/RpcClient"
12
12
  import * as RpcSerialization from "effect/rpc/RpcSerialization"
13
13
  import * as RpcServer from "effect/rpc/RpcServer"
14
14
  import * as AgentExecutor from "./AgentExecutor.ts"
15
+ import { subagentsUnavailable } from "./AgentTools.ts"
15
16
  import type { ImageAttachment } from "./AgentTools.ts"
16
17
  import { equalBytes, supportedImages } from "./fixtures/TestImages.ts"
17
18
 
@@ -68,8 +69,11 @@ describe("RPC image executor", () => {
68
69
  withRpc((executor) =>
69
70
  Effect.gen(function* () {
70
71
  const images: Array<ImageAttachment> = []
72
+ const { environment } = yield* executor.capabilities
71
73
  const output = yield* executor
72
74
  .execute({
75
+ environment,
76
+ onEnvironment: () => Effect.void,
73
77
  script: fixtures
74
78
  .map(
75
79
  ([name]) =>
@@ -83,7 +87,7 @@ describe("RPC image executor", () => {
83
87
  images.push(image)
84
88
  }),
85
89
  onTaskComplete: () => Effect.void,
86
- onSubagent: () => Effect.succeed(""),
90
+ subagents: subagentsUnavailable,
87
91
  })
88
92
  .pipe(Stream.runCollect, Effect.timeout("5 seconds"))
89
93
  assert.strictEqual(images.length, fixtures.length)
@@ -17,8 +17,14 @@ import { tinyPng } from "./fixtures/TestImages.ts"
17
17
 
18
18
  const capabilities = new AgentExecutor.Capabilities({
19
19
  toolsDts: "",
20
- agentsMd: Option.none(),
20
+ environment: new AgentExecutor.ExecutionEnvironment({
21
+ cwd: "/",
22
+ baseline: [],
23
+ seen: [],
24
+ }),
25
+ instructions: Option.none(),
21
26
  supportsSearch: false,
27
+ tools: [],
22
28
  skills: [],
23
29
  })
24
30
 
@@ -264,8 +270,20 @@ describe("Agent images", () => {
264
270
 
265
271
  it.effect("does not copy image bytes into a delegate prompt", () =>
266
272
  Effect.gen(function* () {
267
- const executor = makeExecutor(({ onSubagent }) =>
268
- Stream.fromEffect(onSubagent("child task: describe the layout")),
273
+ const executor = makeExecutor(({ subagents, environment }) =>
274
+ Stream.fromEffect(
275
+ subagents.delegate({
276
+ prompt: "child task: describe the layout",
277
+ background: false,
278
+ environment: new AgentExecutor.EnvironmentUpdate({
279
+ environment,
280
+ update: Option.none(),
281
+ }),
282
+ }),
283
+ ).pipe(
284
+ Stream.map((result) => result.output ?? ""),
285
+ Stream.orDie,
286
+ ),
269
287
  )
270
288
  const { exit, calls } = yield* runAgent({
271
289
  prompt: imagePrompt,
@@ -4,6 +4,7 @@
4
4
  /** @effect-diagnostics schemaNumber:off */
5
5
  import * as Prompt from "effect/ai/Prompt"
6
6
  import * as AiError from "effect/ai/AiError"
7
+ import * as Effect from "effect/Effect"
7
8
  import * as Schema from "effect/Schema"
8
9
 
9
10
  /**
@@ -127,6 +128,14 @@ export class SubagentStart extends Schema.TaggedClass<SubagentStart>()(
127
128
  prompt: Schema.String,
128
129
  model: Schema.String,
129
130
  provider: Schema.String,
131
+ /**
132
+ * Background agents report only their start and completion; their
133
+ * output is not streamed.
134
+ */
135
+ background: Schema.Boolean.pipe(
136
+ Schema.withDecodingDefaultKey(Effect.succeed(false)),
137
+ Schema.withConstructorDefault(Effect.succeed(false)),
138
+ ),
130
139
  },
131
140
  ) {
132
141
  get modelAndProvider() {
@@ -142,7 +151,14 @@ export class SubagentComplete extends Schema.TaggedClass<SubagentComplete>()(
142
151
  "SubagentComplete",
143
152
  {
144
153
  id: Schema.Number,
154
+ /**
155
+ * The agent's final output, or the error message when it failed.
156
+ */
145
157
  summary: Schema.String,
158
+ status: Schema.Literals(["completed", "failed", "cancelled"]).pipe(
159
+ Schema.withDecodingDefaultKey(Effect.succeed("completed" as const)),
160
+ Schema.withConstructorDefault(Effect.succeed("completed" as const)),
161
+ ),
146
162
  },
147
163
  ) {}
148
164
 
@@ -198,6 +214,21 @@ export class CompactionEnded extends Schema.TaggedClass<CompactionEnded>()(
198
214
  },
199
215
  ) {}
200
216
 
217
+ /**
218
+ * Emitted when AGENTS.md files or skills the model has not seen yet are
219
+ * added to the history, after a directory change or a compaction. `update`
220
+ * is the text the model receives.
221
+ *
222
+ * @since 1.0.0
223
+ * @category Output
224
+ */
225
+ export class EnvironmentUpdated extends Schema.TaggedClass<EnvironmentUpdated>()(
226
+ "EnvironmentUpdated",
227
+ {
228
+ update: Schema.String,
229
+ },
230
+ ) {}
231
+
201
232
  export type ContentPart =
202
233
  | ReasoningStart
203
234
  | ReasoningDelta
@@ -211,6 +242,7 @@ export type ContentPart =
211
242
  | ExecuteOutputCapped
212
243
  | CompactionStarted
213
244
  | CompactionEnded
245
+ | EnvironmentUpdated
214
246
 
215
247
  export const ContentPart = Schema.Union([
216
248
  ReasoningStart,
@@ -225,6 +257,7 @@ export const ContentPart = Schema.Union([
225
257
  ExecuteOutputCapped,
226
258
  CompactionStarted,
227
259
  CompactionEnded,
260
+ EnvironmentUpdated,
228
261
  ])
229
262
 
230
263
  /**
@@ -239,12 +272,51 @@ export class SubagentPart extends Schema.TaggedClass<SubagentPart>()(
239
272
  },
240
273
  ) {}
241
274
 
275
+ /**
276
+ * Emitted when messages are committed to the agent's history: the user
277
+ * prompt, steering messages, and each model step's response and tool
278
+ * results. Applying `HistoryAppended` and `HistoryReplaced` in order to the
279
+ * history the agent started `send` with reproduces `agent.history`, minus
280
+ * the system message, which is rebuilt on every `send`.
281
+ *
282
+ * Only the top-level agent emits history events. Subagents have no history.
283
+ *
284
+ * @since 1.0.0
285
+ * @category Output
286
+ */
287
+ export class HistoryAppended extends Schema.TaggedClass<HistoryAppended>()(
288
+ "HistoryAppended",
289
+ {
290
+ messages: Schema.Array(Prompt.Message),
291
+ },
292
+ ) {}
293
+
294
+ /**
295
+ * Emitted when compaction rewrites the agent's history. `messages` is the
296
+ * whole new history, without the system message.
297
+ *
298
+ * @since 1.0.0
299
+ * @category Output
300
+ */
301
+ export class HistoryReplaced extends Schema.TaggedClass<HistoryReplaced>()(
302
+ "HistoryReplaced",
303
+ {
304
+ messages: Schema.Array(Prompt.Message),
305
+ },
306
+ ) {}
307
+
242
308
  /**
243
309
  * @since 1.0.0
244
310
  * @category Output
245
311
  */
246
312
  export type Output =
247
- AgentStart | ContentPart | SubagentStart | SubagentComplete | SubagentPart
313
+ | AgentStart
314
+ | ContentPart
315
+ | SubagentStart
316
+ | SubagentComplete
317
+ | SubagentPart
318
+ | HistoryAppended
319
+ | HistoryReplaced
248
320
 
249
321
  /**
250
322
  * @since 1.0.0
@@ -256,6 +328,8 @@ export const Output = Schema.Union([
256
328
  SubagentStart,
257
329
  SubagentComplete,
258
330
  SubagentPart,
331
+ HistoryAppended,
332
+ HistoryReplaced,
259
333
  ])
260
334
 
261
335
  /**
@@ -268,3 +342,19 @@ export class AgentFinished extends Schema.TaggedError<AgentFinished>()(
268
342
  summary: Schema.String,
269
343
  },
270
344
  ) {}
345
+
346
+ /**
347
+ * The `send` stream fails with this error when a model call, or a turn that
348
+ * hit `TurnTimeout`, was retried `MaxRetries` times in a row and still failed.
349
+ * `error` is the last failure.
350
+ *
351
+ * @since 1.0.0
352
+ * @category Output
353
+ */
354
+ export class RetriesExhausted extends Schema.TaggedError<RetriesExhausted>()(
355
+ "RetriesExhausted",
356
+ {
357
+ retries: Schema.Number,
358
+ error: AiError.AiError,
359
+ },
360
+ ) {}
@@ -521,8 +521,14 @@ describe("AgentSkills", () => {
521
521
  it("defaults skills when constructing capabilities without the new field", () => {
522
522
  const capabilities = new AgentExecutor.Capabilities({
523
523
  toolsDts: "",
524
- agentsMd: Option.none(),
524
+ environment: new AgentExecutor.ExecutionEnvironment({
525
+ cwd: "/",
526
+ baseline: [],
527
+ seen: [],
528
+ }),
529
+ instructions: Option.none(),
525
530
  supportsSearch: false,
531
+ tools: [],
526
532
  })
527
533
  assert.deepStrictEqual(capabilities.skills, [])
528
534
  })
@@ -834,8 +840,14 @@ const makeExecutor = (skills: ReadonlyArray<AgentSkills.Skill>) =>
834
840
  capabilities: Effect.succeed(
835
841
  new AgentExecutor.Capabilities({
836
842
  toolsDts: "",
837
- agentsMd: Option.none(),
843
+ environment: new AgentExecutor.ExecutionEnvironment({
844
+ cwd: "/",
845
+ baseline: [],
846
+ seen: [],
847
+ }),
848
+ instructions: Option.none(),
838
849
  supportsSearch: false,
850
+ tools: [],
839
851
  skills,
840
852
  }),
841
853
  ),
@@ -56,7 +56,6 @@ export const discover: (options: {
56
56
  never,
57
57
  FileSystem.FileSystem | Path.Path
58
58
  > = Effect.fnUntraced(function* (options) {
59
- const fs = yield* FileSystem.FileSystem
60
59
  const path = yield* Path.Path
61
60
 
62
61
  const roots: Array<{ readonly root: string; readonly source: SkillSource }> =
@@ -84,39 +83,71 @@ export const discover: (options: {
84
83
  }
85
84
 
86
85
  const byName = new Map<string, Skill>()
87
- for (const { root: skillsDir, source } of roots) {
88
- const entries = yield* fs
89
- .readDirectory(skillsDir)
90
- .pipe(Effect.orElseSucceed(() => []))
91
- entries.sort()
92
- for (const entry of entries) {
93
- const files = yield* fs
94
- .readDirectory(path.join(skillsDir, entry))
95
- .pipe(Effect.orElseSucceed((): Array<string> => []))
96
- if (!files.includes("SKILL.md")) continue
97
- const location = path.join(skillsDir, entry, "SKILL.md")
98
- const content = yield* Effect.option(
99
- fs.stat(location).pipe(
100
- Effect.filterOrFail((info) => info.type === "File"),
101
- Effect.andThen(() => fs.readFileString(location)),
102
- ),
103
- )
104
- if (Option.isNone(content)) continue
105
- const frontmatter = parseFrontmatter(content.value)
106
- if (Option.isNone(frontmatter)) continue
107
- const description = singleLine(frontmatter.value.description)
108
- if (description === "") continue
109
- const name = Predicate.isString(frontmatter.value.name)
110
- ? singleLine(frontmatter.value.name) || singleLine(entry)
111
- : singleLine(entry)
112
- if (byName.has(name)) continue
113
- byName.set(name, new Skill({ name, description, location, source }))
86
+ for (const { root, source } of roots) {
87
+ for (const skill of yield* scan(root, source)) {
88
+ if (!byName.has(skill.name)) byName.set(skill.name, skill)
114
89
  }
115
90
  }
116
91
 
117
92
  return Array.from(byName.values())
118
93
  })
119
94
 
95
+ /**
96
+ * Scan only `<directory>/.agents/skills/<dir>/SKILL.md`, as `discover` does
97
+ * for the project.
98
+ *
99
+ * @since 1.0.0
100
+ * @category Discovery
101
+ */
102
+ export const discoverProject: (
103
+ directory: string,
104
+ ) => Effect.Effect<
105
+ ReadonlyArray<Skill>,
106
+ never,
107
+ FileSystem.FileSystem | Path.Path
108
+ > = Effect.fnUntraced(function* (directory) {
109
+ const path = yield* Path.Path
110
+ return yield* scan(path.resolve(directory, ".agents", "skills"), "project")
111
+ })
112
+
113
+ // The skills in one `skills` directory. The first name wins.
114
+ const scan = Effect.fnUntraced(function* (
115
+ skillsDir: string,
116
+ source: SkillSource,
117
+ ) {
118
+ const fs = yield* FileSystem.FileSystem
119
+ const path = yield* Path.Path
120
+ const byName = new Map<string, Skill>()
121
+ const entries = yield* fs
122
+ .readDirectory(skillsDir)
123
+ .pipe(Effect.orElseSucceed(() => []))
124
+ entries.sort()
125
+ for (const entry of entries) {
126
+ const files = yield* fs
127
+ .readDirectory(path.join(skillsDir, entry))
128
+ .pipe(Effect.orElseSucceed((): Array<string> => []))
129
+ if (!files.includes("SKILL.md")) continue
130
+ const location = path.join(skillsDir, entry, "SKILL.md")
131
+ const content = yield* Effect.option(
132
+ fs.stat(location).pipe(
133
+ Effect.filterOrFail((info) => info.type === "File"),
134
+ Effect.andThen(() => fs.readFileString(location)),
135
+ ),
136
+ )
137
+ if (Option.isNone(content)) continue
138
+ const frontmatter = parseFrontmatter(content.value)
139
+ if (Option.isNone(frontmatter)) continue
140
+ const description = singleLine(frontmatter.value.description)
141
+ if (description === "") continue
142
+ const name = Predicate.isString(frontmatter.value.name)
143
+ ? singleLine(frontmatter.value.name) || singleLine(entry)
144
+ : singleLine(entry)
145
+ if (byName.has(name)) continue
146
+ byName.set(name, new Skill({ name, description, location, source }))
147
+ }
148
+ return Array.from(byName.values())
149
+ })
150
+
120
151
  /**
121
152
  * Render the skills prompt section, or `None` for an empty catalog.
122
153
  *
@@ -127,12 +158,7 @@ export const renderCatalog = (
127
158
  skills: ReadonlyArray<Skill>,
128
159
  ): Option.Option<string> => {
129
160
  if (skills.length === 0) return Option.none()
130
- const entries = skills
131
- .map(
132
- (skill) => `- ${skill.name}: ${skill.description}
133
- location: ${renderLocation(skill.location)}`,
134
- )
135
- .join("\n")
161
+ const entries = renderEntries(skills)
136
162
  return Option.some(`# Skills
137
163
 
138
164
  The following skills are available. Each one is a folder with instructions for
@@ -149,6 +175,63 @@ paths when accessing them.
149
175
  ${entries}`)
150
176
  }
151
177
 
178
+ /**
179
+ * One catalog line, plus its location, per skill.
180
+ *
181
+ * @since 1.0.0
182
+ * @category Rendering
183
+ */
184
+ export const renderEntries = (skills: ReadonlyArray<Skill>): string =>
185
+ skills
186
+ .map(
187
+ (skill) => `- ${skill.name}: ${skill.description}
188
+ location: ${renderLocation(skill.location)}`,
189
+ )
190
+ .join("\n")
191
+
192
+ /**
193
+ * A skill supplied by the caller instead of discovered on the executor. Its
194
+ * content stays on the loop side and is read with `readSkill`.
195
+ *
196
+ * @since 1.0.0
197
+ * @category Models
198
+ */
199
+ export class ProvidedSkill extends Schema.Class<ProvidedSkill>("ProvidedSkill")(
200
+ {
201
+ name: Schema.String,
202
+ description: Schema.String,
203
+ content: Schema.String,
204
+ },
205
+ ) {}
206
+
207
+ /**
208
+ * Render the skills prompt section for caller-supplied skills, or `None` for
209
+ * an empty catalog.
210
+ *
211
+ * @since 1.0.0
212
+ * @category Rendering
213
+ */
214
+ export const renderProvidedCatalog = (
215
+ skills: ReadonlyArray<ProvidedSkill>,
216
+ ): Option.Option<string> => {
217
+ if (skills.length === 0) return Option.none()
218
+ const entries = skills
219
+ .map(
220
+ (skill) =>
221
+ `- ${singleLine(skill.name)}: ${singleLine(skill.description)}`,
222
+ )
223
+ .join("\n")
224
+ return Option.some(`# Skills
225
+
226
+ The following skills are available. Each one has instructions for a specific
227
+ kind of task.
228
+
229
+ When a task matches a skill's description, call "readSkill" with its name
230
+ BEFORE proceeding, then follow the instructions it returns.
231
+
232
+ ${entries}`)
233
+ }
234
+
152
235
  const Frontmatter = Schema.Struct({
153
236
  name: Schema.optional(Schema.Unknown),
154
237
  description: Schema.String,