@popcomputer/structured-chat 0.1.0

package/dist/core/protocol.js

@@ -0,0 +1,153 @@
+import { Effect, Schema } from "effect";
+import { ChatSessionIdSchema, ChatSessionRevisionSchema, } from "./session.js";
+import { defineView } from "./view.js";
+/** Bounded plain text emitted by a structured chat presenter. */
+export const AssistantTextPartSchema = Schema.Struct({
+    type: Schema.Literal("text"),
+    text: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(20_000)),
+});
+/** Provider-neutral named data emitted by a structured chat presenter. */
+export const AssistantDataPartSchema = Schema.Struct({
+    type: Schema.Literal("data"),
+    name: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100), Schema.pattern(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/)),
+    data: Schema.Unknown,
+});
+/** Message parts transported from a structured chat action to a browser. */
+export const AssistantMessagePartSchema = Schema.Union(AssistantTextPartSchema, AssistantDataPartSchema);
+/** Strict assistant message returned by one structured chat action. */
+export const StructuredChatAssistantMessageSchema = Schema.Struct({
+    role: Schema.Literal("assistant"),
+    content: Schema.NonEmptyArray(AssistantMessagePartSchema).pipe(Schema.maxItems(20)),
+});
+/** Opaque browser-held reference to one server-owned chat session. */
+export const StructuredChatSessionReferenceSchema = Schema.Struct({
+    id: ChatSessionIdSchema,
+    revision: ChatSessionRevisionSchema,
+});
+/** Browser request carrying no server-owned chat state. */
+export const StructuredChatTurnRequestSchema = Schema.Struct({
+    session: Schema.optional(StructuredChatSessionReferenceSchema),
+    message: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(50_000)),
+});
+/** Versioned browser response for one persisted structured chat turn. */
+export const StructuredChatTurnResponseSchema = Schema.Struct({
+    schemaVersion: Schema.Literal(1),
+    session: Schema.optional(StructuredChatSessionReferenceSchema),
+    message: StructuredChatAssistantMessageSchema,
+});
+/** Built-in browser contract for one collect-stage question. */
+export const CollectQuestionView = defineView({
+    name: "collect_question",
+    version: 1,
+    schema: Schema.Struct({
+        stage: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100)),
+        field: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100)),
+        text: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(500)),
+        options: Schema.Array(Schema.Struct({
+            label: Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100)),
+        })).pipe(Schema.maxItems(20)),
+    }),
+});
+/** Safe reason that application-owned message presentation was rejected. */
+export class InvalidChatPresentation extends Schema.TaggedError()("InvalidChatPresentation", { reason: Schema.Literal("invalid_message") }) {
+}
+/** Construct and validate one plain assistant text part. */
+const makeText = (text) => Schema.validateSync(AssistantTextPartSchema)({ type: "text", text });
+/** Constructors for deterministic assistant message parts. */
+export const Text = {
+    make: makeText,
+};
+const invalidPresentation = () => new InvalidChatPresentation({ reason: "invalid_message" });
+const parseResponse = (input) => Schema.decodeUnknown(StructuredChatTurnResponseSchema)(input, {
+    onExcessProperty: "error",
+}).pipe(Effect.mapError(invalidPresentation));
+const buildPresentation = (evaluate) => Effect.try({
+    try: evaluate,
+    catch: invalidPresentation,
+});
+/**
+ * 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 const presentChatNotice = (input) => buildPresentation(() => ({
+    schemaVersion: 1,
+    session: input.session,
+    message: {
+        role: "assistant",
+        content: [makeText(input.text)],
+    },
+})).pipe(Effect.flatMap(parseResponse));
+/**
+ * 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 const presentAnswerValidationRejection = (input) => buildPresentation(() => ({
+    schemaVersion: 1,
+    session: input.session,
+    message: {
+        role: "assistant",
+        content: [
+            CollectQuestionView.make({
+                stage: input.rejection.stage,
+                field: input.rejection.question.field,
+                text: input.rejection.question.text,
+                options: [
+                    ...input.rejection.question.options.map(({ label }) => ({
+                        label,
+                    })),
+                    ...(input.rejection.question.escape === undefined
+                        ? []
+                        : [input.rejection.question.escape]),
+                ],
+            }),
+        ],
+    },
+})).pipe(Effect.flatMap(parseResponse));
+/**
+ * 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 const presentChatReply = (reply, options = {}) => {
+    const buildContent = () => {
+        if (reply.turn._tag === "Question") {
+            // SAFETY: The discriminant narrows the generic Turn to its question
+            // member even though TypeScript cannot retain that fact through Extract.
+            const questionTurn = reply.turn;
+            return options.question?.(questionTurn) ?? [
+                CollectQuestionView.make({
+                    stage: reply.turn.stage,
+                    field: reply.turn.question.field,
+                    text: reply.turn.question.text,
+                    options: [
+                        ...reply.turn.question.options.map(({ label }) => ({
+                            label,
+                        })),
+                        ...(reply.turn.question.escape === undefined
+                            ? []
+                            : [reply.turn.question.escape]),
+                    ],
+                }),
+            ];
+        }
+        // SAFETY: The non-question branch contains only ToolResult and Complete.
+        const toolTurn = reply.turn;
+        return options.result?.(toolTurn) ?? reply.turn.result.views;
+    };
+    return buildPresentation(buildContent).pipe(Effect.flatMap((content) => parseResponse({
+        schemaVersion: 1,
+        session: {
+            id: reply.sessionId,
+            revision: reply.revision,
+        },
+        message: { role: "assistant", content },
+    })), Effect.withSpan("popcomputer.structured_chat.presentation.reply", {
+        attributes: { stage: reply.turn.stage },
+    }));
+};

package/dist/core/question.d.ts

@@ -0,0 +1,52 @@
+/** One application-authored question whose wording never changes. */
+export interface FixedQuestion {
+    readonly _tag: "FixedQuestion";
+    readonly text: string;
+}
+/** A goal from which a model may phrase one contextual question. */
+export interface AdaptiveQuestion {
+    readonly _tag: "AdaptiveQuestion";
+    /** Model-facing phrasing goal; never shown to the user. */
+    readonly goal: string;
+    /** User-facing question shown when no valid model wording is available. */
+    readonly fallback: string;
+}
+/** A contextual question with bounded model suggestions and safe fallbacks. */
+export interface AdaptiveChoiceQuestion {
+    readonly _tag: "AdaptiveChoiceQuestion";
+    readonly prompt: string;
+    readonly minimumOptions: number;
+    readonly maximumOptions: number;
+    readonly fallbackOptions: ReadonlyArray<string>;
+}
+/** One typed answer offered by an application-authored choice question. */
+export interface QuestionChoice<Value> {
+    readonly label: string;
+    readonly value: Value;
+}
+/** One application-authored question with a closed set of typed answers. */
+export interface ChoiceQuestion<Value> {
+    readonly _tag: "ChoiceQuestion";
+    readonly text: string;
+    readonly options: readonly [
+        QuestionChoice<Value>,
+        ...ReadonlyArray<QuestionChoice<Value>>
+    ];
+}
+/** Question strategies supported by a collect stage. */
+export type QuestionDefinition<Value = unknown> = FixedQuestion | AdaptiveQuestion | (Value extends string ? AdaptiveChoiceQuestion : never) | ChoiceQuestion<Value>;
+/** Minimum runtime union retained for any typed question definition. */
+export type QuestionDefinitionContract = FixedQuestion | AdaptiveQuestion | AdaptiveChoiceQuestion | ChoiceQuestion<unknown>;
+/** Constructors for static, adaptive, and typed choice questions. */
+export declare const Question: {
+    readonly fixed: (text: string) => FixedQuestion;
+    readonly adaptive: (goal: string, options: {
+        readonly fallback: string;
+    }) => AdaptiveQuestion;
+    readonly adaptiveChoice: (prompt: string, options: {
+        readonly minimumOptions: number;
+        readonly maximumOptions: number;
+        readonly fallbackOptions?: ReadonlyArray<string>;
+    }) => AdaptiveChoiceQuestion;
+    readonly choice: <const Options extends readonly [QuestionChoice<unknown>, ...ReadonlyArray<QuestionChoice<unknown>>]>(text: string, options: Options) => ChoiceQuestion<Options[number]["value"]>;
+};

