@popcomputer/structured-chat 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { AssistantDataPartSchema, AssistantMessagePartSchema, AssistantTextPartSchema, CollectQuestionView, InvalidChatPresentation, presentAnswerValidationRejection, presentChatNotice, presentChatReply, StructuredChatAssistantMessageSchema, StructuredChatSessionReferenceSchema, StructuredChatTurnRequestSchema, StructuredChatTurnResponseSchema, Text, type AssistantMessagePart, type PresentChatReplyOptions, type StructuredChatAssistantMessage, type StructuredChatSessionReference, type StructuredChatTurnRequest, type StructuredChatTurnResponse, } from "./core/protocol.js";
+export { makeStructuredChatModel, ModelProvider, structuredChatModelLayer, StructuredChatModelIdSchema, StructuredChatProviderIdSchema, StructuredChatRequestTimeoutSchema, type CloudflareWorkersAIProviderConfig, type OpenAIProviderConfig, type StructuredChatModelConfig, type StructuredChatModelId, type StructuredChatProvider, type StructuredChatProviderId, type StructuredChatProviderRequest, } from "./adapters/openai-compatible-model.js";
+export { ChatNameSchema, ChatVersionSchema, defineChat, InvalidChatTransition, InvalidChatTransitionReasonSchema, type ChatDefinition, type ChatError, type ChatRequirements, type ChatReply, type ChatReplyError, type ChatReplyInput, type ChatStageStates, type ChatStageTuple, type ChatState, type ChatTurn, type DefineChatInput, } from "./core/chat.js";
+export { Answer, AnswerModeSchema, type AnswerDefinition, type AnswerDefinitionContract, type AnswerMode, type DefineAnswerInput, type DefineUnvalidatedAnswerInput, type DefineValidatedAnswerInput, } from "./core/answer.js";
+export { InvalidCollectStageResponse, InvalidCollectStageResponseReasonSchema, type AcceptedAnswer, type AcceptedAnswerEvidence, AnswerValidationRejected, type AnswerFields, type CollectAcceptedAnswers, type CollectAnswerValidationError, type CollectAnswerValidationRequirements, type CollectAnswers, type CollectQuestionPolicy, type CollectStage, type CollectStagePrompt, type CollectStageQuestion, type CollectStageState, type CollectStageTurn, type DefineCollectStageInput, type IssuedCollectQuestion, } from "./core/collect-stage.js";
+export { defineTool, defineCommand, InvalidToolCall, InvalidToolCallReasonSchema, InvalidToolProjection, InvalidToolProjectionReasonSchema, Tool, ToolDescriptionSchema, ToolNameSchema, type DefineToolInput, type DefineCommandInput, type CommandDefinitionContract, type CommandExecutionContext, type ModelToolDefinition, type StructuredTool, type StructuredCommand, type ToolBoundaryParseError, type ToolCall, type ToolExecution, type ToolPresenter, type ToolViewPart, } from "./core/tool.js";
+export { defineToolSet, type ToolSet, type ToolSetCall, type ToolSetError, type ToolSetExecution, type ToolSetRequirements, type ToolTuple, } from "./core/tool-set.js";
+export { ChatModelUnavailable, ChatModelUnavailableReasonSchema, ConversationRoleSchema, Instruction, Message, runToolStep, StructuredChatModel, UnsupportedModelToolSchema, UnsupportedModelToolSchemaReasonSchema, TrustedInstructionSchema, UntrustedMessageSchema, type RunToolStepInput, type StructuredChatModelService, type ToolModelRequest, type TrustedInstruction, type UntrustedMessage, } from "./core/model.js";
+export { defineModelGuard, ModelGuardNameSchema, type DefineModelGuardInput, type ModelGuard, type ModelGuardCall, type ModelGuardCallContext, type ModelGuardContext, type ModelGuardError, type ModelGuardRequirements, type ModelGuardTuple, } from "./core/model-guard.js";
+export { Stage, StageNameSchema, ToolStageAfterExecutionSchema, type DefineToolStageInput, type DefineCommandStageInput, type CommandStage, type ToolStage, type ToolStageAfterExecution, } from "./core/stage.js";
+export { CommandIdSchema, deriveCommandId, type CommandId, type CommandIdentityInput, } from "./core/command.js";
+export { Repair, type StandardRepair, type StandardRepairOptions, } from "./core/repair.js";
+export { Question, type AdaptiveQuestion, type AdaptiveChoiceQuestion, type ChoiceQuestion, type FixedQuestion, type QuestionChoice, type QuestionDefinition, type QuestionDefinitionContract, } from "./core/question.js";
+export { ChatSessionConflict, ChatSessionIdSchema, ChatSessionNamespaceSchema, ChatSessionReplacementSchema, ChatSessionRevisionSchema, ChatSessionSnapshotSchema, ChatSessionStore, ChatSessionStoreUnavailable, ChatSessionStoreUnavailableReasonSchema, InvalidChatSession, InvalidChatSessionReasonSchema, type ChatSessionReplacement, type ChatSessionScope, type ChatSessionSnapshot, type ChatSessionStoreService, type ReplaceChatSessionInput, } from "./core/session.js";
+export { defineView, ViewNameSchema, ViewVersionSchema, type DefineViewInput, type ViewData, type ViewDefinition, type ViewDefinitionContract, type ViewInput, type ViewPart, } from "./core/view.js";
+export { JsonValueSchema, type JsonObject, type JsonPrimitive, type JsonValue, } from "./core/json-value.js";

