effect-assistant 0.12.0 → 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 (76) hide show
  1. package/dist/Assistant.d.ts +26 -5
  2. package/dist/Assistant.d.ts.map +1 -1
  3. package/dist/Assistant.js +7 -1
  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 +1 -1
  17. package/dist/Memory.js +1 -1
  18. package/dist/StatusSummary.d.ts +70 -0
  19. package/dist/StatusSummary.d.ts.map +1 -0
  20. package/dist/StatusSummary.js +84 -0
  21. package/dist/StatusSummary.js.map +1 -0
  22. package/dist/Timeline.d.ts +10 -2
  23. package/dist/Timeline.d.ts.map +1 -1
  24. package/dist/Timeline.js +72 -18
  25. package/dist/Timeline.js.map +1 -1
  26. package/dist/ToolStatus.d.ts +72 -0
  27. package/dist/ToolStatus.d.ts.map +1 -0
  28. package/dist/ToolStatus.js +71 -0
  29. package/dist/ToolStatus.js.map +1 -0
  30. package/dist/index.d.ts +4 -1
  31. package/dist/index.js +4 -1
  32. package/dist/internal/chat.js +18 -10
  33. package/dist/internal/chat.js.map +1 -1
  34. package/dist/internal/events.d.ts +1 -1
  35. package/dist/internal/events.js +1 -1
  36. package/dist/internal/history.js +1 -1
  37. package/dist/internal/live.js +87 -0
  38. package/dist/internal/live.js.map +1 -0
  39. package/dist/internal/loop.d.ts +1 -1
  40. package/dist/internal/loop.d.ts.map +1 -1
  41. package/dist/internal/loop.js +42 -11
  42. package/dist/internal/loop.js.map +1 -1
  43. package/dist/internal/schema.js +1 -1
  44. package/dist/internal/specialists.js +3 -2
  45. package/dist/internal/specialists.js.map +1 -1
  46. package/dist/internal/stream.js +72 -0
  47. package/dist/internal/stream.js.map +1 -0
  48. package/dist/internal/summary.js +65 -0
  49. package/dist/internal/summary.js.map +1 -0
  50. package/dist/internal/telemetry.js +3 -2
  51. package/dist/internal/telemetry.js.map +1 -1
  52. package/dist/internal/toolkit.js +1 -1
  53. package/dist/internal/tools.js +1 -1
  54. package/dist/internal/turns.d.ts +3 -1
  55. package/dist/internal/turns.d.ts.map +1 -1
  56. package/dist/internal/turns.js +12 -3
  57. package/dist/internal/turns.js.map +1 -1
  58. package/dist/internal/writer.d.ts +2 -0
  59. package/dist/internal/writer.d.ts.map +1 -1
  60. package/package.json +1 -1
  61. package/src/Assistant.ts +48 -13
  62. package/src/AssistantEngine.ts +25 -11
  63. package/src/ChatSignal.ts +71 -0
  64. package/src/StatusSummary.ts +126 -0
  65. package/src/Timeline.ts +82 -20
  66. package/src/ToolStatus.ts +90 -0
  67. package/src/index.ts +15 -0
  68. package/src/internal/chat.ts +40 -21
  69. package/src/internal/live.ts +133 -0
  70. package/src/internal/loop.ts +104 -25
  71. package/src/internal/specialists.ts +3 -0
  72. package/src/internal/stream.ts +98 -0
  73. package/src/internal/summary.ts +123 -0
  74. package/src/internal/telemetry.ts +5 -1
  75. package/src/internal/turns.ts +20 -1
  76. package/src/internal/writer.ts +3 -0