package/dist/core/question.js

@@ -0,0 +1,62 @@
+import { Schema, unsafeCoerce } from "effect";
+const QuestionTextSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(500));
+const QuestionGoalSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(1_000));
+const ChoiceLabelSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100));
+const fixed = (text) => ({
+    _tag: "FixedQuestion",
+    text: Schema.decodeSync(QuestionTextSchema)(text),
+});
+const adaptive = (goal, options) => ({
+    _tag: "AdaptiveQuestion",
+    goal: Schema.decodeSync(QuestionGoalSchema)(goal),
+    fallback: Schema.decodeSync(QuestionTextSchema)(options.fallback),
+});
+const adaptiveChoice = (prompt, options) => {
+    const minimumOptions = Schema.decodeSync(Schema.Number.pipe(Schema.int(), Schema.between(1, 20)))(options.minimumOptions);
+    const maximumOptions = Schema.decodeSync(Schema.Number.pipe(Schema.int(), Schema.between(1, 20)))(options.maximumOptions);
+    if (minimumOptions > maximumOptions) {
+        throw new Error("Adaptive choice minimumOptions cannot exceed maximumOptions");
+    }
+    const fallbackOptions = (options.fallbackOptions ?? []).map((label) => Schema.decodeSync(ChoiceLabelSchema)(label));
+    const normalizedFallbacks = fallbackOptions.map((label) => label.toLocaleLowerCase("en"));
+    if (new Set(normalizedFallbacks).size !== fallbackOptions.length) {
+        throw new Error("Adaptive choice fallback options must be unique");
+    }
+    if (fallbackOptions.length > 0 &&
+        (fallbackOptions.length < minimumOptions ||
+            fallbackOptions.length > maximumOptions)) {
+        throw new Error("Adaptive choice fallback options must satisfy the configured bounds");
+    }
+    return {
+        _tag: "AdaptiveChoiceQuestion",
+        prompt: Schema.decodeSync(QuestionTextSchema)(prompt),
+        minimumOptions,
+        maximumOptions,
+        fallbackOptions,
+    };
+};
+const choice = (text, options) => {
+    const labels = options.map(({ label }) => Schema.decodeSync(ChoiceLabelSchema)(label));
+    const normalized = labels.map((label) => label.toLocaleLowerCase("en"));
+    if (new Set(normalized).size !== normalized.length) {
+        throw new Error("Choice question labels must be unique");
+    }
+    const parsedOptions = options.map((option, index) => ({
+        ...option,
+        label: labels[index] ?? option.label,
+    }));
+    // SAFETY: map preserves the non-empty tuple length and each option's value;
+    // every replacement label was parsed at the same array index.
+    return {
+        _tag: "ChoiceQuestion",
+        text: Schema.decodeSync(QuestionTextSchema)(text),
+        options: unsafeCoerce(parsedOptions),
+    };
+};
+/** Constructors for static, adaptive, and typed choice questions. */
+export const Question = {
+    fixed,
+    adaptive,
+    adaptiveChoice,
+    choice,
+};

