@xandreed/core 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/core
+
+Efferent composable agent framework, 0.3.0. Bun on Linux.
+
+Documentation: https://github.com/xandreeddev/efferent

package/dist/domain/agent-failure.entity.d.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+/** Stable, serializable failure context shared by products and evaluations. */
+export declare const AgentFailureCategory: Schema.Literal<["authentication", "authorization", "rate-limit", "timeout", "transport", "protocol", "validation", "tool", "persistence", "unknown"]>;
+export type AgentFailureCategory = typeof AgentFailureCategory.Type;
+export declare const AgentFailure: Schema.Struct<{
+    code: typeof Schema.String;
+    category: Schema.Literal<["authentication", "authorization", "rate-limit", "timeout", "transport", "protocol", "validation", "tool", "persistence", "unknown"]>;
+    stage: typeof Schema.String;
+    message: typeof Schema.String;
+    retryable: typeof Schema.Boolean;
+}>;
+export type AgentFailure = typeof AgentFailure.Type;

package/dist/domain/agent-failure.entity.functions.d.ts

@@ -0,0 +1,5 @@
+import type { AgentFailure } from "./agent-failure.entity.js";
+/** Classify adapter/runtime defects without exposing provider-specific types. */
+export declare const toAgentFailure: (error: unknown, stage: string) => AgentFailure;
+/** Preserve a returned tool failure as structured context for hosts/evals. */
+export declare const toolResultFailure: (result: unknown, toolName: string) => AgentFailure;

package/dist/domain/agent-failure.entity.functions.js

@@ -0,0 +1,8 @@
+const record = (value) => typeof value === "object" && value !== null ? value : {}, text = (value) => typeof value === "string" && value.trim().length > 0 ? value : void 0, numeric = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+export const toAgentFailure = (error, stage) => {
+  const value = record(error), response = record(value.response), tag = text(value._tag) ?? (error instanceof Error ? error.name : void 0) ?? "UnknownError", status = numeric(response.status) ?? numeric(value.status), message = text(value.description) ?? (error instanceof Error ? error.message : void 0) ?? String(error), unavailable = /model .* is not available to .*subscription/i.test(message), unsupported = /model .* (?:is )?not supported/i.test(message), terminalQuota = /CreditsError|insufficient (?:balance|credits)|usage limit|quota exhausted/i.test(message), category = unavailable || unsupported ? "validation" : terminalQuota ? "rate-limit" : /timeout/i.test(tag) || /timed? out/i.test(message) ? "timeout" : /AuthError/i.test(tag) || status === 401 ? "authentication" : status === 403 ? "authorization" : status === 429 ? "rate-limit" : /Malformed|Parse|Decode/i.test(tag) || status !== void 0 && status >= 400 && status < 500 ? "protocol" : /Http|Request|Response|Network|Socket|Fetch/i.test(tag) || status !== void 0 && status >= 500 ? "transport" : "unknown";
+  return { code: unavailable ? "ModelUnavailable" : unsupported ? "ModelUnsupported" : status === void 0 ? tag : `${tag}:${status}`, category, stage, message, retryable: category === "timeout" || category === "rate-limit" && !terminalQuota || category === "transport" };
+}, toolResultFailure = (result, toolName) => {
+  const value = record(result), code = text(value.error) ?? "ToolFailure", message = text(value.message) ?? JSON.stringify(result), category = /Rejected|Incomplete|Invalid|TooMany|TooLarge/i.test(code) ? "validation" : /Store/i.test(code) ? "persistence" : "tool";
+  return { code, category, stage: `tool:${toolName}`, message, retryable: category === "persistence" };
+};

package/dist/domain/agent-failure.entity.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+export const AgentFailureCategory = Schema.Literal("authentication", "authorization", "rate-limit", "timeout", "transport", "protocol", "validation", "tool", "persistence", "unknown"), AgentFailure = Schema.Struct({
+  code: Schema.String,
+  category: AgentFailureCategory,
+  stage: Schema.String,
+  message: Schema.String,
+  retryable: Schema.Boolean
+});

