effect-assistant 0.12.0 → 0.13.1
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/Assistant.d.ts +26 -5
- package/dist/Assistant.d.ts.map +1 -1
- package/dist/Assistant.js +7 -1
- package/dist/Assistant.js.map +1 -1
- package/dist/AssistantEngine.d.ts +6 -2
- package/dist/AssistantEngine.d.ts.map +1 -1
- package/dist/AssistantEngine.js +18 -10
- package/dist/AssistantEngine.js.map +1 -1
- package/dist/AssistantLoop.js +1 -1
- package/dist/AssistantTest.js +1 -1
- package/dist/BlockKit.js +1 -1
- package/dist/ChatSignal.d.ts +58 -0
- package/dist/ChatSignal.d.ts.map +1 -0
- package/dist/ChatSignal.js +73 -0
- package/dist/ChatSignal.js.map +1 -0
- package/dist/Compaction.js +1 -1
- package/dist/Memory.js +1 -1
- package/dist/StatusSummary.d.ts +70 -0
- package/dist/StatusSummary.d.ts.map +1 -0
- package/dist/StatusSummary.js +84 -0
- package/dist/StatusSummary.js.map +1 -0
- package/dist/Timeline.d.ts +10 -2
- package/dist/Timeline.d.ts.map +1 -1
- package/dist/Timeline.js +72 -18
- package/dist/Timeline.js.map +1 -1
- package/dist/ToolStatus.d.ts +73 -0
- package/dist/ToolStatus.d.ts.map +1 -0
- package/dist/ToolStatus.js +72 -0
- package/dist/ToolStatus.js.map +1 -0
- package/dist/index.d.ts +4 -1
- package/dist/index.js +4 -1
- package/dist/internal/chat.js +18 -10
- package/dist/internal/chat.js.map +1 -1
- package/dist/internal/events.d.ts +1 -1
- package/dist/internal/events.js +1 -1
- package/dist/internal/history.js +1 -1
- package/dist/internal/live.js +87 -0
- package/dist/internal/live.js.map +1 -0
- package/dist/internal/loop.d.ts +1 -1
- package/dist/internal/loop.d.ts.map +1 -1
- package/dist/internal/loop.js +42 -11
- package/dist/internal/loop.js.map +1 -1
- package/dist/internal/schema.js +1 -1
- package/dist/internal/specialists.js +3 -2
- package/dist/internal/specialists.js.map +1 -1
- package/dist/internal/stream.js +72 -0
- package/dist/internal/stream.js.map +1 -0
- package/dist/internal/summary.js +66 -0
- package/dist/internal/summary.js.map +1 -0
- package/dist/internal/telemetry.js +3 -2
- package/dist/internal/telemetry.js.map +1 -1
- package/dist/internal/toolkit.js +1 -1
- package/dist/internal/tools.js +1 -1
- package/dist/internal/turns.d.ts +3 -1
- package/dist/internal/turns.d.ts.map +1 -1
- package/dist/internal/turns.js +12 -3
- package/dist/internal/turns.js.map +1 -1
- package/dist/internal/writer.d.ts +2 -0
- package/dist/internal/writer.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/Assistant.ts +48 -13
- package/src/AssistantEngine.ts +25 -11
- package/src/ChatSignal.ts +71 -0
- package/src/StatusSummary.ts +126 -0
- package/src/Timeline.ts +82 -20
- package/src/ToolStatus.ts +91 -0
- package/src/index.ts +15 -0
- package/src/internal/chat.ts +40 -21
- package/src/internal/live.ts +133 -0
- package/src/internal/loop.ts +103 -25
- package/src/internal/specialists.ts +3 -0
- package/src/internal/stream.ts +98 -0
- package/src/internal/summary.ts +127 -0
- package/src/internal/telemetry.ts +5 -1
- package/src/internal/turns.ts +20 -1
- 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
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
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((
|
|
890
|
-
|
|
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 ||
|
|
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>(
|
|
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,91 @@
|
|
|
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 a required `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 a required `description` parameter on the tool, and the chat shows what it
|
|
58
|
+
* writes there while the call runs. Required, because models leave optional parameters out; a call
|
|
59
|
+
* without it still runs, with no status. The handler gets its parameters without it. A tool that has a
|
|
60
|
+
* parameter of that name already can't be marked: the loop stops with a defect when it offers one.
|
|
61
|
+
*
|
|
62
|
+
* **Example** (A slow report with a status)
|
|
63
|
+
*
|
|
64
|
+
* ```ts
|
|
65
|
+
* import { ToolStatus } from "effect-assistant"
|
|
66
|
+
* import * as Tool from "effect/ai/Tool"
|
|
67
|
+
* import * as Schema from "effect/Schema"
|
|
68
|
+
*
|
|
69
|
+
* export const CampaignReport = ToolStatus.described(
|
|
70
|
+
* Tool.make("campaign_report", {
|
|
71
|
+
* description: "The spend and results of a past campaign.",
|
|
72
|
+
* parameters: Schema.Struct({ campaignId: Schema.String }),
|
|
73
|
+
* success: Schema.Struct({ spent: Schema.Finite })
|
|
74
|
+
* })
|
|
75
|
+
* )
|
|
76
|
+
* ```
|
|
77
|
+
*
|
|
78
|
+
* @category annotations
|
|
79
|
+
* @since 0.13.0
|
|
80
|
+
*/
|
|
81
|
+
export const described = <Name extends string, Config extends Schemas, R>(
|
|
82
|
+
tool: Tool.Tool<Name, Config, R>
|
|
83
|
+
): Tool.Tool<Name, Config, R> => tool.annotate(Described, true)
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Returns whether a tool's calls show a status.
|
|
87
|
+
*
|
|
88
|
+
* @category guards
|
|
89
|
+
* @since 0.13.0
|
|
90
|
+
*/
|
|
91
|
+
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"
|
package/src/internal/chat.ts
CHANGED
|
@@ -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
|
-
|
|
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 = (
|
|
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
|
-
|
|
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
|
|