package/dist/core/repair.d.ts

@@ -0,0 +1,14 @@
+import { type StructuredDefinition } from "./definition.js";
+/** Package-owned opt-in policy for bounded standard conversation repair. */
+export interface StandardRepair extends StructuredDefinition<"repair"> {
+    readonly _tag: "StandardRepair";
+    readonly maximumCorrections: number;
+}
+/** Options for standard correction detection and state repair. */
+export interface StandardRepairOptions {
+    readonly maximumCorrections?: number;
+}
+/** Opt-in conversation-repair policies. */
+export declare const Repair: {
+    readonly standard: (options?: StandardRepairOptions) => StandardRepair;
+};

package/dist/core/repair.js

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+import { structuredDefinition, } from "./definition.js";
+const maximumCorrectionsSchema = Schema.Number.pipe(Schema.int(), Schema.between(1, 20));
+const standard = (options = {}) => structuredDefinition("repair")({
+    _tag: "StandardRepair",
+    maximumCorrections: Schema.decodeSync(maximumCorrectionsSchema)(options.maximumCorrections ?? 5),
+});
+/** Opt-in conversation-repair policies. */
+export const Repair = { standard };

package/dist/core/session.d.ts

@@ -0,0 +1,78 @@
+import { Context, Effect, Schema } from "effect";
+import { type UntrustedMessage } from "./model.js";
+/** Stable application-owned identifier for one chat session. */
+export declare const ChatSessionIdSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+/** Optional application-owned partition for otherwise public session IDs. */
+export declare const ChatSessionNamespaceSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+/** Opaque optimistic revision emitted by a session store adapter. */
+export declare const ChatSessionRevisionSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+/** Persisted session snapshot revalidated by the chat runtime after loading. */
+export declare const ChatSessionSnapshotSchema: Schema.Struct<{
+    revision: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+    state: typeof Schema.Unknown;
+    messages: Schema.filter<Schema.Array$<Schema.Struct<{
+        role: Schema.Literal<["user", "assistant"]>;
+        content: Schema.filter<typeof Schema.NonEmptyTrimmedString>;
+    }>>>;
+}>;
+/** Parsed persisted chat session snapshot. */
+export type ChatSessionSnapshot = Schema.Schema.Type<typeof ChatSessionSnapshotSchema>;
+/** Successful optimistic session replacement returned by an adapter. */
+export declare const ChatSessionReplacementSchema: Schema.Struct<{
+    revision: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;
+}>;
+/** Successful optimistic session replacement returned by an adapter. */
+export type ChatSessionReplacement = Schema.Schema.Type<typeof ChatSessionReplacementSchema>;
+/** Safe reason that a session store dependency was unavailable. */
+export declare const ChatSessionStoreUnavailableReasonSchema: Schema.Literal<["load_failed", "write_failed"]>;
+declare const ChatSessionStoreUnavailable_base: Schema.TaggedErrorClass<ChatSessionStoreUnavailable, "ChatSessionStoreUnavailable", {
+    readonly _tag: Schema.tag<"ChatSessionStoreUnavailable">;
+} & {
+    reason: Schema.Literal<["load_failed", "write_failed"]>;
+}>;
+/** A session store adapter could not load or replace state. */
+export declare class ChatSessionStoreUnavailable extends ChatSessionStoreUnavailable_base {
+}
+declare const ChatSessionConflict_base: Schema.TaggedErrorClass<ChatSessionConflict, "ChatSessionConflict", {
+    readonly _tag: Schema.tag<"ChatSessionConflict">;
+} & {
+    reason: Schema.Literal<["concurrent_update"]>;
+}>;
+/** A concurrent or stale transition attempted to replace newer state. */
+export declare class ChatSessionConflict extends ChatSessionConflict_base {
+}
+/** Safe reason that session input or persisted data was rejected. */
+export declare const InvalidChatSessionReasonSchema: Schema.Literal<["invalid_input", "invalid_snapshot", "invalid_state", "invalid_replacement", "history_limit"]>;
+declare const InvalidChatSession_base: Schema.TaggedErrorClass<InvalidChatSession, "InvalidChatSession", {
+    readonly _tag: Schema.tag<"InvalidChatSession">;
+} & {
+    reason: Schema.Literal<["invalid_input", "invalid_snapshot", "invalid_state", "invalid_replacement", "history_limit"]>;
+}>;
+/** Session input or persisted state failed runtime validation. */
+export declare class InvalidChatSession extends InvalidChatSession_base {
+}
+/** Stable scope supplied to every session store operation. */
+export interface ChatSessionScope {
+    readonly namespace: string;
+    readonly sessionId: string;
+    readonly chat: string;
+    readonly version: number;
+}
+/** Complete optimistic replacement supplied to a session store adapter. */
+export interface ReplaceChatSessionInput extends ChatSessionScope {
+    readonly expectedRevision: string | null;
+    readonly state: unknown;
+    readonly messages: ReadonlyArray<UntrustedMessage>;
+}
+/** Narrow persistence seam for server-owned structured chat sessions. */
+export interface ChatSessionStoreService {
+    /** Load one raw snapshot, or null when the session has not started. */
+    readonly load: (scope: ChatSessionScope) => Effect.Effect<unknown | null, ChatSessionStoreUnavailable>;
+    /** Atomically replace one complete session at its expected revision. */
+    readonly replace: (input: ReplaceChatSessionInput) => Effect.Effect<unknown, ChatSessionStoreUnavailable | ChatSessionConflict>;
+}
+declare const ChatSessionStore_base: Context.TagClass<ChatSessionStore, "@popcomputer/structured-chat/ChatSessionStore", ChatSessionStoreService>;
+/** Effect service for the configured server-owned chat session store. */
+export declare class ChatSessionStore extends ChatSessionStore_base {
+}
+export {};

