@popcomputer/structured-chat 0.1.0

package/dist/adapters/openai-compatible-model.d.ts

@@ -0,0 +1,89 @@
+import { Layer, Schema } from "effect";
+import { StructuredChatModel, type ChatModelUnavailableReasonSchema, type StructuredChatModelService } from "../core/model.js";
+import type { ModelToolDefinition } from "../core/tool.js";
+import { type JsonValue } from "../core/json-value.js";
+/** Bounded timeout for one provider tool-call request. */
+export declare const StructuredChatRequestTimeoutSchema: Schema.filter<Schema.filter<typeof Schema.Number>>;
+interface OpenAICompatibleMessage {
+    readonly role: "system" | "user";
+    readonly content: string;
+}
+interface OpenAICompatibleTool {
+    readonly type: "function";
+    readonly function: {
+        readonly name: string;
+        readonly description: string;
+        readonly parameters: ModelToolDefinition["inputSchema"];
+        readonly strict?: true;
+    };
+}
+type OpenAICompatibleInputValue = JsonValue | ReadonlyArray<OpenAICompatibleMessage> | ReadonlyArray<OpenAICompatibleTool>;
+interface OpenAICompatibleInput {
+    readonly [key: string]: OpenAICompatibleInputValue;
+}
+declare const OpenAICompatibleToolArgumentsSchema: Schema.Literal<["guided", "strict"]>;
+type OpenAICompatibleToolArguments = Schema.Schema.Type<typeof OpenAICompatibleToolArgumentsSchema>;
+/** Bounded provider model identifier used for routing and diagnostics. */
+export declare const StructuredChatModelIdSchema: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+/** Bounded provider model identifier used for routing and diagnostics. */
+export type StructuredChatModelId = Schema.Schema.Type<typeof StructuredChatModelIdSchema>;
+/** One provider request with its parsed model identifier. */
+export interface StructuredChatProviderRequest {
+    readonly model: StructuredChatModelId;
+    readonly input: OpenAICompatibleInput;
+}
+interface OpenAICompatibleProviderConfig {
+    readonly model: string;
+    readonly complete: (request: StructuredChatProviderRequest, signal: AbortSignal) => Promise<JsonValue>;
+    readonly requestOptions?: Readonly<Record<string, JsonValue>>;
+}
+/** Configuration for the built-in Cloudflare Workers AI provider. */
+export interface CloudflareWorkersAIProviderConfig extends OpenAICompatibleProviderConfig {
+}
+/** Configuration for the built-in OpenAI provider. */
+export interface OpenAIProviderConfig extends OpenAICompatibleProviderConfig {
+}
+/** Stable identifier for a built-in model provider. */
+export declare const StructuredChatProviderIdSchema: Schema.Literal<["cloudflare-workers-ai", "openai"]>;
+/** Stable identifier for a built-in model provider. */
+export type StructuredChatProviderId = Schema.Schema.Type<typeof StructuredChatProviderIdSchema>;
+interface StructuredChatProviderRuntime {
+    readonly toolArguments: OpenAICompatibleToolArguments;
+    readonly complete: (input: OpenAICompatibleInput, signal: AbortSignal) => Promise<JsonValue>;
+    readonly requestOptions: Readonly<Record<string, JsonValue>>;
+}
+declare const StructuredChatProviderRuntime: unique symbol;
+/** Opaque provider definition consumed by the structured model adapter. */
+export interface StructuredChatProvider {
+    readonly id: StructuredChatProviderId;
+    readonly model: StructuredChatModelId;
+    readonly [StructuredChatProviderRuntime]: StructuredChatProviderRuntime;
+}
+/** Configuration for one provider-backed structured chat model. */
+export interface StructuredChatModelConfig {
+    readonly provider: StructuredChatProvider;
+    readonly timeoutMilliseconds: number;
+    readonly classifyError?: (cause: unknown) => Schema.Schema.Type<typeof ChatModelUnavailableReasonSchema>;
+}
+/** Built-in provider definitions that own their tool-call guarantees. */
+export declare const ModelProvider: {
+    /**
+     * Define a Cloudflare Workers AI model.
+     *
+     * Workers AI schemas guide generation but are always validated after the
+     * response because Cloudflare does not guarantee schema-constrained output.
+     */
+    readonly cloudflareWorkersAI: (config: CloudflareWorkersAIProviderConfig) => StructuredChatProvider;
+    /**
+     * Define an OpenAI model.
+     *
+     * Known Structured Outputs model families use strict function arguments.
+     * Unknown and older model identifiers conservatively use schema guidance.
+     */
+    readonly openAI: (config: OpenAIProviderConfig) => StructuredChatProvider;
+};
+/** Build a structured chat model around one provider definition. */
+export declare const makeStructuredChatModel: (config: StructuredChatModelConfig) => StructuredChatModelService;
+/** Build an Effect layer for one provider-backed structured chat model. */
+export declare const structuredChatModelLayer: (config: StructuredChatModelConfig) => Layer.Layer<StructuredChatModel>;
+export {};

