@xandreed/sdk 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xand Reed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @xandreed/sdk
+
+Efferent composable agent framework, 0.3.0. Bun on Linux.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/approval.adapter.d.ts

@@ -0,0 +1,4 @@
+import { Effect } from "effect";
+import type { HarnessError } from "@xandreed/core";
+/** A host supplies interaction; unattended hosts deny requests by default. */
+export declare const approvalPlugin: (request?: (description: string) => Effect.Effect<boolean, HarnessError>) => import("@xandreed/core").Plugin;

package/dist/approval.adapter.js

@@ -0,0 +1,11 @@
+import { Effect, Layer, Schema } from "effect";
+import { Approval, definePlugin } from "@xandreed/core";
+export const approvalPlugin = (request = () => Effect.succeed(!1)) => definePlugin({
+  id: "efferent/approval-host",
+  version: "0.3.0",
+  scope: "runtime",
+  config: Schema.Struct({}),
+  defaults: {},
+  provides: [Approval],
+  layer: () => Layer.succeed(Approval, { request })
+});

package/dist/domain-session.adapter.d.ts

@@ -0,0 +1,22 @@
+import { Effect, Option } from "effect";
+import { HarnessError, SessionStore } from "@xandreed/core";
+import type { ConversationId, Session, SessionHandle } from "@xandreed/core";
+/** Adapt a domain session's event protocol to the durable harness lifecycle. */
+export declare const domainLoop: <E extends {
+    readonly type: string;
+}, R>(options: {
+    readonly create: (id: ConversationId) => Effect.Effect<Session<E>, never, R>;
+    readonly snapshot?: (id: ConversationId) => Effect.Effect<Readonly<Record<string, unknown>>, HarnessError, R>;
+    readonly restore?: (id: ConversationId, data: Readonly<Record<string, unknown>>) => Effect.Effect<void, HarnessError, R>;
+    readonly result: (event: E) => Option.Option<{
+        readonly text: string;
+        readonly outcome: "completed" | "partial";
+    }>;
+}) => Effect.Effect<{
+    readonly run: (input: import("@xandreed/core").LoopInput) => Effect.Effect<{
+        readonly text: string;
+        readonly outcome: "completed" | "partial";
+    }, HarnessError>;
+}, HarnessError, import("effect/Scope").Scope | SessionStore | R>;
+/** Preserve a domain host's public stream vocabulary while the SDK owns lifecycle. */
+export declare const domainSession: <E>(handle: SessionHandle, decode: (value: unknown) => Option.Option<E>, onError: (message: string) => E) => Session<E>;

package/dist/domain-session.adapter.js

