@popcomputer/structured-chat 0.1.0

package/dist/core/definition.d.ts

@@ -0,0 +1,10 @@
+/** Package-owned kinds for executable structured-chat definitions. */
+export type StructuredDefinitionKind = "tool" | "collect_stage" | "tool_stage" | "command_stage" | "repair" | "model_guard";
+declare const structuredDefinitionKind: unique symbol;
+/** @internal Nominal proof that a definition came from this package. */
+export interface StructuredDefinition<Kind extends StructuredDefinitionKind> {
+    readonly [structuredDefinitionKind]: Kind;
+}
+/** @internal Attach a non-copying nominal identity in a public builder. */
+export declare const structuredDefinition: <const Kind extends StructuredDefinitionKind>(kind: Kind) => <Value extends object>(value: Omit<Value, keyof StructuredDefinition<Kind>>) => Value & StructuredDefinition<Kind>;
+export {};

package/dist/core/definition.js

@@ -0,0 +1,14 @@
+const structuredDefinitionKind = Symbol("@popcomputer/structured-chat/StructuredDefinitionKind");
+/** @internal Attach a non-copying nominal identity in a public builder. */
+export const structuredDefinition = (kind) => (value) => {
+    Object.defineProperty(value, structuredDefinitionKind, {
+        value: kind,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    // SAFETY: defineProperty attached the exact private symbol and literal
+    // kind to this freshly constructed package definition. The non-enumerable
+    // proof cannot be copied by ordinary object spread.
+    return value;
+};

package/dist/core/json-value.d.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+/** Primitive value representable by JSON. */
+export type JsonPrimitive = string | number | boolean | null;
+/** Object value representable by JSON. */
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+/** Recursively typed value accepted at serialized JSON boundaries. */
+export type JsonValue = JsonPrimitive | JsonObject | ReadonlyArray<JsonValue>;
+/** Runtime parser for recursively JSON-serializable values. */
+export declare const JsonValueSchema: Schema.Schema<JsonValue>;

package/dist/core/json-value.js

@@ -0,0 +1,3 @@
+import { Schema } from "effect";
+/** Runtime parser for recursively JSON-serializable values. */
+export const JsonValueSchema = Schema.suspend(() => Schema.Union(Schema.String, Schema.JsonNumber, Schema.Boolean, Schema.Null, Schema.Array(JsonValueSchema), Schema.Record({ key: Schema.String, value: JsonValueSchema })));

package/dist/core/model-guard.d.ts

@@ -0,0 +1,52 @@
+import { Effect, Schema } from "effect";
+import { type StructuredDefinition } from "./definition.js";
+import type { UntrustedMessage } from "./model.js";
+import type { JsonValue } from "./json-value.js";
+/** Stable machine-facing name for one model-boundary policy guard. */
+export declare const ModelGuardNameSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+/** Safe context supplied before a structured model request begins. */
+export interface ModelGuardContext {
+    readonly messages: ReadonlyArray<UntrustedMessage>;
+    readonly toolNames: ReadonlyArray<string>;
+}
+/** Strictly parsed model proposal supplied before application execution. */
+export interface ModelGuardCall {
+    readonly name: string;
+    readonly arguments: JsonValue;
+}
+/** Safe context supplied after parsing and before a tool executes. */
+export interface ModelGuardCallContext extends ModelGuardContext {
+    readonly call: ModelGuardCall;
+}
+/** Minimum runtime identity retained for every model-boundary guard. */
+export interface ModelGuardDefinitionContract extends StructuredDefinition<"model_guard"> {
+    readonly _tag: "ModelGuard";
+    readonly name: string;
+}
+/** Composable policy checks around one structured model request. */
+export interface ModelGuard<Name extends string, Error, Requirements> extends ModelGuardDefinitionContract {
+    readonly name: Name;
+    readonly check: (context: ModelGuardContext) => Effect.Effect<void, Error, Requirements>;
+    readonly checkCall?: (context: ModelGuardCallContext) => Effect.Effect<void, Error, Requirements>;
+}
+/** Definition input for one model-boundary policy guard. */
+export interface DefineModelGuardInput<Name extends string, Error, Requirements> {
+    readonly name: Name;
+    readonly check: (context: ModelGuardContext) => Effect.Effect<void, Error, Requirements>;
+    readonly checkCall?: (context: ModelGuardCallContext) => Effect.Effect<void, Error, Requirements>;
+}
+/** Readonly tuple of optional guards applied to one model step. */
+export type ModelGuardTuple = ReadonlyArray<ModelGuardDefinitionContract>;
+type ModelGuardErrorOf<Guard> = Guard extends ModelGuard<infer _Name, infer Error, infer _Requirements> ? Error : never;
+type ModelGuardRequirementsOf<Guard> = Guard extends ModelGuard<infer _Name, infer _Error, infer Requirements> ? Requirements : never;
+/** Failure union produced by a tuple of model guards. */
+export type ModelGuardError<Guards extends ModelGuardTuple> = ModelGuardErrorOf<Guards[number]>;
+/** Effect service union required by a tuple of model guards. */
+export type ModelGuardRequirements<Guards extends ModelGuardTuple> = ModelGuardRequirementsOf<Guards[number]>;
+/** Define Effect-native policy checks around a structured model step. */
+export declare const defineModelGuard: <const Name extends string, Error, Requirements>(definition: DefineModelGuardInput<Name, Error, Requirements>) => ModelGuard<Name, Error, Requirements>;
+/** @internal */
+export declare const runModelGuards: <Guards extends ModelGuardTuple>(guards: Guards, context: ModelGuardContext) => Effect.Effect<void, ModelGuardError<Guards>, ModelGuardRequirements<Guards>>;
+/** @internal Run optional semantic checks on one parsed tool proposal. */
+export declare const runModelCallGuards: <Guards extends ModelGuardTuple>(guards: Guards, context: ModelGuardCallContext) => Effect.Effect<void, ModelGuardError<Guards>, ModelGuardRequirements<Guards>>;
+export {};

package/dist/core/model-guard.js

@@ -0,0 +1,37 @@
+import { Effect, Schema, unsafeCoerce } from "effect";
+import { structuredDefinition, } from "./definition.js";
+/** Stable machine-facing name for one model-boundary policy guard. */
+export const ModelGuardNameSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100), Schema.pattern(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/));
+/** Define Effect-native policy checks around a structured model step. */
+export const defineModelGuard = (definition) => {
+    Schema.decodeSync(ModelGuardNameSchema)(definition.name);
+    const base = {
+        _tag: "ModelGuard",
+        name: definition.name,
+        check: definition.check,
+    };
+    return structuredDefinition("model_guard")(definition.checkCall === undefined
+        ? base
+        : { ...base, checkCall: definition.checkCall });
+};
+const runtimeModelGuard = (guard) => {
+    // SAFETY: ModelGuardDefinitionContract carries the package-owned nominal
+    // identity and can only be constructed by defineModelGuard.
+    return unsafeCoerce(guard);
+};
+const runGuardPhase = (guards, phase, run) => {
+    const execution = Effect.forEach(guards, (guard) => (run(runtimeModelGuard(guard)) ?? Effect.void).pipe(Effect.withSpan("popcomputer.structured_chat.model_guard.check", {
+        attributes: { guard: guard.name, phase },
+    })), { concurrency: 1, discard: true });
+    // SAFETY: guards run sequentially without recovering failures, so the
+    // erased Effect has exactly the conditional error and requirement unions.
+    return execution;
+};
+/** @internal */
+export const runModelGuards = (guards, context) => {
+    return runGuardPhase(guards, "before_model", (guard) => guard.check(context));
+};
+/** @internal Run optional semantic checks on one parsed tool proposal. */
+export const runModelCallGuards = (guards, context) => {
+    return runGuardPhase(guards, "before_tool", (guard) => guard.checkCall?.(context));
+};