package/dist/index.js

@@ -0,0 +1,16 @@
+export { AssistantDataPartSchema, AssistantMessagePartSchema, AssistantTextPartSchema, CollectQuestionView, InvalidChatPresentation, presentAnswerValidationRejection, presentChatNotice, presentChatReply, StructuredChatAssistantMessageSchema, StructuredChatSessionReferenceSchema, StructuredChatTurnRequestSchema, StructuredChatTurnResponseSchema, Text, } from "./core/protocol.js";
+export { makeStructuredChatModel, ModelProvider, structuredChatModelLayer, StructuredChatModelIdSchema, StructuredChatProviderIdSchema, StructuredChatRequestTimeoutSchema, } from "./adapters/openai-compatible-model.js";
+export { ChatNameSchema, ChatVersionSchema, defineChat, InvalidChatTransition, InvalidChatTransitionReasonSchema, } from "./core/chat.js";
+export { Answer, AnswerModeSchema, } from "./core/answer.js";
+export { InvalidCollectStageResponse, InvalidCollectStageResponseReasonSchema, AnswerValidationRejected, } from "./core/collect-stage.js";
+export { defineTool, defineCommand, InvalidToolCall, InvalidToolCallReasonSchema, InvalidToolProjection, InvalidToolProjectionReasonSchema, Tool, ToolDescriptionSchema, ToolNameSchema, } from "./core/tool.js";
+export { defineToolSet, } from "./core/tool-set.js";
+export { ChatModelUnavailable, ChatModelUnavailableReasonSchema, ConversationRoleSchema, Instruction, Message, runToolStep, StructuredChatModel, UnsupportedModelToolSchema, UnsupportedModelToolSchemaReasonSchema, TrustedInstructionSchema, UntrustedMessageSchema, } from "./core/model.js";
+export { defineModelGuard, ModelGuardNameSchema, } from "./core/model-guard.js";
+export { Stage, StageNameSchema, ToolStageAfterExecutionSchema, } from "./core/stage.js";
+export { CommandIdSchema, deriveCommandId, } from "./core/command.js";
+export { Repair, } from "./core/repair.js";
+export { Question, } from "./core/question.js";
+export { ChatSessionConflict, ChatSessionIdSchema, ChatSessionNamespaceSchema, ChatSessionReplacementSchema, ChatSessionRevisionSchema, ChatSessionSnapshotSchema, ChatSessionStore, ChatSessionStoreUnavailable, ChatSessionStoreUnavailableReasonSchema, InvalidChatSession, InvalidChatSessionReasonSchema, } from "./core/session.js";
+export { defineView, ViewNameSchema, ViewVersionSchema, } from "./core/view.js";
+export { JsonValueSchema, } from "./core/json-value.js";

package/dist/integrations/assistant-ui.d.ts

