@xandreed/core 0.3.0

package/dist/harness/capability.entity.d.ts

@@ -0,0 +1,61 @@
+import { Schema } from "effect";
+export declare const CapabilityTool: Schema.Struct<{
+    id: typeof Schema.NonEmptyTrimmedString;
+    version: typeof Schema.NonEmptyTrimmedString;
+    description: typeof Schema.NonEmptyTrimmedString;
+    returns: typeof Schema.NonEmptyTrimmedString;
+    permissions: Schema.Array$<typeof Schema.String>;
+    inputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+    outputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+}>;
+export type CapabilityTool = typeof CapabilityTool.Type;
+export declare const CapabilityRecipe: Schema.Struct<{
+    id: typeof Schema.NonEmptyTrimmedString;
+    version: typeof Schema.NonEmptyTrimmedString;
+    instructions: typeof Schema.NonEmptyTrimmedString;
+    tools: Schema.Array$<typeof Schema.NonEmptyTrimmedString>;
+}>;
+export type CapabilityRecipe = typeof CapabilityRecipe.Type;
+export declare const CapabilityCatalog: Schema.Struct<{
+    version: typeof Schema.NonEmptyTrimmedString;
+    recipes: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.NonEmptyTrimmedString;
+        version: typeof Schema.NonEmptyTrimmedString;
+        instructions: typeof Schema.NonEmptyTrimmedString;
+        tools: Schema.Array$<typeof Schema.NonEmptyTrimmedString>;
+    }>>;
+    tools: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.NonEmptyTrimmedString;
+        version: typeof Schema.NonEmptyTrimmedString;
+        description: typeof Schema.NonEmptyTrimmedString;
+        returns: typeof Schema.NonEmptyTrimmedString;
+        permissions: Schema.Array$<typeof Schema.String>;
+        inputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+        outputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+    }>>;
+}>;
+export type CapabilityCatalog = typeof CapabilityCatalog.Type;
+export declare const CapabilitySelection: Schema.Struct<{
+    recipes: Schema.Array$<typeof Schema.String>;
+    tools: Schema.Array$<typeof Schema.String>;
+}>;
+export type CapabilitySelection = typeof CapabilitySelection.Type;
+export declare const ResolvedCapabilities: Schema.Struct<{
+    catalogVersion: typeof Schema.String;
+    recipes: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.NonEmptyTrimmedString;
+        version: typeof Schema.NonEmptyTrimmedString;
+        instructions: typeof Schema.NonEmptyTrimmedString;
+        tools: Schema.Array$<typeof Schema.NonEmptyTrimmedString>;
+    }>>;
+    tools: Schema.Array$<Schema.Struct<{
+        id: typeof Schema.NonEmptyTrimmedString;
+        version: typeof Schema.NonEmptyTrimmedString;
+        description: typeof Schema.NonEmptyTrimmedString;
+        returns: typeof Schema.NonEmptyTrimmedString;
+        permissions: Schema.Array$<typeof Schema.String>;
+        inputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+        outputSchema: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+    }>>;
+}>;
+export type ResolvedCapabilities = typeof ResolvedCapabilities.Type;

package/dist/harness/capability.entity.functions.d.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import type { CapabilityCatalog, CapabilitySelection, ResolvedCapabilities } from "./capability.entity.js";
+import { HarnessError } from "./plugin.entity.js";
+/** Probabilistic intent never authorizes a capability. Expansions use this same
+ * deterministic resolver against the run-pinned catalog and current grants. */
+export declare const resolveCapabilities: (catalog: CapabilityCatalog, requested: CapabilitySelection, permissions: ReadonlySet<string>) => Effect.Effect<ResolvedCapabilities, HarnessError>;