package/dist/core/session.js

@@ -0,0 +1,34 @@
+import { Context, Effect, Schema } from "effect";
+import { UntrustedMessageSchema } from "./model.js";
+/** Stable application-owned identifier for one chat session. */
+export const ChatSessionIdSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(200), Schema.pattern(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/));
+/** Optional application-owned partition for otherwise public session IDs. */
+export const ChatSessionNamespaceSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(200), Schema.pattern(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/));
+/** Opaque optimistic revision emitted by a session store adapter. */
+export const ChatSessionRevisionSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(200), Schema.pattern(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/));
+/** Persisted session snapshot revalidated by the chat runtime after loading. */
+export const ChatSessionSnapshotSchema = Schema.Struct({
+    revision: ChatSessionRevisionSchema,
+    state: Schema.Unknown,
+    messages: Schema.Array(UntrustedMessageSchema).pipe(Schema.maxItems(200)),
+});
+/** Successful optimistic session replacement returned by an adapter. */
+export const ChatSessionReplacementSchema = Schema.Struct({
+    revision: ChatSessionRevisionSchema,
+});
+/** Safe reason that a session store dependency was unavailable. */
+export const ChatSessionStoreUnavailableReasonSchema = Schema.Literal("load_failed", "write_failed");
+/** A session store adapter could not load or replace state. */
+export class ChatSessionStoreUnavailable extends Schema.TaggedError()("ChatSessionStoreUnavailable", { reason: ChatSessionStoreUnavailableReasonSchema }) {
+}
+/** A concurrent or stale transition attempted to replace newer state. */
+export class ChatSessionConflict extends Schema.TaggedError()("ChatSessionConflict", { reason: Schema.Literal("concurrent_update") }) {
+}
+/** Safe reason that session input or persisted data was rejected. */
+export const InvalidChatSessionReasonSchema = Schema.Literal("invalid_input", "invalid_snapshot", "invalid_state", "invalid_replacement", "history_limit");
+/** Session input or persisted state failed runtime validation. */
+export class InvalidChatSession extends Schema.TaggedError()("InvalidChatSession", { reason: InvalidChatSessionReasonSchema }) {
+}
+/** Effect service for the configured server-owned chat session store. */
+export class ChatSessionStore extends Context.Tag("@popcomputer/structured-chat/ChatSessionStore")() {
+}

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

