effect-assistant 0.11.1 → 0.13.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 (80) hide show
  1. package/dist/Assistant.d.ts +49 -4
  2. package/dist/Assistant.d.ts.map +1 -1
  3. package/dist/Assistant.js +33 -3
  4. package/dist/Assistant.js.map +1 -1
  5. package/dist/AssistantEngine.d.ts +6 -2
  6. package/dist/AssistantEngine.d.ts.map +1 -1
  7. package/dist/AssistantEngine.js +18 -10
  8. package/dist/AssistantEngine.js.map +1 -1
  9. package/dist/AssistantLoop.js +1 -1
  10. package/dist/AssistantTest.js +1 -1
  11. package/dist/BlockKit.js +1 -1
  12. package/dist/ChatSignal.d.ts +58 -0
  13. package/dist/ChatSignal.d.ts.map +1 -0
  14. package/dist/ChatSignal.js +73 -0
  15. package/dist/ChatSignal.js.map +1 -0
  16. package/dist/Compaction.js +2 -2
  17. package/dist/Memory.js +1 -1
  18. package/dist/Specialist.d.ts.map +1 -1
  19. package/dist/Specialist.js +2 -1
  20. package/dist/Specialist.js.map +1 -1
  21. package/dist/StatusSummary.d.ts +70 -0
  22. package/dist/StatusSummary.d.ts.map +1 -0
  23. package/dist/StatusSummary.js +84 -0
  24. package/dist/StatusSummary.js.map +1 -0
  25. package/dist/Timeline.d.ts +10 -2
  26. package/dist/Timeline.d.ts.map +1 -1
  27. package/dist/Timeline.js +74 -20
  28. package/dist/Timeline.js.map +1 -1
  29. package/dist/ToolStatus.d.ts +72 -0
  30. package/dist/ToolStatus.d.ts.map +1 -0
  31. package/dist/ToolStatus.js +71 -0
  32. package/dist/ToolStatus.js.map +1 -0
  33. package/dist/index.d.ts +4 -1
  34. package/dist/index.js +4 -1
  35. package/dist/internal/chat.js +19 -10
  36. package/dist/internal/chat.js.map +1 -1
  37. package/dist/internal/events.d.ts +1 -1
  38. package/dist/internal/events.js +1 -1
  39. package/dist/internal/history.js +1 -1
  40. package/dist/internal/live.js +87 -0
  41. package/dist/internal/live.js.map +1 -0
  42. package/dist/internal/loop.d.ts +1 -1
  43. package/dist/internal/loop.d.ts.map +1 -1
  44. package/dist/internal/loop.js +44 -13
  45. package/dist/internal/loop.js.map +1 -1
  46. package/dist/internal/schema.js +1 -1
  47. package/dist/internal/specialists.js +4 -3
  48. package/dist/internal/specialists.js.map +1 -1
  49. package/dist/internal/stream.js +72 -0
  50. package/dist/internal/stream.js.map +1 -0
  51. package/dist/internal/summary.js +65 -0
  52. package/dist/internal/summary.js.map +1 -0
  53. package/dist/internal/telemetry.js +16 -5
  54. package/dist/internal/telemetry.js.map +1 -1
  55. package/dist/internal/toolkit.js +1 -1
  56. package/dist/internal/tools.js +1 -1
  57. package/dist/internal/turns.d.ts +5 -0
  58. package/dist/internal/turns.d.ts.map +1 -1
  59. package/dist/internal/turns.js +18 -7
  60. package/dist/internal/turns.js.map +1 -1
  61. package/dist/internal/writer.d.ts +2 -0
  62. package/dist/internal/writer.d.ts.map +1 -1
  63. package/package.json +1 -1
  64. package/src/Assistant.ts +77 -13
  65. package/src/AssistantEngine.ts +25 -11
  66. package/src/ChatSignal.ts +71 -0
  67. package/src/Specialist.ts +5 -1
  68. package/src/StatusSummary.ts +126 -0
  69. package/src/Timeline.ts +82 -20
  70. package/src/ToolStatus.ts +90 -0
  71. package/src/index.ts +15 -0
  72. package/src/internal/chat.ts +41 -21
  73. package/src/internal/live.ts +133 -0
  74. package/src/internal/loop.ts +104 -25
  75. package/src/internal/specialists.ts +6 -0
  76. package/src/internal/stream.ts +98 -0
  77. package/src/internal/summary.ts +123 -0
  78. package/src/internal/telemetry.ts +25 -2
  79. package/src/internal/turns.ts +27 -3
  80. package/src/internal/writer.ts +3 -0
@@ -12,13 +12,17 @@ import * as Effect from "effect/Effect"
12
12
  import * as Option from "effect/Option"
