effect-assistant 0.0.0-stage → 0.1.0

package/dist/internal/turns.js

@@ -0,0 +1,221 @@
+import { ToolResult, TurnCompleted, TurnFailed, TurnStarted, isLibraryEvent } from "../AssistantEvent.js";
+import { block, kind } from "../Decision.js";
+import { approvedCalls } from "./decisions.js";
+import { toJsonText } from "./schema.js";
+import { decodeEntries, read } from "./events.js";
+import { fromEntries, mayHaveRunOutput, notRunOutput, owesDelivery, owesReply, unansweredCalls, unhandledInputs, unreadAfter, userText } from "./history.js";
+import { agentInput, agentOutput, agentSpan, currentTraceId } from "./telemetry.js";
+import { duplicateNames, fromToolkitOrEmpty, merge, provide, runOnly } from "./toolkit.js";
+import { makeMessaging, sendUserMessageName, waitToolName } from "./tools.js";
+import { TurnTools, run as run$1 } from "./loop.js";
+import { withCatalog } from "../Skill.js";
+import { protocol } from "../Instructions.js";
+import { toTools } from "./skills.js";
+import { mapText } from "./instructions.js";
+import { toolkit } from "./specialists.js";
+import * as Predicate from "effect/Predicate";
+import "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as Exit from "effect/Exit";
+import * as Option from "effect/Option";
+import * as Cause from "effect/Cause";
+import { identity } from "effect/Function";
+//#region src/internal/turns.ts
+/** @internal */
+const silentTurnMessage = "I finished without sending a reply.";
+/** @internal */
+const defaultReplyNudge = "You haven't replied to the user's latest message yet. Reply now with send_user_message.";
+/** @internal */
+const deliveryNudge = "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.";
+/** @internal */
+const register = Effect.fnUntraced(function* (definition, options) {
+	const model = yield* Effect.context();
+	const decisionBlock = definition.blocks?.byKind.get(kind);
+	if (decisionBlock !== void 0 && decisionBlock !== block) return yield* Effect.die(`The ${kind} block kind is the library's: use Decision.block.`);
+	const specialists = yield* Effect.forEach(definition.specialists, Effect.fnUntraced(function* (specialist) {
+		const built = yield* Effect.serviceOption(specialist.Handler);
+		if (Option.isNone(built)) return yield* Effect.die(`No handler for the ${specialist.name} specialist: provide ${specialist.name}.toLayer.`);
+		return {
+			specialist,
+			built: built.value
+		};
+	}));
+	const builtins = merge(yield* makeMessaging(definition.blocks), yield* toolkit(definition.specialists));
+	return {
+		definition,
+		model,
+		open: options.open,
+		specialists,
+		builtins
+	};
+});
+const ProviderError = Schema.Struct({
+	_tag: Schema.optional(Schema.String),
+	raw: Schema.Unknown
+});
+const failureMessage = (cause) => Option.match(Schema.decodeUnknownOption(ProviderError)(Cause.squash(cause)), {
+	onNone: () => Cause.pretty(cause),
+	onSome: ({ _tag, raw }) => `${_tag ?? "Error"}: ${Predicate.isString(raw) ? raw : toJsonText(raw)}`
+});
+const lastSeq = (entries, otherwise) => entries.at(-1)?.seq ?? otherwise;
+const toHistory = (viewed, app) => {
+	const out = [];
+	let run = [];
+	const flush = () => {
+		out.push(...fromEntries(run, (event) => read(app, event)));
+		run = [];
+	};
+	for (const item of viewed) if (isEntry(item)) run.push(item);
+	else {
+		flush();
+		out.push(item);
+	}
+	flush();
+	return out;
+};
+const isEntry = (item) => Predicate.hasProperty(item, "seq");
+const closeOpenCalls = Effect.fnUntraced(function* (chat, startSeq) {
+	const entries = (yield* chat.entries).filter(({ seq }) => seq > startSeq);
+	const started = new Set(entries.flatMap(({ event }) => Predicate.isTagged(event, "ToolStarted") ? [event.callId] : []));
+	const all = yield* chat.entries;
+	const approved = approvedCalls(all).filter((call) => started.has(call.id));
+	const open = [...unansweredCalls(fromEntries(entries, () => void 0)), ...approved];
+	if (open.length === 0) return;
+	yield* chat.append(open.map((call) => ToolResult.make({
+		callId: call.id,
+		tool: call.name,
+		outcome: "failure",
+		...started.has(call.id) ? {
+			result: mayHaveRunOutput,
+			reason: "MayHaveRun"
+		} : {
+			result: notRunOutput,
+			reason: "NotRun"
+		}
+	})));
+});
+const handledThrough = (entries, startSeq) => entries.reduce((through, { seq, event }) => seq > startSeq && isLibraryEvent(event) && Predicate.isTagged(event, "ModelOutput") && event.seenThroughSeq !== void 0 ? Math.max(through, event.seenThroughSeq) : through, startSeq);
+const finishTurn = Effect.fnUntraced(function* (chat, read, wakes) {
+	const entries = yield* chat.entries;
+	const end = owesReply(entries, read) && !unreadAfter(entries, read, wakes) ? TurnFailed.make({
+		throughSeq: read,
+		message: silentTurnMessage
+	}) : TurnCompleted.make({ throughSeq: read });
+	yield* chat.append([end]);
+});
+const failTurn = Effect.fnUntraced(function* (chat, cause) {
+	yield* Effect.logError("assistant turn failed", cause);
+	const last = lastSeq(yield* chat.entries, 0);
+	yield* chat.append([TurnFailed.make({
+		throughSeq: last,
+		message: failureMessage(cause)
+	})]);
+});
+const makeTurnApi = (registration, chat, startSeq, checkOpen) => {
+	const { definition, builtins } = registration;
+	const { app } = definition;
+	const history = Effect.fnUntraced(function* (view = identity) {
+		yield* checkOpen;
+		const all = yield* chat.entries;
+		return {
+			messages: toHistory(view(decodeEntries(app, all)), app),
+			throughSeq: lastSeq(all, startSeq)
+		};
+	});
+	const instructions = (given) => mapText(given, (text) => `${protocol}\n\n${text}`);
+	const replyPass = (options) => Stream.unwrap(Effect.gen(function* () {
+		const all = yield* chat.entries;
+		const through = handledThrough(all, startSeq);
+		if (unreadAfter(all, through, app.wakes)) return Stream.empty;
+		const owed = owesReply(all, through);
+		const undelivered = !owed && owesDelivery(all, through);
+		if (!owed && !undelivered) return Stream.empty;
+		const nudge = undelivered ? deliveryNudge : options.nudge ?? "You haven't replied to the user's latest message yet. Reply now with send_user_message.";
+		return run$1({
+			instructions: options.instructions,
+			toolkit: runOnly(options.toolkit, owed ? [sendUserMessageName] : [sendUserMessageName, waitToolName], "Not now: reply to the user with send_user_message."),
+			history: Effect.gen(function* () {
+				yield* checkOpen;
+				const entries = yield* chat.entries;
+				return {
+					messages: [...toHistory(options.view(decodeEntries(app, entries)), app), userText(nudge)],
+					throughSeq: lastSeq(entries, startSeq)
+				};
+			}),
+			maxSteps: 2
+		});
+	}));
+	const replyIfOwed = (options) => replyPass({
+		instructions: instructions(options.instructions),
+		toolkit: builtins,
+		view: identity,
+		nudge: options.nudge
+	});
+	const prepare = (options) => {
+		const skills = options.skills ?? [];
+		return {
+			system: mapText(instructions(options.instructions), (text) => withCatalog(text, skills)),
+			toolkit: merge(merge(builtins, toTools(skills)), fromToolkitOrEmpty(options.toolkit)),
+			view: options.history ?? identity
+		};
+	};
+	return {
+		chatId: chat.chatId,
+		history,
+		instructions,
+		replyIfOwed,
+		loop: (options) => {
+			const { system, toolkit, view } = prepare(options);
+			const twice = duplicateNames(toolkit);
+			const deciding = toolkit.definitions.filter((tool) => tool.needsApproval !== void 0 && tool.needsApproval !== false);
+			const loop = twice.length > 0 ? Stream.die(`Tool names used twice, like one named after a built-in: ${twice.join(", ")}`) : deciding.length > 0 && definition.blocks?.byKind.get("decision") === void 0 ? Stream.die(`${deciding.map((tool) => tool.name).join(", ")} can wait for the user's decision: add Decision.block to the assistant's blocks.`) : run$1({
+				instructions: system,
+				toolkit,
+				history: history(view),
+				maxSteps: options.maxSteps ?? 16
+			});
+			return Stream.concat(loop, replyPass({
+				instructions: system,
+				toolkit,
+				view,
+				nudge: options.replyNudge
+			}));
+		}
+	};
+};
+/** @internal */
+const run = Effect.fnUntraced(function* (options) {
+	const { chat } = options;
+	const before = yield* chat.entries;
+	yield* agentInput(unhandledInputs(before, options.registration.definition.app.wakes));
+	const assistant = options.registration.definition.name;
+	const traceId = yield* currentTraceId;
+	const started = yield* chat.append([TurnStarted.make(Option.match(traceId, {
+		onNone: () => ({ assistant }),
+		onSome: (id) => ({
+			assistant,
+			traceId: id
+		})
+	}))]);
+	const startSeq = lastSeq(started, 0);
+	const turn = makeTurnApi(options.registration, chat, startSeq, options.checkOpen);
+	const record = (event) => chat.append([event]);
+	yield* options.handler(turn).pipe(Stream.runForEach(record), Effect.onExit((exit) => Exit.hasInterrupts(exit) ? Effect.void : closeOpenCalls(chat, startSeq)), Effect.provideService(TurnTools, Option.some(provide(options.registration.builtins, options.services))), Effect.provideContext(options.services), Effect.matchCauseEffect({
+		onSuccess: Effect.fnUntraced(function* () {
+			const all = yield* chat.entries;
+			yield* finishTurn(chat, handledThrough(all, startSeq), options.registration.definition.app.wakes);
+		}),
+		onFailure: (cause) => failTurn(chat, cause)
+	}));
+	const shown = (yield* chat.entries).flatMap(({ event, seq }) => seq > startSeq && (Predicate.isTagged(event, "AssistantMessage") || Predicate.isTagged(event, "TurnFailed")) ? [event] : []);
+	yield* agentOutput(shown);
+}, (effect, options) => effect.pipe(agentSpan(options.registration.definition.name, {
+	chatId: options.chat.chatId,
+	root: true
+})));
+//#endregion
+export { defaultReplyNudge, deliveryNudge, register, run, silentTurnMessage };
+
+//# sourceMappingURL=turns.js.map