@@ -0,0 +1,3 @@
+import { Schema } from "effect";
+/** Stable machine-facing name for one structured chat stage. */
+export declare const StageNameSchema: Schema.filter<Schema.filter<typeof Schema.NonEmptyTrimmedString>>;

package/dist/core/stage-name.js

@@ -0,0 +1,3 @@
+import { Schema } from "effect";
+/** Stable machine-facing name for one structured chat stage. */
+export const StageNameSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(100), Schema.pattern(/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/));

package/dist/core/stage.d.ts

@@ -0,0 +1,88 @@
+import { Effect, Schema } from "effect";
+import { StructuredChatModel, type ChatModelUnavailable, type UnsupportedModelToolSchema, type UntrustedMessage } from "./model.js";
+import type { ModelGuardError, ModelGuardRequirements, ModelGuardTuple } from "./model-guard.js";
+import { type ToolSet, type ToolSetCall, type ToolSetError, type ToolSetExecution, type ToolSetRequirements, type ToolTuple } from "./tool-set.js";
+import type { CommandDefinitionContract, CommandExecutionContext, InvalidToolCall, InvalidToolProjection, StructuredCommand, ToolCall, ToolExecution, QueryToolDefinitionContract } from "./tool.js";
+import { type StructuredDefinition } from "./definition.js";
+export { StageNameSchema } from "./stage-name.js";
+/** State transition applied after one tool-stage execution. */
+export declare const ToolStageAfterExecutionSchema: Schema.Literal<["stay", "complete"]>;
+/** State transition applied after one tool-stage execution. */
+export type ToolStageAfterExecution = Schema.Schema.Type<typeof ToolStageAfterExecutionSchema>;
+/** Definition input for one stage-scoped, repeatable tool step. */
+export interface DefineToolStageInput<Name extends string, Tools extends ToolTuple, Guards extends ModelGuardTuple> {
+    readonly name: Name;
+    readonly instructions: readonly [string, ...ReadonlyArray<string>];
+    readonly tools: Tools;
+    readonly guards?: Guards;
+    readonly afterExecution?: ToolStageAfterExecution;
+}
+/** @internal Erased tool-stage behavior consumed by the chat runtime. */
+export interface ToolStageRuntime {
+    readonly afterExecution: ToolStageAfterExecution;
+    readonly toolNames: ReadonlyArray<string>;
+    readonly planWith: (messages: ReadonlyArray<UntrustedMessage>, additionalTool: QueryToolDefinitionContract) => Effect.Effect<ToolCall<string, Schema.Schema.AnyNoContext>, unknown, unknown>;
+    readonly execute: (call: ToolCall<string, Schema.Schema.AnyNoContext>) => Effect.Effect<unknown, unknown, unknown>;
+    readonly run: (messages: ReadonlyArray<UntrustedMessage>) => Effect.Effect<unknown, unknown, unknown>;
+}
+declare const toolStageRuntime: unique symbol;
+/** Minimum sealed tool-stage shape accepted by a chat definition. */
+export interface ToolStageDefinitionContract extends StructuredDefinition<"tool_stage"> {
+    readonly _tag: "ToolStage";
+    readonly name: string;
+    readonly [toolStageRuntime]: ToolStageRuntime;
+}
+/** @internal Read the erased runtime from an authentic tool stage. */
+export declare const readToolStageRuntime: (stage: ToolStageDefinitionContract) => ToolStageRuntime;
+/** @internal Erased command-stage behavior consumed by the chat runtime. */
+export interface CommandStageRuntime {
+    readonly commandName: string;
+    readonly run: (messages: ReadonlyArray<UntrustedMessage>, context: CommandExecutionContext) => Effect.Effect<unknown, unknown, unknown>;
+}
+declare const commandStageRuntime: unique symbol;
+/** Minimum sealed terminal command-stage shape accepted by a chat. */
+export interface CommandStageDefinitionContract extends StructuredDefinition<"command_stage"> {
+    readonly _tag: "CommandStage";
+    readonly name: string;
+    readonly command: CommandDefinitionContract;
+    readonly [commandStageRuntime]: CommandStageRuntime;
+}
+/** @internal Read the erased runtime from an authentic command stage. */
+export declare const readCommandStageRuntime: (stage: CommandStageDefinitionContract) => CommandStageRuntime;
+/** One stage exposing a closed set of structured tools for each user turn. */
+export interface ToolStage<Name extends string, Tools extends ToolTuple, Guards extends ModelGuardTuple> extends ToolStageDefinitionContract {
+    readonly _tag: "ToolStage";
+    readonly name: Name;
+    readonly toolSet: ToolSet<Tools>;
+    readonly guards: Guards;
+    readonly afterExecution: ToolStageAfterExecution;
+    /** Ask for and parse one stage-scoped call without executing it. */
+    readonly plan: (messages: ReadonlyArray<UntrustedMessage>) => Effect.Effect<ToolSetCall<Tools>, ChatModelUnavailable | UnsupportedModelToolSchema | InvalidToolCall | ModelGuardError<Guards>, StructuredChatModel | ModelGuardRequirements<Guards>>;
+    /** Run one required tool call against this stage's capabilities. */
+    readonly run: (messages: ReadonlyArray<UntrustedMessage>) => Effect.Effect<ToolSetExecution<Tools>, ChatModelUnavailable | UnsupportedModelToolSchema | ToolSetError<Tools> | ModelGuardError<Guards>, StructuredChatModel | ToolSetRequirements<Tools> | ModelGuardRequirements<Guards>>;
+}
+type CommandCall<Command> = Command extends StructuredCommand<infer Name, infer InputSchema, infer _ServerResult, infer _Error, infer _Requirements, infer _ModelSchema, infer _Presenters> ? ToolCall<Name, InputSchema> : never;
+type CommandResult<Command> = Command extends StructuredCommand<infer _Name, infer _InputSchema, infer ServerResult, infer _Error, infer _Requirements, infer ModelSchema, infer Presenters> ? ToolExecution<ServerResult, ModelSchema, Presenters> : never;
+type CommandError<Command> = Command extends StructuredCommand<infer _Name, infer _InputSchema, infer _ServerResult, infer Error, infer _Requirements, infer _ModelSchema, infer _Presenters> ? Error : never;
+type CommandRequirements<Command> = Command extends StructuredCommand<infer _Name, infer _InputSchema, infer _ServerResult, infer _Error, infer Requirements, infer _ModelSchema, infer _Presenters> ? Requirements : never;
+/** Definition input for one exactly-once-intent terminal command stage. */
+export interface DefineCommandStageInput<Name extends string, Command extends CommandDefinitionContract, Guards extends ModelGuardTuple> {
+    readonly name: Name;
+    readonly instructions: readonly [string, ...ReadonlyArray<string>];
+    readonly command: Command;
+    readonly guards?: Guards;
+}
+/** One terminal stage exposing exactly one side-effecting command. */
+export interface CommandStage<Name extends string, Command extends CommandDefinitionContract, Guards extends ModelGuardTuple> extends CommandStageDefinitionContract {
+    readonly name: Name;
+    readonly command: Command;
+    readonly guards: Guards;
+    readonly plan: (messages: ReadonlyArray<UntrustedMessage>) => Effect.Effect<CommandCall<Command>, ChatModelUnavailable | UnsupportedModelToolSchema | InvalidToolCall | ModelGuardError<Guards>, StructuredChatModel | ModelGuardRequirements<Guards>>;
+    readonly run: (messages: ReadonlyArray<UntrustedMessage>, context: CommandExecutionContext) => Effect.Effect<CommandResult<Command>, ChatModelUnavailable | UnsupportedModelToolSchema | InvalidToolCall | InvalidToolProjection | CommandError<Command> | ModelGuardError<Guards>, StructuredChatModel | CommandRequirements<Command> | ModelGuardRequirements<Guards>>;
+}
+/** Constructors for sequential structured chat stages. */
+export declare const Stage: {
+    readonly collect: <const Name extends string, const Fields extends import("./collect-stage.js").AnswerFields, const Guards extends ModelGuardTuple = readonly []>(definition: import("./collect-stage.js").DefineCollectStageInput<Name, Fields, Guards>) => import("./collect-stage.js").CollectStage<Name, Fields, Guards>;
+    readonly tools: <const Name extends string, const Tools extends ToolTuple, const Guards extends ModelGuardTuple = readonly []>(definition: DefineToolStageInput<Name, Tools, Guards>) => ToolStage<Name, Tools, Guards>;
+    readonly command: <const Name extends string, const Command extends CommandDefinitionContract, const Guards extends ModelGuardTuple = readonly []>(definition: DefineCommandStageInput<Name, Command, Guards>) => CommandStage<Name, Command, Guards>;
+};