package/dist/harness/capability.entity.functions.js

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import { HarnessError } from "./plugin.entity.js";
+export const resolveCapabilities = (catalog, requested, permissions) => Effect.gen(function* () {
+  const recipeIds = new Set(requested.recipes), recipes = catalog.recipes.filter((recipe) => recipeIds.has(recipe.id)), toolIds = new Set([...requested.tools, ...recipes.flatMap((recipe) => recipe.tools)]), tools = catalog.tools.filter((tool) => toolIds.has(tool.id));
+  if (new Set(catalog.recipes.map((recipe) => recipe.id)).size !== catalog.recipes.length || new Set(catalog.tools.map((tool) => tool.id)).size !== catalog.tools.length || recipes.length !== recipeIds.size || tools.length !== toolIds.size)
+    return yield* Effect.fail(new HarnessError({ code: "capability.catalog", message: "Selection references an ambiguous or missing capability" }));
+  if (tools.some((tool) => tool.permissions.some((permission) => !permissions.has(permission))))
+    return yield* Effect.fail(new HarnessError({ code: "capability.forbidden", message: "Selection requires unavailable permissions" }));
+  return { catalogVersion: catalog.version, recipes, tools };
+});

package/dist/harness/capability.entity.js

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+export const CapabilityTool = Schema.Struct({
+  id: Schema.NonEmptyTrimmedString,
+  version: Schema.NonEmptyTrimmedString,
+  description: Schema.NonEmptyTrimmedString,
+  returns: Schema.NonEmptyTrimmedString,
+  permissions: Schema.Array(Schema.String),
+  inputSchema: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+  outputSchema: Schema.Record({ key: Schema.String, value: Schema.Unknown })
+}), CapabilityRecipe = Schema.Struct({
+  id: Schema.NonEmptyTrimmedString,
+  version: Schema.NonEmptyTrimmedString,
+  instructions: Schema.NonEmptyTrimmedString,
+  tools: Schema.Array(Schema.NonEmptyTrimmedString)
+}), CapabilityCatalog = Schema.Struct({
+  version: Schema.NonEmptyTrimmedString,
+  recipes: Schema.Array(CapabilityRecipe),
+  tools: Schema.Array(CapabilityTool)
+}), CapabilitySelection = Schema.Struct({
+  recipes: Schema.Array(Schema.String),
+  tools: Schema.Array(Schema.String)
+}), ResolvedCapabilities = Schema.Struct({
+  catalogVersion: Schema.String,
+  recipes: Schema.Array(CapabilityRecipe),
+  tools: Schema.Array(CapabilityTool)
+});

package/dist/harness/capability.test.d.ts

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

package/dist/harness/config.entity.d.ts

@@ -0,0 +1,48 @@
+import { Schema } from "effect";
+import type { Plugin } from "./plugin.entity.js";
+export declare const PluginEntry: Schema.Struct<{
+    id: typeof Schema.NonEmptyString;
+    use: typeof Schema.NonEmptyString;
+    enabled: Schema.optional<typeof Schema.Boolean>;
+    options: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+}>;
+export type PluginEntry = typeof PluginEntry.Type;
+export declare const Profile: Schema.Struct<{
+    plugins: Schema.optional<Schema.Array$<Schema.Struct<{
+        id: typeof Schema.NonEmptyString;
+        use: typeof Schema.NonEmptyString;
+        enabled: Schema.optional<typeof Schema.Boolean>;
+        options: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    }>>>;
+    bindings: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+    system: Schema.optional<typeof Schema.String>;
+}>;
+export type Profile = typeof Profile.Type;
+export declare const HarnessConfig: Schema.Struct<{
+    version: Schema.Literal<[1]>;
+    profile: Schema.optional<typeof Schema.String>;
+    plugins: Schema.optional<Schema.Array$<Schema.Struct<{
+        id: typeof Schema.NonEmptyString;
+        use: typeof Schema.NonEmptyString;
+        enabled: Schema.optional<typeof Schema.Boolean>;
+        options: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    }>>>;
+    bindings: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+    profiles: Schema.optional<Schema.Record$<typeof Schema.String, Schema.Struct<{
+        plugins: Schema.optional<Schema.Array$<Schema.Struct<{
+            id: typeof Schema.NonEmptyString;
+            use: typeof Schema.NonEmptyString;
+            enabled: Schema.optional<typeof Schema.Boolean>;
+            options: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        }>>>;
+        bindings: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
+        system: Schema.optional<typeof Schema.String>;
+    }>>>;
+    system: Schema.optional<typeof Schema.String>;
+}>;
+export type HarnessConfig = typeof HarnessConfig.Type;
+export interface AgentDefinition {
+    readonly id: string;
+    readonly config: HarnessConfig;
+    readonly plugins: ReadonlyArray<Plugin>;
+}

