@xandreed/core 0.3.0

package/dist/ports/conversation-store.port.d.ts

@@ -0,0 +1,250 @@
+import { Context, Option, Schema } from "effect";
+import type { Effect } from "effect";
+import { AgentMessage, ConversationId } from "../domain/message.entity.js";
+import type { Checkpoint } from "../domain/message.entity.js";
+declare const StoreError_base: Schema.TaggedErrorClass<StoreError, "StoreError", {
+    readonly _tag: Schema.tag<"StoreError">;
+} & {
+    message: typeof Schema.String;
+}>;
+export declare class StoreError extends StoreError_base {
+}
+declare const RunOutcomeRecord_base: Schema.Class<RunOutcomeRecord, {
+    conversationId: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    /** Epoch millis. */
+    at: typeof Schema.Number;
+    outcome: Schema.Literal<["ok", "partial"]>;
+    reason: Schema.Literal<["completed", "step-cap", "degenerate-loop"]>;
+}, Schema.Struct.Encoded<{
+    conversationId: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    /** Epoch millis. */
+    at: typeof Schema.Number;
+    outcome: Schema.Literal<["ok", "partial"]>;
+    reason: Schema.Literal<["completed", "step-cap", "degenerate-loop"]>;
+}>, never, {
+    readonly at: number;
+} & {
+    readonly conversationId: string & import("effect/Brand").Brand<"ConversationId">;
+} & {
+    readonly outcome: "ok" | "partial";
+} & {
+    readonly reason: "completed" | "step-cap" | "degenerate-loop";
+}, {}, {}>;
+/** How a run ENDED — persisted beside the trail so the database alone says
+ *  whether the last run completed on its own or was stopped by the step cap
+ *  or the degenerate-loop breaker (the loop's `agent_end` was in-memory only). */
+export declare class RunOutcomeRecord extends RunOutcomeRecord_base {
+}
+declare const ConversationSummary_base: Schema.Class<ConversationSummary, {
+    id: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    createdAt: typeof Schema.Number;
+    firstPrompt: Schema.optionalWith<typeof Schema.String, {
+        as: "Option";
+    }>;
+    title: Schema.optionalWith<typeof Schema.String, {
+        as: "Option";
+    }>;
+    /** The latest recorded run outcome, when a run has finished in it. */
+    lastOutcome: Schema.optionalWith<Schema.Struct<{
+        outcome: Schema.Literal<["ok", "partial"]>;
+        reason: Schema.Literal<["completed", "step-cap", "degenerate-loop"]>;
+    }>, {
+        as: "Option";
+    }>;
+}, Schema.Struct.Encoded<{
+    id: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    createdAt: typeof Schema.Number;
+    firstPrompt: Schema.optionalWith<typeof Schema.String, {
+        as: "Option";
+    }>;
+    title: Schema.optionalWith<typeof Schema.String, {
+        as: "Option";
+    }>;
+    /** The latest recorded run outcome, when a run has finished in it. */
+    lastOutcome: Schema.optionalWith<Schema.Struct<{
+        outcome: Schema.Literal<["ok", "partial"]>;
+        reason: Schema.Literal<["completed", "step-cap", "degenerate-loop"]>;
+    }>, {
+        as: "Option";
+    }>;
+}>, never, {
+    readonly createdAt: number;
+} & {
+    readonly id: string & import("effect/Brand").Brand<"ConversationId">;
+} & {
+    readonly firstPrompt: Option.Option<string>;
+} & {
+    readonly title: Option.Option<string>;
+} & {
+    readonly lastOutcome: Option.Option<{
+        readonly outcome: "ok" | "partial";
+        readonly reason: "completed" | "step-cap" | "degenerate-loop";
+    }>;
+}, {}, {}>;
+export declare class ConversationSummary extends ConversationSummary_base {
+}
+declare const StoredMessage_base: Schema.Class<StoredMessage, {
+    position: typeof Schema.Int;
+    message: Schema.Union<[Schema.Struct<{
+        role: Schema.Literal<["user"]>;
+        content: typeof Schema.String;
+        providerOptions: Schema.optional<typeof Schema.Unknown>;
+    }>, Schema.Struct<{
+        role: Schema.Literal<["assistant"]>;
+        content: Schema.Array$<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["reasoning"]>;
+            text: typeof Schema.String;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["tool-call"]>;
+            toolCallId: Schema.brand<typeof Schema.String, "ToolCallId">;
+            toolName: typeof Schema.String;
+            input: typeof Schema.Unknown;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+            providerExecuted: Schema.optional<typeof Schema.Boolean>;
+        }>]>>;
+        providerOptions: Schema.optional<typeof Schema.Unknown>;
+    }>, Schema.Struct<{
+        role: Schema.Literal<["tool"]>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["tool-result"]>;
+            toolCallId: Schema.brand<typeof Schema.String, "ToolCallId">;
+            toolName: typeof Schema.String;
+            output: typeof Schema.Unknown;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+            isError: Schema.optional<typeof Schema.Boolean>;
+        }>>;
+        providerOptions: Schema.optional<typeof Schema.Unknown>;
+    }>]>;
+}, Schema.Struct.Encoded<{
+    position: typeof Schema.Int;
+    message: Schema.Union<[Schema.Struct<{
+        role: Schema.Literal<["user"]>;
+        content: typeof Schema.String;
+        providerOptions: Schema.optional<typeof Schema.Unknown>;
+    }>, Schema.Struct<{
+        role: Schema.Literal<["assistant"]>;
+        content: Schema.Array$<Schema.Union<[Schema.Struct<{
+            type: Schema.Literal<["text"]>;
+            text: typeof Schema.String;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["reasoning"]>;
+            text: typeof Schema.String;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+        }>, Schema.Struct<{
+            type: Schema.Literal<["tool-call"]>;
+            toolCallId: Schema.brand<typeof Schema.String, "ToolCallId">;
+            toolName: typeof Schema.String;
+            input: typeof Schema.Unknown;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+            providerExecuted: Schema.optional<typeof Schema.Boolean>;
+        }>]>>;
+        providerOptions: Schema.optional<typeof Schema.Unknown>;
+    }>, Schema.Struct<{
+        role: Schema.Literal<["tool"]>;
+        content: Schema.Array$<Schema.Struct<{
+            type: Schema.Literal<["tool-result"]>;
+            toolCallId: Schema.brand<typeof Schema.String, "ToolCallId">;
+            toolName: typeof Schema.String;
+            output: typeof Schema.Unknown;
+            providerOptions: Schema.optional<typeof Schema.Unknown>;
+            isError: Schema.optional<typeof Schema.Boolean>;
+        }>>;
+        providerOptions: Schema.optional<typeof Schema.Unknown>;
+    }>]>;
+}>, never, {
+    readonly message: {
+        readonly providerOptions?: unknown;
+        readonly role: "user";
+        readonly content: string;
+    } | {
+        readonly providerOptions?: unknown;
+        readonly role: "assistant";
+        readonly content: readonly ({
+            readonly type: "text";
+            readonly text: string;
+            readonly providerOptions?: unknown;
+        } | {
+            readonly type: "reasoning";
+            readonly text: string;
+            readonly providerOptions?: unknown;
+        } | {
+            readonly type: "tool-call";
+            readonly providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly input: unknown;
+            readonly providerExecuted?: boolean | undefined;
+        })[];
+    } | {
+        readonly providerOptions?: unknown;
+        readonly role: "tool";
+        readonly content: readonly {
+            readonly type: "tool-result";
+            readonly providerOptions?: unknown;
+            readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
+            readonly toolName: string;
+            readonly output: unknown;
+            readonly isError?: boolean | undefined;
+        }[];
+    };
+} & {
+    readonly position: number;
+}, {}, {}>;
+/** A persisted row WITH its durable position — what the active window is
+ *  made of, so a loader never reconstructs positions by arithmetic (an
+ *  undecodable row in between would shift every later one). */
+export declare class StoredMessage extends StoredMessage_base {
+}
+declare const ConversationStore_base: Context.TagClass<ConversationStore, "@xandreed/core/ConversationStore", {
+    readonly create: (workspaceDir?: string) => Effect.Effect<ConversationId, StoreError>;
+    readonly append: (id: ConversationId, message: AgentMessage) => Effect.Effect<number, StoreError>;
+    /** One turn's rows land TOGETHER or not at all — an assistant tool call
+     *  without its results is a row the next run cannot send. Returns the
+     *  positions, aligned with the input. */
+    readonly appendAll: (id: ConversationId, messages: ReadonlyArray<AgentMessage>) => Effect.Effect<ReadonlyArray<number>, StoreError>;
+    readonly list: (id: ConversationId) => Effect.Effect<ReadonlyArray<AgentMessage>, StoreError>;
+    /** The rows after the latest fold, each with its position. */
+    readonly listActive: (id: ConversationId) => Effect.Effect<ReadonlyArray<StoredMessage>, StoreError>;
+    readonly checkpoint: (id: ConversationId, summary: string) => Effect.Effect<void, StoreError>;
+    /** A fold up to an EXPLICIT position (the within-run compaction seam):
+     *  rows at or before it are covered by the summary; `listActive` returns
+     *  only the rows after. `checkpoint` folds everything appended so far. */
+    readonly checkpointAt: (id: ConversationId, summary: string, messagePosition: number) => Effect.Effect<void, StoreError>;
+    readonly latestCheckpoint: (id: ConversationId) => Effect.Effect<Option.Option<Checkpoint>, StoreError>;
+    readonly setTitle: (id: ConversationId, title: string) => Effect.Effect<void, StoreError>;
+    /** Record how a run ended (appended; the latest is the conversation's). */
+    readonly recordOutcome: (id: ConversationId, outcome: RunOutcomeRecord["outcome"], reason: RunOutcomeRecord["reason"]) => Effect.Effect<void, StoreError>;
+    readonly latestOutcome: (id: ConversationId) => Effect.Effect<Option.Option<RunOutcomeRecord>, StoreError>;
+    readonly listByWorkspace: (workspaceDir: string) => Effect.Effect<ReadonlyArray<ConversationSummary>, StoreError>;
+    /** BRANCH: copy rows [0..upToPosition] (default: all) into a NEW
+     *  conversation in the same workspace, along with the latest covered
+     *  checkpoint — the original stays untouched; the fork continues
+     *  independently (git-branch semantics over the trail). */
+    readonly fork: (id: ConversationId, upToPosition?: number) => Effect.Effect<ConversationId, StoreError>;
+    /** RETENTION: delete whole conversations created before `beforeEpochMs`
+     *  (messages + checkpoints + the conversation row) and reclaim the
+     *  space. Nothing calls this automatically — deletion is a deliberate,
+     *  human-initiated act on an otherwise append-only store. Returns the
+     *  number of conversations removed. */
+    readonly prune: (beforeEpochMs: number) => Effect.Effect<number, StoreError>;
+}>;
+/**
+ * The conversation persistence port. Positions are the durable identity:
+ * `append` assigns a monotonic, immutable absolute position per conversation,
+ * and UIs key their blocks on it so a live-streamed block and a later
+ * re-projection of the same message reconcile instead of duplicating.
+ *
+ * A checkpoint FOLDS the history for loading purposes only: `list` always
+ * returns every row; `listActive` returns the rows after the latest fold.
+ * The loop prepends the fold's summary itself (domain logic stays here,
+ * not in the adapter).
+ */
+export declare class ConversationStore extends ConversationStore_base {
+}
+export {};

