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
@@ -1 +1 @@
1
- {"version":3,"file":"turns.js","names":["Toolkits.merge","Tools.makeMessaging","Specialists.toolkit","ToolApproval.fromEntries","History.unansweredCalls","History.fromEntries","History.mayHaveRunOutput","History.notRunOutput","AssistantEvent.isLibraryEvent","History.owesReply","History.unreadAfter","BlockKit.toolNames","AppEvents.decodeEntries","Instructions.protocol","History.owesDelivery","Loop.run","Toolkits.runOnly","Tools.sendUserMessageName","Tools.waitToolName","History.userText","Loop.TurnApprovals","Toolkits.showing","Toolkits.fromToolkitOrEmpty","Toolkits.duplicateNames","Telemetry.agentInput","History.unhandledInputs","Telemetry.currentTraceId","Loop.TurnTools","Toolkits.provide","Telemetry.agentOutput","Telemetry.agentSpan"],"sources":["../../src/internal/turns.ts"],"sourcesContent":["import type * as LanguageModel from \"effect/ai/LanguageModel\"\nimport * as Response from \"effect/ai/Response\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport * as Cause from \"effect/Cause\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as ErrorReporter from \"effect/ErrorReporter\"\nimport * as Exit from \"effect/Exit\"\nimport { identity } from \"effect/Function\"\nimport * as Option from \"effect/Option\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as Ref from \"effect/Ref\"\nimport * as Schema from \"effect/Schema\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Stream from \"effect/Stream\"\nimport type * as Assistant from \"../Assistant.ts\"\nimport type { ChatId } from \"../ChatId.ts\"\nimport * as AssistantEvent from \"../AssistantEvent.ts\"\nimport type * as AssistantLoop from \"../AssistantLoop.ts\"\nimport * as Loop from \"./loop.ts\"\nimport * as BlockKit from \"../BlockKit.ts\"\nimport type { CurrentChat } from \"../CurrentChat.ts\"\nimport * as Instructions from \"../Instructions.ts\"\nimport * as ToolApproval from \"../ToolApproval.ts\"\nimport type * as Specialist from \"../Specialist.ts\"\nimport * as AppEvents from \"./events.ts\"\nimport * as History from \"./history.ts\"\nimport { mapText } from \"./instructions.ts\"\nimport { toJsonText } from \"./schema.ts\"\nimport * as Specialists from \"./specialists.ts\"\nimport * as Telemetry from \"./telemetry.ts\"\nimport * as Toolkits from \"./toolkit.ts\"\nimport type { Writer } from \"./writer.ts\"\nimport * as Tools from \"./tools.ts\"\n\n/** @internal */\nexport const silentTurnMessage = \"I finished without sending a reply.\"\n\n/** @internal */\nexport const defaultReplyNudge =\n \"You haven't replied to the user's latest message yet. Reply now with send_user_message.\"\n\n/** @internal */\nexport const deliveryNudge =\n \"You told the user you're on it, but stopped without giving them the result. Send it now with send_user_message; if part of it is still running, say what and that you'll report back. If they already have everything, call wait.\"\n\n/** @internal */\nexport interface Definition {\n readonly name: string\n readonly blocks: BlockKit.BlockKit | undefined\n readonly specialists: ReadonlyArray<Specialist.Any>\n readonly app: AppEvents.AppEvents\n}\n\n// Once its build ran the layer's services are provided, so its streams need only what a turn provides.\n/** @internal */\nexport type TurnHandler = (\n turn: Assistant.Turn<any>\n) => Stream.Stream<AssistantLoop.Event, unknown, Assistant.TurnServices | LanguageModel.LanguageModel>\n\n// The chat `CurrentChat` gives, with its entries typed as the assistant's decode returns them: the assistant's typed\n// chat is this one, so it needs no check of its own.\n/** @internal */\nexport interface TypedChat {\n readonly chatId: ChatId\n readonly entries: Effect.Effect<AppEvents.DecodedEntries>\n readonly append: CurrentChat[\"Service\"][\"append\"]\n}\n\n/** @internal */\nexport interface Registration {\n readonly definition: Definition\n readonly model: Context.Context<LanguageModel.LanguageModel>\n readonly open: (chat: TypedChat) => Effect.Effect<TurnHandler, never, Scope.Scope | CurrentChat>\n readonly specialists: ReadonlyArray<{\n readonly specialist: Specialist.Any\n readonly built: Specialist.Built\n }>\n readonly builtins: Toolkits.Tools<Assistant.TurnServices>\n}\n\n/** @internal */\nexport const register = Effect.fnUntraced(function* (\n definition: Definition,\n options: { readonly open: Registration[\"open\"] }\n) {\n const model = yield* Effect.context<LanguageModel.LanguageModel>()\n\n const specialists = yield* Effect.forEach(\n definition.specialists,\n Effect.fnUntraced(function* (specialist) {\n const built = yield* Effect.serviceOption(specialist.Handler)\n\n if (Option.isNone(built)) {\n return yield* Effect.die(\n `No handler for the ${specialist.name} specialist: provide ${specialist.name}.toLayer.`\n )\n }\n\n return { specialist, built: built.value }\n })\n )\n\n const builtins = Toolkits.merge(\n yield* Tools.makeMessaging(definition.blocks),\n yield* Specialists.toolkit(definition.specialists)\n )\n\n const registration: Registration = {\n definition,\n model,\n open: options.open,\n specialists,\n builtins\n }\n\n return registration\n})\n\nconst ProviderError = Schema.Struct({ _tag: Schema.optional(Schema.String), raw: Schema.Unknown })\n\n// Provider errors keep their response body.\nconst failureMessage = (cause: Cause.Cause<unknown>): string =>\n Option.match(Schema.decodeUnknownOption(ProviderError)(Cause.squash(cause)), {\n onNone: () => Cause.pretty(cause),\n onSome: ({ _tag, raw }) => `${_tag ?? \"Error\"}: ${Predicate.isString(raw) ? raw : toJsonText(raw)}`\n })\n\n// Approved, and not run yet: also one a crash cut off while it ran, which runs again with the same id.\nconst approvedCalls = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlyArray<AssistantEvent.ToolCallPart> =>\n [...ToolApproval.fromEntries(entries).values()].flatMap(({ request, status, outcome }) =>\n status === \"approved\" && outcome === undefined\n ? [\n Response.makePart(\"tool-call\", {\n id: request.callId,\n name: request.tool,\n params: request.params,\n providerExecuted: false\n })\n ]\n : []\n )\n\nconst lastSequence = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, otherwise: number) =>\n entries.at(-1)?.sequence ?? otherwise\n\n// The handler's stream can end between a step's output and its tools, or while they run. An interrupted turn (a\n// shutdown) leaves its calls open instead: the next turn runs them again.\nconst closeOpenCalls = Effect.fnUntraced(function* (chat: Writer, startSequence: number) {\n const entries = (yield* chat.entries).filter(({ sequence }) => sequence > startSequence)\n\n const started = new Set(\n entries.flatMap(({ event }) => (Predicate.isTagged(event, \"ToolStarted\") ? [event.callId] : []))\n )\n\n const open = History.unansweredCalls(History.fromEntries(entries))\n\n if (open.length === 0) return\n\n yield* chat.append(\n open.map((call) =>\n AssistantEvent.ToolResult.make({\n callId: call.id,\n tool: call.name,\n outcome: \"failure\",\n ...(started.has(call.id)\n ? { result: History.mayHaveRunOutput, reason: \"MayHaveRun\" }\n : { result: History.notRunOutput, reason: \"NotRun\" })\n })\n )\n )\n})\n\n// The inputs before the turn's `TurnStarted` (at `startSequence`) woke it; past that, what its model outputs record\n// reading.\nconst handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, startSequence: number) =>\n entries.reduce(\n (through, { sequence, event }) =>\n sequence > startSequence &&\n AssistantEvent.isLibraryEvent(event) &&\n Predicate.isTagged(event, \"ModelOutput\") &&\n event.seenThroughSequence !== undefined\n ? Math.max(through, event.seenThroughSequence)\n : through,\n startSequence\n )\n\n// A turn that ran the loop fails visibly when the user's latest input got no reply; an input that arrived after what\n// its model read gets the next turn, which replies. A handler that ended without the loop decided that itself.\nconst finishTurn = Effect.fnUntraced(function* (chat: Writer, read: number, ranLoop: boolean) {\n const entries = yield* chat.entries\n\n const end =\n ranLoop && History.owesReply(entries, read) && !History.unreadAfter(entries, read)\n ? AssistantEvent.TurnFailed.make({ throughSequence: read, message: silentTurnMessage })\n : AssistantEvent.TurnCompleted.make({ throughSequence: read })\n\n yield* chat.append([end])\n})\n\n// Everything stored so far counts as read, so a failing input isn't retried forever.\nconst failTurn = Effect.fnUntraced(function* (chat: Writer, cause: Cause.Cause<unknown>) {\n yield* Effect.logError(\"assistant turn failed\", cause)\n yield* ErrorReporter.report(cause)\n\n const last = lastSequence(yield* chat.entries, 0)\n\n yield* chat.append([AssistantEvent.TurnFailed.make({ throughSequence: last, message: failureMessage(cause) })])\n})\n\nconst makeTurnApi = (\n registration: Registration,\n chat: Writer,\n startSequence: number,\n checkOpen: Effect.Effect<void>,\n ranLoop: Ref.Ref<boolean>\n): Assistant.Turn<any> => {\n const { definition, builtins } = registration\n const { app } = definition\n const shownTools = BlockKit.toolNames(definition.blocks)\n\n const running = <A, E, R>(stream: Stream.Stream<A, E, R>) =>\n Stream.unwrap(Ref.set(ranLoop, true).pipe(Effect.as(stream)))\n\n // With how far into the chat it goes: the step records it on the model's output.\n // Read before every model call: a chat the app deleted meanwhile stops here.\n const history = Effect.fnUntraced(function* (view: Assistant.HistoryView<any> = identity) {\n yield* checkOpen\n\n const all = yield* chat.entries\n\n const read: AssistantLoop.ChatHistory = {\n messages: History.fromEntries(view(AppEvents.decodeEntries(app, all))),\n throughSequence: lastSequence(all, startSequence)\n }\n\n return read\n })\n\n const instructions = (given: string | Instructions.Resolved) =>\n mapText(given, (text) => `${Instructions.protocol}\\n\\n${text}`)\n\n // The loop's own prompt and tools, so the prompt stays cached, with the nudge at the end.\n const replyPass = <R>(options: {\n readonly instructions: Instructions.Resolved\n readonly toolkit: Toolkits.Tools<R>\n readonly view: Assistant.HistoryView<any>\n readonly nudge: string | undefined\n }) =>\n Stream.unwrap(\n Effect.gen(function* () {\n const all = yield* chat.entries\n const through = handledThrough(all, startSequence)\n\n // Something arrived after what the loop's model read: the next turn reads it with the full loop, and replies.\n if (History.unreadAfter(all, through)) return Stream.empty\n\n const owed = History.owesReply(all, through)\n const undelivered = !owed && History.owesDelivery(all, through)\n\n if (!owed && !undelivered) return Stream.empty\n\n const nudge = undelivered ? deliveryNudge : (options.nudge ?? defaultReplyNudge)\n\n return Loop.run({\n instructions: options.instructions,\n // A reply that's owed can only be sent; a result it may have given may also be for nobody.\n toolkit: Toolkits.runOnly(\n options.toolkit,\n owed ? [Tools.sendUserMessageName] : [Tools.sendUserMessageName, Tools.waitToolName],\n \"Not now: reply to the user with send_user_message.\"\n ),\n history: Effect.gen(function* () {\n yield* checkOpen\n\n const entries = yield* chat.entries\n\n return {\n messages: [\n ...History.fromEntries(options.view(AppEvents.decodeEntries(app, entries))),\n History.userText(nudge)\n ],\n throughSequence: lastSequence(entries, startSequence)\n }\n }),\n // A second step, for a reply after a call it was refused.\n maxSteps: 2,\n // The pass runs because the model wrote text of its own instead of replying, which reaches nobody: it has to\n // call a tool now. Changing the choice costs a read of the history at full price, on these rare turns only.\n toolChoice: \"required\"\n // The loop ran the approved calls; a pass that can only reply runs none.\n }).pipe(Stream.provideService(Loop.TurnApprovals, Option.none()))\n })\n )\n\n const replyIfOwed = (options: Assistant.ReplyOptions) =>\n running(\n replyPass({\n instructions: instructions(options.instructions),\n toolkit: builtins,\n view: identity,\n nudge: options.nudge\n })\n )\n\n const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.RunOptions<T, any>) => {\n const own = Toolkits.showing(Toolkits.fromToolkitOrEmpty(options.toolkit), shownTools)\n\n return {\n system: instructions(options.instructions),\n toolkit: Toolkits.merge(builtins, own),\n view: options.history ?? identity\n }\n }\n\n return {\n chatId: chat.chatId,\n history,\n instructions,\n replyIfOwed,\n run: (options) => {\n const { system, toolkit, view } = prepare(options)\n const twice = Toolkits.duplicateNames(toolkit)\n\n const loop =\n twice.length > 0\n ? Stream.die(`Tool names used twice, like one named after a built-in: ${twice.join(\", \")}`)\n : Loop.run({\n instructions: system,\n toolkit,\n history: history(view),\n maxSteps: options.maxSteps ?? 16\n })\n\n return running(Stream.concat(loop, replyPass({ instructions: system, toolkit, view, nudge: options.replyNudge })))\n }\n }\n}\n\n// Every event the handler's loop emits is recorded before the loop is pulled again.\n/** @internal */\nexport const run = Effect.fnUntraced(\n function* (options: {\n readonly registration: Registration\n readonly handler: TurnHandler\n readonly chat: Writer\n readonly services: Context.Context<Assistant.TurnServices | LanguageModel.LanguageModel>\n // A chat the app deleted is deleted here, and the turn stops.\n readonly checkOpen: Effect.Effect<void>\n }) {\n const { chat } = options\n const before = yield* chat.entries\n\n yield* Telemetry.agentInput(History.unhandledInputs(before))\n\n const assistant = options.registration.definition.name\n const traceId = yield* Telemetry.currentTraceId\n\n const started = yield* chat.append([\n AssistantEvent.TurnStarted.make(\n Option.match(traceId, {\n onNone: () => ({ assistant }),\n onSome: (id) => ({ assistant, traceId: id })\n })\n )\n ])\n\n const startSequence = lastSequence(started, 0)\n const ranLoop = yield* Ref.make(false)\n const turn = makeTurnApi(options.registration, chat, startSequence, options.checkOpen, ranLoop)\n\n const record = (event: AssistantLoop.Event) => chat.append([event])\n\n yield* options.handler(turn).pipe(\n Stream.runForEach(record),\n Effect.onExit((exit) => (Exit.hasInterrupts(exit) ? Effect.void : closeOpenCalls(chat, startSequence))),\n // A loop the app writes gets the assistant's own tools too, with this turn's services.\n Effect.provideService(\n Loop.TurnTools,\n Option.some(Toolkits.provide(options.registration.builtins, options.services))\n ),\n // A turn's loop waits for the user's approval, and runs the calls they approved.\n Effect.provideService(Loop.TurnApprovals, Option.some({ approved: Effect.map(chat.entries, approvedCalls) })),\n Effect.provideContext(options.services),\n Effect.matchCauseEffect({\n onSuccess: Effect.fnUntraced(function* () {\n const all = yield* chat.entries\n\n yield* finishTurn(chat, handledThrough(all, startSequence), yield* Ref.get(ranLoop))\n }),\n onFailure: (cause) => failTurn(chat, cause)\n })\n )\n\n // The trace's output is what the user saw this turn, and a failure if any.\n const shown = (yield* chat.entries).flatMap(({ event, sequence }) =>\n sequence > startSequence &&\n (Predicate.isTagged(event, \"AssistantMessage\") || Predicate.isTagged(event, \"TurnFailed\"))\n ? [event]\n : []\n )\n\n yield* Telemetry.agentOutput(shown)\n },\n (effect, options) =>\n effect.pipe(\n Telemetry.agentSpan(options.registration.definition.name, {\n chatId: options.chat.chatId,\n root: true\n })\n )\n)\n"],"mappings":"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"}
1
+ {"version":3,"file":"turns.js","names":["Telemetry.withoutTracing","Telemetry.TurnTracer","Toolkits.merge","Tools.makeMessaging","Specialists.toolkit","ToolApproval.fromEntries","History.unansweredCalls","History.fromEntries","History.mayHaveRunOutput","History.notRunOutput","AssistantEvent.isLibraryEvent","History.owesReply","History.unreadAfter","BlockKit.toolNames","AppEvents.decodeEntries","Instructions.protocol","History.owesDelivery","Loop.run","Toolkits.runOnly","Tools.sendUserMessageName","Tools.waitToolName","History.userText","Loop.TurnApprovals","Toolkits.showing","Toolkits.fromToolkitOrEmpty","Toolkits.duplicateNames","Telemetry.agentInput","History.unhandledInputs","Telemetry.currentTraceId","Live.make","Summary.run","Live.TurnLive","Loop.TurnTools","Toolkits.provide","Telemetry.agentOutput","Telemetry.agentSpan","Telemetry.onTracer"],"sources":["../../src/internal/turns.ts"],"sourcesContent":["import type * as LanguageModel from \"effect/ai/LanguageModel\"\nimport * as Response from \"effect/ai/Response\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport * as Cause from \"effect/Cause\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as ErrorReporter from \"effect/ErrorReporter\"\nimport * as Exit from \"effect/Exit\"\nimport { identity } from \"effect/Function\"\nimport * as Option from \"effect/Option\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as Ref from \"effect/Ref\"\nimport * as Schema from \"effect/Schema\"\nimport type * as Scope from \"effect/Scope\"\nimport type * as Tracer from \"effect/Tracer\"\nimport * as Stream from \"effect/Stream\"\nimport type * as Assistant from \"../Assistant.ts\"\nimport type { ChatId } from \"../ChatId.ts\"\nimport * as AssistantEvent from \"../AssistantEvent.ts\"\nimport type * as AssistantLoop from \"../AssistantLoop.ts\"\nimport * as Loop from \"./loop.ts\"\nimport * as BlockKit from \"../BlockKit.ts\"\nimport type { CurrentChat } from \"../CurrentChat.ts\"\nimport * as Instructions from \"../Instructions.ts\"\nimport { StatusSummary } from \"../StatusSummary.ts\"\nimport * as ToolApproval from \"../ToolApproval.ts\"\nimport type * as Specialist from \"../Specialist.ts\"\nimport * as AppEvents from \"./events.ts\"\nimport * as History from \"./history.ts\"\nimport { mapText } from \"./instructions.ts\"\nimport * as Live from \"./live.ts\"\nimport { toJsonText } from \"./schema.ts\"\nimport * as Specialists from \"./specialists.ts\"\nimport * as Summary from \"./summary.ts\"\nimport * as Telemetry from \"./telemetry.ts\"\nimport * as Toolkits from \"./toolkit.ts\"\nimport type { Writer } from \"./writer.ts\"\nimport * as Tools from \"./tools.ts\"\n\n/** @internal */\nexport const silentTurnMessage = \"I finished without sending a reply.\"\n\n/** @internal */\nexport const defaultReplyNudge =\n \"You haven't replied to the user's latest message yet. Reply now with send_user_message.\"\n\n/** @internal */\nexport const deliveryNudge =\n \"You told the user you're on it, but stopped without giving them the result. Send it now with send_user_message; if part of it is still running, say what and that you'll report back. If they already have everything, call wait.\"\n\n/** @internal */\nexport interface Definition {\n readonly name: string\n readonly blocks: BlockKit.BlockKit | undefined\n readonly specialists: ReadonlyArray<Specialist.Any>\n readonly app: AppEvents.AppEvents\n}\n\n// Once its build ran the layer's services are provided, so its streams need only what a turn provides.\n/** @internal */\nexport type TurnHandler = (\n turn: Assistant.Turn<any>\n) => Stream.Stream<AssistantLoop.Event, unknown, Assistant.TurnServices | LanguageModel.LanguageModel>\n\n// The chat `CurrentChat` gives, with its entries typed as the assistant's decode returns them: the assistant's typed\n// chat is this one, so it needs no check of its own.\n/** @internal */\nexport interface TypedChat {\n readonly chatId: ChatId\n readonly entries: Effect.Effect<AppEvents.DecodedEntries>\n readonly append: CurrentChat[\"Service\"][\"append\"]\n}\n\n/** @internal */\nexport interface Registration {\n readonly definition: Definition\n readonly model: Context.Context<LanguageModel.LanguageModel>\n readonly tracer: Option.Option<Tracer.Tracer>\n readonly open: (chat: TypedChat) => Effect.Effect<TurnHandler, never, Scope.Scope | CurrentChat>\n readonly specialists: ReadonlyArray<{\n readonly specialist: Specialist.Any\n readonly built: Specialist.Built\n }>\n readonly builtins: Toolkits.Tools<Assistant.TurnServices>\n // Writes a status for a turn that has been working a while with nothing to show.\n readonly summary: Option.Option<StatusSummary[\"Service\"]>\n}\n\n/** @internal */\nexport const register = Effect.fnUntraced(function* (\n definition: Definition,\n options: { readonly open: Registration[\"open\"] }\n) {\n const model = yield* Effect.context<LanguageModel.LanguageModel>().pipe(Effect.map(Telemetry.withoutTracing))\n const tracer = yield* Telemetry.TurnTracer\n\n const specialists = yield* Effect.forEach(\n definition.specialists,\n Effect.fnUntraced(function* (specialist) {\n const built = yield* Effect.serviceOption(specialist.Handler)\n\n if (Option.isNone(built)) {\n return yield* Effect.die(\n `No handler for the ${specialist.name} specialist: provide ${specialist.name}.toLayer.`\n )\n }\n\n return { specialist, built: built.value }\n })\n )\n\n const builtins = Toolkits.merge(\n yield* Tools.makeMessaging(definition.blocks),\n yield* Specialists.toolkit(definition.specialists)\n )\n\n const registration: Registration = {\n definition,\n model,\n tracer,\n open: options.open,\n specialists,\n builtins,\n summary: yield* Effect.serviceOption(StatusSummary)\n }\n\n return registration\n})\n\nconst ProviderError = Schema.Struct({ _tag: Schema.optional(Schema.String), raw: Schema.Unknown })\n\n// Provider errors keep their response body.\nconst failureMessage = (cause: Cause.Cause<unknown>): string =>\n Option.match(Schema.decodeUnknownOption(ProviderError)(Cause.squash(cause)), {\n onNone: () => Cause.pretty(cause),\n onSome: ({ _tag, raw }) => `${_tag ?? \"Error\"}: ${Predicate.isString(raw) ? raw : toJsonText(raw)}`\n })\n\n// Approved, and not run yet: also one a crash cut off while it ran, which runs again with the same id.\nconst approvedCalls = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlyArray<AssistantEvent.ToolCallPart> =>\n [...ToolApproval.fromEntries(entries).values()].flatMap(({ request, status, outcome }) =>\n status === \"approved\" && outcome === undefined\n ? [\n Response.makePart(\"tool-call\", {\n id: request.callId,\n name: request.tool,\n params: request.params,\n providerExecuted: false\n })\n ]\n : []\n )\n\nconst lastSequence = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, otherwise: number) =>\n entries.at(-1)?.sequence ?? otherwise\n\n// The handler's stream can end between a step's output and its tools, or while they run. An interrupted turn (a\n// shutdown) leaves its calls open instead: the next turn runs them again.\nconst closeOpenCalls = Effect.fnUntraced(function* (chat: Writer, startSequence: number) {\n const entries = (yield* chat.entries).filter(({ sequence }) => sequence > startSequence)\n\n const started = new Set(\n entries.flatMap(({ event }) => (Predicate.isTagged(event, \"ToolStarted\") ? [event.callId] : []))\n )\n\n const open = History.unansweredCalls(History.fromEntries(entries))\n\n if (open.length === 0) return\n\n yield* chat.append(\n open.map((call) =>\n AssistantEvent.ToolResult.make({\n callId: call.id,\n tool: call.name,\n outcome: \"failure\",\n ...(started.has(call.id)\n ? { result: History.mayHaveRunOutput, reason: \"MayHaveRun\" }\n : { result: History.notRunOutput, reason: \"NotRun\" })\n })\n )\n )\n})\n\n// The inputs before the turn's `TurnStarted` (at `startSequence`) woke it; past that, what its model outputs record\n// reading.\nconst handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, startSequence: number) =>\n entries.reduce(\n (through, { sequence, event }) =>\n sequence > startSequence &&\n AssistantEvent.isLibraryEvent(event) &&\n Predicate.isTagged(event, \"ModelOutput\") &&\n event.seenThroughSequence !== undefined\n ? Math.max(through, event.seenThroughSequence)\n : through,\n startSequence\n )\n\n// A turn that ran the loop fails visibly when the user's latest input got no reply; an input that arrived after what\n// its model read gets the next turn, which replies. A handler that ended without the loop decided that itself.\nconst finishTurn = Effect.fnUntraced(function* (chat: Writer, read: number, ranLoop: boolean) {\n const entries = yield* chat.entries\n\n const end =\n ranLoop && History.owesReply(entries, read) && !History.unreadAfter(entries, read)\n ? AssistantEvent.TurnFailed.make({ throughSequence: read, message: silentTurnMessage })\n : AssistantEvent.TurnCompleted.make({ throughSequence: read })\n\n yield* chat.append([end])\n})\n\n// Everything stored so far counts as read, so a failing input isn't retried forever.\nconst failTurn = Effect.fnUntraced(function* (chat: Writer, cause: Cause.Cause<unknown>) {\n yield* Effect.logError(\"assistant turn failed\", cause)\n yield* ErrorReporter.report(cause)\n\n const last = lastSequence(yield* chat.entries, 0)\n\n yield* chat.append([AssistantEvent.TurnFailed.make({ throughSequence: last, message: failureMessage(cause) })])\n})\n\nconst makeTurnApi = (\n registration: Registration,\n chat: Writer,\n startSequence: number,\n checkOpen: Effect.Effect<void>,\n ranLoop: Ref.Ref<boolean>\n): Assistant.Turn<any> => {\n const { definition, builtins } = registration\n const { app } = definition\n const shownTools = BlockKit.toolNames(definition.blocks)\n\n const running = <A, E, R>(stream: Stream.Stream<A, E, R>) =>\n Stream.unwrap(Ref.set(ranLoop, true).pipe(Effect.as(stream)))\n\n // With how far into the chat it goes: the step records it on the model's output.\n // Read before every model call: a chat the app deleted meanwhile stops here.\n const history = Effect.fnUntraced(function* (view: Assistant.HistoryView<any> = identity) {\n yield* checkOpen\n\n const all = yield* chat.entries\n\n const read: AssistantLoop.ChatHistory = {\n messages: History.fromEntries(view(AppEvents.decodeEntries(app, all))),\n throughSequence: lastSequence(all, startSequence)\n }\n\n return read\n })\n\n const instructions = (given: string | Instructions.Resolved) =>\n mapText(given, (text) => `${Instructions.protocol}\\n\\n${text}`)\n\n // The loop's own prompt and tools, so the prompt stays cached, with the nudge at the end.\n const replyPass = <R>(options: {\n readonly instructions: Instructions.Resolved\n readonly toolkit: Toolkits.Tools<R>\n readonly view: Assistant.HistoryView<any>\n readonly nudge: string | undefined\n }) =>\n Stream.unwrap(\n Effect.gen(function* () {\n const all = yield* chat.entries\n const through = handledThrough(all, startSequence)\n\n // Something arrived after what the loop's model read: the next turn reads it with the full loop, and replies.\n if (History.unreadAfter(all, through)) return Stream.empty\n\n const owed = History.owesReply(all, through)\n const undelivered = !owed && History.owesDelivery(all, through)\n\n if (!owed && !undelivered) return Stream.empty\n\n const nudge = undelivered ? deliveryNudge : (options.nudge ?? defaultReplyNudge)\n\n return Loop.run({\n instructions: options.instructions,\n // A reply that's owed can only be sent; a result it may have given may also be for nobody.\n toolkit: Toolkits.runOnly(\n options.toolkit,\n owed ? [Tools.sendUserMessageName] : [Tools.sendUserMessageName, Tools.waitToolName],\n \"Not now: reply to the user with send_user_message.\"\n ),\n history: Effect.gen(function* () {\n yield* checkOpen\n\n const entries = yield* chat.entries\n\n return {\n messages: [\n ...History.fromEntries(options.view(AppEvents.decodeEntries(app, entries))),\n History.userText(nudge)\n ],\n throughSequence: lastSequence(entries, startSequence)\n }\n }),\n // A second step, for a reply after a call it was refused.\n maxSteps: 2,\n // The pass runs because the model wrote text of its own instead of replying, which reaches nobody: it has to\n // call a tool now. Changing the choice costs a read of the history at full price, on these rare turns only.\n toolChoice: \"required\"\n // The loop ran the approved calls; a pass that can only reply runs none.\n }).pipe(Stream.provideService(Loop.TurnApprovals, Option.none()))\n })\n )\n\n const replyIfOwed = (options: Assistant.ReplyOptions) =>\n running(\n replyPass({\n instructions: instructions(options.instructions),\n toolkit: builtins,\n view: identity,\n nudge: options.nudge\n })\n )\n\n const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.RunOptions<T, any>) => {\n const own = Toolkits.showing(Toolkits.fromToolkitOrEmpty(options.toolkit), shownTools)\n\n return {\n system: instructions(options.instructions),\n toolkit: Toolkits.merge(builtins, own),\n view: options.history ?? identity\n }\n }\n\n return {\n chatId: chat.chatId,\n history,\n instructions,\n replyIfOwed,\n run: (options) => {\n const { system, toolkit, view } = prepare(options)\n const twice = Toolkits.duplicateNames(toolkit)\n\n const loop =\n twice.length > 0\n ? Stream.die(`Tool names used twice, like one named after a built-in: ${twice.join(\", \")}`)\n : Loop.run({\n instructions: system,\n toolkit,\n history: history(view),\n maxSteps: options.maxSteps ?? 16\n })\n\n return running(Stream.concat(loop, replyPass({ instructions: system, toolkit, view, nudge: options.replyNudge })))\n }\n }\n}\n\n// Every event the handler's loop emits is recorded before the loop is pulled again.\n/** @internal */\nexport const run = Effect.fnUntraced(\n function* (options: {\n readonly registration: Registration\n readonly handler: TurnHandler\n readonly chat: Writer\n readonly services: Context.Context<Assistant.TurnServices | LanguageModel.LanguageModel>\n // A chat the app deleted is deleted here, and the turn stops.\n readonly checkOpen: Effect.Effect<void>\n }) {\n const { chat } = options\n const before = yield* chat.entries\n\n yield* Telemetry.agentInput(History.unhandledInputs(before))\n\n const assistant = options.registration.definition.name\n const traceId = yield* Telemetry.currentTraceId\n\n const started = yield* chat.append([\n AssistantEvent.TurnStarted.make(\n Option.match(traceId, {\n onNone: () => ({ assistant }),\n onSome: (id) => ({ assistant, traceId: id })\n })\n )\n ])\n\n const startSequence = lastSequence(started, 0)\n const ranLoop = yield* Ref.make(false)\n const turn = makeTurnApi(options.registration, chat, startSequence, options.checkOpen, ranLoop)\n\n const record = (event: AssistantLoop.Event) => chat.append([event])\n const live = yield* Live.make(chat.signal)\n\n // The summary runs beside the turn's work and stops with it.\n const summarizing = <A, E, R>(work: Effect.Effect<A, E, R>) =>\n Option.match(options.registration.summary, {\n onNone: () => work,\n onSome: (summary) =>\n Effect.forkScoped(Summary.run(summary, live, chat)).pipe(Effect.andThen(work), Effect.scoped)\n })\n\n yield* options.handler(turn).pipe(\n Stream.runForEach(record),\n Effect.onExit((exit) => (Exit.hasInterrupts(exit) ? Effect.void : closeOpenCalls(chat, startSequence))),\n Effect.provideService(Live.TurnLive, Option.some(live)),\n // A loop the app writes gets the assistant's own tools too, with this turn's services.\n Effect.provideService(\n Loop.TurnTools,\n Option.some(Toolkits.provide(options.registration.builtins, options.services))\n ),\n // A turn's loop waits for the user's approval, and runs the calls they approved.\n Effect.provideService(Loop.TurnApprovals, Option.some({ approved: Effect.map(chat.entries, approvedCalls) })),\n Effect.provideContext(options.services),\n summarizing,\n // Nothing the turn showed outlives it, also when it fails.\n Effect.ensuring(live.reset),\n Effect.matchCauseEffect({\n onSuccess: Effect.fnUntraced(function* () {\n const all = yield* chat.entries\n\n yield* finishTurn(chat, handledThrough(all, startSequence), yield* Ref.get(ranLoop))\n }),\n onFailure: (cause) => failTurn(chat, cause)\n })\n )\n\n // The trace's output is what the user saw this turn, and a failure if any.\n const shown = (yield* chat.entries).flatMap(({ event, sequence }) =>\n sequence > startSequence &&\n (Predicate.isTagged(event, \"AssistantMessage\") || Predicate.isTagged(event, \"TurnFailed\"))\n ? [event]\n : []\n )\n\n yield* Telemetry.agentOutput(shown)\n },\n (effect, options) =>\n effect.pipe(\n Telemetry.agentSpan(options.registration.definition.name, {\n chatId: options.chat.chatId,\n root: true\n }),\n Telemetry.onTracer(options.registration.tracer)\n )\n)\n"],"mappings":"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"}
@@ -1,5 +1,6 @@
1
1
  import { ChatId } from "../ChatId.js";