@@ -0,0 +1,95 @@
+import { type ComponentType, type FC } from "react";
+import type { ViewData, ViewDefinitionContract } from "../core/view.js";
+import { type StructuredChatSessionReference, type StructuredChatAssistantMessage } from "../core/protocol.js";
+/** Runtime status supplied by assistant-ui to a data-part renderer. */
+export type AssistantViewPartStatus = {
+    readonly type: "running";
+} | {
+    readonly type: "complete";
+} | {
+    readonly type: "incomplete";
+    readonly reason: "cancelled" | "length" | "content-filter" | "other" | "error";
+    readonly error?: unknown;
+} | {
+    readonly type: "requires-action";
+    readonly reason: "interrupt";
+};
+/** Stable data-part props consumed without exposing assistant-ui internals. */
+export interface AssistantDataMessagePartProps<Data = unknown> {
+    readonly type: "data";
+    readonly name: string;
+    readonly data: Data;
+    readonly status: AssistantViewPartStatus;
+}
+/** Parsed props supplied to one schema-bound assistant-ui data renderer. */
+export type AssistantViewRenderProps<View extends ViewDefinitionContract> = Omit<AssistantDataMessagePartProps, "data"> & {
+    readonly data: ViewData<View>;
+};
+/** Renderer and safe fallback for one schema-bound assistant-ui view. */
+export interface AssistantViewConfig<View extends ViewDefinitionContract> {
+    readonly render: ComponentType<AssistantViewRenderProps<View>>;
+    readonly fallback?: ComponentType<AssistantDataMessagePartProps>;
+}
+/** Structural data-UI component returned by assistant-ui registration. */
+export type AssistantDataUI = FC & {
+    readonly unstable_data: {
+        readonly name: string;
+        readonly render: ComponentType<AssistantDataMessagePartProps>;
+    };
+};
+/**
+ * Register one defineView contract as a strictly decoded assistant-ui data UI.
+ *
+ * Unknown or version-mismatched browser data never reaches the application
+ * renderer. It renders the configured fallback, or nothing when omitted.
+ */
+export declare const makeAssistantView: <View extends ViewDefinitionContract>(view: View, config: AssistantViewConfig<View>) => AssistantDataUI;
+/** assistant-ui metadata key carrying the latest opaque session reference. */
+export declare const assistantChatSessionMetadataKey: "popcomputerStructuredChatSession";
+/** Small fetch capability required by the assistant-ui chat adapter. */
+export type AssistantChatFetch = (input: string, init: RequestInit) => Promise<Response>;
+/** Browser dependencies for one structured assistant-ui endpoint. */
+export interface AssistantChatModelAdapterOptions {
+    readonly endpoint: string;
+    readonly fetch?: AssistantChatFetch;
+}
+/** Minimum assistant message shape consumed by the browser adapter. */
+export interface AssistantChatThreadMessage {
+    readonly role: string;
+    readonly content: ReadonlyArray<{
+        readonly type: "text";
+        readonly text: string;
+    } | {
+        readonly type: string;
+    }>;
+    readonly attachments?: ReadonlyArray<unknown>;
+    readonly metadata: {
+        readonly custom: {
+            readonly [assistantChatSessionMetadataKey]?: unknown;
+        };
+    };
+}
+/** Assistant runtime input consumed without importing its nominal types. */
+export interface AssistantChatModelRunInput {
+    readonly messages: ReadonlyArray<AssistantChatThreadMessage>;
+    readonly abortSignal: AbortSignal;
+}
+/** Structural chat adapter that remains compatible across peer installations. */
+export interface AssistantChatModelAdapter {
+    readonly run: (input: AssistantChatModelRunInput) => Promise<{
+        readonly content: StructuredChatAssistantMessage["content"];
+        readonly metadata: {
+            readonly custom: Readonly<Record<never, never>> | {
+                readonly [assistantChatSessionMetadataKey]: StructuredChatSessionReference;
+            };
+        };
+    }>;
+}
+/**
+ * Adapt assistant-ui to one server-owned structured chat endpoint.
+ *
+ * Only the latest text and opaque prior revision cross the browser boundary.
+ * Tools, instructions, history, answer state, and stage position stay server
+ * owned.
+ */
+export declare const makeAssistantChatModelAdapter: (options: AssistantChatModelAdapterOptions) => AssistantChatModelAdapter;

package/dist/integrations/assistant-ui.js