package/dist/adapters/openai-compatible-model.js

@@ -0,0 +1,231 @@
+import { Effect, Either, Layer, Schema } from "effect";
+import { ChatModelUnavailable, StructuredChatModel, UnsupportedModelToolSchema, } from "../core/model.js";
+import { JsonValueSchema, } from "../core/json-value.js";
+/** Bounded timeout for one provider tool-call request. */
+export const StructuredChatRequestTimeoutSchema = Schema.Number.pipe(Schema.int(), Schema.between(1, 60_000));
+const OpenAICompatibleToolArgumentsSchema = Schema.Literal("guided", "strict");
+/** Bounded provider model identifier used for routing and diagnostics. */
+export const StructuredChatModelIdSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(200));
+/** Stable identifier for a built-in model provider. */
+export const StructuredChatProviderIdSchema = Schema.Literal("cloudflare-workers-ai", "openai");
+const StructuredChatProviderRuntime = Symbol("@popcomputer/structured-chat/StructuredChatProviderRuntime");
+const openAIModelSupportsStrictToolArguments = (model) => /^(?:chat-latest$|gpt-4o(?:-|$)|gpt-4\.1(?:-|$)|gpt-5(?:[.-]|$)|o3(?:-|$)|o4(?:-|$))/u.test(model);
+const makeProvider = (id, config, toolArguments) => {
+    const model = Schema.decodeSync(StructuredChatModelIdSchema)(config.model);
+    return {
+        id,
+        model,
+        [StructuredChatProviderRuntime]: {
+            toolArguments,
+            requestOptions: config.requestOptions ?? {},
+            complete: (input, signal) => config.complete({ model, input }, signal),
+        },
+    };
+};
+/** Built-in provider definitions that own their tool-call guarantees. */
+export const ModelProvider = {
+    /**
+     * Define a Cloudflare Workers AI model.
+     *
+     * Workers AI schemas guide generation but are always validated after the
+     * response because Cloudflare does not guarantee schema-constrained output.
+     */
+    cloudflareWorkersAI: (config) => makeProvider("cloudflare-workers-ai", config, "guided"),
+    /**
+     * Define an OpenAI model.
+     *
+     * Known Structured Outputs model families use strict function arguments.
+     * Unknown and older model identifiers conservatively use schema guidance.
+     */
+    openAI: (config) => {
+        const model = Schema.decodeSync(StructuredChatModelIdSchema)(config.model);
+        return makeProvider("openai", { ...config, model }, openAIModelSupportsStrictToolArguments(model)
+            ? "strict"
+            : "guided");
+    },
+};
+const ToolCallResponseSchema = Schema.Struct({
+    choices: Schema.Tuple(Schema.Struct({
+        message: Schema.Struct({
+            tool_calls: Schema.Tuple(Schema.Struct({
+                function: Schema.Struct({
+                    name: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100)),
+                    arguments: Schema.String.pipe(Schema.maxLength(20_000)),
+                }),
+            })),
+        }),
+    })),
+});
+const unavailable = (reason) => new ChatModelUnavailable({ reason });
+const parseJson = (input) => Effect.try({
+    // SAFETY: JSON.parse without a reviver can only return a JSON value when
+    // parsing succeeds; failures are mapped to the typed unavailable reason.
+    try: () => JSON.parse(input),
+    catch: () => unavailable("invalid_response"),
+});
+const JsonSchemaObjectSchema = Schema.Record({
+    key: Schema.String,
+    value: JsonValueSchema,
+});
+const isJsonSchemaObject = (value) => Schema.is(JsonSchemaObjectSchema)(value);
+const appendJsonPointer = (path, segment) => `${path}/${segment.replaceAll("~", "~0").replaceAll("/", "~1")}`;
+const findStrictObjectIssue = (schema, path) => {
+    const objectSchema = schema.type === "object" || isJsonSchemaObject(schema.properties);
+    if (objectSchema) {
+        if (schema.additionalProperties !== false) {
+            return {
+                path,
+                reason: "additional_properties_allowed",
+            };
+        }
+        const properties = isJsonSchemaObject(schema.properties)
+            ? schema.properties
+            : {};
+        const required = Array.isArray(schema.required)
+            ? new Set(schema.required.filter(Schema.is(Schema.String)))
+            : new Set();
+        for (const property of Object.keys(properties)) {
+            if (!required.has(property)) {
+                return {
+                    path: appendJsonPointer(appendJsonPointer(path, "properties"), property),
+                    reason: "optional_property",
+                };
+            }
+        }
+        for (const [property, propertySchema] of Object.entries(properties)) {
+            if (!isJsonSchemaObject(propertySchema)) {
+                continue;
+            }
+            const issue = findStrictObjectIssue(propertySchema, appendJsonPointer(appendJsonPointer(path, "properties"), property));
+            if (issue !== undefined) {
+                return issue;
+            }
+        }
+    }
+    for (const definitionKey of ["$defs", "definitions"]) {
+        const definitions = schema[definitionKey];
+        if (!isJsonSchemaObject(definitions)) {
+            continue;
+        }
+        for (const [name, definition] of Object.entries(definitions)) {
+            if (!isJsonSchemaObject(definition)) {
+                continue;
+            }
+            const issue = findStrictObjectIssue(definition, appendJsonPointer(appendJsonPointer(path, definitionKey), name));
+            if (issue !== undefined) {
+                return issue;
+            }
+        }
+    }
+    for (const unionKey of ["allOf", "anyOf", "oneOf"]) {
+        const members = schema[unionKey];
+        if (!Array.isArray(members)) {
+            continue;
+        }
+        for (const [index, member] of members.entries()) {
+            if (!isJsonSchemaObject(member)) {
+                continue;
+            }
+            const issue = findStrictObjectIssue(member, appendJsonPointer(appendJsonPointer(path, unionKey), String(index)));
+            if (issue !== undefined) {
+                return issue;
+            }
+        }
+    }
+    const items = schema.items;
+    if (isJsonSchemaObject(items)) {
+        return findStrictObjectIssue(items, appendJsonPointer(path, "items"));
+    }
+    return undefined;
+};
+const findStrictSchemaIssue = (schema) => {
+    if (schema.type !== "object") {
+        return { path: "#", reason: "root_not_object" };
+    }
+    return findStrictObjectIssue(schema, "#");
+};
+const strictToolIssue = (tool) => {
+    const parsedSchema = Schema.decodeUnknownEither(JsonSchemaObjectSchema)(tool.inputSchema, { onExcessProperty: "error" });
+    if (Either.isLeft(parsedSchema)) {
+        return new UnsupportedModelToolSchema({
+            tool: tool.name,
+            path: "#",
+            reason: "root_not_object",
+        });
+    }
+    const issue = findStrictSchemaIssue(parsedSchema.right);
+    return issue === undefined
+        ? undefined
+        : new UnsupportedModelToolSchema({
+            tool: tool.name,
+            path: issue.path,
+            reason: issue.reason,
+        });
+};
+const toProviderTool = (tool, toolArguments) => ({
+    type: "function",
+    function: toolArguments === "strict"
+        ? {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+            strict: true,
+        }
+        : {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+        },
+});
+const toProviderInput = (request, requestOptions, toolArguments) => {
+    if (toolArguments === "strict") {
+        const unsupported = request.tools
+            .map(strictToolIssue)
+            .find((issue) => issue !== undefined);
+        if (unsupported !== undefined) {
+            return Effect.fail(unsupported);
+        }
+    }
+    return Effect.succeed({
+        ...requestOptions,
+        messages: [
+            {
+                role: "system",
+                content: request.instructions.join("\n\n"),
+            },
+            {
+                role: "user",
+                content: JSON.stringify({
+                    untrustedConversation: request.untrustedMessages,
+                }),
+            },
+        ],
+        tools: request.tools.map((tool) => toProviderTool(tool, toolArguments)),
+        tool_choice: "required",
+        parallel_tool_calls: false,
+        stream: false,
+    });
+};
+/** Build a structured chat model around one provider definition. */
+export const makeStructuredChatModel = (config) => {
+    const timeoutMilliseconds = Schema.decodeSync(StructuredChatRequestTimeoutSchema)(config.timeoutMilliseconds);
+    const runtime = config.provider[StructuredChatProviderRuntime];
+    const classifyError = config.classifyError ?? (() => "request_failed");
+    return {
+        requestTool: (request) => toProviderInput(request, runtime.requestOptions, runtime.toolArguments).pipe(Effect.flatMap((input) => Effect.tryPromise({
+            try: (signal) => runtime.complete(input, signal),
+            catch: (cause) => unavailable(classifyError(cause)),
+        })), Effect.timeoutFail({
+            duration: timeoutMilliseconds,
+            onTimeout: () => unavailable("timed_out"),
+        }), Effect.flatMap((response) => Schema.decodeUnknown(ToolCallResponseSchema)(response).pipe(Effect.mapError(() => unavailable("invalid_response")))), Effect.flatMap((response) => {
+            const tool = response.choices[0].message.tool_calls[0].function;
+            return parseJson(tool.arguments).pipe(Effect.map((arguments_) => ({
+                name: tool.name,
+                arguments: arguments_,
+            })));
+        })),
+    };
+};
+/** Build an Effect layer for one provider-backed structured chat model. */
+export const structuredChatModelLayer = (config) => Layer.succeed(StructuredChatModel, makeStructuredChatModel(config));

