@batonfx/foldkit 0.4.4 → 0.6.0

package/README.md

@@ -1,5 +1,66 @@
 # `@batonfx/foldkit`
 
-FoldKit adapter for Baton transport sessions and chat UI.
+Focused composition guide for the FoldKit adapter to Baton transport sessions.
 
-See the [Baton documentation](https://github.com/In-Time-Tec/batonfx#readme) for installation, examples, and API guidance.
+## Install
+
+```sh
+bun add effect foldkit @batonfx/foldkit
+```
+
+## Imports
+
+Import the public namespace from the package root:
+
+```ts
+import { Connection } from "@batonfx/foldkit"
+```
+
+## Layer graph
+
+```text
+Connection.testLayer
+└─ provides Connection.AgentConnection
+   └─ session acquisition requires Scope
+      └─ program closes it with Effect.scoped
+```
+
+`testLayer` is a deterministic adapter for examples and tests. Production applications provide an `AgentConnection` backed by a Baton transport client; they do not use this synthetic frame stream.
+
+## Runnable program
+
+Checked source: [`../../examples/package-composition-guides/src/foldkit.ts`](../../examples/package-composition-guides/src/foldkit.ts)
+
+```ts
+import { Console, Effect, Stream } from "effect"
+import { Connection } from "@batonfx/foldkit"
+
+const connectionLayer = Connection.testLayer({
+  frames: () => Stream.make(Connection.ConnectionOpened()),
+  send: () => Effect.void,
+})
+
+const program = Connection.AgentConnection.use((connection) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const session = yield* connection.session({ sessionId: "guide-session" })
+      const frames = yield* Stream.runCollect(session.frames)
+      yield* Console.log(`received ${frames.length} connection event`)
+    }),
+  ),
+).pipe(Effect.provide(connectionLayer))
+
+await Effect.runPromise(program)
+```
+
+From the repository root, run `bun examples/package-composition-guides/src/foldkit.ts`.
+
+## Errors, requirements, and resources
+
+The fully provided program has type-level result `Effect<void, never, never>` and prints one received event. `Effect.scoped` delimits the session lifetime and discharges its `Scope` requirement; this test adapter has no release action, while production scoped connections release their transport resources. Production command writes can fail with schema-backed `Connection.SendFailed`; the test sender cannot fail. This example owns one session, allocates no queue, and creates no timers, detached fibers, or concurrent work.
+
+## More
+
+- Current behavior: [FoldKit adapter](../../docs/features/foldkit.md)
+- Deeper example: [deep research agent](../../examples/deep-research-agent/)
+- Existing custom `AgentConnection` providers must implement the scoped `session` acquisition; `testLayer` remains a compatibility adapter for legacy test implementations.

package/dist/chat.d.ts

@@ -1,7 +1,7 @@
 import { Equivalence, Effect, Option, Schema, Stream } from "effect";
 import { type Command } from "foldkit/command";
 import type { CallableTaggedStruct } from "foldkit/schema";
-import { AgentConnection, Incoming } from "./connection.js";
+import { AgentCommandError, AgentConnection, CommandOperation, Incoming } from "./connection.js";
 declare const CompletedFields: {
     isFailure: Schema.Boolean;
     result: Schema.Unknown;
@@ -16,9 +16,6 @@ declare const AssistantEntryFields: {
 declare const RunCompletedFields: {
     text: Schema.String;
 };
-declare const StringReasonFields: {
-    reason: Schema.String;
-};
 declare const OpenedSessionFields: {
     sessionId: Schema.String;
 };
@@ -117,7 +114,11 @@ export declare const ResolvedApproval: CallableTaggedStruct<"ResolvedApproval",
 /** @experimental */
 export declare const CancelledRun: CallableTaggedStruct<"CancelledRun", {}>;
 /** @experimental */
-export declare const FailedAgentCommand: CallableTaggedStruct<"FailedAgentCommand", typeof StringReasonFields>;
+export declare const FailedAgentCommand: CallableTaggedStruct<"FailedAgentCommand", {
+    operation: typeof CommandOperation;
+    error: typeof AgentCommandError;
+    reason: typeof Schema.String;
+}>;
 /** @experimental */
 export type Message = typeof ReceivedAgent.Type | typeof OpenedSession.Type | typeof ChangedDraft.Type | typeof SubmittedMessage.Type | typeof ClickedCancel.Type | typeof ClickedApprove.Type | typeof ClickedDeny.Type | typeof SentUserMessage.Type | typeof ResolvedApproval.Type | typeof CancelledRun.Type | typeof FailedAgentCommand.Type;
 /** @experimental */
@@ -198,7 +199,7 @@ export type ConversationItem = typeof UserConversationItem.Type | typeof Assista
 /** @experimental */
 export declare const ConversationItem: Schema.Schema<ConversationItem>;
 /** @experimental */
-export type ChatCommand = Command<Message, any, AgentConnection>;
+export type ChatCommand = Command<Message, AgentCommandError, AgentConnection>;
 /** @experimental */
 export declare const initialModel: (sessionId?: string | null) => Model;
 /** @experimental */
@@ -207,7 +208,9 @@ export declare const SendUserMessage: import("foldkit/command").CommandDefinitio
     text: Schema.String;
 }, Effect.Effect<Schema.Struct.ReadonlySide<{
     readonly _tag: Schema.tag<"FailedAgentCommand">;
-    reason: Schema.String;
+    operation: typeof CommandOperation;
+    error: typeof AgentCommandError;
+    reason: typeof Schema.String;
 }, "Type"> | {
     readonly _tag: "SentUserMessage";
 }, never, AgentConnection>>;
@@ -219,7 +222,9 @@ export declare const ResolveApproval: import("foldkit/command").CommandDefinitio
     reason: Schema.NullOr<Schema.String>;
 }, Effect.Effect<Schema.Struct.ReadonlySide<{
     readonly _tag: Schema.tag<"FailedAgentCommand">;
-    reason: Schema.String;
+    operation: typeof CommandOperation;
+    error: typeof AgentCommandError;
+    reason: typeof Schema.String;
 }, "Type"> | {
     readonly _tag: "ResolvedApproval";
 }, never, AgentConnection>>;
@@ -228,7 +233,9 @@ export declare const CancelRun: import("foldkit/command").CommandDefinitionWithA
     sessionId: Schema.String;
 }, Effect.Effect<Schema.Struct.ReadonlySide<{
     readonly _tag: Schema.tag<"FailedAgentCommand">;
-    reason: Schema.String;
+    operation: typeof CommandOperation;
+    error: typeof AgentCommandError;
+    reason: typeof Schema.String;
 }, "Type"> | {
     readonly _tag: "CancelledRun";
 }, never, AgentConnection>>;