package/dist/harness/config.entity.functions.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, HarnessConfig } from "./config.entity.js";
+export declare const defineConfig: <A extends HarnessConfig>(config: A) => A;
+export declare const defineAgent: <A extends AgentDefinition>(agent: A) => A;

package/dist/harness/config.entity.functions.js

@@ -0,0 +1 @@
+export const defineConfig = (config) => config, defineAgent = (agent) => agent;

package/dist/harness/config.entity.js

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+export const PluginEntry = Schema.Struct({
+  id: Schema.NonEmptyString,
+  use: Schema.NonEmptyString,
+  enabled: Schema.optional(Schema.Boolean),
+  options: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown }))
+}), Profile = Schema.Struct({
+  plugins: Schema.optional(Schema.Array(PluginEntry)),
+  bindings: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+  system: Schema.optional(Schema.String)
+}), HarnessConfig = Schema.Struct({
+  version: Schema.Literal(1),
+  profile: Schema.optional(Schema.String),
+  plugins: Schema.optional(Schema.Array(PluginEntry)),
+  bindings: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+  profiles: Schema.optional(Schema.Record({ key: Schema.String, value: Profile })),
+  system: Schema.optional(Schema.String)
+});

package/dist/harness/plugin.adapter.d.ts

@@ -0,0 +1,18 @@
+import { Layer, Schema } from "effect";
+import type { Plugin } from "./plugin.entity.js";
+/** Layers retain their native types until the validated dynamic loading edge. */
+export declare const definePlugin: <A extends Readonly<Record<string, unknown>>, I, Out, E, In>(definition: {
+    readonly id: string;
+    readonly version: string;
+    readonly apiVersion?: number;
+    readonly scope?: "runtime" | "session";
+    readonly requires?: ReadonlyArray<{
+        readonly key: string;
+    }>;
+    readonly provides: ReadonlyArray<{
+        readonly key: string;
+    }>;
+    readonly config: Schema.Schema<A, I>;
+    readonly defaults: A;
+    readonly layer: (config: A) => Layer.Layer<Out, E, In>;
+}) => Plugin;

package/dist/harness/plugin.adapter.js

@@ -0,0 +1,13 @@
+import { Context, Effect, Layer, Schema } from "effect";
+import { HarnessError, PLUGIN_API_VERSION } from "./plugin.entity.js";
+export const definePlugin = (definition) => ({
+  id: definition.id,
+  version: definition.version,
+  apiVersion: definition.apiVersion ?? PLUGIN_API_VERSION,
+  scope: definition.scope ?? "session",
+  requires: (definition.requires ?? []).map((tag) => tag.key),
+  provides: definition.provides.map((tag) => tag.key),
+  schema: definition.config,
+  defaults: definition.defaults,
+  build: (options, services) => Schema.decodeUnknown(definition.config)(options, { onExcessProperty: "error" }).pipe(Effect.flatMap((config) => Layer.build(definition.layer(config)).pipe(Effect.provide(Context.unsafeMake(services.unsafeMap)), Effect.map((built) => Context.unsafeMake(built.unsafeMap)))), Effect.mapError((error) => new HarnessError({ code: "plugin.activation", plugin: definition.id, message: String(error) })), Effect.catchAllDefect((error) => Effect.fail(new HarnessError({ code: "plugin.defect", plugin: definition.id, message: String(error) }))))
+});