@@ -0,0 +1,35 @@
+import { Effect, Fiber, Option, Ref, Stream } from "effect";
+import { AgentLoop, HarnessError, SessionEnvironment, SessionStore } from "@xandreed/core";
+export const domainLoop = (options) => Effect.gen(function* () {
+  const context = yield* Effect.context(), store = yield* SessionStore, environment = yield* Effect.serviceOption(SessionEnvironment), acquire = (id) => Effect.gen(function* () {
+    if (options.restore !== void 0) {
+      const snapshot = (yield* store.read(id, -1)).filter((event) => event.name === "domain.snapshot").at(-1);
+      if (snapshot !== void 0)
+        yield* options.restore(id, snapshot.data).pipe(Effect.provide(context));
+    }
+    return yield* options.create(id).pipe(Effect.provide(context));
+  }), record = Option.isSome(environment) ? environment.value.session : void 0, active = yield* Ref.make(record === void 0 ? Option.none() : Option.some(yield* acquire(record.id)));
+  yield* Effect.addFinalizer(() => Ref.get(active).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (session) => session.shutdown }))));
+  return AgentLoop.of({ run: (input) => Effect.scoped(Effect.gen(function* () {
+    const found = yield* Ref.get(active), session = Option.isSome(found) ? found.value : yield* acquire(input.session.id).pipe(Effect.tap((value) => Ref.set(active, Option.some(value)))), cursor = (yield* session.state).cursor, result = yield* Ref.make(Option.none()), collector = yield* Effect.forkScoped(session.subscribe(cursor).pipe(Stream.tap(({ event }) => input.publish({ name: "domain.event", runId: input.runId, data: { event } })), Stream.tap(({ event }) => Ref.update(result, (current) => Option.orElse(options.result(event), () => current))), Stream.takeUntil(({ event }) => Option.isSome(options.result(event))), Stream.runDrain));
+    yield* Effect.forkScoped(session.transient.pipe(Stream.runForEach((event) => input.transient({ name: "domain.delta", runId: input.runId, data: { event } }))));
+    yield* session.send(input.prompt);
+    if (!(yield* session.state).log.filter((entry) => entry.seq >= cursor).some(({ event }) => Option.isSome(options.result(event))))
+      return yield* Effect.fail(new HarnessError({ code: "domain.unsettled", message: "The domain turn ended without a terminal event" }));
+    yield* Fiber.join(collector);
+    if (options.snapshot !== void 0)
+      yield* options.snapshot(input.session.id).pipe(Effect.provide(context), Effect.flatMap((data) => input.publish({ name: "domain.snapshot", runId: input.runId, data })));
+    return yield* Ref.get(result).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.fail(new HarnessError({ code: "domain.result", message: "The domain session ended without a result" })), onSome: Effect.succeed })));
+  })).pipe(Effect.onInterrupt(() => Ref.get(active).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (session) => session.interrupt }))))) });
+}), domainSession = (handle, decode, onError) => {
+  const event = (name, data) => name === "domain.event" ? decode(data.event) : ["run.failed", "run.cancelled"].includes(name) ? Option.some(onError(String(data.message))) : Option.none();
+  return {
+    conversationId: handle.record.id,
+    send: (text) => handle.send(text).pipe(Effect.ignore),
+    interrupt: handle.interrupt,
+    shutdown: handle.close,
+    state: handle.history.pipe(Effect.map((events) => ({ cursor: (events.at(-1)?.seq ?? -1) + 1, log: events.flatMap((entry) => Option.toArray(Option.map(event(entry.name, entry.data), (value) => ({ seq: entry.seq, event: value })))) })), Effect.orDie),
+    subscribe: (since) => handle.events(since - 1).pipe(Stream.map((entry) => Option.map(event(entry.name, entry.data), (value) => ({ seq: entry.seq, event: value }))), Stream.filterMap((value) => value), Stream.orDie),
+    transient: handle.transient.pipe(Stream.filterMap((entry) => entry.name === "domain.delta" ? decode(entry.data.event) : Option.none()))
+  };
+};

package/dist/domain-session.adapter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/harness.d.ts

@@ -0,0 +1,43 @@
+import { Effect, Scope } from "effect";
+import { HarnessError } from "@xandreed/core";
+import type { ConversationId, HarnessConfig, Plugin, SessionHandle } from "@xandreed/core";
+import type { PluginGraph } from "@xandreed/runtime";
+export declare const makeHarness: (options: {
+    readonly config: HarnessConfig;
+    readonly plugins: ReadonlyArray<Plugin>;
+    readonly workspace: string;
+}) => Effect.Effect<{
+    create: () => Effect.Effect<SessionHandle, HarnessError, never>;
+    resume: (id: ConversationId) => Effect.Effect<SessionHandle, HarnessError, never>;
+    fork: (id: ConversationId, through: number) => Effect.Effect<SessionHandle, HarnessError, never>;
+    list: Effect.Effect<readonly {
+        readonly createdAt: number;
+        readonly id: string & import("effect/Brand").Brand<"ConversationId">;
+        readonly profile: string;
+        readonly workspace: string;
+        readonly parent?: (string & import("effect/Brand").Brand<"ConversationId">) | undefined;
+    }[], HarnessError, never>;
+    graph: Effect.Effect<PluginGraph, never, never>;
+    reconfigure: (config: HarnessConfig, plugins?: ReadonlyArray<Plugin>) => Effect.Effect<"restart-required" | "applied", HarnessError, never>;
+}, HarnessError, Scope.Scope>;
+export declare const Harness: {
+    make: (options: {
+        readonly config: HarnessConfig;
+        readonly plugins: ReadonlyArray<Plugin>;
+        readonly workspace: string;
+    }) => Effect.Effect<{
+        create: () => Effect.Effect<SessionHandle, HarnessError, never>;
+        resume: (id: ConversationId) => Effect.Effect<SessionHandle, HarnessError, never>;
+        fork: (id: ConversationId, through: number) => Effect.Effect<SessionHandle, HarnessError, never>;
+        list: Effect.Effect<readonly {
+            readonly createdAt: number;
+            readonly id: string & import("effect/Brand").Brand<"ConversationId">;
+            readonly profile: string;
+            readonly workspace: string;
+            readonly parent?: (string & import("effect/Brand").Brand<"ConversationId">) | undefined;
+        }[], HarnessError, never>;
+        graph: Effect.Effect<PluginGraph, never, never>;
+        reconfigure: (config: HarnessConfig, plugins?: ReadonlyArray<Plugin>) => Effect.Effect<"restart-required" | "applied", HarnessError, never>;
+    }, HarnessError, Scope.Scope>;
+};
+export type Harness = Effect.Effect.Success<ReturnType<typeof makeHarness>>;