@@ -0,0 +1,71 @@
1
+ /**
2
+ * This module provides the signals a chat sends its live subscribers while a turn works: a short
3
+ * status of what the assistant is doing, and whether it is writing a message to the user.
4
+ *
5
+ * Signals are never stored. They reach only the subscribers that are listening when they are sent
6
+ * (`assistant.subscribe(chatId, { live: true })`), between the chat's entries and in order with
7
+ * them. A turn's model never reads them, compaction never sees them, and a client that loads the
8
+ * chat again starts without them. The turn itself shows in the log, from its `TurnStarted` to its
9
+ * `TurnCompleted` or `TurnFailed`.
10
+ *
11
+ * There is no signal that clears a status: the next one replaces it, typing hides it, and the
12
+ * turn's end clears it. Typing stops before the turn ends, also when it fails, so neither
13
+ * outlives its turn.
14
+ *
15
+ * @since 0.13.0
16
+ */
17
+ import * as Schema from "effect/Schema"
18
+
19
+ /**
20
+ * Represents the line the chat shows next to the assistant while a turn works, like "Checking
21
+ * last summer's campaign budget". The latest one shows until the next, until the model starts
22
+ * writing to the user, or until the turn ends.
23
+ *
24
+ * @category schemas
25
+ * @since 0.13.0
26
+ */
27
+ export class Status extends Schema.TaggedClass<Status>()("Status", {
28
+ text: Schema.String
29
+ }) {}
30
+
31
+ /**
32
+ * Represents the model starting to write a message to the user. The status line goes: the user
33
+ * sees the message coming instead.
34
+ *
35
+ * @category schemas
36
+ * @since 0.13.0
37
+ */
38
+ export class TypingStarted extends Schema.TaggedClass<TypingStarted>()("TypingStarted", {}) {}
39
+
40
+ /**
41
+ * Represents the end of the typing: the message is in the chat's log, or the model wrote none.
42
+ *
43
+ * @category schemas
44
+ * @since 0.13.0
45
+ */
46
+ export class TypingStopped extends Schema.TaggedClass<TypingStopped>()("TypingStopped", {}) {}
47
+
48
+ /**
49
+ * Schema for any of a chat's signals.
50
+ *
51
+ * @category schemas
52
+ * @since 0.13.0
53
+ */
54
+ export const ChatSignal = Schema.Union([Status, TypingStarted, TypingStopped])
55
+
56
+ /**
57
+ * Represents any of a chat's signals.
58
+ *
59
+ * @category models
60
+ * @since 0.13.0
61
+ */
62
+ export type ChatSignal = typeof ChatSignal.Type
63
+
64
+ /**
65
+ * Returns whether a value is one of a chat's signals, such as an item of a live subscription that
66
+ * isn't an entry.
67
+ *
68
+ * @category guards
69
+ * @since 0.13.0
70
+ */
71
+ export const isChatSignal: (u: unknown) => u is ChatSignal = Schema.is(ChatSignal)
@@ -0,0 +1,126 @@
1
+ /**
2
+ * This module provides the status a turn shows when nothing else says what it is doing: when the
3
+ * line stays empty for a while, or a call's status still shows after that call ended, a model reads
4
+ * the turn so far and writes a few words about it, like "Comparing last year's budgets".
5
+ *
6
+ * Provide {@link layer} next to the assistant's `toLayer`, with a small, fast model of its own.
7
+ * Without it, a turn shows only the statuses its tool calls write (see `ToolStatus`). The summary
8
+ * is a `ChatSignal.Status` like any other: it is never stored and the turn's model never reads it.
9
+ * It never replaces the status of a described call that still runs, never shows while the model
10
+ * writes to the user, and never after the turn's message unless the model starts new work. A
11
+ * summary that says what the line says already isn't sent.
12
+ *
13
+ * @since 0.13.0
14
+ */
15
+ import * as LanguageModel from "effect/ai/LanguageModel"
16
+ import * as Prompt from "effect/ai/Prompt"
17
+ import * as Context from "effect/Context"
18
+ import * as Duration from "effect/Duration"
19
+ import * as Effect from "effect/Effect"
20
+ import * as Layer from "effect/Layer"
21
+ import * as Option from "effect/Option"
22
+
23
+ /**
24
+ * The instructions the summary's model gets by default.
25
+ *
26
+ * @category constants
27
+ * @since 0.13.0
28
+ */
29
+ export const defaultInstructions =
30
+ 'You write the status line a chat shows while an assistant works for its user. Read what the assistant did so far in this turn and say what it is doing now, in 3 to 5 plain words, in the language the user writes in, like "Comparing last year\'s budgets". No tool names, ids, code, quotes or final period. Answer with the status only.'
31
+
32
+ /**
33
+ * Represents the options accepted by {@link layer}.
34
+ *
35
+ * @category models
36
+ * @since 0.13.0
37
+ */
38
+ export interface Options {
39
+ /** How long the line may stay empty before a summary fills it. Defaults to 2 seconds. */
40
+ readonly after?: Duration.Input | undefined
41
+ /** How long a line may stay unchanged before a summary refreshes it. Defaults to 5 seconds. */
42
+ readonly staleAfter?: Duration.Input | undefined
43
+ /** The summary model's instructions. Defaults to {@link defaultInstructions}. */
44
+ readonly instructions?: string | undefined
45
+ }
46
+
47
+ /**
48
+ * Service that writes a turn's status from what the turn did so far.
49
+ *
50
+ * @category services
51
+ * @since 0.13.0
52
+ */
53
+ export class StatusSummary extends Context.Service<
54
+ StatusSummary,
55
+ {
56
+ readonly after: Duration.Duration
57
+ readonly staleAfter: Duration.Duration
58
+ /**
59
+ * Returns the status for a turn, from its transcript: the user's input and what the assistant
60
+ * did since. `None` when the model wrote nothing usable or its call failed.
61
+ */
62
+ readonly summarize: (transcript: string) => Effect.Effect<Option.Option<string>>
63
+ }
64
+ >()("effect-assistant/StatusSummary") {}
65
+
66
+ const MAX_LENGTH = 60
67
+
68
+ const clean = (text: string): Option.Option<string> => {
69
+ const line = (text.trim().split("\n")[0] ?? "")
70
+ .replace(/^["'“”‘’]+|["'“”‘’]+$/g, "")
71
+ .replace(/[.…]+$/, "")
72
+ .trim()
73
+
74
+ return line === "" || line.length > MAX_LENGTH ? Option.none() : Option.some(line)
75
+ }
76
+
77
+ /**
78
+ * Creates the summary on the model it is given: provide a small, fast one.
79
+ *
80
+ * **Example** (A cheap model for statuses)
81
+ *
82
+ * ```ts
83
+ * import { StatusSummary } from "effect-assistant"
84
+ * import * as Layer from "effect/Layer"
85
+ *
86
+ * declare const MyAssistantLive: Layer.Layer<never>
87
+ * declare const FastModel: Layer.Layer<import("effect/ai/LanguageModel").LanguageModel>
88
+ *
89
+ * export const Live = MyAssistantLive.pipe(
90
+ * Layer.provide(StatusSummary.layer({ after: "2 seconds" }).pipe(Layer.provide(FastModel)))
91
+ * )
92
+ * ```
93
+ *
94
+ * @category layers
95
+ * @since 0.13.0
96
+ */
97
+ export const layer = (options?: Options): Layer.Layer<StatusSummary, never, LanguageModel.LanguageModel> =>
98
+ Layer.effect(
99
+ StatusSummary,
100
+ Effect.gen(function* () {
101
+ const model = yield* LanguageModel.LanguageModel
102
+ const instructions = options?.instructions ?? defaultInstructions
103
+
104
+ const summarize = Effect.fn("StatusSummary.summarize")(function* (transcript: string) {
105
+ const response = yield* model.generateText({
106
+ prompt: Prompt.fromMessages([
107
+ Prompt.systemMessage({ content: instructions }),
108
+ Prompt.userMessage({ content: [Prompt.textPart({ text: transcript })] })
109
+ ])
110
+ })
111
+
112
+ return clean(response.text)
113
+ })
114
+
115
+ return StatusSummary.of({
116
+ after: Duration.fromInputUnsafe(options?.after ?? "2 seconds"),
117
+ staleAfter: Duration.fromInputUnsafe(options?.staleAfter ?? "5 seconds"),
118
+ summarize: (transcript) =>
119
+ summarize(transcript).pipe(
120
+ Effect.catchCause((cause) =>
121
+ Effect.as(Effect.logDebug("assistant status summary failed", cause), Option.none())
122
+ )
123
+ )
124
+ })
125
+ })
126
+ )
package/src/Timeline.ts CHANGED
@@ -29,6 +29,7 @@ import type * as Assistant from "./Assistant.ts"
29
29
  import * as AssistantActivity from "./AssistantActivity.ts"
30
30
  import * as AssistantEvent from "./AssistantEvent.ts"
31
31
  import * as BlockKit from "./BlockKit.ts"
32
+ import * as ChatSignal from "./ChatSignal.ts"
32
33
  import { InputId } from "./InputId.ts"
33
34
  import * as AppEvents from "./internal/events.ts"
34
35
  import * as ToolApproval from "./ToolApproval.ts"
@@ -227,12 +228,19 @@ export type SpecialistWorking = typeof SpecialistWorking.Type
227
228
  * something that arrived. `specialists` lists the specialists that are working. When the chat is
228
229
  * idle, nothing is working, even if a workflow is waiting on a timer or on the user.
229
230
  *
231
+ * On a live subscription (`subscribe(chatId, { live: true })`), `status` is a short line about what
232
+ * the running turn is doing, and `typing` is true while the model writes a message to the user. Both
233
+ * come from the chat's signals (see `ChatSignal`): they go when the turn ends, and a timeline
234
+ * folded from the log alone has neither.
235
+ *
230
236
  * @category schemas
231
237
  * @since 0.1.0
232
238
  */
233
239
  export const Activity = Schema.Struct({
234
240
  working: Schema.Boolean,
235
- specialists: Schema.Array(SpecialistWorking)
241
+ specialists: Schema.Array(SpecialistWorking),
242
+ status: Schema.optional(Schema.String),
243
+ typing: Schema.Boolean
236
244
  })
237
245
 
238
246
  /**
@@ -363,7 +371,7 @@ export const Change: <const Events extends ReadonlyArray<AssistantEvent.AppEvent
363
371
  export const empty: Timeline = {
364
372
  sequence: 0,
365
373
  items: [],
366
- activity: { working: false, specialists: [] },
374
+ activity: { working: false, specialists: [], typing: false },
367
375
  failed: false,
368
376
  deleted: false
369
377
  }
@@ -599,19 +607,45 @@ interface Schemas {
599
607
 
600
608
  interface Folding {
601
609
  readonly step: (entry: AssistantEvent.AnyEntry) => AnyChange | undefined
610
+ readonly signal: (signal: ChatSignal.ChatSignal) => AnyChange | undefined
602
611
  readonly snapshot: AnyChange
603
612
  }
604
613
 
605
- const activityOf = (activity: AssistantActivity.State): Activity => ({
606
- working: activity.turnSince !== undefined || activity.queued,
607
- specialists: [...activity.specialists.values()].map((run) => ({
608
- specialist: run.specialist,
609
- since: run.since
610
- }))
611
- })
614
+ interface LiveState {
615
+ readonly status: string | undefined
616
+ readonly typing: boolean
617
+ }
618
+
619
+ const noLive: LiveState = { status: undefined, typing: false }
620
+
621
+ const applySignal = (live: LiveState, signal: ChatSignal.ChatSignal): LiveState =>
622
+ Match.value(signal).pipe(
623
+ Match.tagsExhaustive({
624
+ Status: ({ text }): LiveState => ({ ...live, status: text }),
625
+ TypingStarted: (): LiveState => ({ status: undefined, typing: true }),
626
+ TypingStopped: (): LiveState => ({ ...live, typing: false })
627
+ })
628
+ )
629
+
630
+ const activityOf = (activity: AssistantActivity.State, live: LiveState): Activity => {
631
+ const { status } = live
632
+
633
+ const shown: Activity = {
634
+ working: activity.turnSince !== undefined || activity.queued,
635
+ specialists: [...activity.specialists.values()].map((run) => ({
636
+ specialist: run.specialist,
637
+ since: run.since
638
+ })),
639
+ typing: live.typing
640
+ }
641
+
642
+ return status === undefined ? shown : { ...shown, status }
643
+ }
612
644
 
613
645
  const sameActivity = (a: Activity, b: Activity) =>
614
646
  a.working === b.working &&
647
+ a.status === b.status &&
648
+ a.typing === b.typing &&
615
649
  a.specialists.length === b.specialists.length &&
616
650
  a.specialists.every((run, i) => {
617
651
  const other = b.specialists[i]
@@ -626,6 +660,7 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
626
660
  let failed = false
627
661
  let deleted = false
628
662
  let activity = AssistantActivity.empty
663
+ let live = noLive
629
664
  let blocks: ReadonlyMap<string, BlockKit.State> = new Map()
630
665
  // The items in order, and the assistant's messages as stored: their blocks change as the chat goes on.
631
666
  const items = new Map<string, AnyItem>()
@@ -765,15 +800,37 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
765
800
  return [item]
766
801
  })
767
802
 
803
+ // A turn's end clears what it showed, also when a signal didn't arrive.
804
+ const settle = (event: { readonly _tag: string }) => {
805
+ if (
806
+ Predicate.isTagged(event, "TurnCompleted") ||
807
+ Predicate.isTagged(event, "TurnFailed") ||
808
+ Predicate.isTagged(event, "ChatDeleted")
809
+ ) {
810
+ live = noLive
811
+ }
812
+ }
813
+
814
+ const signal = (received: ChatSignal.ChatSignal): AnyChange | undefined => {
815
+ const previous = activityOf(activity, live)
816
+
817
+ live = applySignal(live, received)
818
+
819
+ const now = activityOf(activity, live)
820
+
821
+ return sameActivity(previous, now) ? undefined : { sequence, items: [], activity: now, failed, deleted }
822
+ }
823
+
768
824
  const step = (entry: AssistantEvent.AnyEntry): AnyChange | undefined => {
769
- const previous = { activity: activityOf(activity), failed, deleted }
825
+ const previous = { activity: activityOf(activity, live), failed, deleted }
770
826
  const { event } = entry
771
827
 
772
828
  sequence = entry.sequence
773
829
  activity = AssistantActivity.apply(activity, entry)
830
+ settle(event)
774
831
 
775
832
  if (!AssistantEvent.isLibraryEvent(event)) {
776
- const now = activityOf(activity)
833
+ const now = activityOf(activity, live)
777
834
 
778
835
  return Option.match(eventItemOf(entry), {
779
836
  onNone: () =>
@@ -804,7 +861,7 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
804
861
  })
805
862
 
806
863
  const all = [...changed, ...approvalItems(event, decidedBefore)]
807
- const now = activityOf(activity)
864
+ const now = activityOf(activity, live)
808
865
 
809
866
  return all.length === 0 &&
810
867
  failed === previous.failed &&
@@ -816,8 +873,9 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
816
873
 
817
874
  return {
818
875
  step,
876
+ signal,
819
877
  get snapshot() {
820
- return { sequence, items: [...items.values()], activity: activityOf(activity), failed, deleted }
878
+ return { sequence, items: [...items.values()], activity: activityOf(activity, live), failed, deleted }
821
879
  }
822
880
  }
823
881
  }
@@ -871,12 +929,12 @@ export interface ChangesOptions<
871
929
  }
872
930
 
873
931
  function changesWith<E, R, Events, const Show extends Shown<Events> = readonly []>(
874
- entries: Stream.Stream<AssistantEvent.AnyEntry, E, R>,
932
+ entries: Stream.Stream<AssistantEvent.AnyEntry | ChatSignal.ChatSignal, E, R>,
875
933
  definition: Definition<Events>,
876
934
  options?: ChangesOptions<Show>
877
935
  ): Stream.Stream<Change<Show[number]["Type"]>, E, R>
878
936
  function changesWith<E, R>(
879
- entries: Stream.Stream<AssistantEvent.AnyEntry, E, R>,
937
+ entries: Stream.Stream<AssistantEvent.AnyEntry | ChatSignal.ChatSignal, E, R>,
880
938
  _definition: Schemas,
881
939
  options?: ChangesOptions<ReadonlyArray<AssistantEvent.AppEventSchema>>
882
940
  ): Stream.Stream<AnyChange, E, R> {
@@ -886,10 +944,12 @@ function changesWith<E, R>(
886
944
  Stream.mapAccumArray(
887
945
  () => folding(options?.show ?? []),
888
946
  (timeline, chunk) => {
889
- const changed = chunk.flatMap((entry) => {
890
- const change = timeline.step(entry)
947
+ const changed = chunk.flatMap((item) => {
948
+ if (ChatSignal.isChatSignal(item)) return Option.toArray(Option.fromUndefinedOr(timeline.signal(item)))
949
+
950
+ const change = timeline.step(item)
891
951
 
892
- return change === undefined || entry.sequence <= after ? [] : [change]
952
+ return change === undefined || item.sequence <= after ? [] : [change]
893
953
  })
894
954
 
895
955
  const merged = merge(changed)
@@ -951,9 +1011,11 @@ export const changes: {
951
1011
  <Events, const Show extends Shown<Events> = readonly []>(
952
1012
  definition: Definition<Events>,
953
1013
  options?: ChangesOptions<Show>
954
- ): <E, R>(entries: Stream.Stream<AssistantEvent.AnyEntry, E, R>) => Stream.Stream<Change<Show[number]["Type"]>, E, R>
1014
+ ): <E, R>(
1015
+ entries: Stream.Stream<AssistantEvent.AnyEntry | ChatSignal.ChatSignal, E, R>
1016
+ ) => Stream.Stream<Change<Show[number]["Type"]>, E, R>
955
1017
  <E, R, Events, const Show extends Shown<Events> = readonly []>(
956
- entries: Stream.Stream<AssistantEvent.AnyEntry, E, R>,
1018
+ entries: Stream.Stream<AssistantEvent.AnyEntry | ChatSignal.ChatSignal, E, R>,
957
1019
  definition: Definition<Events>,
958
1020
  options?: ChangesOptions<Show>
959
1021
  ): Stream.Stream<Change<Show[number]["Type"]>, E, R>
@@ -0,0 +1,90 @@
1
+ /**
2
+ * This module provides status labels for tool calls: while a call runs, the chat shows the user a
3
+ * short line about what the assistant is doing, like "Checking last summer's campaign budget".
4
+ *
5
+ * Mark the tools that take a while or act on something with {@link described}: workflows, reports
6
+ * from other systems, orders, specialists. The model then sees an optional `description` parameter
7
+ * on them and fills it in the chat's language. When the call starts, the chat sends the
8
+ * description as a `ChatSignal.Status`; it shows until the next status, so it stays after the call
9
+ * ends. The tool's handler never receives the parameter. Quick reads need no label: the chat shows its generic working state for
10
+ * them.
11
+ *
12
+ * @since 0.13.0
13
+ */
14
+ import type * as Tool from "effect/ai/Tool"
15
+ import * as Context from "effect/Context"
16
+ import type * as Schema from "effect/Schema"
17
+
18
+ type Schemas = {
19
+ readonly parameters: Schema.Constraint
20
+ readonly success: Schema.Constraint
21
+ readonly failure: Schema.Constraint
22
+ readonly failureMode: Tool.FailureMode
23
+ }
24
+
25
+ /**
26
+ * The name of the parameter the model fills with a call's status.
27
+ *
28
+ * @category constants
29
+ * @since 0.13.0
30
+ */
31
+ export const parameterName = "description"
32
+
33
+ /**
34
+ * What the model reads about the parameter.
35
+ *
36
+ * @category constants
37
+ * @since 0.13.0
38
+ */
39
+ export const parameterDescription =
40
+ "Shown to the user while this runs: 3 to 8 plain words in the user's language about what you're doing, like \"Checking last summer's campaign budget\". No tool names, ids or code."
41
+
42
+ /**
43
+ * Annotation for whether a tool's calls show a status, set with {@link described}.
44
+ *
45
+ * @category annotations
46
+ * @since 0.13.0
47
+ */
48
+ export const Described = Context.Reference<boolean>("effect-assistant/ToolStatus/Described", {
49
+ defaultValue: () => false
50
+ })
51
+
52
+ /**
53
+ * Marks a tool whose calls show a status while they run.
54
+ *
55
+ * **Details**
56
+ *
57
+ * The model sees an optional `description` parameter on the tool, and the chat shows what it
58
+ * writes there while the call runs. The handler gets its parameters without it. A tool that has a
59
+ * parameter of that name already can't be marked: the loop stops with a defect when it offers one.
60
+ *
61
+ * **Example** (A slow report with a status)
62
+ *
63
+ * ```ts
64
+ * import { ToolStatus } from "effect-assistant"
65
+ * import * as Tool from "effect/ai/Tool"
66
+ * import * as Schema from "effect/Schema"
67
+ *
68
+ * export const CampaignReport = ToolStatus.described(
69
+ * Tool.make("campaign_report", {
70
+ * description: "The spend and results of a past campaign.",
71
+ * parameters: Schema.Struct({ campaignId: Schema.String }),
72
+ * success: Schema.Struct({ spent: Schema.Finite })
73
+ * })
74
+ * )
75
+ * ```
76
+ *
77
+ * @category annotations
78
+ * @since 0.13.0
79
+ */
80
+ export const described = <Name extends string, Config extends Schemas, R>(
81
+ tool: Tool.Tool<Name, Config, R>
82
+ ): Tool.Tool<Name, Config, R> => tool.annotate(Described, true)
83
+
84
+ /**
85
+ * Returns whether a tool's calls show a status.
86
+ *
87
+ * @category guards
88
+ * @since 0.13.0
89
+ */
90
+ export const isDescribed = (tool: Tool.Any): boolean => Context.get(tool.annotations, Described)
package/src/index.ts CHANGED
@@ -59,6 +59,11 @@ export * as ChatId from "./ChatId.ts"
59
59
  */
60
60
  export * as ChatLog from "./ChatLog.ts"
61
61
 
62
+ /**
63
+ * @since 0.13.0
64
+ */
65
+ export * as ChatSignal from "./ChatSignal.ts"
66
+
62
67
  /**
63
68
  * @since 0.1.0
64
69
  */
@@ -104,6 +109,11 @@ export * as Skill from "./Skill.ts"
104
109
  */
105
110
  export * as Specialist from "./Specialist.ts"
106
111
 
112
+ /**
113
+ * @since 0.13.0
114
+ */
115
+ export * as StatusSummary from "./StatusSummary.ts"
116
+
107
117
  /**
108
118
  * @since 0.3.0
109
119
  */
@@ -128,3 +138,8 @@ export * as ToolFailure from "./ToolFailure.ts"
128
138
  * @since 0.5.0
129
139
  */
130
140
  export * as ToolResult from "./ToolResult.ts"
141
+
142
+ /**
143
+ * @since 0.13.0
144
+ */
145
+ export * as ToolStatus from "./ToolStatus.ts"
@@ -15,6 +15,7 @@ import * as SynchronizedRef from "effect/SynchronizedRef"
15
15
  import * as AssistantEvent from "../AssistantEvent.ts"
16
16
  import type { ChatId } from "../ChatId.ts"
17
17
  import { ChatLog } from "../ChatLog.ts"
18
+ import * as ChatSignal from "../ChatSignal.ts"
18
19
  import { CurrentChat } from "../CurrentChat.ts"
19
20
  import * as Chats from "../Chats.ts"
20
21
  import * as SpecialistService from "../Specialist.ts"
@@ -34,7 +35,11 @@ const idOf = (event: { readonly _tag: string }): string | undefined =>
34
35
  ? event.id
35
36
  : undefined
36
37
 
37
- const makeChannelPubSub = Effect.acquireRelease(PubSub.unbounded<AssistantEvent.Entry>(), PubSub.shutdown)
38
+ /** @internal */
39
+ export type Item = AssistantEvent.Entry | ChatSignal.ChatSignal
40
+
41
+ // Entries and signals share it, so a live subscriber gets them in the order they happened.
42
+ const makeChannelPubSub = Effect.acquireRelease(PubSub.unbounded<Item>(), PubSub.shutdown)
38
43
 
39
44
  const makeHolding = Effect.fnUntraced(function* (keepAlive: (enabled: boolean) => Effect.Effect<void>) {
40
45
  const holds = yield* SynchronizedRef.make(0)
@@ -77,17 +82,22 @@ export interface Chat {
77
82
  // For inputs no turn has read, like a report stored during a shutdown.
78
83
  readonly resume: Effect.Effect<void>
79
84
  readonly stream: (after: number) => Stream.Stream<AssistantEvent.Entry>
85
+ // With the signals sent while it streams; a signal sent before isn't sent again.
86
+ readonly live: (after: number) => Stream.Stream<Item>
80
87
  // Stops what works in the chat and ends its subscribers' streams; its log stays.
81
88
  readonly delete: Effect.Effect<void>
82
89
  }
83
90
 
84
- const isChatDeleted = (entry: AssistantEvent.Entry) => Predicate.isTagged(entry.event, "ChatDeleted")
91
+ const isChatDeleted = (item: Item) => !ChatSignal.isChatSignal(item) && Predicate.isTagged(item.event, "ChatDeleted")
92
+
93
+ const isEntry = (item: Item): item is AssistantEvent.Entry => !ChatSignal.isChatSignal(item)
85
94
 
86
95
  const deletedChat = (entries: ReadonlyArray<AssistantEvent.Entry>): Chat => ({
87
96
  submit: () => Effect.void,
88
97
  submitInBackground: () => Effect.void,
89
98
  resume: Effect.void,
90
99
  stream: (after) => Stream.fromIterable(entries.filter((entry) => entry.sequence > after)),
100
+ live: (after) => Stream.fromIterable(entries.filter((entry) => entry.sequence > after)),
91
101
  delete: Effect.void
92
102
  })
93
103
 
@@ -155,7 +165,11 @@ export const make = Effect.fnUntraced(function* (options: {
155
165
  const chat: Writer = {
156
166
  chatId,
157
167
  entries: Ref.get(entries),
158
- append: (events) => Semaphore.withPermit(writes)(write(events))
168
+ append: (events) => Semaphore.withPermit(writes)(write(events)),
169
+ signal: (signal) =>
170
+ Effect.gen(function* () {
171
+ if (!(yield* isDeleted)) yield* PubSub.publish(channel, signal)
172
+ })
159
173
  }
160
174
 
161
175
  const toStored = (event: {
@@ -297,6 +311,27 @@ export const make = Effect.fnUntraced(function* (options: {
297
311
  // A chat the app deleted while it was closed is deleted now, so its subscribers hear it.
298
312
  yield* checkAvailable
299
313
 
314
+ const subscribe = (after: number): Stream.Stream<Item> =>
315
+ Stream.unwrap(
316
+ Effect.gen(function* () {
317
+ // Subscribes before it reads, so nothing appended in between is missed.
318
+ const subscription = yield* PubSub.subscribe(channel)
319
+ const all = yield* chat.entries
320
+ const stored = all.filter((entry) => entry.sequence > after)
321
+ const last = stored.at(-1)?.sequence ?? after
322
+
323
+ // Deleted: what the reader hasn't seen, then the end. Otherwise the stream ends with the `ChatDeleted`.
324
+ if (all.some(isChatDeleted)) return Stream.fromIterable(stored)
325
+
326
+ return Stream.concat(
327
+ Stream.fromIterable<Item>(stored),
328
+ Stream.fromSubscription(subscription).pipe(
329
+ Stream.filter((item) => ChatSignal.isChatSignal(item) || item.sequence > last)
330
+ )
331
+ ).pipe(Stream.takeUntil(isChatDeleted))
332
+ })
333
+ )
334
+
300
335
  const chatApi: Chat = {
301
336
  submit: Effect.fnUntraced(function* (input) {
302
337
  yield* store(input)
@@ -309,24 +344,8 @@ export const make = Effect.fnUntraced(function* (options: {
309
344
  resume: Effect.gen(function* () {
310
345
  if (History.needsTurn(yield* chat.entries)) yield* inBackground(drain)
311
346
  }),
312
- stream: (after) =>
313
- Stream.unwrap(
314
- Effect.gen(function* () {
315
- // Subscribes before it reads, so nothing appended in between is missed.
316
- const subscription = yield* PubSub.subscribe(channel)
317
- const all = yield* chat.entries
318
- const stored = all.filter((entry) => entry.sequence > after)
319
- const last = stored.at(-1)?.sequence ?? after
320
-
321
- // Deleted: what the reader hasn't seen, then the end. Otherwise the stream ends with the `ChatDeleted`.
322
- if (all.some(isChatDeleted)) return Stream.fromIterable(stored)
323
-
324
- return Stream.concat(
325
- Stream.fromIterable(stored),
326
- Stream.fromSubscription(subscription).pipe(Stream.filter((entry) => entry.sequence > last))
327
- ).pipe(Stream.takeUntil(isChatDeleted))
328
- })
329
- ),
347
+ stream: (after) => subscribe(after).pipe(Stream.filter(isEntry)),
348
+ live: subscribe,
330
349
  delete: remove
331
350
  }
332
351