package/dist/harness/plugin.entity.d.ts

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+import type { Context, Effect, Scope } from "effect";
+export declare const PLUGIN_API_VERSION = 1;
+declare const HarnessError_base: Schema.TaggedErrorClass<HarnessError, "HarnessError", {
+    readonly _tag: Schema.tag<"HarnessError">;
+} & {
+    code: typeof Schema.String;
+    message: typeof Schema.String;
+    plugin: Schema.optional<typeof Schema.String>;
+}>;
+export declare class HarnessError extends HarnessError_base {
+}
+/** The runtime consumes this erased boundary; authors use definePlugin. */
+export interface Plugin {
+    readonly id: string;
+    readonly version: string;
+    readonly apiVersion: number;
+    readonly scope: "runtime" | "session";
+    readonly requires: ReadonlyArray<string>;
+    readonly provides: ReadonlyArray<string>;
+    readonly schema: Schema.Schema.AnyNoContext;
+    readonly defaults: Readonly<Record<string, unknown>>;
+    readonly build: (options: unknown, services: Context.Context<never>) => Effect.Effect<Context.Context<never>, HarnessError, Scope.Scope>;
+}
+export {};

package/dist/harness/plugin.entity.js

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+export const PLUGIN_API_VERSION = 1;
+
+export class HarnessError extends Schema.TaggedError()("HarnessError", {
+  code: Schema.String,
+  message: Schema.String,
+  plugin: Schema.optional(Schema.String)
+}) {
+}

package/dist/harness/session.entity.d.ts

@@ -0,0 +1,33 @@
+import { Schema } from "effect";
+export declare const SessionRecord: Schema.Struct<{
+    id: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    workspace: typeof Schema.String;
+    profile: typeof Schema.String;
+    createdAt: typeof Schema.Number;
+    parent: Schema.optional<Schema.brand<typeof Schema.UUID, "ConversationId">>;
+}>;
+export type SessionRecord = typeof SessionRecord.Type;
+export declare const EventBody: Schema.Struct<{
+    name: typeof Schema.NonEmptyString;
+    runId: Schema.optional<typeof Schema.String>;
+    data: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+}>;
+export type EventBody = typeof EventBody.Type;
+export declare const SessionEvent: Schema.Struct<{
+    version: Schema.Literal<[1]>;
+    id: typeof Schema.String;
+    sessionId: Schema.brand<typeof Schema.UUID, "ConversationId">;
+    seq: typeof Schema.Int;
+    at: typeof Schema.Number;
+    name: typeof Schema.NonEmptyString;
+    runId: Schema.optional<typeof Schema.String>;
+    data: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+}>;
+export type SessionEvent = typeof SessionEvent.Type;
+export declare const MemoryEntry: Schema.Struct<{
+    id: typeof Schema.String;
+    workspace: typeof Schema.String;
+    text: typeof Schema.String;
+    createdAt: typeof Schema.Number;
+}>;
+export type MemoryEntry = typeof MemoryEntry.Type;

package/dist/harness/session.entity.js