package/dist/core/model.d.ts

@@ -0,0 +1,99 @@
+import { Context, Effect, Schema } from "effect";
+import type { InvalidToolCall, ModelToolDefinition } from "./tool.js";
+import { type ModelGuardError, type ModelGuardRequirements, type ModelGuardTuple } from "./model-guard.js";
+import type { ToolSet, ToolSetCall, ToolSetError, ToolSetExecution, ToolSetRequirements, ModelToolTuple, ToolCallPlanner, ToolTuple } from "./tool-set.js";
+import type { JsonValue } from "./json-value.js";
+/** Bounded application-authored instruction supplied to a model adapter. */
+export declare const TrustedInstructionSchema: Schema.brand<Schema.filter<typeof Schema.NonEmptyTrimmedString>, "TrustedInstruction">;
+/** Bounded application-authored instruction supplied to a model adapter. */
+export type TrustedInstruction = Schema.Schema.Type<typeof TrustedInstructionSchema>;
+/** Conversation role accepted as untrusted model context. */
+export declare const ConversationRoleSchema: Schema.Literal<["user", "assistant"]>;
+/** One bounded conversation message treated as untrusted model context. */
+export declare const UntrustedMessageSchema: Schema.Struct<{
+    role: Schema.Literal<["user", "assistant"]>;
+    content: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+}>;
+/** One bounded conversation message treated as untrusted model context. */
+export type UntrustedMessage = Schema.Schema.Type<typeof UntrustedMessageSchema>;
+/** @internal Exact content-character count for bounded message arrays. */
+export declare const countUntrustedMessageCharacters: (messages: ReadonlyArray<UntrustedMessage>) => number;
+/** Safe reason that a configured chat model could not complete a step. */
+export declare const ChatModelUnavailableReasonSchema: Schema.Literal<["request_failed", "timed_out", "response_blocked", "invalid_response"]>;
+declare const ChatModelUnavailable_base: Schema.TaggedErrorClass<ChatModelUnavailable, "ChatModelUnavailable", {
+    readonly _tag: Schema.tag<"ChatModelUnavailable">;
+} & {
+    reason: Schema.Literal<["request_failed", "timed_out", "response_blocked", "invalid_response"]>;
+}>;
+/** A configured chat model could not complete a structured step. */
+export declare class ChatModelUnavailable extends ChatModelUnavailable_base {
+}
+/** Safe reason that a tool schema cannot use strict provider decoding. */
+export declare const UnsupportedModelToolSchemaReasonSchema: Schema.Literal<["root_not_object", "additional_properties_allowed", "optional_property"]>;
+declare const UnsupportedModelToolSchema_base: Schema.TaggedErrorClass<UnsupportedModelToolSchema, "UnsupportedModelToolSchema", {
+    readonly _tag: Schema.tag<"UnsupportedModelToolSchema">;
+} & {
+    tool: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+    path: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+    reason: Schema.Literal<["root_not_object", "additional_properties_allowed", "optional_property"]>;
+}>;
+/** A model tool schema is incompatible with strict provider decoding. */
+export declare class UnsupportedModelToolSchema extends UnsupportedModelToolSchema_base {
+}
+/** Provider-neutral request for exactly one model-authored tool call. */
+export interface ToolModelRequest {
+    readonly instructions: ReadonlyArray<TrustedInstruction>;
+    readonly untrustedMessages: ReadonlyArray<UntrustedMessage>;
+    readonly tools: ReadonlyArray<ModelToolDefinition>;
+    readonly toolChoice: "required";
+    readonly maximumToolCalls: 1;
+    readonly parallelToolCalls: false;
+}
+/** Narrow provider seam used by structured chat model steps. */
+export interface StructuredChatModelService {
+    /** Return one untrusted provider tool call for runtime validation. */
+    readonly requestTool: (request: ToolModelRequest) => Effect.Effect<JsonValue, ChatModelUnavailable | UnsupportedModelToolSchema>;
+}
+declare const StructuredChatModel_base: Context.TagClass<StructuredChatModel, "@popcomputer/structured-chat/StructuredChatModel", StructuredChatModelService>;
+/** Effect service for the configured structured chat model adapter. */
+export declare class StructuredChatModel extends StructuredChatModel_base {
+}
+/** Input for one required, stage-scoped tool step. */
+export interface RunToolStepInput<Tools extends ToolTuple, Guards extends ModelGuardTuple = readonly []> {
+    readonly instructions: ReadonlyArray<TrustedInstruction>;
+    readonly messages: ReadonlyArray<UntrustedMessage>;
+    readonly tools: ToolSet<Tools>;
+    readonly guards?: Guards;
+}
+interface PlanToolCallInput<Tools extends ModelToolTuple, Guards extends ModelGuardTuple> {
+    readonly instructions: ReadonlyArray<TrustedInstruction>;
+    readonly messages: ReadonlyArray<UntrustedMessage>;
+    readonly tools: ToolCallPlanner<Tools>;
+    readonly guards?: Guards;
+}
+/** @internal Plan one strictly parsed and guarded call to a closed tool set. */
+export declare const planToolCall: <const Tools extends ModelToolTuple, const Guards extends ModelGuardTuple = readonly []>(input: PlanToolCallInput<Tools, Guards>) => Effect.Effect<ToolSetCall<Tools>, ChatModelUnavailable | UnsupportedModelToolSchema | InvalidToolCall | ModelGuardError<Guards>, StructuredChatModel | ModelGuardRequirements<Guards>>;
+/**
+ * Ask the configured model for one call to a closed tool set, then execute it.
+ *
+ * One contract-invalid model output may trigger a bounded repair request
+ * before any application tool executes. Model-visible results are returned to
+ * the application and are never sent through another model request.
+ */
+export declare const runToolStep: <const Tools extends ToolTuple, const Guards extends ModelGuardTuple = readonly []>(input: RunToolStepInput<Tools, Guards>) => Effect.Effect<ToolSetExecution<Tools>, ChatModelUnavailable | UnsupportedModelToolSchema | ToolSetError<Tools> | ModelGuardError<Guards>, StructuredChatModel | ToolSetRequirements<Tools> | ModelGuardRequirements<Guards>>;
+/** Constructors that explicitly mark static application instructions. */
+export declare const Instruction: {
+    readonly make: (value: string) => TrustedInstruction;
+};
+/** Constructors that explicitly mark conversation text as untrusted. */
+export declare const Message: {
+    readonly user: (content: string) => {
+        readonly role: "user" | "assistant";
+        readonly content: string;
+    };
+    readonly assistant: (content: string) => {
+        readonly role: "user" | "assistant";
+        readonly content: string;
+    };
+};
+export {};