package/dist/core/answer.d.ts

@@ -0,0 +1,73 @@
+import { Effect, Schema } from "effect";
+import type { ChoiceQuestion, FixedQuestion, QuestionDefinition, QuestionDefinitionContract } from "./question.js";
+/** How strongly a collect-stage answer must be grounded in user messages. */
+export declare const AnswerModeSchema: Schema.Literal<["semantic", "explicit", "confirmed"]>;
+/** How strongly a collect-stage answer must be grounded in user messages. */
+export type AnswerMode = Schema.Schema.Type<typeof AnswerModeSchema>;
+/** Minimum runtime shape retained for every collect-stage answer. */
+export interface AnswerDefinitionContract {
+    readonly _tag: "AnswerDefinition";
+    readonly mode: AnswerMode;
+    readonly schema: Schema.Schema.AnyNoContext;
+    readonly description: string;
+    readonly question: QuestionDefinitionContract;
+    readonly validate?: (value: never) => Effect.Effect<void, unknown, unknown>;
+    readonly reject?: {
+        readonly ask: FixedQuestion | ChoiceQuestion<unknown>;
+    };
+    readonly escape?: {
+        readonly value: unknown;
+    };
+}
+/** One typed fact required by a collect stage. */
+export interface AnswerDefinition<Mode extends AnswerMode, ValueSchema extends Schema.Schema.AnyNoContext, Error = never, Requirements = never> extends AnswerDefinitionContract {
+    readonly mode: Mode;
+    readonly schema: ValueSchema;
+    readonly question: QuestionDefinition<Schema.Schema.Type<ValueSchema>>;
+    readonly validate?: (value: Schema.Schema.Type<ValueSchema>) => Effect.Effect<void, Error, Requirements>;
+    readonly reject?: {
+        readonly ask: FixedQuestion | ChoiceQuestion<Schema.Schema.Type<ValueSchema>>;
+    };
+    readonly escape?: {
+        readonly value: Schema.Schema.Type<ValueSchema>;
+    };
+}
+interface DefineAnswerBase<Value> {
+    readonly description: string;
+    readonly ask: QuestionDefinition<Value>;
+    /**
+     * Application-authored value accepted when the user chooses the stage's
+     * uncertainty escape for this field. Without it, an escaped field stays
+     * unresolved and its question is asked again from another angle.
+     */
+    readonly escape?: {
+        readonly value: Value;
+    };
+}
+/** Configuration for an answer accepted solely by its structural schema. */
+export interface DefineUnvalidatedAnswerInput<Value> extends DefineAnswerBase<Value> {
+    readonly validate?: undefined;
+    readonly reject?: undefined;
+}
+/** Configuration for Effect-native domain acceptance and deterministic retry. */
+export interface DefineValidatedAnswerInput<Value, Error, Requirements> extends DefineAnswerBase<Value> {
+    readonly validate: (value: Value) => Effect.Effect<void, Error, Requirements>;
+    readonly reject: {
+        readonly ask: FixedQuestion | ChoiceQuestion<Value>;
+    };
+}
+/** Configuration shared by all answer grounding modes. */
+export type DefineAnswerInput<Value, Error = never, Requirements = never> = DefineUnvalidatedAnswerInput<Value> | DefineValidatedAnswerInput<Value, Error, Requirements>;
+declare function semantic<ValueSchema extends Schema.Schema.AnyNoContext>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<Schema.Schema.Type<ValueSchema>>): AnswerDefinition<"semantic", ValueSchema, never, never>;
+declare function semantic<ValueSchema extends Schema.Schema.AnyNoContext, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<Schema.Schema.Type<ValueSchema>, Error, Requirements>): AnswerDefinition<"semantic", ValueSchema, Error, Requirements>;
+declare function explicit<ValueSchema extends Schema.Schema.AnyNoContext>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<Schema.Schema.Type<ValueSchema>>): AnswerDefinition<"explicit", ValueSchema, never, never>;
+declare function explicit<ValueSchema extends Schema.Schema.AnyNoContext, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<Schema.Schema.Type<ValueSchema>, Error, Requirements>): AnswerDefinition<"explicit", ValueSchema, Error, Requirements>;
+declare function confirmed<ValueSchema extends Schema.Schema.AnyNoContext>(schema: ValueSchema, input: DefineUnvalidatedAnswerInput<Schema.Schema.Type<ValueSchema>>): AnswerDefinition<"confirmed", ValueSchema, never, never>;
+declare function confirmed<ValueSchema extends Schema.Schema.AnyNoContext, Error, Requirements>(schema: ValueSchema, input: DefineValidatedAnswerInput<Schema.Schema.Type<ValueSchema>, Error, Requirements>): AnswerDefinition<"confirmed", ValueSchema, Error, Requirements>;
+/** Constructors for semantic, explicit, and explicitly confirmed facts. */
+export declare const Answer: {
+    readonly semantic: typeof semantic;
+    readonly explicit: typeof explicit;
+    readonly confirmed: typeof confirmed;
+};
+export {};

