@popcomputer/structured-chat 0.1.0 → 0.2.0

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")));
+});

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

@@ -8,4 +8,4 @@ export interface JsonObject {
 /** 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>;
+export declare const JsonValueSchema: Schema.Codec<JsonValue>;

package/dist/core/json-value.js

@@ -1,3 +1,10 @@
 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 })));
+export const JsonValueSchema = Schema.suspend(() => Schema.Union([
+    Schema.String,
+    Schema.Finite,
+    Schema.Boolean,
+    Schema.Null,
+    Schema.Array(JsonValueSchema),
+    Schema.Record(Schema.String, JsonValueSchema),
+]));

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

@@ -1,9 +1,8 @@
 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>>;
+export declare const ModelGuardNameSchema: Schema.Trimmed;
 /** Safe context supplied before a structured model request begins. */
 export interface ModelGuardContext {
     readonly messages: ReadonlyArray<UntrustedMessage>;
@@ -12,7 +11,7 @@ export interface ModelGuardContext {
 /** Strictly parsed model proposal supplied before application execution. */
 export interface ModelGuardCall {
     readonly name: string;
-    readonly arguments: JsonValue;
+    readonly arguments: unknown;
 }
 /** Safe context supplied after parsing and before a tool executes. */
 export interface ModelGuardCallContext extends ModelGuardContext {

package/dist/core/model-guard.js

@@ -1,7 +1,7 @@
-import { Effect, Schema, unsafeCoerce } from "effect";
+import { Effect, Function as Fn, Schema } 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]+)*$/));
+export const ModelGuardNameSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(100), Schema.isPattern(/^[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);
@@ -17,7 +17,7 @@ export const defineModelGuard = (definition) => {
 const runtimeModelGuard = (guard) => {
     // SAFETY: ModelGuardDefinitionContract carries the package-owned nominal
     // identity and can only be constructed by defineModelGuard.
-    return unsafeCoerce(guard);
+    return Fn.cast(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", {
@@ -25,7 +25,7 @@ const runGuardPhase = (guards, phase, run) => {
     })), { 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;
+    return Fn.cast(execution);
 };
 /** @internal */
 export const runModelGuards = (guards, context) => {

package/dist/core/model.d.ts

@@ -4,39 +4,35 @@ import { type ModelGuardError, type ModelGuardRequirements, type ModelGuardTuple
 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">;
+export declare const TrustedInstructionSchema: Schema.brand<Schema.Trimmed, "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"]>;
+export declare const ConversationRoleSchema: Schema.Literals<readonly ["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>;
+    readonly role: Schema.Literals<readonly ["user", "assistant"]>;
+    readonly content: Schema.Trimmed;
 }>;
 /** 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"]>;
-}>;
+export declare const ChatModelUnavailableReasonSchema: Schema.Literals<readonly ["request_failed", "timed_out", "response_blocked", "invalid_response"]>;
+declare const ChatModelUnavailable_base: Schema.Class<ChatModelUnavailable, Schema.TaggedStruct<"ChatModelUnavailable", {
+    readonly reason: Schema.Literals<readonly ["request_failed", "timed_out", "response_blocked", "invalid_response"]>;
+}>, import("effect/Cause").YieldableError>;
 /** 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"]>;
-}>;
+export declare const UnsupportedModelToolSchemaReasonSchema: Schema.Literals<readonly ["root_not_object", "additional_properties_allowed", "optional_property"]>;
+declare const UnsupportedModelToolSchema_base: Schema.Class<UnsupportedModelToolSchema, Schema.TaggedStruct<"UnsupportedModelToolSchema", {
+    readonly tool: Schema.Trimmed;
+    readonly path: Schema.Trimmed;
+    readonly reason: Schema.Literals<readonly ["root_not_object", "additional_properties_allowed", "optional_property"]>;
+}>, import("effect/Cause").YieldableError>;
 /** A model tool schema is incompatible with strict provider decoding. */
 export declare class UnsupportedModelToolSchema extends UnsupportedModelToolSchema_base {
 }
@@ -54,7 +50,7 @@ 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>;
+declare const StructuredChatModel_base: Context.ServiceClass<StructuredChatModel, "@popcomputer/structured-chat/StructuredChatModel", StructuredChatModelService>;
 /** Effect service for the configured structured chat model adapter. */
 export declare class StructuredChatModel extends StructuredChatModel_base {
 }

package/dist/core/model.js

@@ -1,32 +1,44 @@
 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"));
+export const TrustedInstructionSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(20_000)).pipe(Schema.brand("TrustedInstruction"));
 /** Conversation role accepted as untrusted model context. */
-export const ConversationRoleSchema = Schema.Literal("user", "assistant");
+export const ConversationRoleSchema = Schema.Literals([
+    "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)),
+    content: Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(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");
+export const ChatModelUnavailableReasonSchema = Schema.Literals([
+    "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");
+export const UnsupportedModelToolSchemaReasonSchema = Schema.Literals([
+    "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)),
+    tool: Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(100)),
+    path: Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(2_000)),
     reason: UnsupportedModelToolSchemaReasonSchema,
 }) {
 }
 /** Effect service for the configured structured chat model adapter. */
-export class StructuredChatModel extends Context.Tag("@popcomputer/structured-chat/StructuredChatModel")() {
+export class StructuredChatModel extends Context.Service()("@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" ||
@@ -36,7 +48,7 @@ const isRepairableModelOutput = (error) => error._tag === "InvalidToolCall" ||
 export const planToolCall = (input) => runModelGuards(input.guards ?? [], {
     messages: input.messages,
     toolNames: input.tools.models.map(({ name }) => name),
-}).pipe(Effect.zipRight(StructuredChatModel), Effect.flatMap((model) => {
+}).pipe(Effect.andThen(StructuredChatModel), Effect.flatMap((model) => {
     const requestParsedCall = (instructions, attempt) => model
         .requestTool({
         instructions,
@@ -68,7 +80,7 @@ export const planToolCall = (input) => runModelGuards(input.guards ?? [], {
                 errorTag: error._tag,
                 errorReason: error.reason,
             };
-        return Effect.logWarning("Retrying structured model output").pipe(Effect.annotateLogs(annotations), Effect.zipRight(requestParsedCall([
+        return Effect.logWarning("Retrying structured model output").pipe(Effect.annotateLogs(annotations), Effect.andThen(requestParsedCall([
             ...input.instructions,
             invalidOutputRepairInstruction,
         ], 2)));