@@ -0,0 +1,114 @@
+import { makeAssistantDataUI, } from "@assistant-ui/core/react";
+import { Either, Schema } from "effect";
+import { createElement } from "react";
+import { StructuredChatSessionReferenceSchema, StructuredChatTurnRequestSchema, StructuredChatTurnResponseSchema, } from "../core/protocol.js";
+/**
+ * Register one defineView contract as a strictly decoded assistant-ui data UI.
+ *
+ * Unknown or version-mismatched browser data never reaches the application
+ * renderer. It renders the configured fallback, or nothing when omitted.
+ */
+export const makeAssistantView = (view, config) => {
+    const Renderer = (props) => {
+        const decoded = Schema.decodeUnknownEither(view.partSchema)({
+            type: "data",
+            name: view.name,
+            data: props.data,
+        }, { onExcessProperty: "error" });
+        if (Either.isLeft(decoded)) {
+            return config.fallback === undefined
+                ? null
+                : createElement(config.fallback, props);
+        }
+        return createElement(config.render, {
+            ...props,
+            data: decoded.right.data,
+        });
+    };
+    return makeAssistantDataUI({
+        name: view.name,
+        render: Renderer,
+    });
+};
+/** assistant-ui metadata key carrying the latest opaque session reference. */
+export const assistantChatSessionMetadataKey = "popcomputerStructuredChatSession";
+const readMessageText = (message) => message.content
+    .flatMap((part) => part.type === "text" && "text" in part ? [part.text] : [])
+    .join("\n")
+    .trim();
+const readLatestSession = (messages) => {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message?.role !== "assistant") {
+            continue;
+        }
+        const session = Schema.decodeUnknownEither(StructuredChatSessionReferenceSchema)(message.metadata.custom[assistantChatSessionMetadataKey]);
+        if (Either.isRight(session)) {
+            return session.right;
+        }
+    }
+    return undefined;
+};
+const readTurnRequest = (messages) => {
+    const message = messages.at(-1);
+    if (message?.role !== "user") {
+        throw new Error("A user message is required");
+    }
+    if ((message.attachments?.length ?? 0) > 0) {
+        throw new Error("Attachments are not supported");
+    }
+    return Schema.decodeSync(StructuredChatTurnRequestSchema)({
+        session: readLatestSession(messages),
+        message: readMessageText(message),
+    });
+};
+/**
+ * Adapt assistant-ui to one server-owned structured chat endpoint.
+ *
+ * Only the latest text and opaque prior revision cross the browser boundary.
+ * Tools, instructions, history, answer state, and stage position stay server
+ * owned.
+ */
+export const makeAssistantChatModelAdapter = (options) => {
+    const fetch_ = options.fetch ??
+        ((input, init) => globalThis.fetch(input, init));
+    return {
+        run: async ({ messages, abortSignal }) => {
+            const request = readTurnRequest(messages);
+            const response = await fetch_(options.endpoint, {
+                method: "POST",
+                credentials: "same-origin",
+                headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify(request),
+                signal: abortSignal,
+            });
+            if (!response.ok) {
+                throw new Error("Structured chat is temporarily unavailable");
+            }
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                throw new Error("Structured chat returned an invalid response");
+            }
+            const decoded = Schema.decodeUnknownEither(StructuredChatTurnResponseSchema)(body, { onExcessProperty: "error" });
+            if (Either.isLeft(decoded)) {
+                throw new Error("Structured chat returned an invalid response");
+            }
+            return {
+                content: decoded.right.message.content,
+                metadata: {
+                    custom: decoded.right.session === undefined
+                        ? {}
+                        : {
+                            [assistantChatSessionMetadataKey]: decoded.right.session,
+                        },
+                },
+            };
+        },
+    };
+};

package/dist/testing/in-memory-session-store.d.ts

@@ -0,0 +1,4 @@
+import { Layer } from "effect";
+import { ChatSessionStore } from "../core/session.js";
+/** In-memory optimistic session store intended for tests and examples. */
+export declare const inMemoryChatSessionStore: Layer.Layer<ChatSessionStore>;

package/dist/testing/in-memory-session-store.js