package/dist/internal/turns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turns.js","names":["Decision.kind","Decision.block","Toolkits.merge","Tools.makeMessaging","Specialists.toolkit","History.fromEntries","AppEvents.read","Decisions.approvedCalls","History.unansweredCalls","History.mayHaveRunOutput","History.notRunOutput","AssistantEvent.isLibraryEvent","History.owesReply","History.unreadAfter","AppEvents.decodeEntries","Instructions.protocol","History.owesDelivery","Loop.run","Toolkits.runOnly","Tools.sendUserMessageName","Tools.waitToolName","History.userText","Skill.withCatalog","Skills.toTools","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 type * as Tool from \"effect/ai/Tool\"\nimport type * as Prompt from \"effect/ai/Prompt\"\nimport * as Cause from \"effect/Cause\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\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 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 type * as BlockKit from \"../BlockKit.ts\"\nimport type { CurrentChat } from \"../CurrentChat.ts\"\nimport * as Decision from \"../Decision.ts\"\nimport * as Instructions from \"../Instructions.ts\"\nimport * as Skill from \"../Skill.ts\"\nimport * as Skills from \"./skills.ts\"\nimport type * as Specialist from \"../Specialist.ts\"\nimport * as Decisions from \"./decisions.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 decisionBlock = definition.blocks?.byKind.get(Decision.kind)\n\n  if (decisionBlock !== undefined && decisionBlock !== Decision.block) {\n    return yield* Effect.die(`The ${Decision.kind} block kind is the library's: use Decision.block.`)\n  }\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\nconst lastSeq = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, otherwise: number) => entries.at(-1)?.seq ?? otherwise\n\nconst toHistory = (\n  viewed: ReadonlyArray<Assistant.Entry<any> | Prompt.Message>,\n  app: AppEvents.AppEvents\n): ReadonlyArray<Prompt.Message> => {\n  const out: Array<Prompt.Message> = []\n  let run: Array<AssistantEvent.AnyEntry> = []\n\n  const flush = () => {\n    out.push(...History.fromEntries(run, (event) => AppEvents.read(app, event)))\n    run = []\n  }\n\n  for (const item of viewed) {\n    if (isEntry(item)) run.push(item)\n    else {\n      flush()\n      out.push(item)\n    }\n  }\n\n  flush()\n\n  return out\n}\n\nconst isEntry = (item: Assistant.Entry<any> | Prompt.Message): item is Assistant.Entry<any> =>\n  Predicate.hasProperty(item, \"seq\")\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, startSeq: number) {\n  const entries = (yield* chat.entries).filter(({ seq }) => seq > startSeq)\n\n  const started = new Set(\n    entries.flatMap(({ event }) => (Predicate.isTagged(event, \"ToolStarted\") ? [event.callId] : []))\n  )\n\n  // Approved calls this turn started that have no result are cut off like any other; one not started yet waits.\n  const all = yield* chat.entries\n  const approved = Decisions.approvedCalls(all).filter((call) => started.has(call.id))\n  const open = [...History.unansweredCalls(History.fromEntries(entries, () => undefined)), ...approved]\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 `startSeq`) woke it; past that, what its model outputs record\n// reading.\nconst handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, startSeq: number) =>\n  entries.reduce(\n    (through, { seq, event }) =>\n      seq > startSeq &&\n      AssistantEvent.isLibraryEvent(event) &&\n      Predicate.isTagged(event, \"ModelOutput\") &&\n      event.seenThroughSeq !== undefined\n        ? Math.max(through, event.seenThroughSeq)\n        : through,\n    startSeq\n  )\n\n// Fails visibly when the user's latest input got no reply; an input that arrived after what its model read gets the\n// next turn, which replies.\nconst finishTurn = Effect.fnUntraced(function* (chat: Writer, read: number, wakes: ReadonlySet<string>) {\n  const entries = yield* chat.entries\n\n  const end =\n    History.owesReply(entries, read) && !History.unreadAfter(entries, read, wakes)\n      ? AssistantEvent.TurnFailed.make({ throughSeq: read, message: silentTurnMessage })\n      : AssistantEvent.TurnCompleted.make({ throughSeq: 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\n  const last = lastSeq(yield* chat.entries, 0)\n\n  yield* chat.append([AssistantEvent.TurnFailed.make({ throughSeq: last, message: failureMessage(cause) })])\n})\n\nconst makeTurnApi = (\n  registration: Registration,\n  chat: Writer,\n  startSeq: number,\n  checkOpen: Effect.Effect<void>\n): Assistant.Turn<any> => {\n  const { definition, builtins } = registration\n  const { app } = definition\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: toHistory(view(AppEvents.decodeEntries(app, all)), app),\n      throughSeq: lastSeq(all, startSeq)\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, startSeq)\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, app.wakes)) 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                ...toHistory(options.view(AppEvents.decodeEntries(app, entries)), app),\n                History.userText(nudge)\n              ],\n              throughSeq: lastSeq(entries, startSeq)\n            }\n          }),\n          // A second step, for a reply after a call it was refused.\n          maxSteps: 2\n        })\n      })\n    )\n\n  const replyIfOwed = (options: Assistant.ReplyOptions) =>\n    replyPass({\n      instructions: instructions(options.instructions),\n      toolkit: builtins,\n      view: identity,\n      nudge: options.nudge\n    })\n\n  const prepare = <T extends Record<string, Tool.Any>, RS>(options: Assistant.LoopOptions<T, RS, any>) => {\n    const skills = options.skills ?? []\n\n    return {\n      system: mapText(instructions(options.instructions), (text) => Skill.withCatalog(text, skills)),\n      toolkit: Toolkits.merge(\n        Toolkits.merge(builtins, Skills.toTools(skills)),\n        Toolkits.fromToolkitOrEmpty(options.toolkit)\n      ),\n      view: options.history ?? identity\n    }\n  }\n\n  return {\n    chatId: chat.chatId,\n    history,\n    instructions,\n    replyIfOwed,\n    loop: (options) => {\n      const { system, toolkit, view } = prepare(options)\n      const twice = Toolkits.duplicateNames(toolkit)\n\n      const deciding = toolkit.definitions.filter(\n        (tool) => tool.needsApproval !== undefined && tool.needsApproval !== false\n      )\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          : deciding.length > 0 && definition.blocks?.byKind.get(Decision.kind) === undefined\n            ? Stream.die(\n                `${deciding.map((tool) => tool.name).join(\", \")} can wait for the user's decision: add Decision.block to the assistant's blocks.`\n              )\n            : Loop.run({\n                instructions: system,\n                toolkit,\n                history: history(view),\n                maxSteps: options.maxSteps ?? 16\n              })\n\n      return 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, options.registration.definition.app.wakes))\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 startSeq = lastSeq(started, 0)\n    const turn = makeTurnApi(options.registration, chat, startSeq, options.checkOpen)\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, startSeq))),\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      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, startSeq), options.registration.definition.app.wakes)\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, seq }) =>\n      seq > startSeq && (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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"}