package/dist/domain/failure.entity.d.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+/**
+ * The shared tool-failure shape every engine toolkit uses with
+ * `failureMode: "return"`: a handler failure is returned to the model as
+ * data — `{ error, message }` — never thrown, never a dead turn. The
+ * `message` says exactly what to fix; the model corrects in the same run.
+ */
+export declare const Failure: Schema.Struct<{
+    error: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export type Failure = typeof Failure.Type;

package/dist/domain/failure.entity.functions.d.ts

@@ -0,0 +1,3 @@
+import type { Failure } from "./failure.entity.js";
+/** Project an arbitrary defect into the model-readable failure shape. */
+export declare const toFailure: (error: unknown) => Failure;

package/dist/domain/failure.entity.functions.js

@@ -0,0 +1 @@
+export const toFailure = (error) => error instanceof Error ? { error: error.name, message: error.message } : { error: "Error", message: String(error) };

package/dist/domain/failure.entity.js

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+export const Failure = Schema.Struct({
+  error: Schema.String,
+  message: Schema.String
+});

package/dist/domain/loop-event.entity.d.ts

@@ -0,0 +1,94 @@
+import type { TokenUsage } from "./token-usage.entity.js";
+import type { AgentFailure } from "./agent-failure.entity.js";
+/**
+ * The loop's event vocabulary — everything a driver needs to render a run
+ * live. ONE union, ONE optional sink (`onEvent`), instead of a record of
+ * optional callbacks: the session chassis pumps these onto its ledger and a
+ * product extends the vocabulary with its own `{ type: ... }` events.
+ *
+ * Discriminated on `type` (not `_tag`) so product events compose naturally
+ * (`type SessionEvent = LoopEvent | { type: "math_render"; ... }`).
+ */
+export interface ToolCallSummary {
+    readonly id: string;
+    readonly toolName: string;
+    readonly args: unknown;
+}
+export type LoopEvent = {
+    readonly type: "turn_start";
+    readonly turnIndex: number;
+} | {
+    readonly type: "turn_end";
+    readonly turnIndex: number;
+    readonly status: "completed" | "failed" | "cancelled";
+}
+/**
+ * One streamed content increment, TRANSIENT by design: it exists only for
+ * live rendering, is never ledgered or replayed, and every fact it carries
+ * is restated by the turn's `assistant_message` (the sole finalizer —
+ * position/usage ride only there). `id` scopes deltas to one content chunk
+ * within the turn (a turn can hold several, e.g. reasoning then text).
+ */
+ | {
+    readonly type: "assistant_delta";
+    readonly turnIndex: number;
+    /** `tool-params` deltas carry the tool call's streamed ARGUMENT text —
+     *  they exist for incremental admission (a session may act on a
+     *  complete argument prefix before the call settles) and are noise to
+     *  plain text renderers, which should drop the channel. */
+    readonly channel: "text" | "reasoning" | "tool-params";
+    readonly id: string;
+    readonly delta: string;
+    /** The tool being called — present on `tool-params` deltas only. */
+    readonly toolName?: string;
+} | {
+    readonly type: "assistant_message";
+    readonly turnIndex: number;
+    readonly text: string;
+    readonly reasoning: string;
+    /** The resolved `provider:modelId` that produced this message. */
+    readonly model?: string;
+    readonly toolCalls: ReadonlyArray<ToolCallSummary>;
+    readonly usage: TokenUsage;
+    /** The assistant message's absolute store position, when persisted —
+     *  the durable identity a UI keys its rail block on. */
+    readonly position?: number;
+} | {
+    readonly type: "tool_start";
+    readonly turnIndex: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+} | {
+    readonly type: "tool_end";
+    readonly turnIndex: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly ok: boolean;
+    readonly result: unknown;
+}
+/** The mid-run fold: the buffer outgrew the healthy context range and the
+ *  older turns were replaced by a handoff summary — `kept` verbatim
+ *  messages survive after it. A load-side rewrite; nothing is deleted. */
+ | {
+    readonly type: "compaction";
+    readonly turnIndex: number;
+    readonly tokens: number;
+    readonly kept: number;
+} | {
+    readonly type: "agent_end";
+    readonly outcome: "ok" | "partial";
+    readonly reason: "completed" | "step-cap" | "degenerate-loop";
+    readonly finalText: string;
+}
+/** A turn crashed outside the model's control (provider failure after
+ *  retries, a defect). Published by the chassis, part of the vocabulary so
+ *  every driver renders failures the same way. */
+ | {
+    readonly type: "error";
+    /** Human-readable presentation text. */
+    readonly message: string;
+    /** Machine-readable context retained by stores, hosts, and evals. */
+    readonly failure?: AgentFailure;
+};

package/dist/domain/message.entity.d.ts

@@ -0,0 +1,227 @@
+import { Schema } from "effect";
+/**
+ * The persisted conversation vocabulary — a stable, provider-agnostic shape
+ * the loop appends to and the store persists verbatim. `providerOptions` is
+ * an opaque blob that round-trips provider-private fields (e.g. Gemini's
+ * `thought_signature` on a reasoning part) without the engine inspecting them.
+ */
+export declare const ConversationId: Schema.brand<typeof Schema.UUID, "ConversationId">;
+export type ConversationId = typeof ConversationId.Type;
+/** A tool call's pairing key — the provider's id, or the loop's deterministic
+ *  `<turnIndex>:<toolName>:<ordinal>` mint when the provider omits one. */
+export declare const ToolCallId: Schema.brand<typeof Schema.String, "ToolCallId">;
+export type ToolCallId = typeof ToolCallId.Type;
+declare const Checkpoint_base: Schema.Class<Checkpoint, {
+    conversationId: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    /** The absolute message position this fold covers (inclusive). */
+    messagePosition: typeof Schema.Number;
+    summary: typeof Schema.String;
+    createdAt: typeof Schema.Number;
+}, Schema.Struct.Encoded<{
+    conversationId: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    /** The absolute message position this fold covers (inclusive). */
+    messagePosition: typeof Schema.Number;
+    summary: typeof Schema.String;
+    createdAt: typeof Schema.Number;
+}>, never, {
+    readonly conversationId: string & import("effect/Brand").Brand<"ConversationId">;
+} & {
+    readonly messagePosition: number;
+} & {
+    readonly summary: string;
+} & {
+    readonly createdAt: number;
+}, {}, {}>;
+export declare class Checkpoint extends Checkpoint_base {
+}
+export declare const TextPart: Schema.Struct<{
+    type: Schema.Literal<["text"]>;
+    text: typeof Schema.String;
+    providerOptions: Schema.optional<typeof Schema.Unknown>;
+}>;
+export type TextPart = typeof TextPart.Type;
+export declare const ReasoningPart: Schema.Struct<{
+    type: Schema.Literal<["reasoning"]>;
+    text: typeof Schema.String;
+    providerOptions: Schema.optional<typeof Schema.Unknown>;
+}>;
+export type ReasoningPart = typeof ReasoningPart.Type;
+export declare const ToolCallPart: 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>;
+}>;
+export type ToolCallPart = typeof ToolCallPart.Type;
+export declare const ToolResultPart: 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>;
+}>;
+export type ToolResultPart = typeof ToolResultPart.Type;
+export declare const UserMessage: Schema.Struct<{
+    role: Schema.Literal<["user"]>;
+    content: typeof Schema.String;
+    providerOptions: Schema.optional<typeof Schema.Unknown>;
+}>;
+export type UserMessage = typeof UserMessage.Type;
+export declare const AssistantMessage: 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>;
+}>;
+export type AssistantMessage = typeof AssistantMessage.Type;
+export declare const ToolMessage: 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>;
+}>;
+export type ToolMessage = typeof ToolMessage.Type;
+/** The single conversation unit — persisted as-is, one row per entry. */
+export declare const AgentMessage: 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>;
+}>]>;
+export type AgentMessage = typeof AgentMessage.Type;
+/**
+ * Result of one agent run. `newTail` is exactly what the loop APPENDED —
+ * including synthetic correctives it injected itself. Persist `newTail`;
+ * never reconstruct it by index arithmetic on `messages`.
+ */
+export declare const AgentResult: Schema.Struct<{
+    finalText: typeof Schema.String;
+    messages: Schema.Array$<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>;
+    }>]>>;
+    newTail: Schema.Array$<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>;
+    }>]>>;
+    /** "ok" — the model finished on its own; "partial" — the step cap or the
+     *  degenerate-loop breaker stopped it, so `finalText` is NOT a deliverable. */
+    outcome: Schema.Literal<["ok", "partial"]>;
+    reason: Schema.Literal<["completed", "step-cap", "degenerate-loop"]>;
+}>;
+export type AgentResult = typeof AgentResult.Type;
+export {};