@@ -0,0 +1,38 @@
+import { Effect, Layer, Ref } from "effect";
+import { ChatSessionConflict, ChatSessionStore, } from "../core/session.js";
+const scopeKey = (scope) => JSON.stringify([
+    scope.chat,
+    scope.version,
+    scope.namespace,
+    scope.sessionId,
+]);
+const nextRevision = (current) => current === undefined
+    ? "1"
+    : String(Number.parseInt(current.revision, 10) + 1);
+const replaceSnapshot = (sessions, input) => {
+    const key = scopeKey(input);
+    const current = sessions.get(key);
+    if ((current === undefined && input.expectedRevision !== null) ||
+        (current !== undefined &&
+            input.expectedRevision !== current.revision)) {
+        return [
+            new ChatSessionConflict({ reason: "concurrent_update" }),
+            sessions,
+        ];
+    }
+    const snapshot = {
+        revision: nextRevision(current),
+        state: input.state,
+        messages: input.messages,
+    };
+    const next = new Map(sessions);
+    next.set(key, snapshot);
+    return [snapshot, next];
+};
+/** In-memory optimistic session store intended for tests and examples. */
+export const inMemoryChatSessionStore = Layer.effect(ChatSessionStore, Ref.make(new Map()).pipe(Effect.map((sessions) => ({
+    load: (scope) => Ref.get(sessions).pipe(Effect.map((current) => current.get(scopeKey(scope)) ?? null)),
+    replace: (input) => Ref.modify(sessions, (current) => replaceSnapshot(current, input)).pipe(Effect.flatMap((result) => result instanceof ChatSessionConflict
+        ? Effect.fail(result)
+        : Effect.succeed({ revision: result.revision }))),
+}))));

package/dist/testing/scenario.d.ts

@@ -0,0 +1,59 @@
+import { Layer, Schema } from "effect";
+import type { AnswerFields, CollectAnswers, CollectStage } from "../core/collect-stage.js";
+import { StructuredChatModel, type ToolModelRequest } from "../core/model.js";
+import type { ModelGuardTuple } from "../core/model-guard.js";
+import type { StructuredTool, ToolDefinitionContract } from "../core/tool.js";
+import { type JsonValue } from "../core/json-value.js";
+declare const scenarioQuote: unique symbol;
+/** One typed scenario value paired with its exact supporting user quote. */
+export interface ScenarioQuote<Value> {
+    readonly value: Value;
+    readonly quote: string;
+    readonly messageIndex?: number;
+    readonly [scenarioQuote]: true;
+}
+interface ScenarioStep {
+    readonly respond: (request: ToolModelRequest) => JsonValue;
+}
+type QuotedAnswers<Fields extends AnswerFields> = Partial<{
+    readonly [Field in keyof Fields]: ScenarioQuote<CollectAnswers<Fields>[Field]>;
+}>;
+type ScenarioNextQuestion<Fields extends AnswerFields> = {
+    readonly field: keyof Fields & string;
+    readonly text: string;
+    readonly options?: ReadonlyArray<{
+        readonly label: string;
+    }>;
+};
+type ReplaceableField<Fields extends AnswerFields> = {
+    [Field in keyof Fields & string]: Fields[Field]["mode"] extends "confirmed" ? never : Field;
+}[keyof Fields & string];
+type ConfirmedField<Fields extends AnswerFields> = {
+    [Field in keyof Fields & string]: Fields[Field]["mode"] extends "confirmed" ? Field : never;
+}[keyof Fields & string];
+interface ScenarioRepair {
+    readonly respond: (request: ToolModelRequest) => JsonValue;
+}
+type ToolInput<Tool> = Tool extends StructuredTool<infer _Name, infer InputSchema, infer _ServerResult, infer _Error, infer _Requirements, infer _ModelSchema, infer _Presenters, infer _Operation> ? Schema.Schema.Type<InputSchema> : never;
+/** Typed constructors for concise valid transcript scenarios. */
+export declare const Scenario: {
+    readonly quoted: <Value>(value: Value, options: {
+        readonly quote: string;
+        readonly messageIndex?: number;
+    }) => ScenarioQuote<Value>;
+    readonly answers: <const Name extends string, const Fields extends AnswerFields, const Guards extends ModelGuardTuple>(stage: CollectStage<Name, Fields, Guards>, proposed: QuotedAnswers<Fields>, options?: {
+        readonly nextQuestion?: ScenarioNextQuestion<Fields> | null;
+    }) => ScenarioStep;
+    readonly call: <Tool extends ToolDefinitionContract>(tool: Tool, input: ToolInput<Tool>) => ScenarioStep;
+    readonly replace: <const Name extends string, const Fields extends AnswerFields, const Guards extends ModelGuardTuple, const Field extends ReplaceableField<Fields>>(stage: CollectStage<Name, Fields, Guards>, field: Field, value: CollectAnswers<Fields>[Field], options: {
+        readonly quote: string;
+        readonly messageIndex?: number;
+    }) => ScenarioRepair;
+    readonly reconfirm: <const Name extends string, const Fields extends AnswerFields, const Guards extends ModelGuardTuple, const Field extends ConfirmedField<Fields>>(stage: CollectStage<Name, Fields, Guards>, field: Field, options: {
+        readonly quote: string;
+        readonly messageIndex?: number;
+    }) => ScenarioRepair;
+    readonly repairs: (first: ScenarioRepair, ...remaining: ReadonlyArray<ScenarioRepair>) => ScenarioStep;
+    readonly model: (first: ScenarioStep, ...remaining: ReadonlyArray<ScenarioStep>) => Layer.Layer<StructuredChatModel>;
+};
+export {};