package/dist/internal/uuid.js

@@ -0,0 +1,45 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Random from "effect/Random";
+//#region src/internal/uuid.ts
+/** @internal */
+const Uuid = Schema.String.check(Schema.isUUID());
+const hex = (bytes) => {
+	const digits = bytes.map((byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${digits.slice(0, 8)}-${digits.slice(8, 12)}-${digits.slice(12, 16)}-${digits.slice(16, 20)}-${digits.slice(20)}`;
+};
+const format = (bytes, version) => {
+	const out = [...bytes];
+	out[6] = (out[6] ?? 0) & 15 | version << 4;
+	out[8] = (out[8] ?? 0) & 63 | 128;
+	return hex(out);
+};
+/** @internal */
+const make = Effect.gen(function* () {
+	const bytes = yield* Effect.forEach(Array.from({ length: 16 }), () => Random.nextIntBetween(0, 255));
+	return format(bytes, 4);
+});
+const fnv1a = (key, round) => {
+	let hash = 2166136261 ^ round;
+	for (let i = 0; i < key.length; i++) hash = Math.imul(hash ^ key.charCodeAt(i), 16777619);
+	return hash >>> 0;
+};
+/** @internal */
+const fromKey = (key) => format([
+	0,
+	1,
+	2,
+	3
+].flatMap((round) => {
+	const hash = fnv1a(key, round);
+	return [
+		hash >>> 24,
+		hash >>> 16 & 255,
+		hash >>> 8 & 255,
+		hash & 255
+	];
+}), 8);
+//#endregion
+export { Uuid, fromKey, make };
+
+//# sourceMappingURL=uuid.js.map

package/dist/internal/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","names":[],"sources":["../../src/internal/uuid.ts"],"sourcesContent":["import * as Effect from \"effect/Effect\"\nimport * as Random from \"effect/Random\"\nimport * as Schema from \"effect/Schema\"\n\n/** @internal */\nexport const Uuid = Schema.String.check(Schema.isUUID())\n\nconst hex = (bytes: ReadonlyArray<number>): string => {\n  const digits = bytes.map((byte) => byte.toString(16).padStart(2, \"0\")).join(\"\")\n\n  return `${digits.slice(0, 8)}-${digits.slice(8, 12)}-${digits.slice(12, 16)}-${digits.slice(16, 20)}-${digits.slice(20)}`\n}\n\n// RFC 9562 version nibble and variant bits.\nconst format = (bytes: ReadonlyArray<number>, version: number): string => {\n  const out = [...bytes]\n\n  out[6] = ((out[6] ?? 0) & 0x0f) | (version << 4)\n  out[8] = ((out[8] ?? 0) & 0x3f) | 0x80\n\n  return hex(out)\n}\n\n// From the `Random` service, so a seeded test gets the same ids every run.\n/** @internal */\nexport const make: Effect.Effect<string> = Effect.gen(function* () {\n  const bytes = yield* Effect.forEach(Array.from({ length: 16 }), () => Random.nextIntBetween(0, 255))\n\n  return format(bytes, 4)\n})\n\nconst fnv1a = (key: string, round: number): number => {\n  let hash = 0x811c9dc5 ^ round\n\n  for (let i = 0; i < key.length; i++) hash = Math.imul(hash ^ key.charCodeAt(i), 0x01000193)\n\n  return hash >>> 0\n}\n\n// Version 8: the same key gives the same UUID. Not a secret, only unlikely to collide: four 32-bit FNV-1a hashes.\n/** @internal */\nexport const fromKey = (key: string): string =>\n  format(\n    [0, 1, 2, 3].flatMap((round) => {\n      const hash = fnv1a(key, round)\n\n      return [hash >>> 24, (hash >>> 16) & 0xff, (hash >>> 8) & 0xff, hash & 0xff]\n    }),\n    8\n  )\n"],"mappings":";;;;;AAKA,MAAa,OAAO,OAAO,OAAO,MAAM,OAAO,OAAO,CAAC;AAEvD,MAAM,OAAO,UAAyC;CACpD,MAAM,SAAS,MAAM,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;CAE9E,OAAO,GAAG,OAAO,MAAM,GAAG,CAAC,EAAE,GAAG,OAAO,MAAM,GAAG,EAAE,EAAE,GAAG,OAAO,MAAM,IAAI,EAAE,EAAE,GAAG,OAAO,MAAM,IAAI,EAAE,EAAE,GAAG,OAAO,MAAM,EAAE;AACxH;AAGA,MAAM,UAAU,OAA8B,YAA4B;CACxE,MAAM,MAAM,CAAC,GAAG,KAAK;CAErB,IAAI,MAAO,IAAI,MAAM,KAAK,KAAS,WAAW;CAC9C,IAAI,MAAO,IAAI,MAAM,KAAK,KAAQ;CAElC,OAAO,IAAI,GAAG;AAChB;;AAIA,MAAa,OAA8B,OAAO,IAAI,aAAa;CACjE,MAAM,QAAQ,OAAO,OAAO,QAAQ,MAAM,KAAK,EAAE,QAAQ,GAAG,CAAC,SAAS,OAAO,eAAe,GAAG,GAAG,CAAC;CAEnG,OAAO,OAAO,OAAO,CAAC;AACxB,CAAC;AAED,MAAM,SAAS,KAAa,UAA0B;CACpD,IAAI,OAAO,aAAa;CAExB,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,QAAQ,KAAK,OAAO,KAAK,KAAK,OAAO,IAAI,WAAW,CAAC,GAAG,QAAU;CAE1F,OAAO,SAAS;AAClB;;AAIA,MAAa,WAAW,QACtB,OACE;CAAC;CAAG;CAAG;CAAG;AAAC,CAAC,CAAC,SAAS,UAAU;CAC9B,MAAM,OAAO,MAAM,KAAK,KAAK;CAE7B,OAAO;EAAC,SAAS;EAAK,SAAS,KAAM;EAAO,SAAS,IAAK;EAAM,OAAO;CAAI;AAC7E,CAAC,GACD,CACF"}

package/dist/internal/writer.d.ts

@@ -0,0 +1,12 @@
+import { ChatId } from "../ChatId.js";
+import { AssistantEvent, AssistantEvent_d_exports, Entry, StoredAppEvent } from "../AssistantEvent.js";
+import * as Effect from "effect/Effect";
+//#region src/internal/writer.d.ts
+/** @internal */
+export interface Writer {
+  readonly chatId: ChatId;
+  readonly entries: Effect.Effect<ReadonlyArray<Entry>>;
+  readonly append: (events: ReadonlyArray<AssistantEvent | StoredAppEvent>) => Effect.Effect<ReadonlyArray<Entry>>;
+}
+//#endregion
+//# sourceMappingURL=writer.d.ts.map

package/dist/internal/writer.d.ts.map

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "effect-assistant",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A colleague assistant on Effect: an append-only event log per chat, an interruptible agent loop, specialists, skills, and UI blocks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dbrxnds/effect-assistant.git",
+    "directory": "packages/effect-assistant"
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map"
+  ],
+  "type": "module",
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./internal/*": null
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@effect/ai-anthropic": "4.0.0",
+    "@effect/sql-sqlite-node": "4.0.0",
+    "@effect/vitest": "4.0.0",
+    "@types/node": "^22.15.3",
+    "effect": "4.0.0",
+    "typescript": "7.0.2",
+    "vite-plus": "1.0.0-rc.0",
+    "vitest": "5.0.1"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test run --exclude test/contract.test.ts",
+    "test:contract": "vp test run test/contract.test.ts"
+  }
 }

package/src/AppEvent.ts

@@ -0,0 +1,134 @@
+/**
+ * Registers an application's own events with an assistant.
+ *
+ * An app event is a tagged schema for something the application reports into a chat, such as a
+ * workflow's progress, a webhook, a summary for compaction, or the draft the user opened.
+ * {@link make} registers one with two choices: whether storing it wakes a turn (`wakes`), and
+ * how the model reads it (`render`).
+ *
+ * @since 0.1.0
+ */
+import * as Predicate from "effect/Predicate"
+import type * as Schema from "effect/Schema"
+import * as SchemaAST from "effect/SchemaAST"
+
+/**
+ * Schema for one of the application's own events.
+ *
+ * It is a tagged struct or class (`Schema.TaggedStruct`, `Schema.TaggedClass`) that needs no
+ * services.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type EventSchema = Schema.Codec<{ readonly _tag: string }, { readonly _tag: string }> & {
+  readonly fields: { readonly _tag: { readonly ast: SchemaAST.AST } }
+}
+
+/**
+ * Describes how the model reads an event.
+ *
+ * `"json"` shows the event's tag and fields as JSON. A function shows the text it returns for the
+ * event.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Render<A> = "json" | ((event: A) => string)
+
+/**
+ * Represents one of the application's events, registered with an assistant.
+ *
+ * It holds the event's schema and tag, whether storing it wakes a turn, and how the model reads
+ * it. A `render` of `undefined` means the model doesn't read it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AppEvent<S extends EventSchema = EventSchema> {
+  readonly schema: S
+  readonly tag: string
+  readonly wakes: boolean
+  readonly render: Render<S["Type"]> | undefined
+}
+
+/**
+ * Represents any registered event, for generic constraints.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Any = AppEvent<any>
+
+/**
+ * Extracts the type of a registered event's values.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Type<E extends Any> = E["schema"]["Type"]
+
+const tagOf = (schema: EventSchema): string => {
+  const ast = schema.fields._tag.ast
+
+  if (SchemaAST.isLiteral(ast) && Predicate.isString(ast.literal)) return ast.literal
+
+  throw new Error("An app event is a tagged struct or class.")
+}
+
+/**
+ * Registers one of the application's events with an assistant.
+ *
+ * **Details**
+ *
+ * Storing the event wakes a turn only when `wakes` is `true`; it defaults to `false`. `render`
+ * defaults to `"json"` for an event that wakes a turn. An event that doesn't wake a turn and has
+ * no `render` isn't read by the model.
+ *
+ * The schema must be a tagged struct or class whose `_tag` is a string literal; `make` throws
+ * otherwise.
+ *
+ * **Example** (Registering an event that wakes a turn)
+ *
+ * ```ts
+ * import { AppEvent, Assistant, InputId } from "effect-assistant"
+ * import * as Schema from "effect/Schema"
+ *
+ * class OrderShipped extends Schema.TaggedClass<OrderShipped>()("OrderShipped", {
+ *   id: InputId.InputId,
+ *   orderId: Schema.String,
+ *   carrier: Schema.String
+ * }) {}
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", {
+ *   events: [
+ *     AppEvent.make(OrderShipped, {
+ *       wakes: true,
+ *       render: (shipped) =>
+ *         `Order ${shipped.orderId} shipped with ${shipped.carrier}. Tell the user if it matters.`
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <S extends EventSchema>(
+  schema: S,
+  options?: {
+    /** Whether storing it starts a turn, like a user's message. Default false. */
+    readonly wakes?: boolean | undefined
+    /** How the model reads it in its history. */
+    readonly render?: Render<S["Type"]> | undefined
+  }
+): AppEvent<S> => {
+  const wakes = options?.wakes ?? false
+
+  return {
+    schema,
+    tag: tagOf(schema),
+    wakes,
+    render: options?.render ?? (wakes ? "json" : undefined)
+  }
+}