package/dist/domain/message.entity.js

@@ -0,0 +1,51 @@
+import { Schema } from "effect";
+export const ConversationId = Schema.UUID.pipe(Schema.brand("ConversationId")), ToolCallId = Schema.String.pipe(Schema.brand("ToolCallId"));
+
+export class Checkpoint extends Schema.Class("Checkpoint")({
+  conversationId: ConversationId,
+  messagePosition: Schema.Number,
+  summary: Schema.String,
+  createdAt: Schema.Number
+}) {
+}
+export const TextPart = Schema.Struct({
+  type: Schema.Literal("text"),
+  text: Schema.String,
+  providerOptions: Schema.optional(Schema.Unknown)
+}), ReasoningPart = Schema.Struct({
+  type: Schema.Literal("reasoning"),
+  text: Schema.String,
+  providerOptions: Schema.optional(Schema.Unknown)
+}), ToolCallPart = Schema.Struct({
+  type: Schema.Literal("tool-call"),
+  toolCallId: ToolCallId,
+  toolName: Schema.String,
+  input: Schema.Unknown,
+  providerOptions: Schema.optional(Schema.Unknown),
+  providerExecuted: Schema.optional(Schema.Boolean)
+}), ToolResultPart = Schema.Struct({
+  type: Schema.Literal("tool-result"),
+  toolCallId: ToolCallId,
+  toolName: Schema.String,
+  output: Schema.Unknown,
+  providerOptions: Schema.optional(Schema.Unknown),
+  isError: Schema.optional(Schema.Boolean)
+}), UserMessage = Schema.Struct({
+  role: Schema.Literal("user"),
+  content: Schema.String,
+  providerOptions: Schema.optional(Schema.Unknown)
+}), AssistantMessage = Schema.Struct({
+  role: Schema.Literal("assistant"),
+  content: Schema.Array(Schema.Union(TextPart, ReasoningPart, ToolCallPart)),
+  providerOptions: Schema.optional(Schema.Unknown)
+}), ToolMessage = Schema.Struct({
+  role: Schema.Literal("tool"),
+  content: Schema.Array(ToolResultPart),
+  providerOptions: Schema.optional(Schema.Unknown)
+}), AgentMessage = Schema.Union(UserMessage, AssistantMessage, ToolMessage), AgentResult = Schema.Struct({
+  finalText: Schema.String,
+  messages: Schema.Array(AgentMessage),
+  newTail: Schema.Array(AgentMessage),
+  outcome: Schema.Literal("ok", "partial"),
+  reason: Schema.Literal("completed", "step-cap", "degenerate-loop")
+});