package/dist/core/model.js

@@ -0,0 +1,109 @@
+import { Context, Effect, Schema } from "effect";
+import { runModelCallGuards, runModelGuards, } from "./model-guard.js";
+/** Bounded application-authored instruction supplied to a model adapter. */
+export const TrustedInstructionSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(20_000), Schema.brand("TrustedInstruction"));
+/** Conversation role accepted as untrusted model context. */
+export const ConversationRoleSchema = Schema.Literal("user", "assistant");
+/** One bounded conversation message treated as untrusted model context. */
+export const UntrustedMessageSchema = Schema.Struct({
+    role: ConversationRoleSchema,
+    content: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(50_000)),
+});
+/** @internal Exact content-character count for bounded message arrays. */
+export const countUntrustedMessageCharacters = (messages) => messages.reduce((total, message) => total + message.content.length, 0);
+/** Safe reason that a configured chat model could not complete a step. */
+export const ChatModelUnavailableReasonSchema = Schema.Literal("request_failed", "timed_out", "response_blocked", "invalid_response");
+/** A configured chat model could not complete a structured step. */
+export class ChatModelUnavailable extends Schema.TaggedError()("ChatModelUnavailable", { reason: ChatModelUnavailableReasonSchema }) {
+}
+/** Safe reason that a tool schema cannot use strict provider decoding. */
+export const UnsupportedModelToolSchemaReasonSchema = Schema.Literal("root_not_object", "additional_properties_allowed", "optional_property");
+/** A model tool schema is incompatible with strict provider decoding. */
+export class UnsupportedModelToolSchema extends Schema.TaggedError()("UnsupportedModelToolSchema", {
+    tool: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100)),
+    path: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(2_000)),
+    reason: UnsupportedModelToolSchemaReasonSchema,
+}) {
+}
+/** Effect service for the configured structured chat model adapter. */
+export class StructuredChatModel extends Context.Tag("@popcomputer/structured-chat/StructuredChatModel")() {
+}
+const invalidOutputRepairInstruction = Schema.decodeSync(TrustedInstructionSchema)("Your previous response did not satisfy the required tool-call contract. Call exactly one listed tool and return only arguments allowed by its JSON Schema.");
+const isRepairableModelOutput = (error) => error._tag === "InvalidToolCall" ||
+    (error._tag === "ChatModelUnavailable" &&
+        error.reason === "invalid_response");
+/** @internal Plan one strictly parsed and guarded call to a closed tool set. */
+export const planToolCall = (input) => runModelGuards(input.guards ?? [], {
+    messages: input.messages,
+    toolNames: input.tools.models.map(({ name }) => name),
+}).pipe(Effect.zipRight(StructuredChatModel), Effect.flatMap((model) => {
+    const requestParsedCall = (instructions, attempt) => model
+        .requestTool({
+        instructions,
+        untrustedMessages: input.messages,
+        tools: input.tools.models,
+        toolChoice: "required",
+        maximumToolCalls: 1,
+        parallelToolCalls: false,
+    })
+        .pipe(Effect.withSpan("popcomputer.structured_chat.model.request", {
+        attributes: {
+            attempt,
+            messageCount: input.messages.length,
+            messageCharacterCount: countUntrustedMessageCharacters(input.messages),
+            instructionCount: instructions.length,
+            toolCount: input.tools.models.length,
+        },
+    }), Effect.flatMap(input.tools.parseCall));
+    return requestParsedCall(input.instructions, 1).pipe(Effect.catchIf(isRepairableModelOutput, (error) => {
+        const annotations = error._tag === "InvalidToolCall" && error.path !== null
+            ? {
+                attempt: 2,
+                errorTag: error._tag,
+                errorReason: error.reason,
+                errorPath: error.path,
+            }
+            : {
+                attempt: 2,
+                errorTag: error._tag,
+                errorReason: error.reason,
+            };
+        return Effect.logWarning("Retrying structured model output").pipe(Effect.annotateLogs(annotations), Effect.zipRight(requestParsedCall([
+            ...input.instructions,
+            invalidOutputRepairInstruction,
+        ], 2)));
+    }));
+}), Effect.tap((call) => runModelCallGuards(input.guards ?? [], {
+    messages: input.messages,
+    toolNames: input.tools.models.map(({ name }) => name),
+    call,
+})), Effect.withSpan("popcomputer.structured_chat.tool_step.plan", {
+    attributes: {
+        messageCount: input.messages.length,
+        toolCount: input.tools.models.length,
+    },
+}));
+/**
+ * Ask the configured model for one call to a closed tool set, then execute it.
+ *
+ * One contract-invalid model output may trigger a bounded repair request
+ * before any application tool executes. Model-visible results are returned to
+ * the application and are never sent through another model request.
+ */
+export const runToolStep = (input) => planToolCall(input).pipe(Effect.flatMap(input.tools.execute), Effect.withSpan("popcomputer.structured_chat.tool_step.run", {
+    attributes: {
+        messageCount: input.messages.length,
+        toolCount: input.tools.models.length,
+    },
+}));
+const makeInstruction = (value) => Schema.decodeSync(TrustedInstructionSchema)(value);
+const makeMessage = (role, content) => Schema.decodeSync(UntrustedMessageSchema)({ role, content });
+/** Constructors that explicitly mark static application instructions. */
+export const Instruction = {
+    make: makeInstruction,
+};
+/** Constructors that explicitly mark conversation text as untrusted. */
+export const Message = {
+    user: (content) => makeMessage("user", content),
+    assistant: (content) => makeMessage("assistant", content),
+};