package/dist/ports/conversation-store.port.js

@@ -0,0 +1,36 @@
+import { Context, Option, Schema } from "effect";
+import { AgentMessage, ConversationId } from "../domain/message.entity.js";
+
+export class StoreError extends Schema.TaggedError()("StoreError", {
+  message: Schema.String
+}) {
+}
+
+export class RunOutcomeRecord extends Schema.Class("RunOutcomeRecord")({
+  conversationId: ConversationId,
+  at: Schema.Number,
+  outcome: Schema.Literal("ok", "partial"),
+  reason: Schema.Literal("completed", "step-cap", "degenerate-loop")
+}) {
+}
+
+export class ConversationSummary extends Schema.Class("ConversationSummary")({
+  id: ConversationId,
+  createdAt: Schema.Number,
+  firstPrompt: Schema.optionalWith(Schema.String, { as: "Option" }),
+  title: Schema.optionalWith(Schema.String, { as: "Option" }),
+  lastOutcome: Schema.optionalWith(Schema.Struct({
+    outcome: Schema.Literal("ok", "partial"),
+    reason: Schema.Literal("completed", "step-cap", "degenerate-loop")
+  }), { as: "Option" })
+}) {
+}
+
+export class StoredMessage extends Schema.Class("StoredMessage")({
+  position: Schema.Int,
+  message: AgentMessage
+}) {
+}
+
+export class ConversationStore extends Context.Tag("@xandreed/core/ConversationStore")() {
+}