package/dist/testing/scenario.js

@@ -0,0 +1,147 @@
+import { Effect, Layer, Ref, Schema } from "effect";
+import { StructuredChatModel, } from "../core/model.js";
+import { JsonValueSchema, } from "../core/json-value.js";
+const scenarioQuote = Symbol("@popcomputer/structured-chat/testing/ScenarioQuote");
+const ScenarioQuoteSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(2_000));
+const evidenceIndex = (request, quoted) => {
+    if (quoted.messageIndex !== undefined) {
+        const message = request.untrustedMessages[quoted.messageIndex];
+        if (message === undefined ||
+            message.role !== "user" ||
+            !message.content.includes(quoted.quote)) {
+            throw new Error(`Scenario quote does not match user message ${quoted.messageIndex}`);
+        }
+        return quoted.messageIndex;
+    }
+    const matches = request.untrustedMessages.flatMap((message, index) => message.role === "user" && message.content.includes(quoted.quote)
+        ? [index]
+        : []);
+    if (matches.length !== 1) {
+        throw new Error(`Scenario quote must match exactly one user message; matched ${matches.length}`);
+    }
+    const match = matches[0];
+    if (match === undefined) {
+        throw new Error("Scenario quote match disappeared");
+    }
+    return match;
+};
+const quoted = (value, options) => {
+    const base = {
+        value,
+        quote: Schema.decodeSync(ScenarioQuoteSchema)(options.quote),
+        [scenarioQuote]: true,
+    };
+    return options.messageIndex === undefined
+        ? base
+        : { ...base, messageIndex: options.messageIndex };
+};
+const answers = (stage, proposed, options = {}) => ({
+    respond: (request) => {
+        const encodedAnswers = {};
+        for (const field of Object.keys(stage.fields)) {
+            encodedAnswers[field] = null;
+        }
+        const evidence = [];
+        // SAFETY: proposed is a mapped type whose only keys are Fields keys.
+        for (const field of Object.keys(proposed)) {
+            const value = proposed[field];
+            const answer = stage.fields[field];
+            if (value === undefined || answer === undefined) {
+                continue;
+            }
+            encodedAnswers[field] = Schema.decodeSync(JsonValueSchema)(Schema.encodeSync(answer.schema)(value.value));
+            evidenceIndex(request, value);
+            evidence.push({
+                field,
+                quote: value.quote,
+            });
+        }
+        return {
+            name: "submit_answers",
+            arguments: {
+                answers: encodedAnswers,
+                evidence,
+                nextQuestion: options.nextQuestion === undefined ||
+                    options.nextQuestion === null
+                    ? null
+                    : {
+                        field: options.nextQuestion.field,
+                        text: options.nextQuestion.text,
+                        options: options.nextQuestion.options?.map(({ label }) => label) ?? [],
+                    },
+            },
+        };
+    },
+});
+const call = (tool, input) => ({
+    respond: () => ({
+        name: tool.name,
+        arguments: Schema.decodeSync(JsonValueSchema)(Schema.encodeSync(tool.inputSchema)(input)),
+    }),
+});
+const replace = (stage, field, value, options) => {
+    const support = quoted(value, options);
+    const answer = stage.fields[field];
+    if (answer === undefined) {
+        throw new Error(`Unknown scenario repair field: ${String(field)}`);
+    }
+    return {
+        respond: (request) => {
+            evidenceIndex(request, support);
+            return {
+                _tag: "ReplaceAcceptedAnswer",
+                stage: stage.name,
+                field,
+                value: Schema.decodeSync(JsonValueSchema)(Schema.encodeSync(answer.schema)(value)),
+                evidence: {
+                    quote: support.quote,
+                },
+            };
+        },
+    };
+};
+const reconfirm = (stage, field, options) => {
+    const support = quoted(undefined, options);
+    return {
+        respond: (request) => {
+            evidenceIndex(request, support);
+            return {
+                _tag: "ReconfirmAnswer",
+                stage: stage.name,
+                field,
+                evidence: {
+                    quote: support.quote,
+                },
+            };
+        },
+    };
+};
+const repairs = (first, ...remaining) => ({
+    respond: (request) => ({
+        name: "apply_conversation_repairs",
+        arguments: {
+            corrections: [first, ...remaining].map((repair) => repair.respond(request)),
+        },
+    }),
+});
+const model = (first, ...remaining) => Layer.effect(StructuredChatModel, Ref.make(0).pipe(Effect.map((cursor) => {
+    const steps = [first, ...remaining];
+    return {
+        requestTool: (request) => Ref.getAndUpdate(cursor, (index) => index + 1).pipe(Effect.flatMap((index) => {
+            const step = steps[index];
+            return step === undefined
+                ? Effect.die(new Error(`Scenario model exhausted after ${steps.length} requests`))
+                : Effect.sync(() => step.respond(request));
+        })),
+    };
+})));
+/** Typed constructors for concise valid transcript scenarios. */
+export const Scenario = {
+    quoted,
+    answers,
+    call,
+    replace,
+    reconfirm,
+    repairs,
+    model,
+};