package/dist/core/answer.js

@@ -0,0 +1,60 @@
+import { Effect, Schema } from "effect";
+/** How strongly a collect-stage answer must be grounded in user messages. */
+export const AnswerModeSchema = Schema.Literal("semantic", "explicit", "confirmed");
+const AnswerDescriptionSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(1_000));
+const defineAnswer = (mode, schema, input) => {
+    if (input.ask._tag === "ChoiceQuestion") {
+        for (const option of input.ask.options) {
+            Schema.decodeSync(schema)(option.value);
+        }
+    }
+    if (input.ask._tag === "AdaptiveChoiceQuestion") {
+        // A selected fallback label is later submitted as this answer's wire
+        // value, so every label must decode against the answer schema.
+        for (const label of input.ask.fallbackOptions) {
+            Schema.decodeSync(schema)(label);
+        }
+    }
+    if (input.reject?.ask._tag === "ChoiceQuestion") {
+        for (const option of input.reject.ask.options) {
+            Schema.decodeSync(schema)(option.value);
+        }
+    }
+    const base = {
+        _tag: "AnswerDefinition",
+        mode,
+        schema,
+        description: Schema.decodeSync(AnswerDescriptionSchema)(input.description),
+        question: input.ask,
+    };
+    const withEscape = input.escape === undefined
+        ? base
+        : {
+            ...base,
+            escape: {
+                value: Schema.validateSync(schema)(input.escape.value),
+            },
+        };
+    return input.validate === undefined
+        ? withEscape
+        : {
+            ...withEscape,
+            validate: input.validate,
+            reject: input.reject,
+        };
+};
+function semantic(schema, input) {
+    return defineAnswer("semantic", schema, input);
+}
+function explicit(schema, input) {
+    return defineAnswer("explicit", schema, input);
+}
+function confirmed(schema, input) {
+    return defineAnswer("confirmed", schema, input);
+}
+/** Constructors for semantic, explicit, and explicitly confirmed facts. */
+export const Answer = {
+    semantic,
+    explicit,
+    confirmed,
+};