package/dist/ports/file-system.port.d.ts

@@ -0,0 +1,26 @@
+import { Context, Schema } from "effect";
+import type { Effect } from "effect";
+declare const FsError_base: Schema.TaggedErrorClass<FsError, "FsError", {
+    readonly _tag: Schema.tag<"FsError">;
+} & {
+    path: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export declare class FsError extends FsError_base {
+}
+declare const FileSystem_base: Context.TagClass<FileSystem, "@xandreed/core/FileSystem", {
+    readonly read: (path: string) => Effect.Effect<string, FsError>;
+    readonly write: (path: string, content: string) => Effect.Effect<void, FsError>;
+    readonly exists: (path: string) => Effect.Effect<boolean, FsError>;
+    readonly list: (dir: string) => Effect.Effect<ReadonlyArray<string>, FsError>;
+    readonly mkdir: (dir: string) => Effect.Effect<void, FsError>;
+    /** Resolve symlinks to the canonical absolute path. */
+    readonly realPath: (path: string) => Effect.Effect<string, FsError>;
+    /** Delete a file. A missing path is a no-op (idempotent), not an error. */
+    readonly remove: (path: string) => Effect.Effect<void, FsError>;
+}>;
+/** Minimal filesystem port for agent tools. Paths are absolute or
+ *  caller-resolved — the port does no cwd magic. */
+export declare class FileSystem extends FileSystem_base {
+}
+export {};

package/dist/ports/file-system.port.js

@@ -0,0 +1,10 @@
+import { Context, Schema } from "effect";
+
+export class FsError extends Schema.TaggedError()("FsError", {
+  path: Schema.String,
+  message: Schema.String
+}) {
+}
+
+export class FileSystem extends Context.Tag("@xandreed/core/FileSystem")() {
+}

package/dist/ports/harness.port.d.ts

@@ -0,0 +1,106 @@
+import { Context } from "effect";
+import type { Effect, Option, Stream } from "effect";
+import type { Tool, Toolkit } from "@effect/ai";
+import type { AgentMessage, ConversationId } from "../domain/message.entity.js";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { EventBody, MemoryEntry, SessionEvent, SessionRecord } from "../harness/session.entity.js";
+declare const SessionStore_base: Context.TagClass<SessionStore, "efferent/SessionStore", {
+    readonly create: (workspace: string, profile: string) => Effect.Effect<SessionRecord, HarnessError>;
+    readonly get: (id: ConversationId) => Effect.Effect<SessionRecord, HarnessError>;
+    readonly list: (workspace: string) => Effect.Effect<ReadonlyArray<SessionRecord>, HarnessError>;
+    readonly read: (id: ConversationId, after: number) => Effect.Effect<ReadonlyArray<SessionEvent>, HarnessError>;
+    readonly append: (id: ConversationId, body: EventBody) => Effect.Effect<SessionEvent, HarnessError>;
+    readonly fork: (id: ConversationId, through: number) => Effect.Effect<SessionRecord, HarnessError>;
+}>;
+export declare class SessionStore extends SessionStore_base {
+}
+export interface LoopInput {
+    readonly session: SessionRecord;
+    readonly runId: string;
+    readonly prompt: string;
+    readonly system: string;
+    readonly publish: (event: EventBody) => Effect.Effect<SessionEvent, HarnessError>;
+    readonly transient: (event: EventBody) => Effect.Effect<void>;
+    readonly steering: Effect.Effect<Option.Option<string>, HarnessError>;
+}
+declare const AgentLoop_base: Context.TagClass<AgentLoop, "efferent/AgentLoop", {
+    readonly run: (input: LoopInput) => Effect.Effect<{
+        readonly text: string;
+        readonly outcome: "completed" | "partial";
+    }, HarnessError>;
+}>;
+export declare class AgentLoop extends AgentLoop_base {
+}
+declare const DelegateLoop_base: Context.TagClass<DelegateLoop, "efferent/DelegateLoop", {
+    readonly run: (input: LoopInput) => Effect.Effect<{
+        readonly text: string;
+        readonly outcome: "completed" | "partial";
+    }, HarnessError>;
+}>;
+/** A workflow can delegate coding while retaining its own outer loop. */
+export declare class DelegateLoop extends DelegateLoop_base {
+}
+declare const AgentTools_base: Context.TagClass<AgentTools, "efferent/AgentTools", {
+    readonly toolkit: Toolkit.Toolkit<Record<string, Tool.Any>>;
+    readonly handlers: Context.Context<Tool.HandlersFor<Record<string, Tool.Any>>>;
+    readonly prompt: string;
+}>;
+export declare class AgentTools extends AgentTools_base {
+}
+declare const ActionPolicy_base: Context.TagClass<ActionPolicy, "efferent/ActionPolicy", {
+    readonly authorize: (tool: string, input: unknown) => Effect.Effect<void, HarnessError>;
+}>;
+export declare class ActionPolicy extends ActionPolicy_base {
+}
+declare const Approval_base: Context.TagClass<Approval, "efferent/Approval", {
+    readonly request: (description: string) => Effect.Effect<boolean, HarnessError>;
+}>;
+export declare class Approval extends Approval_base {
+}
+declare const ContextManager_base: Context.TagClass<ContextManager, "efferent/ContextManager", {
+    readonly compact: (messages: ReadonlyArray<AgentMessage>, tokens: number) => Effect.Effect<Option.Option<{
+        readonly summary: string;
+        readonly keepFrom: number;
+    }>, HarnessError>;
+}>;
+export declare class ContextManager extends ContextManager_base {
+}
+declare const Memory_base: Context.TagClass<Memory, "efferent/Memory", {
+    readonly recall: (workspace: string, query: string) => Effect.Effect<ReadonlyArray<MemoryEntry>, HarnessError>;
+    readonly remember: (workspace: string, text: string) => Effect.Effect<MemoryEntry, HarnessError>;
+    readonly forget: (workspace: string, id: string) => Effect.Effect<void, HarnessError>;
+}>;
+export declare class Memory extends Memory_base {
+}
+declare const SessionEnvironment_base: Context.TagClass<SessionEnvironment, "efferent/SessionEnvironment", {
+    readonly workspace: string;
+    readonly session?: SessionRecord;
+}>;
+export declare class SessionEnvironment extends SessionEnvironment_base {
+}
+declare const TurnHooks_base: Context.TagClass<TurnHooks, "efferent/TurnHooks", {
+    readonly before: (input: LoopInput) => Effect.Effect<LoopInput, HarnessError>;
+    readonly after: (input: LoopInput) => Effect.Effect<void, HarnessError>;
+}>;
+/** Ordered hooks alter a turn; observers subscribe to the journal separately. */
+export declare class TurnHooks extends TurnHooks_base {
+}
+export interface SessionHandle {
+    readonly record: SessionRecord;
+    readonly use: <I, A, B, E, R>(tag: Context.Tag<I, A>, run: (service: A) => Effect.Effect<B, E, R>) => Effect.Effect<B, E | HarnessError, R>;
+    readonly send: (text: string) => Effect.Effect<void, HarnessError>;
+    readonly steer: (text: string) => Effect.Effect<void, HarnessError>;
+    readonly interrupt: Effect.Effect<void>;
+    readonly events: (after?: number) => Stream.Stream<SessionEvent, HarnessError>;
+    readonly transient: Stream.Stream<EventBody>;
+    readonly history: Effect.Effect<ReadonlyArray<SessionEvent>, HarnessError>;
+    readonly busy: Effect.Effect<boolean>;
+    readonly pending: Effect.Effect<ReadonlyArray<{
+        readonly id: string;
+        readonly text: string;
+    }>>;
+    readonly continue: Effect.Effect<void, HarnessError>;
+    readonly refresh: Effect.Effect<void, HarnessError>;
+    readonly close: Effect.Effect<void>;
+}
+export {};

package/dist/ports/harness.port.js

@@ -0,0 +1,31 @@
+import { Context } from "effect";
+
+export class SessionStore extends Context.Tag("efferent/SessionStore")() {
+}
+
+export class AgentLoop extends Context.Tag("efferent/AgentLoop")() {
+}
+
+export class DelegateLoop extends Context.Tag("efferent/DelegateLoop")() {
+}
+
+export class AgentTools extends Context.Tag("efferent/AgentTools")() {
+}
+
+export class ActionPolicy extends Context.Tag("efferent/ActionPolicy")() {
+}
+
+export class Approval extends Context.Tag("efferent/Approval")() {
+}
+
+export class ContextManager extends Context.Tag("efferent/ContextManager")() {
+}
+
+export class Memory extends Context.Tag("efferent/Memory")() {
+}
+
+export class SessionEnvironment extends Context.Tag("efferent/SessionEnvironment")() {
+}
+
+export class TurnHooks extends Context.Tag("efferent/TurnHooks")() {
+}

package/dist/ports/mcp-client.port.d.ts

@@ -0,0 +1,74 @@
+import { Context, Schema } from "effect";
+import type { Effect } from "effect";
+declare const McpError_base: Schema.TaggedErrorClass<McpError, "McpError", {
+    readonly _tag: Schema.tag<"McpError">;
+} & {
+    server: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+/**
+ * The MCP client port — external, user-configured tool servers surfaced to
+ * agents through the ordinary toolkit machinery (see `mcp/bridge.ts`). The
+ * adapter owns transport (stdio JSON-RPC) and lifecycle; the engine sees
+ * only descriptors and calls. Consent model: servers exist ONLY because the
+ * human wrote them into `.efferent/config.json`.
+ */
+export declare class McpError extends McpError_base {
+}
+declare const McpToolDescriptor_base: Schema.Class<McpToolDescriptor, {
+    server: typeof Schema.String;
+    name: typeof Schema.String;
+    description: Schema.optionalWith<typeof Schema.String, {
+        as: "Option";
+    }>;
+    /** The server's inputSchema, verbatim JSON Schema — the provider sees it
+     *  unchanged through the bridge's annotation override. */
+    inputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+}, Schema.Struct.Encoded<{
+    server: typeof Schema.String;
+    name: typeof Schema.String;
+    description: Schema.optionalWith<typeof Schema.String, {
+        as: "Option";
+    }>;
+    /** The server's inputSchema, verbatim JSON Schema — the provider sees it
+     *  unchanged through the bridge's annotation override. */
+    inputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+}>, never, {
+    readonly description: import("effect/Option").Option<string>;
+} & {
+    readonly name: string;
+} & {
+    readonly server: string;
+} & {
+    readonly inputSchema: {
+        readonly [x: string]: unknown;
+    };
+}, {}, {}>;
+export declare class McpToolDescriptor extends McpToolDescriptor_base {
+}
+declare const McpCallOutcome_base: Schema.Class<McpCallOutcome, {
+    /** MCP's in-band failure flag — bridged to failure-as-data, never thrown. */
+    isError: typeof Schema.Boolean;
+    /** structuredContent when the server sent it, else the text blocks joined. */
+    result: typeof Schema.Unknown;
+}, Schema.Struct.Encoded<{
+    /** MCP's in-band failure flag — bridged to failure-as-data, never thrown. */
+    isError: typeof Schema.Boolean;
+    /** structuredContent when the server sent it, else the text blocks joined. */
+    result: typeof Schema.Unknown;
+}>, never, {
+    readonly isError: boolean;
+} & {
+    readonly result: unknown;
+}, {}, {}>;
+export declare class McpCallOutcome extends McpCallOutcome_base {
+}
+declare const McpClient_base: Context.TagClass<McpClient, "@xandreed/core/McpClient", {
+    /** Aggregate across every configured server — best-effort: an
+     *  unreachable server contributes nothing, never a failure. */
+    readonly listTools: Effect.Effect<ReadonlyArray<McpToolDescriptor>>;
+    readonly callTool: (server: string, tool: string, args: unknown) => Effect.Effect<McpCallOutcome, McpError>;
+}>;
+export declare class McpClient extends McpClient_base {
+}
+export {};

package/dist/ports/mcp-client.port.js

@@ -0,0 +1,24 @@
+import { Context, Schema } from "effect";
+
+export class McpError extends Schema.TaggedError()("McpError", {
+  server: Schema.String,
+  message: Schema.String
+}) {
+}
+
+export class McpToolDescriptor extends Schema.Class("McpToolDescriptor")({
+  server: Schema.String,
+  name: Schema.String,
+  description: Schema.optionalWith(Schema.String, { as: "Option" }),
+  inputSchema: Schema.Record({ key: Schema.String, value: Schema.Unknown })
+}) {
+}
+
+export class McpCallOutcome extends Schema.Class("McpCallOutcome")({
+  isError: Schema.Boolean,
+  result: Schema.Unknown
+}) {
+}
+
+export class McpClient extends Context.Tag("@xandreed/core/McpClient")() {
+}

package/dist/ports/model-catalog.port.d.ts

@@ -0,0 +1,10 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+import type { ModelCatalogEntry } from "../domain/model-catalog.entity.js";
+declare const ModelCatalog_base: Context.TagClass<ModelCatalog, "@xandreed/core/ModelCatalog", {
+    readonly list: Effect.Effect<ReadonlyArray<ModelCatalogEntry>>;
+}>;
+/** Provider-neutral discovery of models usable by configured adapters. */
+export declare class ModelCatalog extends ModelCatalog_base {
+}
+export {};

package/dist/ports/model-catalog.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+
+export class ModelCatalog extends Context.Tag("@xandreed/core/ModelCatalog")() {
+}