13
13
  import * as Predicate from "effect/Predicate"
14
14
  import * as Schema from "effect/Schema"
15
+ import * as SchemaAST from "effect/SchemaAST"
15
16
  import * as Stream from "effect/Stream"
16
17
  import * as AssistantEvent from "../AssistantEvent.ts"
17
18
  import type * as Instructions from "../Instructions.ts"
19
+ import * as ToolStatus from "../ToolStatus.ts"
18
20
  import * as History from "./history.ts"
21
+ import * as Live from "./live.ts"
22
+ import * as Streamed from "./stream.ts"
19
23
  import * as Telemetry from "./telemetry.ts"
20
24
  import * as Toolkits from "./toolkit.ts"
21
- import { isTurnEnding, isUserMessage } from "./tools.ts"
25
+ import { isTurnEnding, isUserMessage, sendUserMessageName } from "./tools.ts"
22
26
 
23
27
  /** @internal */
24
28
  export type Event =
@@ -87,41 +91,85 @@ export interface StepResult {
87
91
  // every tool's params, `unknown` for a schema of unknown type, though deferred validation encodes none.
88
92
  type RequestTool = Tool.Tool<string, any, any>
89
93
 
94
+ const statusParameter = Schema.String.annotate({ description: ToolStatus.parameterDescription }).pipe(
95
+ Schema.optionalKey
96
+ )
97
+
98
+ // What the model reads of a described tool: its parameters with the status one. Only the request has it; the call
99
+ // runs without it (see `withoutStatus`). A record of no keys (a tool without parameters) becomes an object with it.
100
+ const withStatusParameter = (tool: Tool.Any): Tool.Any => {
101
+ const ast = tool.parametersSchema.ast
102
+
103
+ if (!ToolStatus.isDescribed(tool) || !SchemaAST.isObjects(ast)) return tool
104
+
105
+ if (ast.propertySignatures.some((property) => property.name === ToolStatus.parameterName)) {
106
+ throw new Error(
107
+ `${tool.name} has a parameter named ${ToolStatus.parameterName} already, so it can't show a status: rename it.`
108
+ )
109
+ }
110
+
111
+ const added = Schema.Struct({ [ToolStatus.parameterName]: statusParameter }).ast.propertySignatures
112
+
113
+ return tool.setParameters(
114
+ Schema.make<Schema.Top>(
115
+ new SchemaAST.Objects(
116
+ [...ast.propertySignatures, ...added],
117
+ ast.indexSignatures.filter((index) => !SchemaAST.isNever(index.type)),
118
+ ast.annotations
119
+ )
120
+ )
121
+ )
122
+ }
123
+
90
124
  // The loop runs the calls itself, after storing each as started, so the model call runs none. It also decides which
91
125
  // calls wait for approval: the model call would ask for approvals of its own.
92
126
  const requestToolkit = (definitions: ReadonlyArray<Tool.Any>): Toolkit.WithHandler<Record<string, RequestTool>> => ({
93
127
  tools: Object.fromEntries(
94
- definitions.map((tool) => [
95
- tool.name,
96
- tool.needsApproval === undefined || tool.needsApproval === false ? tool : tool.setNeedsApproval(false)
97
- ])
128
+ definitions.map((tool) => {
129
+ const requested = withStatusParameter(tool)
130
+
131
+ return [
132
+ tool.name,
133
+ requested.needsApproval === undefined || requested.needsApproval === false
134
+ ? requested
135
+ : requested.setNeedsApproval(false)
136
+ ]
137
+ })
98
138
  ),
99
139
  handle: () => Effect.succeed(Stream.empty)
100
140
  })
101
141
 
142
+ // The model starts a message to the user: a `send_user_message` call, or text of its own, which the reply pass turns
143
+ // into one.
144
+ const startsMessage = (part: Response.AnyPart) =>
145
+ part.type === "text-start" || (part.type === "tool-params-start" && part.name === sendUserMessageName)
146
+
102
147
  // Validation is deferred: a call to a tool that isn't in the toolkit (one in the history the turn no longer offers),
103
148
  // or with params that don't fit its schema, would otherwise fail the whole model call. The loop runs it instead, and
104
149
  // the model reads why it failed.
150
+ // Streamed, so the chat can show the user that a message is on its way while the model writes it.
105
151
  const generate = (
106
152
  prompt: Prompt.Prompt,
107
153
  definitions: ReadonlyArray<Tool.Any>,
108
154
  toolChoice: LanguageModel.ToolChoice<string> | undefined
109
- ): Effect.Effect<
110
- LanguageModel.GenerateTextResponse<Record<string, RequestTool>, "deferred">,
111
- AiError.AiError,
112
- LanguageModel.LanguageModel
113
- > =>
114
- LanguageModel.generateText({
115
- prompt,
116
- toolkit: requestToolkit(definitions),
117
- toolChoice,
118
- disableToolCallResolution: true,
119
- toolCallValidation: "deferred"
120
- })
155
+ ): Effect.Effect<ReadonlyArray<Response.AnyPart>, AiError.AiError, LanguageModel.LanguageModel> =>
156
+ Stream.suspend(() =>
157
+ LanguageModel.streamText({
158
+ prompt,
159
+ toolkit: requestToolkit(definitions),
160
+ toolChoice,
161
+ disableToolCallResolution: true,
162
+ toolCallValidation: "deferred"
163
+ })
164
+ ).pipe(
165
+ Stream.tap((part) => (startsMessage(part) ? Live.use((live) => live.typing(true)) : Effect.void)),
166
+ Stream.runCollect,
167
+ Effect.map(Streamed.collect)
168
+ )
121
169
 