2
2
  import { AssistantEvent, AssistantEvent_d_exports, Entry, StoredAppEvent } from "../AssistantEvent.js";
3
+ import { ChatSignal } from "../ChatSignal.js";
3
4
  import * as Effect from "effect/Effect";
4
5
  //#region src/internal/writer.d.ts
5
6
  /** @internal */
@@ -7,6 +8,7 @@ export interface Writer {
7
8
  readonly chatId: ChatId;
8
9
  readonly entries: Effect.Effect<ReadonlyArray<Entry>>;
9
10
  readonly append: (events: ReadonlyArray<AssistantEvent | StoredAppEvent>) => Effect.Effect<ReadonlyArray<Entry>>;
11
+ readonly signal: (signal: ChatSignal) => Effect.Effect<void>;
10
12
  }
11
13
  //#endregion
12
14
  //# sourceMappingURL=writer.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"writer.d.ts","names":[],"sources":["../../src/internal/writer.ts"],"mappings":";;;;;iBAKiB;WACN,QAAQ;WACR,SAAS,OAAO,OAAO,cAAc;WACrC,SACP,QAAQ,cAAc,iBAAgC,oBACnD,OAAO,OAAO,cAAc"}
1
+ {"version":3,"file":"writer.d.ts","names":[],"sources":["../../src/internal/writer.ts"],"mappings":";;;;;;iBAMiB;WACN,QAAQ;WACR,SAAS,OAAO,OAAO,cAAc;WACrC,SACP,QAAQ,cAAc,iBAAgC,oBACnD,OAAO,OAAO,cAAc;WAExB,SAAS,QAAQ,eAAe,OAAO"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "effect-assistant",
3
- "version": "0.11.1",
3
+ "version": "0.13.0",
4
4
  "description": "A colleague assistant on Effect: an append-only event log per chat, an interruptible agent loop, specialists, skills, and UI blocks",
5
5
  "license": "MIT",
6
6
  "repository": {
package/src/Assistant.ts CHANGED
@@ -20,19 +20,23 @@ import * as Context from "effect/Context"
20
20
  import * as Effect from "effect/Effect"
21
21
  import * as Filter from "effect/Filter"
22
22
  import * as Layer from "effect/Layer"
23
+ import * as Option from "effect/Option"
23
24
  import * as Predicate from "effect/Predicate"
24
25
  import * as Schema from "effect/Schema"
25
26
  import * as Scope from "effect/Scope"
26
27
  import * as Stream from "effect/Stream"
28
+ import type * as Tracer from "effect/Tracer"
27
29
  import { AssistantEngine } from "./AssistantEngine.ts"
28
30
  import * as AssistantEvent from "./AssistantEvent.ts"
29
31
  import type * as AssistantLoop from "./AssistantLoop.ts"
30
32
  import type * as BlockKit from "./BlockKit.ts"
31
33
  import { ChatId } from "./ChatId.ts"
34
+ import * as ChatSignal from "./ChatSignal.ts"
32
35
  import * as Chats from "./Chats.ts"
33
36
  import type { CurrentChat } from "./CurrentChat.ts"
34
37
  import type * as Instructions from "./Instructions.ts"
35
38
  import * as AppEvents from "./internal/events.ts"
39
+ import * as Telemetry from "./internal/telemetry.ts"
36
40
  import * as Turns from "./internal/turns.ts"
37
41
  import type * as Specialist from "./Specialist.ts"
38
42
 
@@ -237,6 +241,29 @@ const toStream = <R, RE>(
237
241
  | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>
238
242
  ): Stream.Stream<AssistantLoop.Event, unknown, R | RE> => (Effect.isEffect(result) ? Stream.unwrap(result) : result)
239
243
 
244
+ /**
245
+ * Sets the tracer that an assistant's turns and specialist runs record their spans with. Each
246
+ * turn's `invoke_agent` span is then the root of a trace on that tracer, with the turn's model
247
+ * calls and tool calls below it. By default they use the tracer of the fiber that runs them.
248
+ *
249
+ * Provide it to the assistant's layer to send the agent's work to its own backend, such as an LLM
250
+ * observability tool, while the rest of the app traces elsewhere.
251
+ *
252
+ * @example
253
+ * ```ts
254
+ * const AgentTracer = Layer.effect(
255
+ * Assistant.TurnTracer,
256
+ * OtlpTracer.make({ url: "https://llm-observability.example.com/v1/traces" }).pipe(Effect.map(Option.some))
257
+ * )
258
+ *
259
+ * const MyAssistantLive = MyAssistant.toLayer(handler).pipe(Layer.provide(AgentTracer))
260
+ * ```
261
+ *
262
+ * @category references
263
+ * @since 0.12.0
264
+ */
265
+ export const TurnTracer: Context.Reference<Option.Option<Tracer.Tracer>> = Telemetry.TurnTracer
266
+
240
267
  /**
241
268
  * Identifies an assistant's service in a context. Each assistant has its own identifier, keyed by
242
269
  * its name.
@@ -284,6 +311,17 @@ export interface Chat<Events = never> {
284
311
  append(...events: ReadonlyArray<AssistantEvent.AssistantEvent | Events>): Effect.Effect<void>
285
312
  }
286
313
 
314
+ /**
315
+ * Represents the options accepted by an assistant's `subscribe`.
316
+ *
317
+ * @category models
318
+ * @since 0.13.0
319
+ */
320
+ export interface SubscribeOptions {
321
+ /** The `sequence` after which the stream starts. Defaults to `0`, the whole log. */
322
+ readonly after?: number | undefined
323
+ }
324
+
287
325
  /**
288
326
  * Represents the service that `yield* MyAssistant` returns. It gives code outside a chat, such as
289
327
  * a server or a workflow, access to the assistant's chats. Code that runs inside a chat uses
@@ -316,10 +354,18 @@ export interface Service<Events = never> {
316
354
  * on the timeline depends on earlier entries. The timeline shows only the app events named in its
317
355
  * `show`, none by default (see `Timeline.changes`).
318
356
  */
319
- readonly subscribe: (
320
- chatId: ChatId,
321
- options?: { readonly after?: number | undefined }
322
- ) => Stream.Stream<Entry<Events>>
357
+ readonly subscribe: {
358
+ (chatId: ChatId, options?: SubscribeOptions & { readonly live?: false | undefined }): Stream.Stream<Entry<Events>>
359
+ /**
360
+ * With `live: true`, the stream also has the chat's signals (see `ChatSignal`): the status of
361
+ * what a turn is doing, and whether a message to the user is on its way. They come in order
362
+ * with the entries, only while the stream runs, and are never stored.
363
+ */
364
+ (
365
+ chatId: ChatId,
366
+ options: SubscribeOptions & { readonly live: true }
367
+ ): Stream.Stream<Entry<Events> | ChatSignal.ChatSignal>
368
+ }
323
369
  /**
324
370
  * Deletes a chat by storing a `ChatDeleted` event and stopping everything that works in it.
325
371
  *
@@ -552,20 +598,35 @@ export const make = <
552
598
  const engine = yield* AssistantEngine
553
599
  const chats = yield* Chats.Chats
554
600
 
601
+ const decode = (
602
+ item: AssistantEvent.Entry | ChatSignal.ChatSignal
603
+ ): Option.Option<Entry<OwnEvents> | ChatSignal.ChatSignal> =>
604
+ ChatSignal.isChatSignal(item) ? Option.some(item) : AppEvents.decodeEntry(definition.app, item)
605
+
606
+ function subscribe(
607
+ chatId: ChatId,
608
+ options?: SubscribeOptions & { readonly live?: false | undefined }
609
+ ): Stream.Stream<Entry<OwnEvents>>
610
+ function subscribe(
611
+ chatId: ChatId,
612
+ options: SubscribeOptions & { readonly live: true }
613
+ ): Stream.Stream<Entry<OwnEvents> | ChatSignal.ChatSignal>
614
+ function subscribe(
615
+ chatId: ChatId,
616
+ options?: SubscribeOptions & { readonly live?: boolean | undefined }
617
+ ): Stream.Stream<Entry<OwnEvents> | ChatSignal.ChatSignal> {
618
+ return engine
619
+ .subscribe(name, chatId, options?.after ?? 0, options?.live === true)
620
+ .pipe(Stream.filterMap(Filter.fromPredicateOption(decode)))
621
+ }
622
+
555
623
  return Key.of({
556
624
  submit: Effect.fn("Assistant.submit")(function* (chatId: ChatId, input: AssistantEvent.Input | OwnEvents) {
557
625
  // Checked here, where the caller can handle it: the chat checks again when it stores the input.
558
626
  yield* chats.get(chatId)
559
627
  yield* engine.submit(name, chatId, yield* stored(input))
560
628
  }),
561
- subscribe: (chatId, options) =>
562
- engine
563
- .subscribe(name, chatId, options?.after ?? 0)
564
- .pipe(
565
- Stream.filterMap(
566
- Filter.fromPredicateOption((entry: AssistantEvent.Entry) => AppEvents.decodeEntry(definition.app, entry))
567
- )
568
- ),
629
+ subscribe,
569
630
  delete: (chatId) => engine.delete(name, chatId)
570
631
  })
571
632
  })
@@ -591,7 +652,10 @@ export const make = <
591
652
  Key,
592
653
  Effect.gen(function* () {
593
654
  // Without the layer's scope: what a build or a turn sets up lives as long as the chat or the turn.
594
- const context = yield* Effect.context().pipe(Effect.map(Context.omit(Scope.Scope)))
655
+ const context = yield* Effect.context().pipe(
656
+ Effect.map(Context.omit(Scope.Scope)),
657
+ Effect.map(Telemetry.withoutTracing)
658
+ )
595
659
 
596
660
  const registration = yield* Turns.register(definition, {
597
661
  // The build runs per chat activation, in the chat; here it only keeps the layer's services for it.
@@ -29,6 +29,7 @@ import * as Stream from "effect/Stream"
29
29
  import * as AssistantEvent from "./AssistantEvent.ts"
30
30
  import { ChatId } from "./ChatId.ts"
31
31
  import { ChatLog } from "./ChatLog.ts"
32
+ import * as ChatSignal from "./ChatSignal.ts"
32
33
  import * as Chat from "./internal/chat.ts"
33
34
  import * as History from "./internal/history.ts"
34
35
  import type * as Turns from "./internal/turns.ts"
@@ -54,8 +55,16 @@ export class AssistantEngine extends Context.Service<
54
55
  chatId: ChatId,
55
56
  input: AssistantEvent.Input | AssistantEvent.StoredAppEvent
56
57
  ) => Effect.Effect<void>
57
- /** Streams the chat's stored entries after the `after` sequence, then live ones. */
58
- readonly subscribe: (assistant: string, chatId: ChatId, after: number) => Stream.Stream<AssistantEvent.Entry>
58
+ /**
59
+ * Streams the chat's stored entries after the `after` sequence, then live ones. With `live`,
60
+ * the chat's signals too, in order with the entries.
61
+ */
62
+ readonly subscribe: (
63
+ assistant: string,
64
+ chatId: ChatId,
65
+ after: number,
66
+ live: boolean
67
+ ) => Stream.Stream<AssistantEvent.Entry | ChatSignal.ChatSignal>
59
68
  /**
60
69
  * Deletes one of the assistant's chats. The chat's log records the deletion, and everything
61
70
  * that works in the chat stops.
@@ -182,12 +191,12 @@ export const layerMemory: Layer.Layer<AssistantEngine, never, ChatLog> = Layer.e
182
191
  yield* RcMap.invalidate(chats, new ChatKey({ assistant, chatId }))
183
192
  }),
184
193
  // The subscriber holds the chat open while it streams.
185
- subscribe: (assistant, chatId, after) =>
194
+ subscribe: (assistant, chatId, after, live) =>
186
195
  Stream.unwrap(
187
196
  Effect.gen(function* () {
188
197
  const chat = yield* RcMap.get(chats, new ChatKey({ assistant, chatId }))
189
198
 
190
- return chat.stream(after)
199
+ return live ? chat.live(after) : chat.stream(after)
191
200
  })
192
201
  )
193
202
  })
@@ -196,7 +205,11 @@ export const layerMemory: Layer.Layer<AssistantEngine, never, ChatLog> = Layer.e
196
205
 
197
206
  interface EntityClient {
198
207
  readonly submit: (chatId: ChatId, input: AssistantEvent.Input | AssistantEvent.StoredAppEvent) => Effect.Effect<void>
199
- readonly subscribe: (chatId: ChatId, after: number) => Stream.Stream<AssistantEvent.Entry>
208
+ readonly subscribe: (
209
+ chatId: ChatId,
210
+ after: number,
211
+ live: boolean
212
+ ) => Stream.Stream<AssistantEvent.Entry | ChatSignal.ChatSignal>
200
213
  readonly delete: (chatId: ChatId) => Effect.Effect<void>
201
214
  }
202
215
 
@@ -205,8 +218,8 @@ const Submit = Rpc.make("Submit", {
205
218
  }).annotate(ClusterSchema.Persisted, true)
206
219
 
207
220
  const Subscribe = Rpc.make("Subscribe", {
208
- payload: { after: Schema.Int },
209
- success: AssistantEvent.Entry,
221
+ payload: { after: Schema.Int, live: Schema.optionalKey(Schema.Boolean) },
222
+ success: Schema.Union([AssistantEvent.Entry, ChatSignal.ChatSignal]),
210
223
  stream: true
211
224
  })
212
225
 
@@ -230,7 +243,7 @@ const makeClusterClient = Effect.gen(function* () {
230
243
 
231
244
  const client: EntityClient = {
232
245
  submit: (chatId, input) => makeClient(chatId).Submit({ input }, { discard: true }).pipe(Effect.orDie),
233
- subscribe: (chatId, after) => makeClient(chatId).Subscribe({ after }).pipe(Stream.orDie),
246
+ subscribe: (chatId, after, live) => makeClient(chatId).Subscribe({ after, live }).pipe(Stream.orDie),
234
247
  delete: (chatId) => makeClient(chatId).Delete().pipe(Effect.orDie)
235
248
  }
236
249
 
@@ -249,12 +262,12 @@ const makeClusterClient = Effect.gen(function* () {
249
262
 
250
263
  yield* client.submit(chatId, input)
251
264
  }),
252
- subscribe: (assistant, chatId, after) =>
265
+ subscribe: (assistant, chatId, after, live) =>
253
266
  Stream.unwrap(
254
267
  Effect.gen(function* () {
255
268
  const client = yield* clientOf(assistant)
256
269
 
257
- return client.subscribe(chatId, after)
270
+ return client.subscribe(chatId, after, live)
258
271
  })
259
272
  ),
260
273
  delete: Effect.fn("AssistantEngine.delete")(function* (assistant: string, chatId: ChatId) {
@@ -340,7 +353,8 @@ export const layerCluster: Layer.Layer<AssistantEngine, never, ChatLog | Shardin
340
353
  return ChatEntity.of({
341
354
  // The turns run inside the request, so a crash leaves it unprocessed and the cluster redelivers it.
342
355
  Submit: (request) => chat.submit(request.payload.input),
343
- Subscribe: (request) => chat.stream(request.payload.after),
356
+ Subscribe: (request) =>
357
+ request.payload.live === true ? chat.live(request.payload.after) : chat.stream(request.payload.after),
344
358
  Delete: () => chat.delete
345
359
  })
346
360
  })
@@ -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)
package/src/Specialist.ts CHANGED
@@ -22,6 +22,7 @@ import type * as AssistantLoop from "./AssistantLoop.ts"
22
22
  import type { ChatId } from "./ChatId.ts"
23
23
  import type { CurrentChat } from "./CurrentChat.ts"
24
24
  import type * as Instructions from "./Instructions.ts"
25
+ import * as Telemetry from "./internal/telemetry.ts"
25
26
  import type { RunId } from "./RunId.ts"
26
27
 
27
28
  const TypeId = "~effect-assistant/Specialist"
@@ -258,7 +259,10 @@ export const make = <const Name extends string>(
258
259
  Handler,
259
260
  Effect.gen(function* () {
260
261
  // Without the layer's scope: what a build or a turn sets up lives as long as the chat or the turn.
261
- const context = yield* Effect.context().pipe(Effect.map(Context.omit(Scope.Scope)))
262
+ const context = yield* Effect.context().pipe(
263
+ Effect.map(Context.omit(Scope.Scope)),
264
+ Effect.map(Telemetry.withoutTracing)
265
+ )
262
266
 
263
267
  return {
264
268
  // The build runs per chat activation, in the chat; here it only keeps the layer's
@@ -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
+ )