@popcomputer/structured-chat 0.2.0-rc.0 → 0.2.0

package/README.md

@@ -600,6 +600,59 @@ that expose message editing, regeneration, or persistent branching should pair
 it with an application-owned branch/session policy rather than treating browser
 history as authoritative.
 
+## Inspect development state
+
+The optional debug inspector shows the current stage, stage progress, required
+fields, accepted values, issued questions, and supporting evidence. It uses a
+small package-owned panel inspired by DialKit, without adding DialKit or another
+runtime dependency.
+
+Debug data uses a separate, explicit response contract. Select it on an
+authenticated development endpoint:
+
+```ts
+import {
+  presentChatDebugReply,
+  presentChatReply,
+} from "@popcomputer/structured-chat"
+
+const response = debugAccessGranted
+  ? yield* presentChatDebugReply(
+      ResourceFinder,
+      { ...reply, sessionId: publicSessionId },
+      { inspection: { evidence: "include" } },
+    )
+  : yield* presentChatReply({ ...reply, sessionId: publicSessionId })
+```
+
+Connect that endpoint to the inspector store:
+
+```tsx
+import { makeAssistantChatModelAdapter } from "@popcomputer/structured-chat/assistant-ui"
+import {
+  createStructuredChatDebugStore,
+  StructuredChatDebugPanel,
+} from "@popcomputer/structured-chat/assistant-ui/debug"
+
+const debugStore = createStructuredChatDebugStore()
+const model = makeAssistantChatModelAdapter({
+  endpoint: "/api/resource-finder/debug/turn",
+  onDebugSnapshot: debugStore.receive,
+})
+
+export function ResourceFinderDebugPanel() {
+  return <StructuredChatDebugPanel store={debugStore} />
+}
+```
+
+Without `onDebugSnapshot`, the normal adapter continues to reject a response
+containing debug data. Hiding or unmounting the panel is not an authorization
+boundary: the server must decide whether to emit the debug response. Use
+`evidence: "omit"` when transcript quotes should not cross that boundary.
+Create one store per chat runtime; it reflects the most recently completed
+debug response. Observer failures are isolated and never change the outcome of
+the persisted chat turn.
+
 ## Plan without executing
 
 The default remains one call:

package/dist/core/collect-stage.d.ts

@@ -3,7 +3,7 @@ import type { AnswerDefinition, AnswerDefinitionContract, AnswerMode } from "./a
 import { ChatModelUnavailable, StructuredChatModel, type UnsupportedModelToolSchema, type UntrustedMessage } from "./model.js";
 import type { ModelGuardError, ModelGuardRequirements, ModelGuardTuple } from "./model-guard.js";
 import { InvalidToolCall, type InvalidToolProjection } from "./tool.js";
-import type { AdaptiveChoiceQuestion, ChoiceQuestion, QuestionChoice } from "./question.js";
+import type { AdaptiveChoiceQuestion, ChoiceQuestion, QuestionDefinitionContract, QuestionChoice } from "./question.js";
 import { type StructuredDefinition } from "./definition.js";
 /** Safe reason that a collect-stage model proposal was rejected. */
 export declare const InvalidCollectStageResponseReasonSchema: Schema.Literals<readonly ["invalid_evidence", "invalid_repair"]>;
@@ -148,15 +148,31 @@ export interface CollectStageRuntime {
         readonly messages: ReadonlyArray<UntrustedMessage>;
     }) => Effect.Effect<RuntimeCollectStageTurn, unknown, unknown>;
 }
+/** @internal One definition-ordered field exposed to trusted projections. */
+export interface CollectStageInspectionField {
+    readonly field: string;
+    readonly mode: AnswerMode;
+    readonly description: string;
+    readonly question: QuestionDefinitionContract;
+    readonly encodeValue: (value: RuntimeAnswerValue) => Effect.Effect<unknown, Schema.SchemaError>;
+}
+/** @internal Read-only collect-stage metadata used by trusted projections. */
+export interface CollectStageInspection {
+    readonly fields: ReadonlyArray<CollectStageInspectionField>;
+}
 declare const collectStageRuntime: unique symbol;