package/dist/testing.d.ts

@@ -0,0 +1,4 @@
+export type { StructuredTool, ToolCall, ToolExecution, } from "./core/tool.js";
+export type { ViewData, ViewDefinition, ViewPart, } from "./core/view.js";
+export { inMemoryChatSessionStore } from "./testing/in-memory-session-store.js";
+export { Scenario, type ScenarioQuote, } from "./testing/scenario.js";

package/dist/testing.js

@@ -0,0 +1,2 @@
+export { inMemoryChatSessionStore } from "./testing/in-memory-session-store.js";
+export { Scenario, } from "./testing/scenario.js";

package/examples/agency-search.ts

@@ -0,0 +1,101 @@
+import {
+  Context,
+  Effect,
+  Layer,
+  Schema,
+} from "effect"
+import {
+  defineTool,
+  defineView,
+  Message,
+  Stage,
+  Tool,
+} from "@popcomputer/structured-chat"
+
+interface AgencyMatch {
+  readonly id: string
+  readonly name: string
+  readonly reason: string
+  readonly internalScore: number
+  readonly retrievedText: string
+}
+
+class AgencyCatalog extends Context.Tag("AgencyCatalog")<
+  AgencyCatalog,
+  {
+    readonly search: (
+      query: string,
+    ) => Effect.Effect<ReadonlyArray<AgencyMatch>>
+  }
+>() {}
+
+const AgencyCards = defineView({
+  name: "agency_cards",
+  version: 1,
+  schema: Schema.Struct({
+    agencies: Schema.Array(
+      Schema.Struct({
+        id: Schema.String,
+        name: Schema.String,
+        reason: Schema.String,
+      }),
+    ),
+  }),
+})
+
+const AgencyEvidence = Schema.Struct({
+  matches: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      reason: Schema.String,
+    }),
+  ),
+})
+
+export const SearchAgencies = defineTool({
+  name: "search_agencies",
+  description: "Find agencies relevant to the project.",
+  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
+  execute: ({ query }) =>
+    AgencyCatalog.pipe(
+      Effect.flatMap((catalog) => catalog.search(query)),
+    ),
+}).pipe(
+  Tool.modelResult(AgencyEvidence, (matches) => ({
+    matches: matches.map(({ id, reason }) => ({ id, reason })),
+  })),
+  Tool.present(AgencyCards, (matches) => ({
+    agencies: matches.map(({ id, name, reason }) => ({
+      id,
+      name,
+      reason,
+    })),
+  })),
+)
+
+export const Matching = Stage.tools({
+  name: "matching",
+  instructions: ["Route the project brief to one agency search."],
+  tools: [SearchAgencies],
+})
+
+const AgencyCatalogLive = Layer.succeed(AgencyCatalog, {
+  search: () =>
+    Effect.succeed([
+      {
+        id: "agency:1",
+        name: "Northbank",
+        reason: "Relevant public-sector transformation work.",
+        internalScore: 0.93,
+        retrievedText: "Untrusted source text remains server-side.",
+      },
+    ]),
+})
+
+export const example = SearchAgencies.execute({
+  query: "A public-sector digital service",
+}).pipe(Effect.provide(AgencyCatalogLive))
+
+export const stageExample = Matching.run([
+  Message.user("We need a public-sector digital service."),
+])