package/dist/harness.js

@@ -0,0 +1,141 @@
+import { Cause, Context, Effect, Exit, Fiber, Option, PubSub, Ref, Scope, Stream } from "effect";
+import { AgentLoop, HarnessError, SessionEnvironment, SessionStore, TurnHooks } from "@xandreed/core";
+import { activateGraph, graphFingerprint, resolveGraph } from "@xandreed/runtime";
+const failure = (code, message) => new HarnessError({ code, message }), service = (context, tag) => Option.match(Context.getOption(context, tag), {
+  onNone: () => Effect.fail(failure("service.missing", `The profile does not provide ${tag.key}`)),
+  onSome: Effect.succeed
+});
+export const makeHarness = (options) => Effect.gen(function* () {
+  const parent = yield* Effect.scope, initial = yield* resolveGraph(options.config, options.plugins, [SessionEnvironment.key]), graphRef = yield* Ref.make(initial), registryRef = yield* Ref.make(options.plugins), seed = Context.make(SessionEnvironment, { workspace: options.workspace }), runtime = yield* activateGraph(initial, "runtime", Context.unsafeMake(seed.unsafeMap), parent), store = yield* service(runtime, SessionStore), handles = yield* Ref.make(new Map), open = (record) => Effect.gen(function* () {
+    const existing = (yield* Ref.get(handles)).get(record.id);
+    if (existing !== void 0)
+      return existing;
+    const journal = yield* store.read(record.id, -1), abandoned = journal.reduce((runs, event) => {
+      if (event.runId === void 0)
+        return runs;
+      return event.name === "run.started" ? [...runs, event.runId] : ["run.completed", "run.cancelled", "run.failed"].includes(event.name) ? runs.filter((id) => id !== event.runId) : runs;
+    }, []);
+    yield* Effect.forEach(abandoned, (runId) => store.append(record.id, { name: "run.cancelled", runId, data: { reason: "process interrupted before settlement; tool effects may be incomplete" } }));
+    const pending = yield* Ref.make(journal.reduce((queue, event) => {
+      if (event.name === "input.queued" && typeof event.data.id === "string" && typeof event.data.text === "string")
+        return [...queue, { id: event.data.id, text: event.data.text, kind: event.data.kind === "steer" ? "steer" : "turn" }];
+      return event.name === "input.claimed" ? queue.filter((input) => input.id !== event.data.id) : queue;
+    }, [])), notifications = yield* PubSub.sliding(1), transientHub = yield* PubSub.sliding(128), running = yield* Ref.make(Option.none()), busy = yield* Ref.make(!1), closed = yield* Ref.make(!1), gate = yield* Effect.makeSemaphore(1), acquire = (graph) => Effect.gen(function* () {
+      const scope = yield* Scope.make(), sessionSeed = Context.add(runtime, SessionEnvironment, { workspace: options.workspace, session: record }), context = yield* activateGraph(graph, "session", Context.unsafeMake(sessionSeed.unsafeMap), scope).pipe(Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))));
+      yield* service(context, AgentLoop).pipe(Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))));
+      return { context, scope, graph, fingerprint: graphFingerprint(graph) };
+    }), mounted = yield* Ref.make(yield* acquire(yield* Ref.get(graphRef))), publish = (body) => store.append(record.id, body).pipe(Effect.tap(() => PubSub.publish(notifications, void 0))), assertOpen = Ref.get(closed).pipe(Effect.flatMap((value) => value ? Effect.fail(failure("session.closed", "Session is closed")) : Effect.void)), refresh = Effect.gen(function* () {
+      if (yield* Ref.get(busy))
+        return;
+      const graph = yield* Ref.get(graphRef), previous = yield* Ref.get(mounted);
+      if (graphFingerprint(graph) === previous.fingerprint)
+        return;
+      const next = yield* acquire(graph);
+      yield* Ref.set(mounted, next);
+      yield* Scope.close(previous.scope, Exit.void);
+      yield* publish({ name: "config.applied", data: { fingerprint: next.fingerprint } });
+    }), claim = (input) => publish({ name: "input.claimed", data: { id: input.id } }).pipe(Effect.zipRight(Ref.update(pending, (queue) => queue.filter((item) => item.id !== input.id)))), steering = Effect.gen(function* () {
+      const inputs = (yield* Ref.get(pending)).filter((input) => input.kind === "steer");
+      yield* Effect.forEach(inputs, claim);
+      return inputs.length === 0 ? Option.none() : Option.some(inputs.map((input) => input.text).join(`
+
+`));
+    }), run = (input) => Effect.gen(function* () {
+      yield* refresh;
+      const current = yield* Ref.get(mounted), loop = yield* service(current.context, AgentLoop), hooks = Context.getOption(current.context, TurnHooks), runId = crypto.randomUUID();
+      yield* claim(input);
+      yield* publish({ name: "run.started", runId, data: { config: current.fingerprint } });
+      const args = {
+        session: record,
+        runId,
+        prompt: input.text,
+        system: current.graph.config.system ?? "You are a helpful agent.",
+        publish,
+        transient: (event) => PubSub.publish(transientHub, event).pipe(Effect.asVoid),
+        steering
+      }, task = Effect.gen(function* () {
+        const prepared = Option.isSome(hooks) ? yield* hooks.value.before(args) : args, result = yield* loop.run(prepared);
+        if (Option.isSome(hooks))
+          yield* hooks.value.after(prepared);
+        return result;
+      }).pipe(Effect.interruptible);
+      yield* Ref.set(busy, !0);
+      const fiber = yield* Effect.forkIn(task, parent);
+      yield* Ref.set(running, Option.some(fiber));
+      const exit = yield* Fiber.await(fiber);
+      yield* Ref.set(running, Option.none());
+      yield* Ref.set(busy, !1);
+      yield* Exit.isSuccess(exit) ? publish({ name: "run.completed", runId, data: { ...exit.value } }) : publish({
+        name: Cause.isInterruptedOnly(exit.cause) ? "run.cancelled" : "run.failed",
+        runId,
+        data: { message: Cause.isInterruptedOnly(exit.cause) ? "Cancelled; unfinished tool effects are not replayed" : Cause.pretty(exit.cause) }
+      });
+      yield* Ref.set(running, Option.none());
+      yield* Ref.set(busy, !1);
+      if (Exit.isFailure(exit) && !Cause.isInterruptedOnly(exit.cause))
+        return yield* Effect.fail(failure("run.failed", Cause.pretty(exit.cause)));
+      return Exit.isSuccess(exit);
+    }).pipe(Effect.uninterruptible), drain = gate.withPermits(1)(Effect.gen(function* () {
+      yield* assertOpen;
+      yield* Effect.iterate(!0, { while: (more) => more, body: () => Effect.gen(function* () {
+        if (yield* Ref.get(closed))
+          return !1;
+        const next = (yield* Ref.get(pending))[0];
+        return next === void 0 ? !1 : yield* run(next);
+      }) });
+    })), enqueue = (text, kind) => Effect.gen(function* () {
+      yield* assertOpen;
+      if (text.trim().length === 0)
+        return yield* Effect.fail(failure("input.empty", "Enter a message"));
+      const input = { id: crypto.randomUUID(), text, kind };
+      yield* publish({ name: "input.queued", data: input });
+      yield* Ref.update(pending, (queue) => [...queue, input]);
+    }), interrupt = Ref.get(running).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.asVoid) }))), close = Ref.getAndSet(closed, !0).pipe(Effect.flatMap((already) => already ? Effect.void : Effect.gen(function* () {
+      yield* interrupt;
+      yield* gate.withPermits(1)(Ref.get(mounted).pipe(Effect.flatMap((current) => Scope.close(current.scope, Exit.void))));
+      yield* PubSub.shutdown(notifications);
+      yield* PubSub.shutdown(transientHub);
+      yield* Ref.update(handles, (all) => new Map([...all].filter(([id]) => id !== record.id)));
+    }))), handle = {
+      record,
+      use: (tag, run) => gate.withPermits(1)(assertOpen.pipe(Effect.zipRight(Ref.get(mounted)), Effect.flatMap((current) => service(current.context, tag)), Effect.flatMap(run))),
+      send: (text) => enqueue(text, "turn").pipe(Effect.zipRight(drain)),
+      steer: (text) => enqueue(text, "steer"),
+      continue: drain,
+      interrupt,
+      close,
+      busy: Ref.get(busy),
+      pending: Ref.get(pending),
+      refresh: gate.withPermits(1)(refresh),
+      history: store.read(record.id, -1),
+      transient: Stream.fromPubSub(transientHub),
+      events: (after = -1) => Stream.unwrapScoped(Effect.gen(function* () {
+        const subscription = yield* PubSub.subscribe(notifications), cursor = yield* Ref.make(after);
+        return Stream.concat(Stream.make(void 0), Stream.fromQueue(subscription)).pipe(Stream.mapEffect(() => Ref.get(cursor).pipe(Effect.flatMap((position) => store.read(record.id, position)), Effect.tap((events) => events.length === 0 ? Effect.void : Ref.set(cursor, events[events.length - 1].seq)))), Stream.flatMap(Stream.fromIterable));
+      }))
+    };
+    yield* Scope.addFinalizer(parent, close);
+    yield* Ref.update(handles, (all) => new Map([...all, [record.id, handle]]));
+    return handle;
+  }), opening = yield* Effect.makeSemaphore(1), ownRecord = (id) => store.get(id).pipe(Effect.flatMap((record) => record.workspace !== options.workspace ? Effect.fail(failure("session.workspace", "This session belongs to a different workspace")) : Effect.succeed(record)));
+  return {
+    create: () => Ref.get(graphRef).pipe(Effect.flatMap((graph) => store.create(options.workspace, graph.config.profile ?? "smith")), Effect.flatMap((record) => opening.withPermits(1)(open(record)))),
+    resume: (id) => ownRecord(id).pipe(Effect.flatMap((record) => opening.withPermits(1)(open(record)))),
+    fork: (id, through) => ownRecord(id).pipe(Effect.zipRight(store.fork(id, through)), Effect.flatMap((record) => opening.withPermits(1)(open(record)))),
+    list: store.list(options.workspace),
+    graph: Ref.get(graphRef),
+    reconfigure: (config, plugins) => Effect.gen(function* () {
+      const registry = plugins ?? (yield* Ref.get(registryRef)), next = yield* resolveGraph(config, registry, [SessionEnvironment.key]);
+      if (graphFingerprint(next, "runtime") !== graphFingerprint(initial, "runtime"))
+        return "restart-required";
+      yield* Effect.forEach([...(yield* Ref.get(handles)).values()], (handle) => Effect.scoped(Effect.gen(function* () {
+        const scope = yield* Effect.scope, seed = Context.add(runtime, SessionEnvironment, { workspace: options.workspace, session: handle.record }), context = yield* activateGraph(next, "session", Context.unsafeMake(seed.unsafeMap), scope);
+        yield* service(context, AgentLoop);
+      })));
+      yield* Ref.set(registryRef, registry);
+      yield* Ref.set(graphRef, next);
+      yield* Effect.forEach([...(yield* Ref.get(handles)).values()], (handle) => handle.busy.pipe(Effect.flatMap((active) => active ? Effect.void : handle.refresh)));
+      return "applied";
+    })
+  };
+}), Harness = { make: makeHarness };

package/dist/harness.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "@xandreed/core";
+export * from "./harness.js";
+export * from "./approval.adapter.js";
+export { domainLoop, domainSession } from "./domain-session.adapter.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "@xandreed/core";
+export * from "./harness.js";
+export * from "./approval.adapter.js";
+export { domainLoop, domainSession } from "./domain-session.adapter.js";

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@xandreed/sdk",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@xandreed/core": "0.3.0",
+    "effect": "3.21.4",
+    "@xandreed/runtime": "0.3.0",
+    "@xandreed/plugin-memory": "0.3.0",
+    "@xandreed/plugin-session-sqlite": "0.3.0"
+  },
+  "private": false,
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "skills",
+    "profiles",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "license": "MIT"
+}