+declare const collectStageInspection: unique symbol;
 /** Minimum sealed collect-stage shape accepted by a chat definition. */
 export interface CollectStageDefinitionContract extends StructuredDefinition<"collect_stage"> {
     readonly _tag: "CollectStage";
     readonly name: string;
     readonly [collectStageRuntime]: CollectStageRuntime;
+    readonly [collectStageInspection]: CollectStageInspection;
 }
 /** @internal Read the erased runtime from an authentic collect stage. */
 export declare const readCollectStageRuntime: (stage: CollectStageDefinitionContract) => CollectStageRuntime;
+/** @internal Read trusted definition metadata from an authentic collect stage. */
+export declare const readCollectStageInspection: (stage: CollectStageDefinitionContract) => CollectStageInspection;
 /** Shared conversational policy for questions in one collect stage. */
 export interface CollectQuestionPolicy {
     /** Trusted style guidance applied to every adaptive question in this stage. */

package/dist/core/collect-stage.js

@@ -19,8 +19,11 @@ export class InvalidCollectStageResponse extends Schema.TaggedError()("InvalidCo
 export class AnswerValidationRejected extends Data.TaggedError("AnswerValidationRejected") {
 }
 const collectStageRuntime = Symbol("@popcomputer/structured-chat/CollectStageRuntime");
+const collectStageInspection = Symbol("@popcomputer/structured-chat/CollectStageInspection");
 /** @internal Read the erased runtime from an authentic collect stage. */
 export const readCollectStageRuntime = (stage) => stage[collectStageRuntime];
+/** @internal Read trusted definition metadata from an authentic collect stage. */
+export const readCollectStageInspection = (stage) => stage[collectStageInspection];
 const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
 /** Define one deterministic schema-derived fact collection stage. */
 export const defineCollectStage = (definition) => {
@@ -171,6 +174,18 @@ export const defineCollectStage = (definition) => {
         accepted: {},
         asked: {},
     });
+    const inspectionFields = fieldNames.map((field) => {
+        const answer = getAnswer(field);
+        return {
+            field,
+            mode: answer.mode,
+            description: answer.description,
+            question: answer.question,
+            encodeValue: (value) => Schema.encodeUnknownEffect(answer.schema)(value, {
+                onExcessProperty: "error",
+            }),
+        };
+    });
     // SAFETY: when guards are omitted, Guards uses its readonly [] default; an
     // explicitly supplied tuple is returned unchanged.
     const guards = definition.guards ?? cast([]);
@@ -630,6 +645,9 @@ export const defineCollectStage = (definition) => {
                 },
         }),
         run,