@@ -0,0 +1,25 @@
+import { Schema } from "effect";
+import { ConversationId } from "../domain/message.entity.js";
+export const SessionRecord = Schema.Struct({
+  id: ConversationId,
+  workspace: Schema.String,
+  profile: Schema.String,
+  createdAt: Schema.Number,
+  parent: Schema.optional(ConversationId)
+}), EventBody = Schema.Struct({
+  name: Schema.NonEmptyString,
+  runId: Schema.optional(Schema.String),
+  data: Schema.Record({ key: Schema.String, value: Schema.Unknown })
+}), SessionEvent = Schema.Struct({
+  ...EventBody.fields,
+  version: Schema.Literal(1),
+  id: Schema.String,
+  sessionId: ConversationId,
+  seq: Schema.Int,
+  at: Schema.Number
+}), MemoryEntry = Schema.Struct({
+  id: Schema.String,
+  workspace: Schema.String,
+  text: Schema.String,
+  createdAt: Schema.Number
+});

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+export { AgentMessage, AgentResult, AssistantMessage, Checkpoint, ConversationId, ReasoningPart, TextPart, ToolCallId, ToolCallPart, ToolMessage, ToolResultPart, UserMessage, } from "./domain/message.entity.js";
+export { Failure } from "./domain/failure.entity.js";
+export { toFailure } from "./domain/failure.entity.functions.js";
+export { AgentFailure, AgentFailureCategory } from "./domain/agent-failure.entity.js";
+export type { AgentFailure as AgentFailureType, AgentFailureCategory as AgentFailureCategoryType } from "./domain/agent-failure.entity.js";
+export { toAgentFailure, toolResultFailure } from "./domain/agent-failure.entity.functions.js";
+export { TokenUsage } from "./domain/token-usage.entity.js";
+export { addUsage, zeroUsage } from "./domain/token-usage.entity.functions.js";
+export { ModelId, ModelSelection, ProviderId, } from "./domain/model-selection.entity.js";
+export { ModelCallPolicy, ReasoningEffort } from "./domain/model-call-policy.entity.js";
+export type { ReasoningEffort as ReasoningEffortType } from "./domain/model-call-policy.entity.js";
+export { ModelCatalogEntry } from "./domain/model-catalog.entity.js";
+export type { ModelCatalogEntry as ModelCatalogEntryType } from "./domain/model-catalog.entity.js";
+export type { ModelCallPolicy as ModelCallPolicyType } from "./domain/model-call-policy.entity.js";
+export { CurrentEmptyResponseTolerance, CurrentModelCallPolicy } from "./loop/modelPolicy.js";
+export { formatModelSelection, parseModelSelection } from "./domain/model-selection.entity.functions.js";
+export type { LoopEvent, ToolCallSummary } from "./domain/loop-event.entity.js";
+export { ConversationStore, ConversationSummary, RunOutcomeRecord, StoredMessage, StoreError, } from "./ports/conversation-store.port.js";
+export { EngineSettings, SETTINGS_KEYS, SettingsError, SettingsStore, } from "./ports/settings-store.port.js";
+export type { ModelRole, SettingsKey } from "./ports/settings-store.port.js";
+export { AuthError, AuthStore, Credential } from "./ports/auth-store.port.js";
+export { ModelCatalog } from "./ports/model-catalog.port.js";
+export { FileSystem, FsError } from "./ports/file-system.port.js";
+export { Shell, ShellError, ShellResult } from "./ports/shell.port.js";
+export { UtilityCompletion, UtilityError, UtilityLlm } from "./ports/utility-llm.port.js";
+export { asJsonRecord, decodeJsonLines, parseJsonOption, parseJsonWarn } from "./util/json.js";
+export { assistantModel, assistantUsage, extractUsage, extractModel, handoffToMessage, safeKeepFrom, responseReasoning, responseText, responseToAgentMessages, responseToolCalls, responseToolResults, toPromptMessages, withToolCallIds, withUsageOnAssistant, } from "./loop/mapping.js";
+export type { ToolResultSummary } from "./loop/mapping.js";
+export { CurrentPromptCacheKey } from "./loop/cacheKey.js";
+export { foldStreamParts } from "./loop/streamFold.js";
+export type { FoldedTurn, StreamDelta } from "./loop/streamFold.js";
+export { McpCallOutcome, McpClient, McpError, McpToolDescriptor } from "./ports/mcp-client.port.js";
+export { buildMcpBridge, emptyMcpBridge, McpCall, McpDescribe } from "./mcp/bridge.js";
+export type { McpBridge, McpBridgedTool } from "./mcp/bridge.js";
+export { makeSession } from "./session/chassis.js";
+export type { SeqEvent, Session } from "./session/chassis.js";
+export { DEFAULT_SPEC_LIMITS, renderSpecSection, SpecCheck, SpecDoc, SpecGates, SpecLimits, SpecSlug, SpecStatus, } from "./spec/SpecDoc.js";
+export { decodeSpecDocText, encodeSpecDocText, SpecDocParseError, specSlug, uniqueSlug, } from "./spec/codec.js";
+export { parseFrontmatter } from "./spec/frontmatter.js";
+export * from "./harness/plugin.entity.js";
+export * from "./harness/plugin.adapter.js";
+export * from "./harness/config.entity.js";
+export * from "./harness/session.entity.js";
+export * from "./ports/harness.port.js";
+export { defineAgent, defineConfig } from "./harness/config.entity.functions.js";
+export * from "./harness/capability.entity.js";
+export * from "./harness/capability.entity.functions.js";
+export * from "./ports/capability.port.js";
+export * from "./domain/prompt-provenance.entity.js";
+export * from "./loop/promptProvenance.js";
+export { CurrentAgentStep } from "./loop/stepContext.js";