122
170
  const decodePart = Schema.decodeUnknownOption(AssistantEvent.ModelPart)
123
171
 
124
- const modelParts = (content: ReadonlyArray<Response.AllParts<Record<string, Tool.Any>>>) =>
172
+ const modelParts = (content: ReadonlyArray<Response.AnyPart>) =>
125
173
  content.flatMap((part) =>
126
174
  Option.toArray(decodePart(part)).filter((decoded) => !(decoded.type === "tool-call" && decoded.providerExecuted))
127
175
  )
@@ -129,14 +177,43 @@ const modelParts = (content: ReadonlyArray<Response.AllParts<Record<string, Tool
129
177
  const toolCalls = (parts: ReadonlyArray<AssistantEvent.ModelPart>): ReadonlyArray<AssistantEvent.ToolCallPart> =>
130
178
  parts.flatMap((part) => (part.type === "tool-call" ? [part] : []))
131
179
 
180
+ const decodeParams = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Json))
181
+
182
+ const isDescribedCall = <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) =>
183
+ tools.definitions.some((tool) => tool.name === call.name && ToolStatus.isDescribed(tool))
184
+
185
+ // The status the model wrote for a described tool's call, and the call as the tool's handler gets it.
186
+ const splitStatus = (call: AssistantEvent.ToolCallPart): readonly [string | undefined, AssistantEvent.ToolCallPart] => {
187
+ const params = decodeParams(call.params)
188
+
189
+ if (Option.isNone(params) || !Object.hasOwn(params.value, ToolStatus.parameterName)) return [undefined, call]
190
+
191
+ const { [ToolStatus.parameterName]: written, ...rest } = params.value
192
+ const status = Predicate.isString(written) ? written.trim() : ""
193
+
194
+ return [status === "" ? undefined : status, { ...call, params: rest }]
195
+ }
196
+
197
+ // A call's status shows when it starts; a message's typing stops once the message is stored.
132
198
  const runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) {
199
+ const [status, run] = isDescribedCall(tools, call) ? splitStatus(call) : [undefined, call]
200
+
133
201
  const result = yield* Effect.gen(function* () {
134
- const result = yield* tools.run(call)
202
+ if (status !== undefined) yield* Live.use((live) => live.callStarted(call.id, status))
203
+
204
+ const result = yield* tools.run(run)
135
205
 
136
206
  yield* Telemetry.toolOutput(result.result)
137
207
 
138
208
  return result
139
- }).pipe(Telemetry.toolSpan(call))
209
+ }).pipe(
210
+ Telemetry.toolSpan(call),
211
+ Effect.ensuring(
212
+ Live.use((live) =>
213
+ Effect.andThen(live.callEnded(call.id), call.name === sendUserMessageName ? live.typing(false) : Effect.void)
214
+ )
215
+ )
216
+ )
140
217
 
141
218
  return AssistantEvent.ToolResult.make({ callId: call.id, tool: call.name, ...result })
142
219
  })
