@popcomputer/structured-chat 0.1.0 → 0.2.0

package/dist/integrations/assistant-ui.d.ts

@@ -1,4 +1,5 @@
 import { type ComponentType, type FC } from "react";
+import type { StructuredChatDebugSnapshot } from "../core/debug.js";
 import type { ViewData, ViewDefinitionContract } from "../core/view.js";
 import { type StructuredChatSessionReference, type StructuredChatAssistantMessage } from "../core/protocol.js";
 /** Runtime status supplied by assistant-ui to a data-part renderer. */
@@ -52,6 +53,12 @@ export type AssistantChatFetch = (input: string, init: RequestInit) => Promise<R
 export interface AssistantChatModelAdapterOptions {
     readonly endpoint: string;
     readonly fetch?: AssistantChatFetch;
+    /**
+     * Select the explicit debug response contract and receive its safe state
+     * projection after every successful turn. Observer failures are ignored so
+     * they cannot change the outcome of an already-persisted chat turn.
+     */
+    readonly onDebugSnapshot?: (snapshot: StructuredChatDebugSnapshot) => void | Promise<void>;
 }
 /** Minimum assistant message shape consumed by the browser adapter. */
 export interface AssistantChatThreadMessage {
@@ -88,8 +95,8 @@ export interface AssistantChatModelAdapter {
 /**
  * Adapt assistant-ui to one server-owned structured chat endpoint.
  *
- * Only the latest text and opaque prior revision cross the browser boundary.
- * Tools, instructions, history, answer state, and stage position stay server
- * owned.
+ * By default, only the latest text and opaque prior revision cross the browser
+ * boundary. Supplying `onDebugSnapshot` explicitly selects the separate debug
+ * response contract and receives its safe answer-and-stage projection.
  */
 export declare const makeAssistantChatModelAdapter: (options: AssistantChatModelAdapterOptions) => AssistantChatModelAdapter;

package/dist/integrations/assistant-ui.js

@@ -1,7 +1,8 @@
 import { makeAssistantDataUI, } from "@assistant-ui/core/react";
-import { Either, Schema } from "effect";
+import { Exit, Result, Schema } from "effect";
 import { createElement } from "react";
 import { StructuredChatSessionReferenceSchema, StructuredChatTurnRequestSchema, StructuredChatTurnResponseSchema, } from "../core/protocol.js";
+import { JsonValueSchema } from "../core/json-value.js";
 /**
  * Register one defineView contract as a strictly decoded assistant-ui data UI.
  *
@@ -10,19 +11,25 @@ import { StructuredChatSessionReferenceSchema, StructuredChatTurnRequestSchema,
  */
 export const makeAssistantView = (view, config) => {
     const Renderer = (props) => {
-        const decoded = Schema.decodeUnknownEither(view.partSchema)({
+        const data = Schema.decodeUnknownResult(JsonValueSchema)(props.data);
+        if (Result.isFailure(data)) {
+            return config.fallback === undefined
+                ? null
+                : createElement(config.fallback, props);
+        }
+        const decoded = view.decodeResult({
             type: "data",
             name: view.name,
-            data: props.data,
-        }, { onExcessProperty: "error" });
-        if (Either.isLeft(decoded)) {
+            data: data.success,
+        });
+        if (Result.isFailure(decoded)) {
             return config.fallback === undefined
                 ? null
                 : createElement(config.fallback, props);
         }
         return createElement(config.render, {
             ...props,
-            data: decoded.right.data,
+            data: decoded.success.data,
         });
     };
     return makeAssistantDataUI({
@@ -32,6 +39,15 @@ export const makeAssistantView = (view, config) => {
 };
 /** assistant-ui metadata key carrying the latest opaque session reference. */
 export const assistantChatSessionMetadataKey = "popcomputerStructuredChatSession";
+const notifyDebugSnapshot = (callback, snapshot) => {
+    try {
+        const notified = callback(snapshot);
+        void Promise.resolve(notified).catch(() => undefined);
+    }
+    catch {
+        // Debug observers are deliberately isolated from the persisted turn.
+    }
+};
 const readMessageText = (message) => message.content
     .flatMap((part) => part.type === "text" && "text" in part ? [part.text] : [])
     .join("\n")
@@ -42,9 +58,9 @@ const readLatestSession = (messages) => {
         if (message?.role !== "assistant") {
             continue;
         }
-        const session = Schema.decodeUnknownEither(StructuredChatSessionReferenceSchema)(message.metadata.custom[assistantChatSessionMetadataKey]);
-        if (Either.isRight(session)) {
-            return session.right;
+        const session = Schema.decodeUnknownExit(StructuredChatSessionReferenceSchema)(message.metadata.custom[assistantChatSessionMetadataKey]);
+        if (Exit.isSuccess(session)) {
+            return session.value;
         }
     }
     return undefined;
@@ -65,13 +81,14 @@ const readTurnRequest = (messages) => {
 /**
  * Adapt assistant-ui to one server-owned structured chat endpoint.
  *
- * Only the latest text and opaque prior revision cross the browser boundary.
- * Tools, instructions, history, answer state, and stage position stay server
- * owned.
+ * By default, only the latest text and opaque prior revision cross the browser
+ * boundary. Supplying `onDebugSnapshot` explicitly selects the separate debug
+ * response contract and receives its safe answer-and-stage projection.
  */
 export const makeAssistantChatModelAdapter = (options) => {
     const fetch_ = options.fetch ??
         ((input, init) => globalThis.fetch(input, init));
+    const onDebugSnapshot = options.onDebugSnapshot;
     return {
         run: async ({ messages, abortSignal }) => {
             const request = readTurnRequest(messages);
@@ -95,17 +112,30 @@ export const makeAssistantChatModelAdapter = (options) => {
             catch {
                 throw new Error("Structured chat returned an invalid response");
             }
-            const decoded = Schema.decodeUnknownEither(StructuredChatTurnResponseSchema)(body, { onExcessProperty: "error" });
-            if (Either.isLeft(decoded)) {
-                throw new Error("Structured chat returned an invalid response");
+            let value;
+            if (onDebugSnapshot === undefined) {
+                const decoded = Schema.decodeUnknownExit(StructuredChatTurnResponseSchema)(body, { onExcessProperty: "error" });
+                if (Exit.isFailure(decoded)) {
+                    throw new Error("Structured chat returned an invalid response");
+                }
+                value = decoded.value;
+            }
+            else {
+                const { StructuredChatDebugTurnResponseSchema } = await import("../core/debug-protocol.js");
+                const decoded = Schema.decodeUnknownExit(StructuredChatDebugTurnResponseSchema)(body, { onExcessProperty: "error" });
+                if (Exit.isFailure(decoded)) {
+                    throw new Error("Structured chat returned an invalid response");
+                }
+                notifyDebugSnapshot(onDebugSnapshot, decoded.value.debug);
+                value = decoded.value;
             }
             return {
-                content: decoded.right.message.content,
+                content: value.message.content,
                 metadata: {
-                    custom: decoded.right.session === undefined
+                    custom: value.session === undefined
                         ? {}
                         : {
-                            [assistantChatSessionMetadataKey]: decoded.right.session,
+                            [assistantChatSessionMetadataKey]: value.session,
                         },
                 },
             };

package/dist/testing/in-memory-session-store.js

@@ -30,7 +30,7 @@ const replaceSnapshot = (sessions, input) => {
     return [snapshot, next];
 };
 /** In-memory optimistic session store intended for tests and examples. */
-export const inMemoryChatSessionStore = Layer.effect(ChatSessionStore, Ref.make(new Map()).pipe(Effect.map((sessions) => ({
+export const inMemoryChatSessionStore = Layer.effect(ChatSessionStore, Ref.make(new Map()).pipe(Effect.map((sessions) => ChatSessionStore.of({
     load: (scope) => Ref.get(sessions).pipe(Effect.map((current) => current.get(scopeKey(scope)) ?? null)),
     replace: (input) => Ref.modify(sessions, (current) => replaceSnapshot(current, input)).pipe(Effect.flatMap((result) => result instanceof ChatSessionConflict
         ? Effect.fail(result)

package/dist/testing/scenario.js

@@ -2,7 +2,7 @@ import { Effect, Layer, Ref, Schema } from "effect";
 import { StructuredChatModel, } from "../core/model.js";
 import { JsonValueSchema, } from "../core/json-value.js";
 const scenarioQuote = Symbol("@popcomputer/structured-chat/testing/ScenarioQuote");
-const ScenarioQuoteSchema = Schema.NonEmptyTrimmedString.pipe(Schema.maxLength(2_000));
+const ScenarioQuoteSchema = Schema.Trimmed.check(Schema.isNonEmpty(), Schema.isMaxLength(2_000));
 const evidenceIndex = (request, quoted) => {
     if (quoted.messageIndex !== undefined) {
         const message = request.untrustedMessages[quoted.messageIndex];
@@ -49,7 +49,7 @@ const answers = (stage, proposed, options = {}) => ({
             if (value === undefined || answer === undefined) {
                 continue;
             }
-            encodedAnswers[field] = Schema.decodeSync(JsonValueSchema)(Schema.encodeSync(answer.schema)(value.value));
+            encodedAnswers[field] = Schema.decodeUnknownSync(JsonValueSchema)(Schema.encodeSync(answer.schema)(value.value));
             evidenceIndex(request, value);
             evidence.push({
                 field,
@@ -76,7 +76,7 @@ const answers = (stage, proposed, options = {}) => ({
 const call = (tool, input) => ({
     respond: () => ({
         name: tool.name,
-        arguments: Schema.decodeSync(JsonValueSchema)(Schema.encodeSync(tool.inputSchema)(input)),
+        arguments: Schema.decodeUnknownSync(JsonValueSchema)(Schema.encodeSync(tool.inputSchema)(input)),
     }),
 });
 const replace = (stage, field, value, options) => {
@@ -92,7 +92,7 @@ const replace = (stage, field, value, options) => {
                 _tag: "ReplaceAcceptedAnswer",
                 stage: stage.name,
                 field,
-                value: Schema.decodeSync(JsonValueSchema)(Schema.encodeSync(answer.schema)(value)),
+                value: Schema.decodeUnknownSync(JsonValueSchema)(Schema.encodeSync(answer.schema)(value)),
                 evidence: {
                     quote: support.quote,
                 },
@@ -126,14 +126,14 @@ const repairs = (first, ...remaining) => ({
 });
 const model = (first, ...remaining) => Layer.effect(StructuredChatModel, Ref.make(0).pipe(Effect.map((cursor) => {
     const steps = [first, ...remaining];
-    return {
+    return StructuredChatModel.of({
         requestTool: (request) => Ref.getAndUpdate(cursor, (index) => index + 1).pipe(Effect.flatMap((index) => {
             const step = steps[index];
             return step === undefined
                 ? Effect.die(new Error(`Scenario model exhausted after ${steps.length} requests`))
                 : Effect.sync(() => step.respond(request));
         })),
-    };
+    });
 })));
 /** Typed constructors for concise valid transcript scenarios. */
 export const Scenario = {

package/examples/answer-modes.ts

@@ -9,84 +9,95 @@ import {
 
 const SearchCatalog = defineTool({
   name: "search_catalog",
-  description: "Search the catalog for relevant agency matches.",
-  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
+  description: "Search the catalog for relevant resources.",
+  input: Schema.Struct({
+    query: Schema.Trimmed.check(Schema.isNonEmpty()),
+  }),
   execute: ({ query }) => Effect.succeed({ query }),
 })
 
 const Search = Stage.tools({
   name: "search",
-  instructions: ["Search the catalog using the completed project brief."],
+  instructions: ["Search the catalog using the completed request details."],
   tools: [SearchCatalog],
 })
 
-const ProjectBrief = Stage.collect({
-  name: "project_brief",
+const RequestDetails = Stage.collect({
+  name: "request_details",
   questions: {
     guidance: "Ask one concise, conversational question at a time.",
     escape: "Not sure yet",
   },
   fields: {
-    priority: Answer.confirmed(Schema.NonEmptyTrimmedString, {
-      description: "Where the client most needs outside help.",
-      ask: Question.adaptiveChoice(
-        "Where could an agency make the biggest difference?",
-        {
-          minimumOptions: 2,
-          maximumOptions: 3,
-          fallbackOptions: [
-            "Launch or grow a product",
-            "Build the brand long term",
-            "Fix a performance problem",
-          ],
-        },
-      ),
-    }),
-    location: Answer.confirmed(Schema.NonEmptyTrimmedString, {
-      description: "Where the client is based.",
-      ask: Question.adaptive(
-        "Ask where the client is based and whether location matters.",
-        {
-          fallback: "Where are you based, and does location matter?",
-        },
-      ),
-    }),
+    goal: Answer.confirmed(
+      Schema.Trimmed.check(Schema.isNonEmpty()),
+      {
+        description: "The outcome the user wants to achieve.",
+        ask: Question.adaptiveChoice(
+          "What would you like help accomplishing?",
+          {
+            minimumOptions: 2,
+            maximumOptions: 3,
+            fallbackOptions: [
+              "Understand a topic",
+              "Compare available options",
+              "Plan the next steps",
+            ],
+          },
+        ),
+      },
+    ),
+    audience: Answer.confirmed(
+      Schema.Trimmed.check(Schema.isNonEmpty()),
+      {
+        description: "Who the requested result is for.",
+        ask: Question.adaptive(
+          "Ask who will use the result and what they already know.",
+          {
+            fallback: "Who is this for, and what do they already know?",
+          },
+        ),
+      },
+    ),
   },
 })
 
 /** A required ask-then-answer workflow before catalog search. */
-export const Matchmaker = defineChat({
-  name: "matchmaker",
+export const GuidedResourceFinder = defineChat({
+  name: "guided_resource_finder",
   version: 1,
-  stages: [ProjectBrief, Search],
+  stages: [RequestDetails, Search],
 })
 
-const ProjectUnderstanding = Stage.collect({
-  name: "project_understanding",
+const RequestUnderstanding = Stage.collect({
+  name: "request_understanding",
   fields: {
-    intent: Answer.semantic(Schema.NonEmptyTrimmedString, {
-      description:
-        "The client's searchable need, desired outcome, sector, or relevant experience.",
-      ask: Question.adaptive(
-        "Ask one useful follow-up only when the request is not searchable yet.",
-        {
-          fallback: "What outcome or experience should I search for?",
-        },
-      ),
-    }),
+    intent: Answer.semantic(
+      Schema.Trimmed.check(Schema.isNonEmpty()),
+      {
+        description:
+          "The user's searchable goal, subject, constraints, or desired outcome.",
+        ask: Question.adaptive(
+          "Ask one useful follow-up only when the request is not searchable yet.",
+          {
+            fallback: "What subject or outcome should I search for?",
+          },
+        ),
+      },
+    ),
   },
 })
 
 /** A chat that can infer a searchable intent from the opening request. */
-export const FreeformMatchmaker = defineChat({
-  name: "freeform_matchmaker",
+export const FreeformResourceFinder = defineChat({
+  name: "freeform_resource_finder",
   version: 1,
-  stages: [ProjectUnderstanding, Search],
+  stages: [RequestUnderstanding, Search],
 })
 
 /** A chat whose catalog search tool is available on the opening turn. */
-export const OpenSearchChat = defineChat({
-  name: "open_search_chat",
+export const OpenResourceSearch = defineChat({
+  name: "open_resource_search",
   version: 1,
   stages: [Search],
 })

package/examples/prompt-injection-policy.ts

@@ -21,9 +21,7 @@ export class UnsafeConversation extends Schema.TaggedError<UnsafeConversation>()
  * Application-owned classifier; production may use any local or remote
  * policy.
  */
-export class ConversationSafety extends Context.Tag(
-  "ConversationSafety",
-)<
+export class ConversationSafety extends Context.Service<
   ConversationSafety,
   {
     readonly checkConversation: (
@@ -33,34 +31,36 @@ export class ConversationSafety extends Context.Tag(
       context: ModelGuardCallContext,
     ) => Effect.Effect<void, UnsafeConversation>
   }
->() {}
+>()("ConversationSafety") {}
 
 /** Effect-native guard composed into any model-backed stage. */
 export const PromptInjectionPolicy = defineModelGuard({
   name: "prompt_injection_policy",
   check: (context) =>
-    ConversationSafety.pipe(
-      Effect.flatMap((safety) =>
-        safety.checkConversation(context),
-      ),
-    ),
+    Effect.gen(function* () {
+      const safety = yield* ConversationSafety
+      return yield* safety.checkConversation(context)
+    }),
   checkCall: (context) =>
-    ConversationSafety.pipe(
-      Effect.flatMap((safety) => safety.checkCall(context)),
-    ),
+    Effect.gen(function* () {
+      const safety = yield* ConversationSafety
+      return yield* safety.checkCall(context)
+    }),
 })
 
-const SearchAgencies = defineTool({
-  name: "search_agencies",
-  description: "Find agencies relevant to the project brief.",
-  input: Schema.Struct({ query: Schema.NonEmptyTrimmedString }),
+const FindResources = defineTool({
+  name: "find_resources",
+  description: "Find resources relevant to the request.",
+  input: Schema.Struct({
+    query: Schema.Trimmed.check(Schema.isNonEmpty()),
+  }),
   execute: ({ query }) => Effect.succeed({ query }),
 })
 
 /** Closed search stage protected by the application policy. */
-export const Matching = Stage.tools({
-  name: "matching",
-  instructions: ["Route the completed brief to one search."],
-  tools: [SearchAgencies],
+export const Lookup = Stage.tools({
+  name: "lookup",
+  instructions: ["Route the completed request to one resource lookup."],
+  tools: [FindResources],
   guards: [PromptInjectionPolicy],
 })

package/examples/resource-search.ts

@@ -0,0 +1,104 @@
+import {
+  Context,
+  Effect,
+  Layer,
+  Schema,
+} from "effect"
+import {
+  defineTool,
+  defineView,
+  Message,
+  Stage,
+  Tool,
+} from "@popcomputer/structured-chat"
+
+interface ResourceMatch {
+  readonly id: string
+  readonly title: string
+  readonly summary: string
+  readonly internalScore: number
+  readonly retrievedText: string
+}
+
+class ResourceCatalog extends Context.Service<
+  ResourceCatalog,
+  {
+    readonly search: (
+      query: string,
+    ) => Effect.Effect<ReadonlyArray<ResourceMatch>>
+  }
+>()("ResourceCatalog") {}
+
+const ResultCards = defineView({
+  name: "result_cards",
+  version: 1,
+  schema: Schema.Struct({
+    results: Schema.Array(
+      Schema.Struct({
+        id: Schema.String,
+        title: Schema.String,
+        summary: Schema.String,
+      }),
+    ),
+  }),
+})
+
+const ResourceEvidence = Schema.Struct({
+  matches: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      summary: Schema.String,
+    }),
+  ),
+})
+
+export const FindResources = defineTool({
+  name: "find_resources",
+  description: "Find resources relevant to the request.",
+  input: Schema.Struct({
+    query: Schema.Trimmed.check(Schema.isNonEmpty()),
+  }),
+  execute: ({ query }) =>
+    Effect.gen(function* () {
+      const catalog = yield* ResourceCatalog
+      return yield* catalog.search(query)
+    }),
+}).pipe(
+  Tool.modelResult(ResourceEvidence, (matches) => ({
+    matches: matches.map(({ id, summary }) => ({ id, summary })),
+  })),
+  Tool.present(ResultCards, (matches) => ({
+    results: matches.map(({ id, title, summary }) => ({
+      id,
+      title,
+      summary,
+    })),
+  })),
+)
+
+export const Lookup = Stage.tools({
+  name: "lookup",
+  instructions: ["Route the completed request to one resource lookup."],
+  tools: [FindResources],
+})
+
+const ResourceCatalogLive = Layer.succeed(ResourceCatalog, {
+  search: () =>
+    Effect.succeed([
+      {
+        id: "resource:1",
+        title: "Onboarding checklist",
+        summary: "A concise sequence of practical onboarding steps.",
+        internalScore: 0.93,
+        retrievedText: "Untrusted source text remains server-side.",
+      },
+    ]),
+})
+
+export const example = FindResources.execute({
+  query: "A practical onboarding guide",
+}).pipe(Effect.provide(ResourceCatalogLive))
+
+export const stageExample = Lookup.run([
+  Message.user("We need a practical onboarding guide."),
+])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcomputer/structured-chat",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Schema-defined structured chats with typed tools, stages, and UI views",
   "type": "module",
   "packageManager": "bun@1.3.1",
@@ -23,6 +23,10 @@
     "./assistant-ui": {
       "types": "./dist/integrations/assistant-ui.d.ts",
       "import": "./dist/integrations/assistant-ui.js"
+    },
+    "./assistant-ui/debug": {
+      "types": "./dist/integrations/assistant-ui-debug.d.ts",
+      "import": "./dist/integrations/assistant-ui-debug.js"
     }
   },
   "files": [
@@ -57,13 +61,21 @@
   ],
   "author": "Patrick Ogilvie",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PatrickOgilvie/popcomputer-structured-chat.git"
+  },
+  "homepage": "https://github.com/PatrickOgilvie/popcomputer-structured-chat#readme",
+  "bugs": {
+    "url": "https://github.com/PatrickOgilvie/popcomputer-structured-chat/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
     "@assistant-ui/core": "^0.3.1",
     "react": "^18.0.0 || ^19.0.0",
-    "effect": "^3.21.2"
+    "effect": "^4.0.0-rc.109"
   },
   "peerDependenciesMeta": {
     "@assistant-ui/core": {
@@ -80,7 +92,7 @@
     "@types/bun": "^1.3.14",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "effect": "3.21.2",
+    "effect": "4.0.0-rc.109",
     "oxlint": "1.78.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",