package/dist/core/protocol.d.ts

@@ -0,0 +1,257 @@
+import { Effect, Schema } from "effect";
+import { ChatSessionIdSchema, ChatSessionRevisionSchema } from "./session.js";
+/** Bounded plain text emitted by a structured chat presenter. */
+export declare const AssistantTextPartSchema: Schema.Struct<{
+    type: Schema.Literal<["text"]>;
+    text: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+}>;
+/** Provider-neutral named data emitted by a structured chat presenter. */
+export declare const AssistantDataPartSchema: Schema.Struct<{
+    type: Schema.Literal<["data"]>;
+    name: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    data: typeof Schema.Unknown;
+}>;
+/** Message parts transported from a structured chat action to a browser. */
+export declare const AssistantMessagePartSchema: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["text"]>;
+    text: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["data"]>;
+    name: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    data: typeof Schema.Unknown;
+}>]>;
+/** Message parts transported from a structured chat action to a browser. */
+export type AssistantMessagePart = Schema.Schema.Type<typeof AssistantMessagePartSchema>;
+/** Strict assistant message returned by one structured chat action. */
+export declare const StructuredChatAssistantMessageSchema: Schema.Struct<{
+    role: Schema.Literal<["assistant"]>;
+    content: Schema.filter<Schema.NonEmptyArray<Schema.Union<[Schema.Struct<{
+        type: Schema.Literal<["text"]>;
+        text: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+    }>, Schema.Struct<{
+        type: Schema.Literal<["data"]>;
+        name: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+        data: typeof Schema.Unknown;
+    }>]>>>;
+}>;
+/** Strict assistant message returned by one structured chat action. */
+export type StructuredChatAssistantMessage = Schema.Schema.Type<typeof StructuredChatAssistantMessageSchema>;
+/** Opaque browser-held reference to one server-owned chat session. */
+export declare const StructuredChatSessionReferenceSchema: Schema.Struct<{
+    id: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    revision: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+}>;
+/** Opaque browser-held reference to one server-owned chat session. */
+export type StructuredChatSessionReference = Schema.Schema.Type<typeof StructuredChatSessionReferenceSchema>;
+/** Browser request carrying no server-owned chat state. */
+export declare const StructuredChatTurnRequestSchema: Schema.Struct<{
+    session: Schema.optional<Schema.Struct<{
+        id: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+        revision: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    }>>;
+    message: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+}>;
+/** Browser request carrying no server-owned chat state. */
+export type StructuredChatTurnRequest = Schema.Schema.Type<typeof StructuredChatTurnRequestSchema>;
+/** Versioned browser response for one persisted structured chat turn. */
+export declare const StructuredChatTurnResponseSchema: Schema.Struct<{
+    schemaVersion: Schema.Literal<[1]>;
+    session: Schema.optional<Schema.Struct<{
+        id: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+        revision: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    }>>;
+    message: Schema.Struct<{
+        role: Schema.Literal<["assistant"]>;
+        content: Schema.filter<Schema.NonEmptyArray<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["data"]>;
+            name: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+            data: typeof Schema.Unknown;
+        }>]>>>;
+    }>;
+}>;
+/** Versioned browser response for one persisted structured chat turn. */
+export type StructuredChatTurnResponse = Schema.Schema.Type<typeof StructuredChatTurnResponseSchema>;
+/** Built-in browser contract for one collect-stage question. */
+export declare const CollectQuestionView: {
+    name: "collect_question";
+    version: 1;
+    inputSchema: Schema.Struct<{
+        stage: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        field: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        text: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        options: Schema.filter<Schema.Array$<Schema.Struct<{
+            label: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        }>>>;
+    }>;
+    dataSchema: Schema.Struct<{
+        readonly schemaVersion: Schema.Literal<[1]>;
+    } & {
+        stage: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        field: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        text: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        options: Schema.filter<Schema.Array$<Schema.Struct<{
+            label: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+        }>>>;
+    }>;
+    partSchema: Schema.Struct<{
+        readonly type: Schema.Literal<["data"]>;
+        readonly name: Schema.Literal<["collect_question"]>;
+        readonly data: Schema.Struct<{
+            readonly schemaVersion: Schema.Literal<[1]>;
+        } & {
+            stage: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+            field: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+            text: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+            options: Schema.filter<Schema.Array$<Schema.Struct<{
+                label: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+            }>>>;
+        }>;
+    }>;
+    make: (input: {
+        readonly text: string;
+        readonly stage: string;
+        readonly field: string;
+        readonly options: readonly {
+            readonly label: string;
+        }[];
+    }) => {
+        readonly name: "collect_question";
+        readonly type: "data";
+        readonly data: {
+            readonly schemaVersion: 1;
+            readonly text: string;
+            readonly stage: string;
+            readonly field: string;
+            readonly options: readonly {
+                readonly label: string;
+            }[];
+        };
+    };
+    parseData: (input: import("./json-value.js").JsonValue) => Effect.Effect<{
+        readonly name: "collect_question";
+        readonly type: "data";
+        readonly data: {
+            readonly schemaVersion: 1;
+            readonly text: string;
+            readonly stage: string;
+            readonly field: string;
+            readonly options: readonly {
+                readonly label: string;
+            }[];
+        };
+    }, import("effect/ParseResult").ParseError, never>;
+    decode: (input: import("./json-value.js").JsonValue) => Effect.Effect<{
+        readonly name: "collect_question";
+        readonly type: "data";
+        readonly data: {
+            readonly schemaVersion: 1;
+            readonly text: string;
+            readonly stage: string;
+            readonly field: string;
+            readonly options: readonly {
+                readonly label: string;
+            }[];
+        };
+    }, import("effect/ParseResult").ParseError, never>;
+    decodeEither: (input: import("./json-value.js").JsonValue) => import("effect/Either").Either<{
+        readonly name: "collect_question";
+        readonly type: "data";
+        readonly data: {
+            readonly schemaVersion: 1;
+            readonly text: string;
+            readonly stage: string;
+            readonly field: string;
+            readonly options: readonly {
+                readonly label: string;
+            }[];
+        };
+    }, import("effect/ParseResult").ParseError>;
+};
+declare const InvalidChatPresentation_base: Schema.TaggedErrorClass<InvalidChatPresentation, "InvalidChatPresentation", {
+    readonly _tag: Schema.tag<"InvalidChatPresentation">;
+} & {
+    reason: Schema.Literal<["invalid_message"]>;
+}>;
+/** Safe reason that application-owned message presentation was rejected. */
+export declare class InvalidChatPresentation extends InvalidChatPresentation_base {
+}
+interface PresentableQuestionTurn {
+    readonly _tag: "Question";
+    readonly stage: string;
+    readonly question: {
+        readonly field: string;
+        readonly text: string;
+        readonly options: ReadonlyArray<{
+            readonly label: string;
+        }>;
+        readonly escape?: {
+            readonly label: string;
+        };
+    };
+}
+interface PresentableToolTurn {
+    readonly _tag: "ToolResult" | "Complete";
+    readonly stage: string;
+    readonly result: {
+        readonly views: ReadonlyArray<AssistantMessagePart>;
+    };
+}
+type PresentableTurn = PresentableQuestionTurn | PresentableToolTurn;
+/** Optional application projections for question and tool-result messages. */
+export interface PresentChatReplyOptions<Turn extends PresentableTurn> {
+    readonly question?: (turn: Extract<Turn, PresentableQuestionTurn>) => ReadonlyArray<AssistantMessagePart>;
+    readonly result?: (turn: Extract<Turn, PresentableToolTurn>) => ReadonlyArray<AssistantMessagePart>;
+}
+/** Constructors for deterministic assistant message parts. */
+export declare const Text: {
+    readonly make: (text: string) => AssistantMessagePart;
+};
+/**
+ * Present a safe non-progressing notice after a rejected or unavailable turn.
+ *
+ * Supplying the prior session reference lets the browser retry from the same
+ * server-owned state. An initial rejected turn may omit it entirely.
+ */
+export declare const presentChatNotice: (input: {
+    readonly text: string;
+    readonly session?: StructuredChatSessionReference | undefined;
+}) => Effect.Effect<StructuredChatTurnResponse, InvalidChatPresentation>;
+/**
+ * Present an application-authored retry question after answer validation.
+ *
+ * The rejection is non-progressing: pass the browser's prior session
+ * reference, if any, so its next answer retries from the same revision.
+ */
+export declare const presentAnswerValidationRejection: (input: {
+    readonly rejection: {
+        readonly stage: string;
+        readonly question: {
+            readonly field: string;
+            readonly text: string;
+            readonly options: ReadonlyArray<{
+                readonly label: string;
+                readonly value?: unknown;
+            }>;
+            readonly escape?: {
+                readonly label: string;
+            };
+        };
+    };
+    readonly session?: StructuredChatSessionReference | undefined;
+}) => Effect.Effect<StructuredChatTurnResponse, InvalidChatPresentation>;
+/**
+ * Project one persisted chat reply into the strict browser protocol.
+ *
+ * Questions use the built-in CollectQuestionView unless overridden. Tool
+ * results use their validated views unless the application adds text or a
+ * different ordered composition.
+ */
+export declare const presentChatReply: <Turn extends PresentableTurn>(reply: {
+    readonly sessionId: Schema.Schema.Type<typeof ChatSessionIdSchema> | string;
+    readonly revision: Schema.Schema.Type<typeof ChatSessionRevisionSchema> | string;
+    readonly turn: Turn;
+}, options?: PresentChatReplyOptions<Turn>) => Effect.Effect<StructuredChatTurnResponse, InvalidChatPresentation>;
+export {};