package/dist/index.js

@@ -0,0 +1,99 @@
+export {
+  AgentMessage,
+  AgentResult,
+  AssistantMessage,
+  Checkpoint,
+  ConversationId,
+  ReasoningPart,
+  TextPart,
+  ToolCallId,
+  ToolCallPart,
+  ToolMessage,
+  ToolResultPart,
+  UserMessage
+} from "./domain/message.entity.js";
+export { Failure } from "./domain/failure.entity.js";
+export { toFailure } from "./domain/failure.entity.functions.js";
+export { AgentFailure, AgentFailureCategory } from "./domain/agent-failure.entity.js";
+export { toAgentFailure, toolResultFailure } from "./domain/agent-failure.entity.functions.js";
+export { TokenUsage } from "./domain/token-usage.entity.js";
+export { addUsage, zeroUsage } from "./domain/token-usage.entity.functions.js";
+export {
+  ModelId,
+  ModelSelection,
+  ProviderId
+} from "./domain/model-selection.entity.js";
+export { ModelCallPolicy, ReasoningEffort } from "./domain/model-call-policy.entity.js";
+export { ModelCatalogEntry } from "./domain/model-catalog.entity.js";
+export { CurrentEmptyResponseTolerance, CurrentModelCallPolicy } from "./loop/modelPolicy.js";
+export { formatModelSelection, parseModelSelection } from "./domain/model-selection.entity.functions.js";
+export {
+  ConversationStore,
+  ConversationSummary,
+  RunOutcomeRecord,
+  StoredMessage,
+  StoreError
+} from "./ports/conversation-store.port.js";
+export {
+  EngineSettings,
+  SETTINGS_KEYS,
+  SettingsError,
+  SettingsStore
+} from "./ports/settings-store.port.js";
+export { AuthError, AuthStore, Credential } from "./ports/auth-store.port.js";
+export { ModelCatalog } from "./ports/model-catalog.port.js";
+export { FileSystem, FsError } from "./ports/file-system.port.js";
+export { Shell, ShellError, ShellResult } from "./ports/shell.port.js";
+export { UtilityCompletion, UtilityError, UtilityLlm } from "./ports/utility-llm.port.js";
+export { asJsonRecord, decodeJsonLines, parseJsonOption, parseJsonWarn } from "./util/json.js";
+export {
+  assistantModel,
+  assistantUsage,
+  extractUsage,
+  extractModel,
+  handoffToMessage,
+  safeKeepFrom,
+  responseReasoning,
+  responseText,
+  responseToAgentMessages,
+  responseToolCalls,
+  responseToolResults,
+  toPromptMessages,
+  withToolCallIds,
+  withUsageOnAssistant
+} from "./loop/mapping.js";
+export { CurrentPromptCacheKey } from "./loop/cacheKey.js";
+export { foldStreamParts } from "./loop/streamFold.js";
+export { McpCallOutcome, McpClient, McpError, McpToolDescriptor } from "./ports/mcp-client.port.js";
+export { buildMcpBridge, emptyMcpBridge, McpCall, McpDescribe } from "./mcp/bridge.js";
+export { makeSession } from "./session/chassis.js";
+export {
+  DEFAULT_SPEC_LIMITS,
+  renderSpecSection,
+  SpecCheck,
+  SpecDoc,
+  SpecGates,
+  SpecLimits,
+  SpecSlug,
+  SpecStatus
+} from "./spec/SpecDoc.js";
+export {
+  decodeSpecDocText,
+  encodeSpecDocText,
+  SpecDocParseError,
+  specSlug,
+  uniqueSlug
+} from "./spec/codec.js";
+export { parseFrontmatter } from "./spec/frontmatter.js";
+export * from "./harness/plugin.entity.js";
+export * from "./harness/plugin.adapter.js";
+export * from "./harness/config.entity.js";
+export * from "./harness/session.entity.js";
+export * from "./ports/harness.port.js";
+export { defineAgent, defineConfig } from "./harness/config.entity.functions.js";
+export * from "./harness/capability.entity.js";
+export * from "./harness/capability.entity.functions.js";
+export * from "./ports/capability.port.js";
+export * from "./domain/prompt-provenance.entity.js";
+export * from "./loop/promptProvenance.js";
+export { CurrentAgentStep } from "./loop/stepContext.js";