package/dist/chat.js

@@ -1,16 +1,15 @@
-import { Cause, Equivalence, Effect, Option, Schema, Stream } from "effect";
+import { Cause, Equivalence, Effect, Option, Result, Schema, Stream } from "effect";
 import { dual } from "effect/Function";
 import { Prompt } from "effect/unstable/ai";
 import { define } from "foldkit/command";
 import { m } from "foldkit/message";
 import { make } from "foldkit/subscription";
 import { Wire } from "@batonfx/transport";
-import { AgentConnection, Incoming, SendFailed } from "./connection.js";
+import { AgentCommandError, AgentConnection, CommandOperation, Incoming, SendFailed } from "./connection.js";
 const CompletedFields = { isFailure: Schema.Boolean, result: Schema.Unknown };
 const UserEntryFields = { text: Schema.String };
 const AssistantEntryFields = { text: Schema.String, reasoning: Schema.NullOr(Schema.String) };
 const RunCompletedFields = { text: Schema.String };
-const StringReasonFields = { reason: Schema.String };
 const OpenedSessionFields = { sessionId: Schema.String };
 /** @experimental */
 export const ToolPendingPhase = Schema.Literals(["called", "executing"]);
@@ -91,7 +90,11 @@ export const ResolvedApproval = m("ResolvedApproval");
 /** @experimental */
 export const CancelledRun = m("CancelledRun");
 /** @experimental */