package/dist/domain/model-call-policy.entity.d.ts

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+/** `none` skips reasoning entirely — live-probed 2026-07-16 on the codex
+ * subscription dialect (accepted, reasoning_tokens 0); `minimal` was
+ * REJECTED there and stays out of the vocabulary. Non-codex adapters clamp
+ * `none` to their nearest supported value. */
+export declare const ReasoningEffort: Schema.Literal<["none", "low", "medium", "high", "xhigh", "max"]>;
+export type ReasoningEffort = typeof ReasoningEffort.Type;
+export declare const ModelCallPolicy: Schema.Struct<{
+    effort: Schema.Literal<["none", "low", "medium", "high", "xhigh", "max"]>;
+    maxOutputTokens: Schema.optional<typeof Schema.Number>;
+}>;
+export type ModelCallPolicy = typeof ModelCallPolicy.Type;

package/dist/domain/model-call-policy.entity.js

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+export const ReasoningEffort = Schema.Literal("none", "low", "medium", "high", "xhigh", "max"), ModelCallPolicy = Schema.Struct({
+  effort: ReasoningEffort,
+  maxOutputTokens: Schema.optional(Schema.Number)
+});

package/dist/domain/model-catalog.entity.d.ts

@@ -0,0 +1,10 @@
+import { Schema } from "effect";
+/** A selectable model exposed by one configured provider adapter. */
+export declare const ModelCatalogEntry: Schema.Struct<{
+    selection: typeof Schema.String;
+    /** Human-facing route name. `selection` remains the stable persisted id. */
+    label: Schema.optional<typeof Schema.String>;
+    provider: typeof Schema.String;
+    credential: Schema.Literal<["api_key", "oauth", "local"]>;
+}>;
+export type ModelCatalogEntry = typeof ModelCatalogEntry.Type;