package/dist/loop/cacheKey.d.ts

@@ -0,0 +1,13 @@
+import { FiberRef, Option } from "effect";
+/**
+ * The CURRENT conversation's cache identity, stamped by `runAgent` for the
+ * duration of a run. Adapters that can key server-side prompt caches on a
+ * stable id (OpenAI-compatible `prompt_cache_key`) read it at call time —
+ * one conversation, one cache lane, so parallel sessions stop evicting
+ * each other's prefixes. `None` (the default) sends nothing.
+ *
+ * A FiberRef, not a port: it's ambient call metadata, not a capability —
+ * and it must flow through the loop's fibers without threading a parameter
+ * through every seam.
+ */
+export declare const CurrentPromptCacheKey: FiberRef.FiberRef<Option.Option<string>>;

package/dist/loop/cacheKey.js

@@ -0,0 +1,2 @@
+import { FiberRef, GlobalValue, Option } from "effect";
+export const CurrentPromptCacheKey = GlobalValue.globalValue("@xandreed/core/CurrentPromptCacheKey", () => FiberRef.unsafeMake(Option.none()));

package/dist/loop/mapping.d.ts

@@ -0,0 +1,79 @@
+import { Option } from "effect";
+import type { ToolCallSummary } from "../domain/loop-event.entity.js";
+import type { AgentMessage } from "../domain/message.entity.js";
+import type { TokenUsage } from "../domain/token-usage.entity.js";
+/**
+ * Bridges the persisted `AgentMessage` with `@effect/ai`'s `Prompt`/`Response`
+ * encodings. The opaque provider blob is carried verbatim both ways —
+ * `AgentMessage.providerOptions ↔ prompt part options ↔ response part
+ * metadata` — which is how Gemini's `thought_signature` round-trips across
+ * turns (the framework's own `fromResponseParts` drops it, so the engine maps
+ * by hand and keeps the blob). Everything here is pure: no mutation, no IO.
+ */
+/** Wrap a fold summary as the single user message standing in for the folded
+ *  history — prepended by `runAgent` when the conversation has a checkpoint. */
+export declare const handoffToMessage: (summary: string) => AgentMessage;
+/**
+ * The largest SAFE fold cut keeping at least `keepTurns` assistant turns
+ * verbatim: the cut always lands ON an assistant message (a tool message
+ * follows its assistant, so a tool-call is never split from its results),
+ * and never at index 0 (something must fold). `None` when the buffer is too
+ * small to fold at all.
+ */
+export declare const safeKeepFrom: (messages: ReadonlyArray<AgentMessage>, keepTurns: number) => Option.Option<number>;
+/** `AgentMessage[]` → `@effect/ai` encoded prompt messages (spreadable). */
+export declare const toPromptMessages: (messages: ReadonlyArray<AgentMessage>) => ReadonlyArray<unknown>;
+/**
+ * Some providers (notably Gemini) return tool calls WITHOUT an id. An absent
+ * id breaks durable UI identity (a live event and a later re-projection of
+ * the same persisted message must compute the same key), so a deterministic
+ * id — `<turnIndex>:<toolName>:<ordinalInTurn>` — is minted ONCE here, before
+ * the content fans out into events and persisted messages. The Nth id-less
+ * call and the Nth id-less result pair on the same ordinal, so the
+ * call ↔ result pairing stays valid. A non-empty provider id is left as-is.
+ *
+ * Pure: returns new part objects; the input is never mutated.
+ */
+export declare const withToolCallIds: (content: ReadonlyArray<unknown>, turnIndex: number) => ReadonlyArray<unknown>;
+/**
+ * One turn's response content → the `AgentMessage` tail: an assistant message
+ * holding text/reasoning/tool-call parts, then a tool message holding the
+ * resolved tool-result parts. Provider metadata (incl. `thought_signature`)
+ * is preserved into `providerOptions`.
+ */
+export declare const responseToAgentMessages: (content: ReadonlyArray<unknown>) => ReadonlyArray<AgentMessage>;
+/** Joined text of the assistant text parts in one turn's response. */
+export declare const responseText: (content: ReadonlyArray<unknown>) => string;
+/** Joined text of the reasoning parts (when the provider surfaces them). */
+export declare const responseReasoning: (content: ReadonlyArray<unknown>) => string;
+/** Tool-call summaries; `id` is the key that pairs a call with its result. */
+export declare const responseToolCalls: (content: ReadonlyArray<unknown>) => ReadonlyArray<ToolCallSummary>;
+export interface ToolResultSummary {
+    readonly id: string;
+    readonly toolName: string;
+    readonly ok: boolean;
+    readonly result: unknown;
+}
+/** Tool-result summaries; `id` matches the originating call's id. */
+export declare const responseToolResults: (content: ReadonlyArray<unknown>) => ReadonlyArray<ToolResultSummary>;
+/**
+ * Token usage from a response's `usage` + the finish part's metadata. The
+ * Anthropic fold matters: its `input_tokens` EXCLUDES cache reads/writes
+ * (both ride only in the raw usage on the finish part's anthropic metadata),
+ * so without folding them back a fully-cached turn reads ~0 input.
+ * Gemini/OpenAI already include cached tokens in their prompt counts.
+ */
+export declare const extractUsage: (usage: unknown, content: ReadonlyArray<unknown>) => TokenUsage;
+/**
+ * Embed the turn usage into the first assistant message's `providerOptions`
+ * so it persists with the conversation and can be recovered on resume. Pure —
+ * returns a new array with the first assistant message re-built.
+ * {@link toPromptMessages} strips this stamp before anything goes back out.
+ */
+export declare const withUsageOnAssistant: (messages: ReadonlyArray<AgentMessage>, usage: TokenUsage, model?: Option.Option<string>) => ReadonlyArray<AgentMessage>;
+/** The resolved `provider:modelId` the router stamped onto the finish part. */
+export declare const extractModel: (content: ReadonlyArray<unknown>) => Option.Option<string>;
+/** The turn usage embedded on a persisted assistant message, if any. */
+export declare const assistantUsage: (msg: AgentMessage) => Option.Option<TokenUsage>;
+/** The `provider:modelId` embedded alongside the usage stamp, if any. */
+export declare const assistantModel: (msg: AgentMessage) => Option.Option<string>;