+        [collectStageInspection]: {
+            fields: inspectionFields,
+        },
         [collectStageRuntime]: {
             initialState,
             stateSchema,

package/dist/core/debug-protocol.d.ts

@@ -0,0 +1,126 @@
+import { Effect, Schema } from "effect";
+import type { ChatDefinition, ChatReply, ChatStageTuple } from "./chat.js";
+import { type InspectChatStateOptions, type InvalidChatDebugProjection } from "./debug.js";
+import { presentChatReply, type InvalidChatPresentation, type PresentChatReplyOptions } from "./protocol.js";
+type BrowserPresentableTurn = Parameters<typeof presentChatReply>[0]["turn"];
+type DebugChatTurn<Name extends string, Version extends number, Stages extends ChatStageTuple> = ChatReply<Name, Version, Stages>["turn"] & BrowserPresentableTurn;
+type DebugChatReply<Name extends string, Version extends number, Stages extends ChatStageTuple> = Omit<ChatReply<Name, Version, Stages>, "turn"> & {
+    readonly sessionId: string;
+    readonly turn: DebugChatTurn<Name, Version, Stages>;
+};
+/** Explicit opt-in browser response carrying one debug state projection. */
+export declare const StructuredChatDebugTurnResponseSchema: Schema.Struct<{
+    readonly debug: Schema.Struct<{
+        readonly schemaVersion: Schema.Literal<1>;
+        readonly chat: Schema.Struct<{
+            readonly name: Schema.Trimmed;
+            readonly version: Schema.Number;
+        }>;
+        readonly status: Schema.Literals<readonly ["active", "complete"]>;
+        readonly currentStage: Schema.Struct<{
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly kind: Schema.Literals<readonly ["collect", "tool", "command"]>;
+        }>;
+        readonly stages: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly satisfiedFields: Schema.Natural;
+            readonly totalFields: Schema.Natural;
+            readonly fields: Schema.$Array<Schema.Struct<{
+                readonly field: Schema.String;
+                readonly mode: Schema.Literals<readonly ["semantic", "explicit", "confirmed"]>;
+                readonly description: Schema.String;
+                readonly question: Schema.Union<readonly [Schema.Struct<{
+                    readonly _tag: Schema.Literal<"FixedQuestion">;
+                    readonly text: Schema.String;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"AdaptiveQuestion">;
+                    readonly goal: Schema.String;
+                    readonly fallback: Schema.String;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"AdaptiveChoiceQuestion">;
+                    readonly prompt: Schema.String;
+                    readonly minimumOptions: Schema.Natural;
+                    readonly maximumOptions: Schema.Natural;
+                    readonly fallbackOptions: Schema.$Array<Schema.String>;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"ChoiceQuestion">;
+                    readonly text: Schema.String;
+                    readonly options: Schema.$Array<Schema.Struct<{
+                        readonly label: Schema.String;
+                    }>>;
+                }>]>;
+                readonly state: Schema.Union<readonly [Schema.Struct<{
+                    readonly _tag: Schema.Literal<"Missing">;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"Asked">;
+                    readonly issuedQuestion: Schema.Struct<{
+                        readonly messageIndex: Schema.Natural;
+                        readonly text: Schema.String;
+                    }>;
+                }>, Schema.Struct<{
+                    readonly _tag: Schema.Literal<"Accepted">;
+                    readonly value: Schema.Codec<import("./json-value.js").JsonValue, import("./json-value.js").JsonValue, never, never>;
+                    readonly evidence: Schema.NullOr<Schema.Struct<{
+                        readonly messageIndex: Schema.Natural;
+                        readonly quote: Schema.String;
+                    }>>;
+                    readonly issuedQuestion: Schema.NullOr<Schema.Struct<{
+                        readonly messageIndex: Schema.Natural;
+                        readonly text: Schema.String;
+                    }>>;
+                }>]>;
+            }>>;
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+            readonly repairPending: Schema.Boolean;
+            readonly _tag: Schema.Literal<"CollectStage">;
+        }>, Schema.Struct<{
+            readonly tools: Schema.$Array<Schema.Trimmed>;
+            readonly afterExecution: Schema.Literals<readonly ["stay", "complete"]>;
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+            readonly repairPending: Schema.Boolean;
+            readonly _tag: Schema.Literal<"ToolStage">;
+        }>, Schema.Struct<{
+            readonly command: Schema.Trimmed;
+            readonly index: Schema.Natural;
+            readonly name: Schema.Trimmed;
+            readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+            readonly repairPending: Schema.Boolean;
+            readonly _tag: Schema.Literal<"CommandStage">;
+        }>]>>;
+    }>;
+    readonly schemaVersion: Schema.Literal<1>;
+    readonly session: Schema.optional<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly revision: Schema.Trimmed;
+    }>>;
+    readonly message: Schema.Struct<{
+        readonly role: Schema.Literal<"assistant">;
+        readonly content: Schema.NonEmptyArray<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"text">;
+            readonly text: Schema.Trimmed;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"data">;
+            readonly name: Schema.Trimmed;
+            readonly data: Schema.Unknown;
+        }>]>>;
+    }>;
+}>;
+/** Explicit opt-in browser response carrying one debug state projection. */
+export type StructuredChatDebugTurnResponse = Schema.Schema.Type<typeof StructuredChatDebugTurnResponseSchema>;
+/** Presentation and state-inspection policies for one debug chat reply. */
+export interface PresentChatDebugReplyOptions<Name extends string, Version extends number, Stages extends ChatStageTuple> {
+    readonly presentation?: PresentChatReplyOptions<DebugChatTurn<Name, Version, Stages>>;
+    readonly inspection?: InspectChatStateOptions;
+}
+/**
+ * Project one persisted reply into the explicit debug browser protocol.
+ *
+ * Applications must select this presenter deliberately and should authorize
+ * its endpoint independently from whether a debug panel is visually mounted.
+ */
+export declare const presentChatDebugReply: <const Name extends string, const Version extends number, const Stages extends ChatStageTuple>(chat: ChatDefinition<Name, Version, Stages>, reply: DebugChatReply<Name, Version, Stages>, options?: PresentChatDebugReplyOptions<Name, Version, Stages>) => Effect.Effect<StructuredChatDebugTurnResponse, InvalidChatPresentation | InvalidChatDebugProjection>;
+export {};