package/dist/domain/model-catalog.entity.js

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+export const ModelCatalogEntry = Schema.Struct({
+  selection: Schema.String,
+  label: Schema.optional(Schema.String),
+  provider: Schema.String,
+  credential: Schema.Literal("api_key", "oauth", "local")
+});

package/dist/domain/model-selection.entity.d.ts

@@ -0,0 +1,24 @@
+import { Schema } from "effect";
+/**
+ * A model selection is `"<provider>:<modelId>"` — the human's choice, persisted
+ * in settings. The engine treats the provider as an opaque id; which providers
+ * exist (and how to build their clients) is the providers package's knowledge.
+ */
+export declare const ProviderId: Schema.brand<typeof Schema.String, "ProviderId">;
+export type ProviderId = typeof ProviderId.Type;
+export declare const ModelId: Schema.brand<typeof Schema.String, "ModelId">;
+export type ModelId = typeof ModelId.Type;
+declare const ModelSelection_base: Schema.Class<ModelSelection, {
+    provider: Schema.brand<typeof Schema.String, "ProviderId">;
+    modelId: Schema.brand<typeof Schema.String, "ModelId">;
+}, Schema.Struct.Encoded<{
+    provider: Schema.brand<typeof Schema.String, "ProviderId">;
+    modelId: Schema.brand<typeof Schema.String, "ModelId">;
+}>, never, {
+    readonly provider: string & import("effect/Brand").Brand<"ProviderId">;
+} & {
+    readonly modelId: string & import("effect/Brand").Brand<"ModelId">;
+}, {}, {}>;
+export declare class ModelSelection extends ModelSelection_base {
+}
+export {};

package/dist/domain/model-selection.entity.functions.d.ts

@@ -0,0 +1,5 @@
+import { Option } from "effect";
+import { ModelSelection } from "./model-selection.entity.js";
+/** Parse `"<provider>:<modelId>"`; model ids may themselves contain `:`. */
+export declare const parseModelSelection: (value: string) => Option.Option<ModelSelection>;
+export declare const formatModelSelection: (selection: ModelSelection) => string;