@@ -204,6 +281,7 @@ const runCalls = <R, S, E, R2>(
204
281
  Effect.gen(function* () {
205
282
  const explained = pending.some(({ call }) => isUserMessage(call))
206
283
 
284
+ // Text that became no message, or a message that failed, stops the typing too.
207
285
  const done = yield* Effect.forEach(
208
286
  pending,
209
287
  ({ call }, i): Effect.Effect<Event, never, R> =>
@@ -213,7 +291,7 @@ const runCalls = <R, S, E, R2>(
213
291
  ? awaitApproval(call)
214
292
  : Effect.succeed(unexplained(call)),
215
293
  { concurrency: "unbounded" }
216
- )
294
+ ).pipe(Effect.ensuring(Live.use((live) => live.typing(false))))
217
295
 
218
296
  return Stream.fromIterable(done.map(value)).pipe(
219
297
  Stream.concat(
@@ -322,18 +400,19 @@ export const step = <R, S, E2 = never, R2 = never>(
322
400
  const name = yield* Effect.serviceOption(Model.ModelName)
323
401
  const started = yield* Clock.currentTimeMillis
324
402
 
325
- const response = yield* generate(prompt, toolkit.definitions, options.toolChoice).pipe(
403
+ const content = yield* generate(prompt, toolkit.definitions, options.toolChoice).pipe(
326
404
  Telemetry.annotateModelCall(instructions.attributes)
327
405
  )
328
406
 
329
- const metadata = response.content.find((part) => part.type === "response-metadata")
407
+ const metadata = content.find((part) => part.type === "response-metadata")
408
+ const finish = content.find((part) => part.type === "finish")
330
409
 
331
410
  const output = AssistantEvent.ModelOutput.make({
332
- parts: modelParts(response.content),
411
+ parts: modelParts(content),
333
412
  seenThroughSequence: throughSequence,
334
413
  model: metadata?.modelId ?? Option.getOrUndefined(name),
335
414
  responseId: metadata?.id,
336
- usage: response.usage,
415
+ usage: finish?.usage,
337
416
  durationMillis: (yield* Clock.currentTimeMillis) - started
338
417
  })
339
418
 
@@ -16,6 +16,7 @@ import * as Ref from "effect/Ref"
16
16
  import * as Schema from "effect/Schema"
17
17
  import * as Semaphore from "effect/Semaphore"
18
18
  import * as Stream from "effect/Stream"
19
+ import type * as Tracer from "effect/Tracer"
19
20
  import * as AssistantEvent from "../AssistantEvent.ts"
20
21
  import type * as AssistantLoop from "../AssistantLoop.ts"
21
22
  import * as Loop from "./loop.ts"
@@ -25,6 +26,7 @@ import * as RunId from "../RunId.ts"
25
26
  import * as Specialist from "../Specialist.ts"
26
27
  import * as ToolFailure from "../ToolFailure.ts"
27
28
  import { toolMessage, userText } from "./history.ts"
29
+ import * as Live from "./live.ts"
28
30
  import * as Telemetry from "./telemetry.ts"
29
31
  import * as Toolkits from "./toolkit.ts"
30
32
  import type { Writer } from "./writer.ts"
@@ -237,6 +239,7 @@ export const makeRunner = Effect.fnUntraced(function* (options: {
237
239
  readonly handler: RunHandler
238
240
  }>
239
241
  readonly model: Context.Context<LanguageModel.LanguageModel>
242
+ readonly tracer: Option.Option<Tracer.Tracer>
240
243
  // An interruption keeps the hold.
241
244
  readonly holding: (effect: Effect.Effect<void>) => Effect.Effect<void>
242
245
  readonly report: (finished: AssistantEvent.SpecialistFinished) => Effect.Effect<void>
@@ -264,9 +267,12 @@ export const makeRunner = Effect.fnUntraced(function* (options: {
264
267
  inbox: run.inbox,
265
268
  chatId: chat.chatId
266
269
  }).pipe(
270
+ Telemetry.onTracer(options.tracer),
267
271
  Effect.provideContext(Context.merge(options.model, services)),
268
272
  // Spawned from a turn, a run would inherit the turn's own tools: a run can't message the user.
269
273
  Effect.provideService(Loop.TurnTools, Option.none()),
274
+ // Nor show the user a status or typing: its turn may have ended.
275
+ Effect.provideService(Live.TurnLive, Option.none()),
270
276
  Effect.matchCause({
271
277
  onSuccess: (answer): Outcome => ({ status: "answered", report: answer }),
272
278
  onFailure: unanswered
@@ -0,0 +1,98 @@
1
+ import * as Response from "effect/ai/Response"
2
+ import * as Predicate from "effect/Predicate"
3
+
4
+ type Metadata = Response.ProviderMetadata
5
+
6
+ // Per provider, the later part's keys win.
7
+ const mergeMetadata = (left: Metadata, right: Metadata): Metadata => ({
8
+ ...left,
9
+ ...Object.fromEntries(
10
+ Object.entries(right).map(([provider, metadata]) => {
11
+ const previous = left[provider]
12
+
13
+ return [
14
+ provider,
15
+ Predicate.isObject(previous) && Predicate.isObject(metadata) ? Object.assign({}, previous, metadata) : metadata
16
+ ]
17
+ })
18
+ )
19
+ })
20
+
21
+ interface Open {
22
+ readonly index: number
23
+ text: string
24
+ metadata: Metadata
25
+ }
26
+
27
+ // A streamed call's parts as the call would have returned them whole: each text and reasoning block joined into one
28
+ // part, with its provider metadata (a reasoning block's signature arrives on one of its deltas). Partial text is kept;
29
+ // reasoning that never ended is dropped, as a provider would refuse it back without its signature.
30
+ /** @internal */
31
+ export const collect = (parts: ReadonlyArray<Response.AnyPart>): ReadonlyArray<Response.AnyPart> => {
32
+ const collected: Array<Response.AnyPart | undefined> = []
33
+ const texts = new Map<string, Open>()
34
+ const reasonings = new Map<string, Open>()
35
+
36
+ const start = (open: Map<string, Open>, id: string, metadata: Metadata) => {
37
+ open.set(id, { index: collected.length, text: "", metadata })
38
+ collected.push(undefined)
39
+ }
40
+
41
+ const delta = (open: Map<string, Open>, id: string, text: string, metadata: Metadata) => {
42
+ const active = open.get(id)
43
+
44
+ if (active === undefined) return
45
+
46
+ active.text += text
47
+ active.metadata = mergeMetadata(active.metadata, metadata)
48
+ }
49
+
50
+ const end = (open: Map<string, Open>, id: string, metadata: Metadata, type: "text" | "reasoning") => {
51
+ const active = open.get(id)
52
+
53
+ if (active === undefined) return
54
+
55
+ open.delete(id)
56
+ collected[active.index] = Response.makePart(type, {
57
+ text: active.text,
58
+ metadata: mergeMetadata(active.metadata, metadata)
59
+ })
60
+ }
61
+
62
+ for (const part of parts) {
63
+ switch (part.type) {
64
+ case "text-start":
65
+ start(texts, part.id, part.metadata)
66
+ break
67
+ case "text-delta":
68
+ delta(texts, part.id, part.delta, part.metadata)
69
+ break
70
+ case "text-end":
71
+ end(texts, part.id, part.metadata, "text")
72
+ break
73
+ case "reasoning-start":
74
+ start(reasonings, part.id, part.metadata)
75
+ break
76
+ case "reasoning-delta":
77
+ delta(reasonings, part.id, part.delta, part.metadata)
78
+ break
79
+ case "reasoning-end":
80
+ end(reasonings, part.id, part.metadata, "reasoning")
81
+ break
82
+ case "tool-params-start":
83
+ case "tool-params-delta":
84
+ case "tool-params-end":
85
+ break
86
+ default:
87
+ collected.push(part)
88
+ }
89
+ }
90
+
91
+ for (const active of texts.values()) {
92
+ if (active.text.length > 0) {
93
+ collected[active.index] = Response.makePart("text", { text: active.text, metadata: active.metadata })
94
+ }
95
+ }
96
+
97
+ return collected.filter(Predicate.isNotUndefined)
98
+ }
@@ -0,0 +1,123 @@
1
+ import type * as Prompt from "effect/ai/Prompt"
2
+ import * as Clock from "effect/Clock"
3
+ import * as Duration from "effect/Duration"
4
+ import * as Effect from "effect/Effect"
5
+ import * as Option from "effect/Option"
6
+ import * as Predicate from "effect/Predicate"
7
+ import * as Ref from "effect/Ref"
8
+ import * as Schedule from "effect/Schedule"
9
+ import * as AssistantEvent from "../AssistantEvent.ts"
10
+ import type * as StatusSummary from "../StatusSummary.ts"
11
+ import * as History from "./history.ts"
12
+ import * as Live from "./live.ts"
13
+ import { toJsonText } from "./schema.ts"
14
+ import type { Writer } from "./writer.ts"
15
+
16
+ const MAX_LINE = 300
17
+
18
+ const MAX_MESSAGES = 12
19
+
20
+ const clip = (text: string) => (text.length > MAX_LINE ? `${text.slice(0, MAX_LINE)}…` : text)
21
+
22
+ const assistantLines = (part: Prompt.AssistantMessagePart): ReadonlyArray<string> => {
23
+ switch (part.type) {
24
+ case "text":
25
+ return [`Assistant: ${clip(part.text)}`]
26
+ case "tool-call":
27
+ return [`Assistant runs ${part.name} ${clip(toJsonText(part.params))}`]
28
+ default:
29
+ return []
30
+ }
31
+ }
32
+
33
+ const lines = (message: Prompt.Message): ReadonlyArray<string> => {
34
+ switch (message.role) {
35
+ case "system":
36
+ return []
37
+ case "user":
38
+ return message.content.flatMap((part) => (part.type === "text" ? [`User: ${clip(part.text)}`] : []))
39
+ case "assistant":
40
+ return message.content.flatMap(assistantLines)
41
+ case "tool":
42
+ return message.content.flatMap((part) =>
43
+ part.type === "tool-result"
44
+ ? [`Result of ${part.name}: ${clip(Predicate.isString(part.result) ? part.result : toJsonText(part.result))}`]
45
+ : []
46
+ )
47
+ }
48
+ }
49
+
50
+ // The calls started and not answered yet: what the assistant is doing right now.
51
+ const runningCalls = (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => {
52
+ const events = entries.flatMap(({ event }) => (AssistantEvent.isLibraryEvent(event) ? [event] : []))
53
+ const answered = new Set(events.flatMap((event) => (Predicate.isTagged(event, "ToolResult") ? [event.callId] : [])))
54
+
55
+ return events.flatMap((event) =>
56
+ Predicate.isTagged(event, "ToolStarted") && !answered.has(event.callId) ? [event.tool] : []
57
+ )
58
+ }
59
+
60
+ // The latest messages, as plain lines, and what still runs: the summary's model gets no tools, so no tool call parts.
61
+ /** @internal */
62
+ export const transcript = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): string => {
63
+ const running = runningCalls(entries)
64
+ const lastLines = History.fromEntries(entries).slice(-MAX_MESSAGES).flatMap(lines)
65
+
66
+ return [...lastLines, ...(running.length === 0 ? [] : [`Running now: ${running.join(", ")}`])].join("\n")
67
+ }
68
+
69
+ const lastSequence = (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => entries.at(-1)?.sequence ?? 0
70
+
71
+ const isWork = (event: { readonly _tag: string }) =>
72
+ Predicate.isTagged(event, "TurnStarted") ||
73
+ Predicate.isTagged(event, "ModelOutput") ||
74
+ Predicate.isTagged(event, "ToolStarted")
75
+
76
+ // After a message the user is up to date: a summary shows again only for work the model started since, not for what a
77
+ // handler does after its reply (a compaction, say).
78
+ const workingSinceMessage = (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => {
79
+ const message = entries.findLastIndex(({ event }) => Predicate.isTagged(event, "AssistantMessage"))
80
+
81
+ return message === -1 || entries.slice(message + 1).some(({ event }) => isWork(event))
82
+ }
83
+
84
+ const MAX_CHECK_MILLIS = 500
85
+
86
+ // A line for a turn that shows nothing for a while, or whose line hasn't changed for longer: never while a described
87
+ // call says what runs, or the model writes to the user, and only after something new happened.
88
+ /** @internal */
89
+ export const run = Effect.fnUntraced(function* (
90
+ summary: StatusSummary.StatusSummary["Service"],
91
+ live: Live.Live,
92
+ chat: Writer
93
+ ) {
94
+ const summarized = yield* Ref.make(-1)
95
+ const after = Duration.toMillis(summary.after)
96
+ const staleAfter = Duration.toMillis(summary.staleAfter)
97
+
98
+ const tick = Effect.gen(function* () {
99
+ const current = yield* live.state
100
+ const entries = yield* chat.entries
101
+ const through = lastSequence(entries)
102
+ const waited = (yield* Clock.currentTimeMillis) - current.shownAt
103
+
104
+ if (
105
+ current.typing ||
106
+ current.running.length > 0 ||
107
+ waited < (current.shown === undefined ? after : staleAfter) ||
108
+ through === (yield* Ref.get(summarized)) ||
109
+ !workingSinceMessage(entries)
110
+ ) {
111
+ return
112
+ }
113
+
114
+ const written = yield* summary.summarize(transcript(entries))
115
+
116
+ yield* Ref.set(summarized, through)
117
+
118
+ if (Option.isSome(written)) yield* live.summarized(written.value)
119
+ })
120
+
121
+ // Often enough that a line is filled or refreshed close to when it's due.
122
+ yield* tick.pipe(Effect.repeat(Schedule.spaced(Math.min(MAX_CHECK_MILLIS, after / 2, staleAfter / 2))))
123
+ })
@@ -1,6 +1,7 @@
1
1
  import * as Model from "effect/ai/Model"
2
2
  import * as Prompt from "effect/ai/Prompt"
3
3
  import * as Telemetry from "effect/ai/Telemetry"
4
+ import * as Context from "effect/Context"
4
5
  import * as Effect from "effect/Effect"
5
6
  import * as Option from "effect/Option"
6
7
  import * as References from "effect/References"
@@ -9,6 +10,7 @@ import * as Tracer from "effect/Tracer"
9
10
  import * as AssistantEvent from "../AssistantEvent.ts"
10
11
  import type { SpanAttributes } from "../Instructions.ts"
11
12
  import { toJsonText } from "./schema.ts"
13
+ import { collect } from "./stream.ts"
12
14
 
13
15
  type Traced = string | ReadonlyArray<{ readonly _tag: string }>
14
16
 
@@ -27,6 +29,21 @@ export const agentSpan = (name: string, options: { readonly chatId: string; read
27
29
  }
28
30
  })
29
31
 
32
+ /** @internal */
33
+ export const TurnTracer = Context.Reference<Option.Option<Tracer.Tracer>>("effect-assistant/Assistant/TurnTracer", {
34
+ defaultValue: Option.none
35
+ })
36
+
37
+ // A layer's context carries the tracer and span it was built with: a turn's own must not be replaced by them.
38
+ /** @internal */
39
+ export const withoutTracing = Context.omit(Tracer.ParentSpan, Tracer.Tracer)
40
+
41
+ /** @internal */
42
+ export const onTracer =
43
+ (tracer: Option.Option<Tracer.Tracer>) =>
44
+ <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
45
+ Option.match(tracer, { onNone: () => self, onSome: (tracer) => self.pipe(Effect.withTracer(tracer)) })
46
+
30
47
  // None when tracing is off, or when the tracer is Effect's own, which exports nothing.
31
48
  /** @internal */
32
49
  export const currentTraceId: Effect.Effect<Option.Option<string>> = Effect.gen(function* () {
@@ -49,15 +66,21 @@ const encodeParts = Schema.encodeOption(Schema.Array(AssistantEvent.ModelPart))
49
66
 
50
67
  type ModelCall = Parameters<Telemetry.SpanTransformer>[0]
51
68
 
69
+ // A streamed call's response is its stream's parts: joined first, as the log stores them.
52
70
  const completionOf = (response: ModelCall["response"]) =>
53
- encodeParts(response.flatMap((part) => Option.toArray(Schema.decodeUnknownOption(AssistantEvent.ModelPart)(part))))
71
+ encodeParts(
72
+ collect(response).flatMap((part) => Option.toArray(Schema.decodeUnknownOption(AssistantEvent.ModelPart)(part)))
73
+ )
54
74
 
55
75
  const annotateModelSpan = (
56
76
  { span, prompt, response }: ModelCall,
57
77
  name: Option.Option<string>,
58
78
  attributes: SpanAttributes | undefined
59
79
  ) => {
60
- span.attribute("gen_ai.prompt", toJsonText(Option.map(encodePrompt(prompt), (encoded) => encoded.content)))
80
+ span.attribute(
81
+ "gen_ai.prompt",
82
+ toJsonText(Option.getOrUndefined(Option.map(encodePrompt(prompt), (encoded) => encoded.content)))
83
+ )
61
84
  span.attribute("gen_ai.completion", toJsonText(Option.getOrUndefined(completionOf(response))))
62
85
 
63
86
  for (const [key, value] of Object.entries(attributes ?? {})) {
@@ -12,6 +12,7 @@ import * as Predicate from "effect/Predicate"
12
12
  import * as Ref from "effect/Ref"
13
13
  import * as Schema from "effect/Schema"
14
14
  import type * as Scope from "effect/Scope"
15
+ import type * as Tracer from "effect/Tracer"
15
16
  import * as Stream from "effect/Stream"
16
17
  import type * as Assistant from "../Assistant.ts"
17
18
  import type { ChatId } from "../ChatId.ts"
@@ -21,13 +22,16 @@ import * as Loop from "./loop.ts"
21
22
  import * as BlockKit from "../BlockKit.ts"
22
23
  import type { CurrentChat } from "../CurrentChat.ts"
23
24
  import * as Instructions from "../Instructions.ts"
25
+ import { StatusSummary } from "../StatusSummary.ts"
24
26
  import * as ToolApproval from "../ToolApproval.ts"
25
27
  import type * as Specialist from "../Specialist.ts"
26
28
  import * as AppEvents from "./events.ts"
27
29
  import * as History from "./history.ts"
28
30
  import { mapText } from "./instructions.ts"
31
+ import * as Live from "./live.ts"
29
32
  import { toJsonText } from "./schema.ts"
30
33
  import * as Specialists from "./specialists.ts"
34
+ import * as Summary from "./summary.ts"
31
35
  import * as Telemetry from "./telemetry.ts"
32
36
  import * as Toolkits from "./toolkit.ts"
33
37
  import type { Writer } from "./writer.ts"
@@ -71,12 +75,15 @@ export interface TypedChat {
71
75
  export interface Registration {
72
76
  readonly definition: Definition
73
77
  readonly model: Context.Context<LanguageModel.LanguageModel>
78
+ readonly tracer: Option.Option<Tracer.Tracer>
74
79
  readonly open: (chat: TypedChat) => Effect.Effect<TurnHandler, never, Scope.Scope | CurrentChat>
75
80
  readonly specialists: ReadonlyArray<{
76
81
  readonly specialist: Specialist.Any
77
82
  readonly built: Specialist.Built
78
83
  }>
79
84
  readonly builtins: Toolkits.Tools<Assistant.TurnServices>
85
+ // Writes a status for a turn that has been working a while with nothing to show.
86
+ readonly summary: Option.Option<StatusSummary["Service"]>
80
87
  }
81
88
 
82
89
  /** @internal */
@@ -84,7 +91,8 @@ export const register = Effect.fnUntraced(function* (
84
91
  definition: Definition,
85
92
  options: { readonly open: Registration["open"] }
86
93
  ) {
87
- const model = yield* Effect.context<LanguageModel.LanguageModel>()
94
+ const model = yield* Effect.context<LanguageModel.LanguageModel>().pipe(Effect.map(Telemetry.withoutTracing))
95
+ const tracer = yield* Telemetry.TurnTracer
88
96
 
89
97
  const specialists = yield* Effect.forEach(
90
98
  definition.specialists,
@@ -109,9 +117,11 @@ export const register = Effect.fnUntraced(function* (
109
117
  const registration: Registration = {
110
118
  definition,
111
119
  model,
120
+ tracer,
112
121
  open: options.open,
113
122
  specialists,
114
- builtins
123
+ builtins,
124
+ summary: yield* Effect.serviceOption(StatusSummary)
115
125
  }
116
126
 
117
127
  return registration
@@ -370,10 +380,20 @@ export const run = Effect.fnUntraced(
370
380
  const turn = makeTurnApi(options.registration, chat, startSequence, options.checkOpen, ranLoop)
371
381
 
372
382
  const record = (event: AssistantLoop.Event) => chat.append([event])
383
+ const live = yield* Live.make(chat.signal)
384
+
385
+ // The summary runs beside the turn's work and stops with it.
386
+ const summarizing = <A, E, R>(work: Effect.Effect<A, E, R>) =>
387
+ Option.match(options.registration.summary, {
388
+ onNone: () => work,
389
+ onSome: (summary) =>
390
+ Effect.forkScoped(Summary.run(summary, live, chat)).pipe(Effect.andThen(work), Effect.scoped)
391
+ })
373
392
 
374
393
  yield* options.handler(turn).pipe(
375
394
  Stream.runForEach(record),
376
395
  Effect.onExit((exit) => (Exit.hasInterrupts(exit) ? Effect.void : closeOpenCalls(chat, startSequence))),
396
+ Effect.provideService(Live.TurnLive, Option.some(live)),
377
397
  // A loop the app writes gets the assistant's own tools too, with this turn's services.
378
398
  Effect.provideService(
379
399
  Loop.TurnTools,
@@ -382,6 +402,9 @@ export const run = Effect.fnUntraced(
382
402
  // A turn's loop waits for the user's approval, and runs the calls they approved.
383
403
  Effect.provideService(Loop.TurnApprovals, Option.some({ approved: Effect.map(chat.entries, approvedCalls) })),
384
404
  Effect.provideContext(options.services),
405
+ summarizing,
406
+ // Nothing the turn showed outlives it, also when it fails.
407
+ Effect.ensuring(live.reset),
385
408
  Effect.matchCauseEffect({
386
409
  onSuccess: Effect.fnUntraced(function* () {
387
410
  const all = yield* chat.entries
@@ -407,6 +430,7 @@ export const run = Effect.fnUntraced(
407
430
  Telemetry.agentSpan(options.registration.definition.name, {
408
431
  chatId: options.chat.chatId,
409
432
  root: true
410
- })
433
+ }),
434
+ Telemetry.onTracer(options.registration.tracer)
411
435
  )
412
436
  )
@@ -1,6 +1,7 @@
1
1
  import type * as Effect from "effect/Effect"
2
2
  import type * as AssistantEvent from "../AssistantEvent.ts"
3
3
  import type { ChatId } from "../ChatId.ts"
4
+ import type { ChatSignal } from "../ChatSignal.ts"
4
5
 
5
6
  /** @internal */
6
7
  export interface Writer {
@@ -9,4 +10,6 @@ export interface Writer {
9
10
  readonly append: (
10
11
  events: ReadonlyArray<AssistantEvent.AssistantEvent | AssistantEvent.StoredAppEvent>
11
12
  ) => Effect.Effect<ReadonlyArray<AssistantEvent.Entry>>
13
+ // Sent to the live subscribers only, never stored.
14
+ readonly signal: (signal: ChatSignal) => Effect.Effect<void>
12
15
  }