package/dist/core/stage.js

@@ -0,0 +1,104 @@
+import { Effect, Schema, unsafeCoerce } from "effect";
+import { Instruction, planToolCall, StructuredChatModel, } from "./model.js";
+import { defineToolSet, } from "./tool-set.js";
+import { defineCollectStage } from "./collect-stage.js";
+import { StageNameSchema } from "./stage-name.js";
+import { structuredDefinition, } from "./definition.js";
+export { StageNameSchema } from "./stage-name.js";
+/** State transition applied after one tool-stage execution. */
+export const ToolStageAfterExecutionSchema = Schema.Literal("stay", "complete");
+const toolStageRuntime = Symbol("@popcomputer/structured-chat/ToolStageRuntime");
+/** @internal Read the erased runtime from an authentic tool stage. */
+export const readToolStageRuntime = (stage) => stage[toolStageRuntime];
+const commandStageRuntime = Symbol("@popcomputer/structured-chat/CommandStageRuntime");
+/** @internal Read the erased runtime from an authentic command stage. */
+export const readCommandStageRuntime = (stage) => stage[commandStageRuntime];
+const defineToolStage = (definition) => {
+    Schema.decodeSync(StageNameSchema)(definition.name);
+    const instructions = definition.instructions.map(Instruction.make);
+    const toolSet = defineToolSet(...definition.tools);
+    // SAFETY: when guards are omitted, Guards uses its readonly [] default; an
+    // explicitly supplied tuple is returned unchanged.
+    const guards = definition.guards ?? unsafeCoerce([]);
+    const afterExecution = Schema.decodeSync(ToolStageAfterExecutionSchema)(definition.afterExecution ?? "stay");
+    const plan = (messages) => planToolCall({
+        instructions,
+        messages,
+        tools: toolSet,
+        guards,
+    }).pipe(Effect.withSpan("popcomputer.structured_chat.stage.plan", {
+        attributes: { stage: definition.name },
+    }));
+    const run = (messages) => plan(messages).pipe(Effect.flatMap(toolSet.execute));
+    // SAFETY: chat repair supplies only a call parsed by a combined set that
+    // contains this exact query tuple; non-repair names therefore belong here.
+    const executeRuntime = toolSet.execute;
+    const planWith = (messages, additionalTool) => {
+        // SAFETY: the additional package-owned query and this non-empty exact
+        // query tuple form another valid closed tool set for planning only.
+        const combined = defineToolSet(additionalTool, ...definition.tools);
+        return planToolCall({
+            instructions,
+            messages,
+            tools: combined,
+            guards,
+        });
+    };
+    return structuredDefinition("tool_stage")({
+        _tag: "ToolStage",
+        name: definition.name,
+        toolSet,
+        guards,
+        afterExecution,
+        plan,
+        run,
+        [toolStageRuntime]: {
+            afterExecution,
+            toolNames: definition.tools.map(({ name }) => name),
+            planWith,
+            execute: executeRuntime,
+            run,
+        },
+    });
+};
+const defineCommandStage = (definition) => {
+    Schema.decodeSync(StageNameSchema)(definition.name);
+    const instructions = definition.instructions.map(Instruction.make);
+    // SAFETY: when omitted, Guards is its readonly [] default.
+    const guards = definition.guards ?? unsafeCoerce([]);
+    const planner = {
+        models: [definition.command.model],
+        // SAFETY: this command parses its literal name and exact input schema.
+        parseCall: definition.command.parseCall,
+    };
+    const plan = (messages) => planToolCall({ instructions, messages, tools: planner, guards }).pipe(Effect.withSpan("popcomputer.structured_chat.command_stage.plan", {
+        attributes: { stage: definition.name },
+    }));
+    // SAFETY: Command has the package-owned identity and command operation;
+    // its parsed call and runtime execute input originate from one definition.
+    const runtimeCommand = unsafeCoerce(definition.command);
+    const runRuntime = (messages, context) => plan(messages).pipe(Effect.flatMap((call) => runtimeCommand.execute(call.arguments, context)), Effect.withSpan("popcomputer.structured_chat.command_stage.run", {
+        attributes: { stage: definition.name },
+    }));
+    // SAFETY: failures and requirements are not recovered; the command's
+    // projections and result are preserved by its own execute operation.
+    const run = runRuntime;
+    return structuredDefinition("command_stage")({
+        _tag: "CommandStage",
+        name: definition.name,
+        command: definition.command,
+        guards,
+        plan,
+        run,
+        [commandStageRuntime]: {
+            commandName: definition.command.name,
+            run: runRuntime,
+        },
+    });
+};
+/** Constructors for sequential structured chat stages. */
+export const Stage = {
+    collect: defineCollectStage,
+    tools: defineToolStage,
+    command: defineCommandStage,
+};