package/dist/core/chat.d.ts

@@ -0,0 +1,124 @@
+import { Effect, Schema } from "effect";
+import type * as ParseResult from "effect/ParseResult";
+import type { AcceptedAnswer, CollectAnswers, CollectStage, CollectStageDefinitionContract, CollectStagePrompt, CollectStageState } from "./collect-stage.js";
+import { type UntrustedMessage } from "./model.js";
+import { type CommandStage, type CommandStageDefinitionContract, type ToolStage, type ToolStageDefinitionContract } from "./stage.js";
+import type { ToolSetExecution } from "./tool-set.js";
+import type { StandardRepair } from "./repair.js";
+import { ChatSessionConflict, ChatSessionStore, InvalidChatSession, type ChatSessionStoreUnavailable } from "./session.js";
+/** Stable machine-facing name for one structured chat definition. */
+export declare const ChatNameSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+/** Positive persisted-state version for one structured chat definition. */
+export declare const ChatVersionSchema: Schema.filter<Schema.filter<typeof Schema.Number>>;
+/** Safe reason that a server-owned chat transition was rejected. */
+export declare const InvalidChatTransitionReasonSchema: Schema.Literal<["already_complete", "invalid_state"]>;
+declare const InvalidChatTransition_base: Schema.TaggedErrorClass<InvalidChatTransition, "InvalidChatTransition", {
+    readonly _tag: Schema.tag<"InvalidChatTransition">;
+} & {
+    chat: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    reason: Schema.Literal<["already_complete", "invalid_state"]>;
+}>;
+/** A server-owned chat state cannot perform the requested transition. */
+export declare class InvalidChatTransition extends InvalidChatTransition_base {
+}
+/** Minimum runtime identity retained for every structured chat stage. */
+export type ChatStageDefinitionContract = CollectStageDefinitionContract | ToolStageDefinitionContract | CommandStageDefinitionContract;
+/** Non-empty sequential stage tuple accepted by one chat definition. */
+export type ChatStageTuple = readonly [
+    ChatStageDefinitionContract,
+    ...ReadonlyArray<ChatStageDefinitionContract>
+];
+type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (value: infer Intersection) => void ? Intersection : never;
+type CollectStateEntry<Stage> = Stage extends CollectStage<infer Name, infer Fields, infer _Guards> ? {
+    readonly [Key in Name]: CollectStageState<Fields>;
+} : never;
+type ChatCollectStage<Stages extends ChatStageTuple> = Extract<Stages[number], CollectStageDefinitionContract>;
+type CollectFields<Stage> = Stage extends CollectStage<infer _Name, infer Fields, infer _Guards> ? Fields : never;
+/** Persisted state entries derived from every collect stage. */
+export type ChatStageStates<Stages extends ChatStageTuple> = [
+    CollectStateEntry<Stages[number]>
+] extends [never] ? Readonly<Record<never, never>> : UnionToIntersection<CollectStateEntry<Stages[number]>>;
+/** Complete server-owned state for one structured chat session. */
+export interface ChatState<Name extends string, Version extends number, Stages extends ChatStageTuple> {
+    readonly schemaVersion: Version;
+    readonly chat: Name;
+    readonly stage: number;
+    readonly status: "active" | "complete";
+    readonly stages: ChatStageStates<Stages>;
+    readonly repair?: {
+        readonly pendingStages: ReadonlyArray<number>;
+    };
+}
+type ChatQuestion<Stage> = Stage extends CollectStage<infer _Name, infer Fields, infer _Guards> ? CollectStagePrompt<Fields> : never;
+type ChatToolExecution<Stage> = Stage extends ToolStage<infer _Name, infer Tools, infer _Guards> ? ToolSetExecution<Tools> : Stage extends CommandStage<infer _Name, infer _Command, infer _Guards> ? Extract<Effect.Effect.Success<ReturnType<Stage["run"]>>, object> : never;
+type StageEffect<Stage> = Stage extends CollectStage<infer _CollectName, infer _Fields, infer _CollectGuards> ? ReturnType<Stage["run"]> : Stage extends ToolStage<infer _ToolName, infer _Tools, infer _ToolGuards> ? ReturnType<Stage["run"]> : Stage extends CommandStage<infer _CommandName, infer _Command, infer _CommandGuards> ? ReturnType<Stage["run"]> : never;
+/** Failure union produced by any stage in one chat. */
+export type ChatError<Stages extends ChatStageTuple> = InvalidChatTransition | Effect.Effect.Error<StageEffect<Stages[number]>>;
+/** Effect service union required by any stage in one chat. */
+export type ChatRequirements<Stages extends ChatStageTuple> = Effect.Effect.Context<StageEffect<Stages[number]>>;
+/** Question, ongoing tool result, or terminal result emitted by one turn. */
+export type ChatTurn<Name extends string, Version extends number, Stages extends ChatStageTuple> = {
+    readonly _tag: "Question";
+    readonly stage: string;
+    readonly state: ChatState<Name, Version, Stages>;
+    readonly question: ChatQuestion<Stages[number]>;
+} | {
+    readonly _tag: "ToolResult";
+    readonly stage: string;
+    readonly state: ChatState<Name, Version, Stages>;
+    readonly result: ChatToolExecution<Stages[number]>;
+} | {
+    readonly _tag: "Complete";
+    readonly stage: string;
+    readonly state: ChatState<Name, Version, Stages>;
+    readonly result: ChatToolExecution<Stages[number]>;
+};
+/** Input for one persisted server-owned chat reply. */
+export interface ChatReplyInput {
+    readonly namespace?: string | undefined;
+    readonly sessionId: string;
+    readonly expectedRevision?: string | undefined;
+    readonly message: string;
+}
+/** Persisted result of one server-owned chat reply. */
+export interface ChatReply<Name extends string, Version extends number, Stages extends ChatStageTuple> {
+    readonly revision: string;
+    readonly turn: ChatTurn<Name, Version, Stages>;
+}
+/** Failure union produced while loading, running, and replacing a session. */
+export type ChatReplyError<Stages extends ChatStageTuple> = ChatError<Stages> | ChatSessionStoreUnavailable | ChatSessionConflict | InvalidChatSession;
+/** Definition input for one sequential structured chat. */
+export interface DefineChatInput<Name extends string, Version extends number, Stages extends ChatStageTuple> {
+    readonly name: Name;
+    readonly version: Version;
+    readonly stages: Stages;
+    readonly repair?: StandardRepair;
+}
+/** One schema-defined sequential chat runtime. */
+export interface ChatDefinition<Name extends string, Version extends number, Stages extends ChatStageTuple> {
+    readonly name: Name;
+    readonly version: Version;
+    readonly stages: Stages;
+    readonly repair: StandardRepair | undefined;
+    readonly stateSchema: Schema.Schema<ChatState<Name, Version, Stages>, unknown, never>;
+    readonly initialState: ChatState<Name, Version, Stages>;
+    /** Read one accepted value together with its supporting transcript data. */
+    readonly getAcceptedAnswer: <Stage extends ChatCollectStage<Stages>, Field extends keyof CollectFields<Stage> & string>(state: ChatState<Name, Version, Stages>, stage: Stage, field: Field) => AcceptedAnswer<CollectAnswers<CollectFields<Stage>>[Field]> | undefined;
+    /** Strictly parse persisted server-owned chat state. */
+    readonly parseState: (input: Schema.Schema.Encoded<Schema.Schema<ChatState<Name, Version, Stages>, unknown, never>>) => Effect.Effect<ChatState<Name, Version, Stages>, ParseResult.ParseError>;
+    /** Run the active stage and any immediately reachable tool stage. */
+    readonly run: (input: {
+        readonly state: ChatState<Name, Version, Stages>;
+        readonly messages: ReadonlyArray<UntrustedMessage>;
+    }) => Effect.Effect<ChatTurn<Name, Version, Stages>, ChatError<Stages>, ChatRequirements<Stages>>;
+    /** Load, run, and atomically replace one server-owned chat session. */
+    readonly reply: (input: ChatReplyInput) => Effect.Effect<ChatReply<Name, Version, Stages>, ChatReplyError<Stages>, ChatSessionStore | ChatRequirements<Stages>>;
+}
+/**
+ * Define one sequential chat with collectors and one final executable stage.
+ *
+ * A final query stage remains active by default so later user messages can
+ * refine results. A final command stage is always terminal.
+ */
+export declare const defineChat: <const Name extends string, const Version extends number, const Stages extends ChatStageTuple>(definition: DefineChatInput<Name, Version, Stages>) => ChatDefinition<Name, Version, Stages>;
+export {};