package/dist/core/debug-protocol.js

@@ -0,0 +1,19 @@
+import { Effect, Schema } from "effect";
+import { inspectChatState, StructuredChatDebugSnapshotSchema, } from "./debug.js";
+import { presentChatReply, StructuredChatTurnResponseSchema, } from "./protocol.js";
+/** Explicit opt-in browser response carrying one debug state projection. */
+export const StructuredChatDebugTurnResponseSchema = Schema.Struct({
+    ...StructuredChatTurnResponseSchema.fields,
+    debug: StructuredChatDebugSnapshotSchema,
+});
+/**
+ * Project one persisted reply into the explicit debug browser protocol.
+ *
+ * Applications must select this presenter deliberately and should authorize
+ * its endpoint independently from whether a debug panel is visually mounted.
+ */
+export const presentChatDebugReply = (chat, reply, options = {}) => Effect.gen(function* () {
+    const response = yield* presentChatReply(reply, options.presentation);
+    const debug = yield* inspectChatState(chat, reply.turn.state, options.inspection);
+    return { ...response, debug };
+});

package/dist/core/debug.d.ts

@@ -0,0 +1,103 @@
+import { Effect, Schema } from "effect";
+import { type ChatDefinition, type ChatStageTuple, type ChatState } from "./chat.js";
+/** Runtime schema for one JSON-safe structured-chat debug snapshot. */
+export declare const StructuredChatDebugSnapshotSchema: Schema.Struct<{
+    readonly schemaVersion: Schema.Literal<1>;
+    readonly chat: Schema.Struct<{
+        readonly name: Schema.Trimmed;
+        readonly version: Schema.Number;
+    }>;
+    readonly status: Schema.Literals<readonly ["active", "complete"]>;
+    readonly currentStage: Schema.Struct<{
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly kind: Schema.Literals<readonly ["collect", "tool", "command"]>;
+    }>;
+    readonly stages: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly satisfiedFields: Schema.Natural;
+        readonly totalFields: Schema.Natural;
+        readonly fields: Schema.$Array<Schema.Struct<{
+            readonly field: Schema.String;
+            readonly mode: Schema.Literals<readonly ["semantic", "explicit", "confirmed"]>;
+            readonly description: Schema.String;
+            readonly question: Schema.Union<readonly [Schema.Struct<{
+                readonly _tag: Schema.Literal<"FixedQuestion">;
+                readonly text: Schema.String;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"AdaptiveQuestion">;
+                readonly goal: Schema.String;
+                readonly fallback: Schema.String;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"AdaptiveChoiceQuestion">;
+                readonly prompt: Schema.String;
+                readonly minimumOptions: Schema.Natural;
+                readonly maximumOptions: Schema.Natural;
+                readonly fallbackOptions: Schema.$Array<Schema.String>;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"ChoiceQuestion">;
+                readonly text: Schema.String;
+                readonly options: Schema.$Array<Schema.Struct<{
+                    readonly label: Schema.String;
+                }>>;
+            }>]>;
+            readonly state: Schema.Union<readonly [Schema.Struct<{
+                readonly _tag: Schema.Literal<"Missing">;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"Asked">;
+                readonly issuedQuestion: Schema.Struct<{
+                    readonly messageIndex: Schema.Natural;
+                    readonly text: Schema.String;
+                }>;
+            }>, Schema.Struct<{
+                readonly _tag: Schema.Literal<"Accepted">;
+                readonly value: Schema.Codec<import("./json-value.js").JsonValue, import("./json-value.js").JsonValue, never, never>;
+                readonly evidence: Schema.NullOr<Schema.Struct<{
+                    readonly messageIndex: Schema.Natural;
+                    readonly quote: Schema.String;
+                }>>;
+                readonly issuedQuestion: Schema.NullOr<Schema.Struct<{
+                    readonly messageIndex: Schema.Natural;
+                    readonly text: Schema.String;
+                }>>;
+            }>]>;
+        }>>;
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+        readonly repairPending: Schema.Boolean;
+        readonly _tag: Schema.Literal<"CollectStage">;
+    }>, Schema.Struct<{
+        readonly tools: Schema.$Array<Schema.Trimmed>;
+        readonly afterExecution: Schema.Literals<readonly ["stay", "complete"]>;
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+        readonly repairPending: Schema.Boolean;
+        readonly _tag: Schema.Literal<"ToolStage">;
+    }>, Schema.Struct<{
+        readonly command: Schema.Trimmed;
+        readonly index: Schema.Natural;
+        readonly name: Schema.Trimmed;
+        readonly status: Schema.Literals<readonly ["complete", "current", "upcoming"]>;
+        readonly repairPending: Schema.Boolean;
+        readonly _tag: Schema.Literal<"CommandStage">;
+    }>]>>;
+}>;
+/** JSON-safe read model rendered by a structured-chat debug inspector. */
+export type StructuredChatDebugSnapshot = Schema.Schema.Type<typeof StructuredChatDebugSnapshotSchema>;
+/** Controls sensitive provenance included in a structured-chat debug snapshot. */
+export interface InspectChatStateOptions {
+    readonly evidence?: "include" | "omit";
+}
+declare const InvalidChatDebugProjection_base: Schema.Class<InvalidChatDebugProjection, Schema.TaggedStruct<"InvalidChatDebugProjection", {
+    readonly reason: Schema.Literals<readonly ["invalid_options", "invalid_state", "invalid_answer_value", "invalid_snapshot"]>;
+}>, import("effect/Cause").YieldableError>;
+/** A chat state or answer could not be projected into safe debug JSON. */
+export declare class InvalidChatDebugProjection extends InvalidChatDebugProjection_base {
+}
+/**
+ * Project one trusted chat definition and Type-side state into browser-safe
+ * inspector data without exposing choice values or raw Effect schemas.
+ */
+export declare const inspectChatState: <const Name extends string, const Version extends number, const Stages extends ChatStageTuple>(chat: ChatDefinition<Name, Version, Stages>, state: ChatState<Name, Version, Stages>, options?: InspectChatStateOptions) => Effect.Effect<StructuredChatDebugSnapshot, InvalidChatDebugProjection>;
+export {};