package/dist/domain/model-selection.entity.functions.js

@@ -0,0 +1,9 @@
+import { Option } from "effect";
+import { ModelId, ModelSelection, ProviderId } from "./model-selection.entity.js";
+export const parseModelSelection = (value) => {
+  const at = value.indexOf(":"), provider = at > 0 ? value.slice(0, at) : "", modelId = at > 0 ? value.slice(at + 1) : "";
+  return provider.length > 0 && modelId.length > 0 ? Option.some(new ModelSelection({
+    provider: ProviderId.make(provider),
+    modelId: ModelId.make(modelId)
+  })) : Option.none();
+}, formatModelSelection = (selection) => `${selection.provider}:${selection.modelId}`;

package/dist/domain/model-selection.entity.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+export const ProviderId = Schema.String.pipe(Schema.brand("ProviderId")), ModelId = Schema.String.pipe(Schema.brand("ModelId"));
+
+export class ModelSelection extends Schema.Class("ModelSelection")({
+  provider: ProviderId,
+  modelId: ModelId
+}) {
+}

package/dist/domain/prompt-provenance.entity.d.ts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+export declare const PromptId: Schema.brand<typeof Schema.NonEmptyTrimmedString, "PromptId">;
+/** Metadata accompanies a native @effect/ai Prompt; it never replaces its messages. */
+export declare const PromptProvenance: Schema.Struct<{
+    id: Schema.brand<typeof Schema.NonEmptyTrimmedString, "PromptId">;
+    version: typeof Schema.NonEmptyTrimmedString;
+    variant: typeof Schema.NonEmptyTrimmedString;
+    modelOverride: Schema.OptionFromNullOr<typeof Schema.String>;
+    hash: typeof Schema.NonEmptyTrimmedString;
+}>;
+export type PromptProvenance = typeof PromptProvenance.Type;

package/dist/domain/prompt-provenance.entity.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+export const PromptId = Schema.NonEmptyTrimmedString.pipe(Schema.brand("PromptId")), PromptProvenance = Schema.Struct({
+  id: PromptId,
+  version: Schema.NonEmptyTrimmedString,
+  variant: Schema.NonEmptyTrimmedString,
+  modelOverride: Schema.OptionFromNullOr(Schema.String),
+  hash: Schema.NonEmptyTrimmedString
+});

package/dist/domain/token-usage.entity.d.ts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+/** Billed tokens for one model call (or a sum of them). */
+export declare const TokenUsage: Schema.Struct<{
+    inputTokens: typeof Schema.Number;
+    outputTokens: typeof Schema.Number;
+    totalTokens: typeof Schema.Number;
+    cacheReadTokens: typeof Schema.Number;
+}>;
+export type TokenUsage = typeof TokenUsage.Type;

package/dist/domain/token-usage.entity.functions.d.ts

@@ -0,0 +1,3 @@
+import type { TokenUsage } from "./token-usage.entity.js";
+export declare const zeroUsage: TokenUsage;
+export declare const addUsage: (a: TokenUsage, b: TokenUsage) => TokenUsage;

package/dist/domain/token-usage.entity.functions.js

@@ -0,0 +1,11 @@
+export const zeroUsage = {
+  inputTokens: 0,
+  outputTokens: 0,
+  totalTokens: 0,
+  cacheReadTokens: 0
+}, addUsage = (a, b) => ({
+  inputTokens: a.inputTokens + b.inputTokens,
+  outputTokens: a.outputTokens + b.outputTokens,
+  totalTokens: a.totalTokens + b.totalTokens,
+  cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens
+});

package/dist/domain/token-usage.entity.js

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+export const TokenUsage = Schema.Struct({
+  inputTokens: Schema.Number,
+  outputTokens: Schema.Number,
+  totalTokens: Schema.Number,
+  cacheReadTokens: Schema.Number
+});