-export const FailedAgentCommand = m("FailedAgentCommand", StringReasonFields);
+export const FailedAgentCommand = m("FailedAgentCommand", {
+    operation: CommandOperation,
+    error: AgentCommandError,
+    reason: Schema.String,
+});
 /** @experimental */
 export const Message = Schema.Union([
     ReceivedAgent,
@@ -174,10 +177,28 @@ export const initialModel = (sessionId = null) => ({
     streaming: null,
     draft: "",
 });
-const commandFailed = (error) => FailedAgentCommand({ reason: Schema.is(SendFailed)(error) ? error.reason : String(error) });
-const catchCommandFailure = (effect) => effect.pipe(Effect.catchCause((cause) => Effect.succeed(commandFailed(Cause.squash(cause)))));
+const unexpectedCause = (cause) => {
+    const reasons = [];
+    for (const reason of cause.reasons) {
+        if (Cause.isDieReason(reason) || Cause.isInterruptReason(reason))
+            reasons.push(reason);
+    }
+    return reasons.length === 0 ? Option.none() : Option.some(Cause.fromReasons(reasons));
+};
+const commandFailed = (operation, error) => FailedAgentCommand({
+    operation,
+    error,
+    reason: Schema.is(SendFailed)(error) ? error.reason : error.message,
+});
+const catchCommandFailure = (operation, effect) => effect.pipe(Effect.catchCause((cause) => Option.match(unexpectedCause(cause), {
+    onNone: () => Result.match(Cause.findError(cause), {
+        onFailure: Effect.failCause,
+        onSuccess: (error) => Effect.succeed(commandFailed(operation, error)),
+    }),
+    onSome: Effect.failCause,
+})));
 /** @experimental */
-export const SendUserMessage = define("SendUserMessage", { sessionId: Schema.String, text: Schema.String }, SentUserMessage, FailedAgentCommand)(({ sessionId, text }) => AgentConnection.use((connection) => catchCommandFailure(connection.send({ _tag: "SendMessage", sessionId, prompt: text }).pipe(Effect.as(SentUserMessage())))));
+export const SendUserMessage = define("SendUserMessage", { sessionId: Schema.String, text: Schema.String }, SentUserMessage, FailedAgentCommand)(({ sessionId, text }) => AgentConnection.use((connection) => catchCommandFailure("send", connection.send({ _tag: "SendMessage", sessionId, prompt: text }).pipe(Effect.as(SentUserMessage())))));
 /** @experimental */
 export const ResolveApproval = define("ResolveApproval", {
     sessionId: Schema.String,
@@ -190,10 +211,10 @@ export const ResolveApproval = define("ResolveApproval", {
         : reason === null
             ? { _tag: "Denied" }
             : { _tag: "Denied", reason };
-    return AgentConnection.use((connection) => catchCommandFailure(connection.send({ _tag: "ResolveApproval", sessionId, token, decision }).pipe(Effect.as(ResolvedApproval()))));
+    return AgentConnection.use((connection) => catchCommandFailure("resolveApproval", connection.send({ _tag: "ResolveApproval", sessionId, token, decision }).pipe(Effect.as(ResolvedApproval()))));
 });
 /** @experimental */
-export const CancelRun = define("CancelRun", { sessionId: Schema.String }, CancelledRun, FailedAgentCommand)(({ sessionId }) => AgentConnection.use((connection) => catchCommandFailure(connection.send({ _tag: "Cancel", sessionId }).pipe(Effect.as(CancelledRun())))));
+export const CancelRun = define("CancelRun", { sessionId: Schema.String }, CancelledRun, FailedAgentCommand)(({ sessionId }) => AgentConnection.use((connection) => catchCommandFailure("cancel", connection.send({ _tag: "Cancel", sessionId }).pipe(Effect.as(CancelledRun())))));
 const isRecord = (value) => typeof value === "object" && value !== null;
 const isToolCall = (value) => isRecord(value) &&
     value.type === "tool-call" &&
@@ -262,10 +283,20 @@ const failureMessage = (failure) => {
     switch (failure._tag) {
         case "@batonfx/core/AgentError":
             return failure.message;
+        case "@batonfx/core/TurnPolicyError":
+            return failure.message;
+        case "@batonfx/core/TurnPolicyStopped":
+            return failure.reason._tag === "Policy" ? failure.reason.detail : failure.reason._tag;
         case "@batonfx/core/MiddlewareViolation":
             return failure.detail;
         case "@batonfx/core/TurnLimitExceeded":
             return `Turn limit exceeded at turn ${failure.turn}`;
+        case "@batonfx/core/ResumeMismatch":
+            return failure.reason === "identity-mismatch"
+                ? "Resume suspension does not match the current checkpoint"
+                : "Resume checkpoint not found";
+        case "@batonfx/core/FrameworkFailure":
+            return `${failure.tool} ${failure.stage}: ${failure.message}`;
     }
 };
 const applyPart = (model, turn, part) => {
@@ -390,6 +421,9 @@ const projectPrompt = (prompt) => {
     return entries;
 };
 const applyFrame = (model, frame) => {
+    if (frame._tag === "Snapshot") {
+        return [{ ...model, lastSeq: frame.seq, entries: projectPrompt(frame.transcript), streaming: null }, Option.none()];
+    }
     if (frame.seq <= model.lastSeq)
         return [model, Option.none()];
     const withSeq = { ...model, lastSeq: frame.seq };
@@ -404,8 +438,6 @@ const applyFrame = (model, frame) => {
         }
         case "Ended":
             return [withSeq, Option.none()];
-        case "Snapshot":
-            return [{ ...withSeq, entries: projectPrompt(frame.transcript), streaming: null }, Option.none()];
         case "SessionStatus":
             return applyStatus(withSeq, frame.status);
     }
@@ -597,9 +629,9 @@ export const subscriptions = make()((entry) => ({
                 return Stream.empty;
             return Stream.unwrap(AgentConnection.use((connection) => {
                 const afterSeq = readDependencies().afterSeq;
-                return Effect.succeed(connection
-                    .frames(afterSeq < 0 ? { sessionId } : { sessionId, afterSeq })
-                    .pipe(Stream.map((incoming) => ReceivedAgent({ incoming }))));
+                return connection
+                    .session(afterSeq < 0 ? { sessionId } : { sessionId, afterSeq })
+                    .pipe(Effect.map((sessionConnection) => sessionConnection.frames.pipe(Stream.map((incoming) => ReceivedAgent({ incoming })))));
             }));
         },
     }),

package/dist/connection.d.ts

@@ -1,13 +1,15 @@
-import { Cause, Context, Effect, Layer, Schema, Stream } from "effect";
+import { Cause, Context, Effect, Layer, Schema, Scope, Stream } from "effect";
 import { Socket } from "effect/unstable/socket";
 import type { CallableTaggedStruct } from "foldkit/schema";
-import { Wire } from "@batonfx/transport";
+import { Errors, Wire } from "@batonfx/transport";
 /** @experimental */
 export declare const ConnectionOpened: CallableTaggedStruct<"ConnectionOpened", {}>;
 /** @experimental */
 export declare const ConnectionLost: CallableTaggedStruct<"ConnectionLost", {}>;
 /** @experimental */
 export declare const ConnectionFailed: CallableTaggedStruct<"ConnectionFailed", {
+    operation: Schema.Literal<"connect">;
+    error: typeof Errors.TransportError;
     reason: typeof Schema.String;
 }>;
 /** @experimental */
@@ -21,19 +23,40 @@ declare const SendFailed_base: Schema.Class<SendFailed, Schema.TaggedStruct<"@ba
 export declare class SendFailed extends SendFailed_base {
 }
 /** @experimental */
+export declare const AgentCommandError: Schema.Union<readonly [typeof Errors.TransportError, typeof SendFailed]>;
+/** @experimental */
+export type AgentCommandError = typeof AgentCommandError.Type;
+/** @experimental */
+export declare const CommandOperation: Schema.Literals<readonly ["send", "cancel", "resolveApproval"]>;
+/** @experimental */
+export type CommandOperation = typeof CommandOperation.Type;
+/** @experimental */
+export interface SessionConnection {
+    readonly sessionId: string;
+    readonly frames: Stream.Stream<Incoming, never>;
+    readonly send: (frame: Exclude<Wire.ClientFrameType, {
+        readonly _tag: "Attach";
+    }>) => Effect.Effect<void, AgentCommandError>;
+}
+/** @experimental */
 export interface Interface {
+    readonly session: (options: {
+        readonly sessionId: string;
+        readonly afterSeq?: number;
+    }) => Effect.Effect<SessionConnection, never, Scope.Scope>;
     readonly frames: (options: {
         readonly sessionId: string;
         readonly afterSeq?: number;
     }) => Stream.Stream<Incoming, never>;
-    readonly send: (frame: Wire.ClientFrameType) => Effect.Effect<void, SendFailed>;
+    readonly send: (frame: Wire.ClientFrameType) => Effect.Effect<void, AgentCommandError>;
 }
 declare const AgentConnection_base: Context.ServiceClass<AgentConnection, "@batonfx/foldkit/connection/AgentConnection", Interface>;
 /** @experimental */
 export declare class AgentConnection extends AgentConnection_base {
 }
+type LegacyInterface = Omit<Interface, "session">;
 /** @experimental */
-export declare const testLayer: (implementation: Interface) => Layer.Layer<AgentConnection>;
+export declare const testLayer: (implementation: Interface | LegacyInterface) => Layer.Layer<AgentConnection>;
 /** @experimental */
 export declare const layerWebSocket: (options: {
     readonly url: string;

package/dist/connection.js

@@ -1,13 +1,17 @@
-import { Cause, Context, Effect, Layer, Option, Ref, Result, Schema, Stream } from "effect";
+import { Cause, Context, Effect, Layer, Option, Ref, Result, Schema, Scope, Stream } from "effect";
 import { Socket } from "effect/unstable/socket";
 import { m } from "foldkit/message";
-import { Client, Wire } from "@batonfx/transport";
+import { Client, Errors, Wire } from "@batonfx/transport";
 /** @experimental */
 export const ConnectionOpened = m("ConnectionOpened");
 /** @experimental */
 export const ConnectionLost = m("ConnectionLost");
 /** @experimental */
-export const ConnectionFailed = m("ConnectionFailed", { reason: Schema.String });
+export const ConnectionFailed = m("ConnectionFailed", {
+    operation: Schema.Literal("connect"),
+    error: Errors.TransportError,
+    reason: Schema.String,
+});
 /** @experimental */
 export const Incoming = Schema.Union([
     Wire.LooseServerFrame,
@@ -21,50 +25,93 @@ export class SendFailed extends Schema.TaggedErrorClass()("@batonfx/foldkit/Send
 }) {
 }
 /** @experimental */
+export const AgentCommandError = Schema.Union([Errors.TransportError, SendFailed]);
+/** @experimental */
+export const CommandOperation = Schema.Literals(["send", "cancel", "resolveApproval"]);
+/** @experimental */
 export class AgentConnection extends Context.Service()("@batonfx/foldkit/connection/AgentConnection") {
 }
-const reasonFrom = (error) => {
-    if (Schema.is(SendFailed)(error))
-        return error.reason;
-    if (error instanceof Error)
-        return error.message;
-    return String(error);
+const sendThrough = (connection, frame) => connection.send(frame);
+const unexpectedCause = (cause) => {
+    const reasons = [];
+    for (const reason of cause.reasons) {
+        if (Cause.isDieReason(reason) || Cause.isInterruptReason(reason))
+            reasons.push(reason);
+    }
+    return reasons.length === 0 ? Option.none() : Option.some(Cause.fromReasons(reasons));
 };
 const statusIncoming = (status) => {
     switch (status._tag) {
-        case "Open":
+        case "Connected":
             return Option.some(ConnectionOpened());
-        case "Reconnecting":
-        case "Closed":
+        case "Disconnected":
+        case "Retrying":
             return Option.some(ConnectionLost());
         case "Connecting":
             return Option.none();
     }
 };
 /** @experimental */
-export const testLayer = (implementation) => Layer.succeed(AgentConnection, AgentConnection.of(implementation));
+export const testLayer = (implementation) => {
+    const session = "session" in implementation
+        ? implementation.session
+        : (options) => Effect.succeed({
+            sessionId: options.sessionId,
+            frames: implementation.frames(options),
+            send: (frame) => frame.sessionId === options.sessionId
+                ? implementation.send(frame)
+                : Effect.fail(SendFailed.make({
+                    reason: `Session ${options.sessionId} cannot send a command for ${frame.sessionId}`,
+                })),
+        });
+    return Layer.succeed(AgentConnection, AgentConnection.of({ ...implementation, session }));
+};
 /** @experimental */
 export const layerWebSocket = (options) => Layer.effect(AgentConnection, Effect.gen(function* () {
     const client = yield* Client.AgentClient;
-    const active = yield* Ref.make(Option.none());
-    const clearActive = (connection) => Ref.update(active, (current) => Option.isSome(current) && current.value.connection === connection ? Option.none() : current);
+    const active = yield* Ref.make(new Map());
+    const clearActive = (owner) => Ref.update(active, (current) => {
+        if (current.get(owner.sessionId) !== owner)
+            return current;
+        const updated = new Map(current);
+        updated.delete(owner.sessionId);
+        return updated;
+    });
+    const session = ({ sessionId }) => Effect.gen(function* () {
+        const connection = yield* client.connect({ url: options.url, sessionId });
+        const owner = { sessionId, connection };
+        yield* Effect.acquireRelease(Ref.update(active, (current) => {
+            const updated = new Map(current);
+            updated.set(sessionId, owner);
+            return updated;
+        }), () => clearActive(owner));
+        const statuses = connection.status.pipe(Stream.filterMap((status) => Option.match(statusIncoming(status), {
+            onNone: () => Result.fail(undefined),
+            onSome: Result.succeed,
+        })));
+        const frames = connection.frames.pipe(Stream.map((frame) => frame), Stream.catchCause((cause) => Option.match(unexpectedCause(cause), {
+            onNone: () => Result.match(Cause.findError(cause), {
+                onFailure: Stream.failCause,
+                onSuccess: (error) => Stream.succeed(ConnectionFailed({ operation: "connect", error, reason: error.message })),
+            }),
+            onSome: Stream.failCause,
+        })));
+        return {
+            sessionId,
+            frames: statuses.pipe(Stream.merge(frames)),
+            send: (frame) => frame.sessionId === sessionId
+                ? sendThrough(connection, frame)
+                : Effect.fail(SendFailed.make({ reason: `Session ${sessionId} cannot send a command for ${frame.sessionId}` })),
+        };
+    });
     return AgentConnection.of({
-        frames: ({ sessionId }) => Stream.unwrap(Effect.gen(function* () {
-            const connection = yield* client.connect({ url: options.url, sessionId });
-            yield* Ref.set(active, Option.some({ sessionId, connection }));
-            yield* Effect.addFinalizer(() => clearActive(connection));
-            const statuses = connection.status.pipe(Stream.filterMap((status) => Option.match(statusIncoming(status), {
-                onNone: () => Result.fail(undefined),
-                onSome: Result.succeed,
-            })));
-            const frames = connection.frames.pipe(Stream.map((frame) => frame), Stream.catchCause((cause) => Stream.succeed(ConnectionFailed({ reason: reasonFrom(Cause.squash(cause)) }))));
-            return statuses.pipe(Stream.merge(frames));
+        session,
+        frames: (sessionOptions) => Stream.unwrap(session(sessionOptions).pipe(Effect.map((owned) => owned.frames))),
+        send: (frame) => Ref.get(active).pipe(Effect.flatMap((current) => {
+            const owner = current.get(frame.sessionId);
+            return owner === undefined
+                ? Effect.fail(SendFailed.make({ reason: `No active agent connection for session ${frame.sessionId}` }))
+                : sendThrough(owner.connection, frame);
         })),
-        send: (frame) => Ref.get(active).pipe(Effect.flatMap(Option.match({
-            onNone: () => Effect.fail(SendFailed.make({ reason: "No active agent connection" })),
-            onSome: ({ connection }) => connection
-                .send(frame)
-                .pipe(Effect.mapError((error) => SendFailed.make({ reason: reasonFrom(error) }))),
-        }))),
     });
 })).pipe(Layer.provide(Client.layerWebSocket));

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@batonfx/foldkit",
-  "version": "0.4.4",
+  "version": "0.6.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typecheck": "bun tsc --noEmit"
   },
   "dependencies": {
-    "@batonfx/transport": "0.4.4"
+    "@batonfx/transport": "0.6.0"
   },
   "peerDependencies": {
     "effect": ">=4.0.0-beta.88 <4.0.1",