package/dist/core/debug.js

@@ -0,0 +1,276 @@
+import { cast, Effect, Schema } from "effect";
+import { AnswerModeSchema } from "./answer.js";
+import { ChatNameSchema, ChatVersionSchema, } from "./chat.js";
+import { readCollectStageInspection, } from "./collect-stage.js";
+import { JsonValueSchema } from "./json-value.js";
+import { readCommandStageRuntime, readToolStageRuntime, ToolStageAfterExecutionSchema, } from "./stage.js";
+import { StageNameSchema } from "./stage-name.js";
+import { ToolNameSchema } from "./tool.js";
+const DebugIndexSchema = Schema.Natural;
+const DebugIssuedQuestionSchema = Schema.Struct({
+    messageIndex: DebugIndexSchema,
+    text: Schema.String,
+});
+const DebugAnswerEvidenceSchema = Schema.Struct({
+    messageIndex: DebugIndexSchema,
+    quote: Schema.String,
+});
+const DebugQuestionSchema = Schema.Union([
+    Schema.Struct({
+        _tag: Schema.Literal("FixedQuestion"),
+        text: Schema.String,
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("AdaptiveQuestion"),
+        goal: Schema.String,
+        fallback: Schema.String,
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("AdaptiveChoiceQuestion"),
+        prompt: Schema.String,
+        minimumOptions: Schema.Natural,
+        maximumOptions: Schema.Natural,
+        fallbackOptions: Schema.Array(Schema.String),
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("ChoiceQuestion"),
+        text: Schema.String,
+        options: Schema.Array(Schema.Struct({
+            label: Schema.String,
+        })),
+    }),
+]);
+const DebugFieldStateSchema = Schema.Union([
+    Schema.Struct({
+        _tag: Schema.Literal("Missing"),
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("Asked"),
+        issuedQuestion: DebugIssuedQuestionSchema,
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("Accepted"),
+        value: JsonValueSchema,
+        evidence: Schema.NullOr(DebugAnswerEvidenceSchema),
+        issuedQuestion: Schema.NullOr(DebugIssuedQuestionSchema),
+    }),
+]);
+const DebugFieldSchema = Schema.Struct({
+    field: Schema.String,
+    mode: AnswerModeSchema,
+    description: Schema.String,
+    question: DebugQuestionSchema,
+    state: DebugFieldStateSchema,
+});
+const DebugStageStatusSchema = Schema.Literals([
+    "complete",
+    "current",
+    "upcoming",
+]);
+const DebugStageBaseFields = {
+    index: DebugIndexSchema,
+    name: StageNameSchema,
+    status: DebugStageStatusSchema,
+    repairPending: Schema.Boolean,
+};
+const DebugStageSchema = Schema.Union([
+    Schema.Struct({
+        _tag: Schema.Literal("CollectStage"),
+        ...DebugStageBaseFields,
+        satisfiedFields: Schema.Natural,
+        totalFields: Schema.Natural,
+        fields: Schema.Array(DebugFieldSchema),
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("ToolStage"),
+        ...DebugStageBaseFields,
+        tools: Schema.Array(ToolNameSchema),
+        afterExecution: ToolStageAfterExecutionSchema,
+    }),
+    Schema.Struct({
+        _tag: Schema.Literal("CommandStage"),
+        ...DebugStageBaseFields,
+        command: ToolNameSchema,
+    }),
+]);
+/** Runtime schema for one JSON-safe structured-chat debug snapshot. */
+export const StructuredChatDebugSnapshotSchema = Schema.Struct({
+    schemaVersion: Schema.Literal(1),
+    chat: Schema.Struct({
+        name: ChatNameSchema,
+        version: ChatVersionSchema,
+    }),
+    status: Schema.Literals(["active", "complete"]),
+    currentStage: Schema.Struct({
+        index: DebugIndexSchema,
+        name: StageNameSchema,
+        kind: Schema.Literals(["collect", "tool", "command"]),
+    }),
+    stages: Schema.Array(DebugStageSchema),
+});
+const InspectChatStateOptionsSchema = Schema.Struct({
+    evidence: Schema.optionalKey(Schema.Literals(["include", "omit"])),
+});
+const InvalidChatDebugProjectionReasonSchema = Schema.Literals([
+    "invalid_options",
+    "invalid_state",
+    "invalid_answer_value",
+    "invalid_snapshot",
+]);
+/** A chat state or answer could not be projected into safe debug JSON. */
+export class InvalidChatDebugProjection extends Schema.TaggedError()("InvalidChatDebugProjection", { reason: InvalidChatDebugProjectionReasonSchema }) {
+}
+const invalidProjection = (reason) => new InvalidChatDebugProjection({ reason });
+const projectQuestion = (question) => {
+    switch (question._tag) {
+        case "FixedQuestion":
+            return { _tag: question._tag, text: question.text };
+        case "AdaptiveQuestion":
+            return {
+                _tag: question._tag,
+                goal: question.goal,
+                fallback: question.fallback,
+            };
+        case "AdaptiveChoiceQuestion":
+            return {
+                _tag: question._tag,
+                prompt: question.prompt,
+                minimumOptions: question.minimumOptions,
+                maximumOptions: question.maximumOptions,
+                fallbackOptions: question.fallbackOptions,
+            };
+        case "ChoiceQuestion":
+            return {
+                _tag: question._tag,
+                text: question.text,
+                options: question.options.map(({ label }) => ({ label })),
+            };
+    }
+};
+const stageKind = (stage) => {
+    switch (stage._tag) {
+        case "CollectStage":
+            return "collect";
+        case "ToolStage":
+            return "tool";
+        case "CommandStage":
+            return "command";
+    }
+};
+const stageStatus = (state, index) => {
+    if (index === state.stage) {
+        return state.status === "complete" ? "complete" : "current";
+    }
+    if (index < state.stage) {
+        return "complete";
+    }
+    return "upcoming";
+};
+/**
+ * Project one trusted chat definition and Type-side state into browser-safe
+ * inspector data without exposing choice values or raw Effect schemas.
+ */
+export const inspectChatState = (chat, state, options = {}) => Effect.gen(function* () {
+    const parsedOptions = yield* Schema.decodeUnknownEffect(InspectChatStateOptionsSchema)(options, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidProjection("invalid_options")));
+    const parsedState = yield* Schema.decodeUnknownEffect(Schema.toType(chat.stateSchema))(state, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidProjection("invalid_state")));
+    // SAFETY: this definition's exact state schema parsed the envelope and all
+    // named collect-stage states immediately above; only tuple correlations are
+    // erased for definition-ordered read-only projection.
+    const runtimeState = cast(parsedState);
+    const currentStage = chat.stages[runtimeState.stage];
+    if (currentStage === undefined) {
+        return yield* Effect.fail(invalidProjection("invalid_state"));
+    }
+    const stages = [];
+    for (const [index, stage] of chat.stages.entries()) {
+        const repairPending = runtimeState.repair?.pendingStages.includes(index) ?? false;
+        if (stage._tag === "ToolStage") {
+            const runtime = readToolStageRuntime(stage);
+            stages.push({
+                _tag: "ToolStage",
+                index,
+                name: stage.name,
+                status: stageStatus(runtimeState, index),
+                repairPending,
+                tools: runtime.toolNames,
+                afterExecution: runtime.afterExecution,
+            });
+            continue;
+        }
+        if (stage._tag === "CommandStage") {
+            stages.push({
+                _tag: "CommandStage",
+                index,
+                name: stage.name,
+                status: stageStatus(runtimeState, index),
+                repairPending,
+                command: readCommandStageRuntime(stage).commandName,
+            });
+            continue;
+        }
+        const collectState = runtimeState.stages[stage.name];
+        if (collectState === undefined) {
+            return yield* Effect.fail(invalidProjection("invalid_state"));
+        }
+        const inspection = readCollectStageInspection(stage);
+        const fields = [];
+        let satisfiedFields = 0;
+        for (const field of inspection.fields) {
+            const accepted = collectState.accepted[field.field];
+            const issuedQuestion = collectState.asked[field.field];
+            const fieldBase = {
+                field: field.field,
+                mode: field.mode,
+                description: field.description,
+                question: projectQuestion(field.question),
+            };
+            if (accepted === undefined) {
+                fields.push(issuedQuestion === undefined
+                    ? { ...fieldBase, state: { _tag: "Missing" } }
+                    : {
+                        ...fieldBase,
+                        state: {
+                            _tag: "Asked",
+                            issuedQuestion,
+                        },
+                    });
+                continue;
+            }
+            const encoded = yield* field.encodeValue(accepted.value).pipe(Effect.mapError(() => invalidProjection("invalid_answer_value")));
+            const value = yield* Schema.decodeUnknownEffect(JsonValueSchema)(encoded, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidProjection("invalid_answer_value")));
+            satisfiedFields += 1;
+            fields.push({
+                ...fieldBase,
+                state: {
+                    _tag: "Accepted",
+                    value,
+                    evidence: (parsedOptions.evidence ?? "include") === "include"
+                        ? accepted.evidence
+                        : null,
+                    issuedQuestion: issuedQuestion ?? null,
+                },
+            });
+        }
+        stages.push({
+            _tag: "CollectStage",
+            index,
+            name: stage.name,
+            status: stageStatus(runtimeState, index),
+            repairPending,
+            satisfiedFields,
+            totalFields: inspection.fields.length,
+            fields,
+        });
+    }
+    return yield* Schema.decodeUnknownEffect(StructuredChatDebugSnapshotSchema)({
+        schemaVersion: 1,
+        chat: { name: chat.name, version: chat.version },
+        status: runtimeState.status,
+        currentStage: {
+            index: runtimeState.stage,
+            name: currentStage.name,
+            kind: stageKind(currentStage),
+        },
+        stages,
+    }, { onExcessProperty: "error" }).pipe(Effect.mapError(() => invalidProjection("invalid_snapshot")));
+});