@xandreed/core 0.3.0

package/dist/loop/mapping.js

@@ -0,0 +1,154 @@
+import { Option } from "effect";
+import { ToolCallId } from "../domain/message.entity.js";
+export const handoffToMessage = (summary) => ({
+  role: "user",
+  content: `[System note: the earlier history of this conversation has been handed off into the summary below to free up context. Treat the summary as the source of truth for everything before this point.]
+
+` + summary
+}), safeKeepFrom = (messages, keepTurns) => {
+  const assistantIndexes = messages.flatMap((message, index) => message.role === "assistant" ? [index] : []);
+  if (assistantIndexes.length <= keepTurns)
+    return Option.none();
+  const cut = assistantIndexes[assistantIndexes.length - keepTurns];
+  return cut === void 0 || cut <= 0 ? Option.none() : Option.some(cut);
+};
+const hasKeys = (o) => typeof o === "object" && o !== null && Object.keys(o).length > 0, withOptions = (blob) => hasKeys(blob) ? { options: blob } : {}, withProviderOptions = (blob) => hasKeys(blob) ? { providerOptions: blob } : {}, USAGE_KEY = "engine", withoutEngineStamp = (blob) => {
+  if (!hasKeys(blob))
+    return blob;
+  const { [USAGE_KEY]: _engine, ...rest } = blob;
+  return rest;
+};
+export const toPromptMessages = (messages) => messages.map((m) => {
+  if (m.role === "user")
+    return { role: "user", content: m.content };
+  if (m.role === "assistant")
+    return {
+      role: "assistant",
+      content: m.content.map((p) => {
+        if (p.type === "text")
+          return { type: "text", text: p.text, ...withOptions(p.providerOptions) };
+        if (p.type === "reasoning")
+          return { type: "reasoning", text: p.text, ...withOptions(p.providerOptions) };
+        return {
+          type: "tool-call",
+          id: p.toolCallId,
+          name: p.toolName,
+          params: p.input ?? {},
+          providerExecuted: p.providerExecuted ?? !1,
+          ...withOptions(p.providerOptions)
+        };
+      }),
+      ...withOptions(withoutEngineStamp(m.providerOptions))
+    };
+  return {
+    role: "tool",
+    content: m.content.map((p) => ({
+      type: "tool-result",
+      id: p.toolCallId,
+      name: p.toolName,
+      result: p.output,
+      isFailure: p.isError ?? !1,
+      providerExecuted: !1,
+      ...withOptions(p.providerOptions)
+    }))
+  };
+}), withToolCallIds = (content, turnIndex) => content.reduce((acc, part) => {
+  const p = part, bare = p.id === void 0 || p.id === "";
+  if (p.type === "tool-call")
+    return {
+      calls: acc.calls + 1,
+      results: acc.results,
+      out: [
+        ...acc.out,
+        bare ? { ...p, id: `${turnIndex}:${p.name ?? ""}:${acc.calls}` } : part
+      ]
+    };
+  if (p.type === "tool-result")
+    return {
+      calls: acc.calls,
+      results: acc.results + 1,
+      out: [
+        ...acc.out,
+        bare ? { ...p, id: `${turnIndex}:${p.name ?? ""}:${acc.results}` } : part
+      ]
+    };
+  return { ...acc, out: [...acc.out, part] };
+}, { calls: 0, results: 0, out: [] }).out, responseToAgentMessages = (content) => {
+  const parts = content, assistantParts = parts.flatMap((p) => {
+    if (p.type === "text")
+      return [{ type: "text", text: p.text ?? "", ...withProviderOptions(p.metadata) }];
+    if (p.type === "reasoning")
+      return [
+        { type: "reasoning", text: p.text ?? "", ...withProviderOptions(p.metadata) }
+      ];
+    if (p.type === "tool-call")
+      return [
+        {
+          type: "tool-call",
+          toolCallId: ToolCallId.make(p.id ?? ""),
+          toolName: p.name ?? "",
+          input: p.params ?? {},
+          providerExecuted: p.providerExecuted ?? !1,
+          ...withProviderOptions(p.metadata)
+        }
+      ];
+    return [];
+  }), toolParts = parts.flatMap((p) => p.type === "tool-result" ? [
+    {
+      type: "tool-result",
+      toolCallId: ToolCallId.make(p.id ?? ""),
+      toolName: p.name ?? "",
+      output: p.result,
+      isError: p.isFailure ?? !1,
+      ...withProviderOptions(p.metadata)
+    }
+  ] : []);
+  return [
+    ...assistantParts.length > 0 ? [{ role: "assistant", content: assistantParts }] : [],
+    ...toolParts.length > 0 ? [{ role: "tool", content: toolParts }] : []
+  ];
+}, responseText = (content) => content.filter((p) => p.type === "text").map((p) => p.text ?? "").join(""), responseReasoning = (content) => content.filter((p) => p.type === "reasoning").map((p) => p.text ?? "").join("").trim(), responseToolCalls = (content) => content.filter((p) => p.type === "tool-call").map((p) => ({ id: p.id ?? "", toolName: p.name ?? "", args: p.params ?? {} })), responseToolResults = (content) => content.filter((p) => p.type === "tool-result").map((p) => ({
+  id: p.id ?? "",
+  toolName: p.name ?? "",
+  ok: !(p.isFailure ?? !1),
+  result: p.result
+})), extractUsage = (usage, content) => {
+  const u = usage ?? {}, finishes = content.filter((p) => p.type === "finish"), finish = finishes.find((p) => {
+    const fu = p.usage;
+    return fu?.inputTokens !== void 0 || fu?.outputTokens !== void 0;
+  }) ?? finishes[0], gm = finish?.metadata?.google?.usageMetadata, fu = finish?.usage, inputTokens = u.inputTokens ?? fu?.inputTokens ?? gm?.promptTokenCount ?? 0, outputTokens = u.outputTokens ?? fu?.outputTokens ?? gm?.candidatesTokenCount ?? 0, totalTokens = u.totalTokens ?? fu?.totalTokens ?? gm?.totalTokenCount ?? 0, cacheReadTokens = u.cachedInputTokens ?? fu?.cachedInputTokens ?? gm?.cachedContentTokenCount ?? 0, au = finish?.metadata?.anthropic?.usage;
+  if (au !== void 0 && au !== null && typeof au === "object") {
+    const cacheRead = au.cache_read_input_tokens ?? 0, cacheWrite = au.cache_creation_input_tokens ?? 0, fullInput = inputTokens + cacheRead + cacheWrite;
+    return {
+      inputTokens: fullInput,
+      outputTokens,
+      totalTokens: fullInput + outputTokens,
+      cacheReadTokens: cacheRead
+    };
+  }
+  return { inputTokens, outputTokens, totalTokens, cacheReadTokens };
+}, withUsageOnAssistant = (messages, usage, model = Option.none()) => {
+  const at = messages.findIndex((m) => m.role === "assistant"), stamp = {
+    ...usage,
+    ...Option.match(model, { onNone: () => ({}), onSome: (id) => ({ model: id }) })
+  };
+  return messages.map((m, i) => {
+    if (i !== at || m.role !== "assistant")
+      return m;
+    const prev = hasKeys(m.providerOptions) ? m.providerOptions : {};
+    return { ...m, providerOptions: { ...prev, [USAGE_KEY]: stamp } };
+  });
+}, extractModel = (content) => {
+  const model = content.find((p) => p.type === "finish")?.metadata?.router?.model;
+  return typeof model === "string" && model.length > 0 ? Option.some(model) : Option.none();
+}, assistantUsage = (msg) => {
+  if (msg.role !== "assistant")
+    return Option.none();
+  const usage = msg.providerOptions?.[USAGE_KEY];
+  return hasKeys(usage) ? Option.some(usage) : Option.none();
+}, assistantModel = (msg) => {
+  if (msg.role !== "assistant")
+    return Option.none();
+  const model = msg.providerOptions?.[USAGE_KEY]?.model;
+  return typeof model === "string" && model.length > 0 ? Option.some(model) : Option.none();
+};

package/dist/loop/mapping.test.d.ts

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

package/dist/loop/modelPolicy.d.ts

@@ -0,0 +1,21 @@
+import { FiberRef, Option } from "effect";
+export declare const CurrentModelCallPolicy: FiberRef.FiberRef<Option.Option<{
+    readonly effort: "none" | "low" | "medium" | "high" | "xhigh" | "max";
+    readonly maxOutputTokens?: number | undefined;
+}>>;
+/**
+ * Whether the CURRENT model call may legitimately return an empty response.
+ *
+ * An HTTP-200-but-empty body on a run's FIRST call is a provider-outage
+ * signature and must stay hard-rejected (it would fake-complete the turn).
+ * But once the run has executed a tool call, a following empty response is
+ * how models say "I'm done" — rejecting it sends the call into the patient
+ * outage ladder, which parks the turn until a deadline kills it (observed
+ * live: math turns riding 120s budgets, ui composers riding 55s soft
+ * deadlines, for work that finished in seconds).
+ *
+ * The LOOP sets this once the run has tool calls; adapters' empty-response
+ * rejection consults it at call time. A FiberRef, not a port: ambient call
+ * metadata, exactly like {@link CurrentModelCallPolicy}.
+ */
+export declare const CurrentEmptyResponseTolerance: FiberRef.FiberRef<boolean>;

package/dist/loop/modelPolicy.js

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

package/dist/loop/promptProvenance.d.ts

@@ -0,0 +1,8 @@
+import { FiberRef, Option } from "effect";
+export declare const CurrentPromptProvenance: FiberRef.FiberRef<Option.Option<{
+    readonly id: string & import("effect/Brand").Brand<"PromptId">;
+    readonly version: string;
+    readonly variant: string;
+    readonly modelOverride: Option.Option<string>;
+    readonly hash: string;
+}>>;

package/dist/loop/promptProvenance.js

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

package/dist/loop/stepContext.d.ts

@@ -0,0 +1,3 @@
+import { FiberRef, Option } from "effect";
+/** Correlation only; unset for work outside the agent loop. */
+export declare const CurrentAgentStep: FiberRef.FiberRef<Option.Option<number>>;

package/dist/loop/stepContext.js

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

package/dist/loop/streamFold.d.ts

@@ -0,0 +1,31 @@
+import { Effect, Stream } from "effect";
+/**
+ * Folds a `streamText` part stream into the SETTLED turn shape `step()`
+ * reads — after this fold the loop's turn body is identical code on both
+ * paths, so replay ≡ live for final events by construction.
+ *
+ * - Streamed text/reasoning chunks occupy ORDERED SLOTS at the position
+ *   their start/first-delta arrived; deltas append in place (and fan out
+ *   through `onDelta` for live rendering); a chunk that accumulated nothing
+ *   is dropped (content-part identity).
+ * - Every settled part (tool-call, tool-result, finish, provider extras)
+ *   passes through at its arrival position unchanged — metadata included,
+ *   so the router's model stamp and the usage fold read exactly what the
+ *   non-streaming path reads.
+ * - `finishReason`/`usage` lift off the finish part (the last one carrying
+ *   usage wins, matching `extractUsage`'s scan).
+ */
+export interface StreamDelta {
+    readonly channel: "text" | "reasoning" | "tool-params";
+    readonly id: string;
+    readonly delta: string;
+    /** The tool being called — set on `tool-params` deltas only. */
+    readonly toolName?: string;
+}
+/** Structurally what the loop reads off a `GenerateTextResponse`. */
+export interface FoldedTurn {
+    readonly content: ReadonlyArray<unknown>;
+    readonly finishReason: string;
+    readonly usage: unknown;
+}
+export declare const foldStreamParts: <E, R, R2 = never>(parts: Stream.Stream<unknown, E, R>, onDelta: (delta: StreamDelta) => Effect.Effect<void, never, R2>) => Effect.Effect<FoldedTurn, E, R | R2>;

package/dist/loop/streamFold.js

@@ -0,0 +1,58 @@
+import { Effect, Option, Stream } from "effect";
+const CHANNEL_BY_TYPE = {
+  "text-start": "text",
+  "text-delta": "text",
+  "text-end": "text",
+  "reasoning-start": "reasoning",
+  "reasoning-delta": "reasoning",
+  "reasoning-end": "reasoning"
+}, openChunk = (entries, channel, id) => entries.some((e) => e.kind === "chunk" && e.channel === channel && e.id === id) ? entries : [...entries, { kind: "chunk", channel, id, text: "" }], appendDelta = (entries, channel, id, delta) => openChunk(entries, channel, id).map((e) => e.kind === "chunk" && e.channel === channel && e.id === id ? { ...e, text: e.text + delta } : e), entryParts = (entry) => {
+  if (entry.kind === "part")
+    return [entry.part];
+  return entry.text.length > 0 ? [{ type: entry.channel, text: entry.text }] : [];
+};
+export const foldStreamParts = (parts, onDelta) => Stream.runFoldEffect(parts, {
+  entries: [],
+  finishReason: Option.none(),
+  usage: Option.none()
+}, (state, part) => {
+  const p = part, type = p.type ?? "";
+  if (type === "tool-params-start" || type === "tool-params-delta") {
+    const id = p.id ?? "tool-params-1";
+    return onDelta({
+      channel: "tool-params",
+      id,
+      delta: type === "tool-params-delta" ? p.delta ?? "" : "",
+      ...type === "tool-params-start" && p.name !== void 0 ? { toolName: p.name } : {}
+    }).pipe(Effect.as({
+      ...state,
+      entries: [...state.entries, { kind: "part", part }]
+    }));
+  }
+  const channel = CHANNEL_BY_TYPE[type];
+  if (channel !== void 0) {
+    const id = p.id ?? `${channel}-1`;
+    if (type.endsWith("-start"))
+      return Effect.succeed({ ...state, entries: openChunk(state.entries, channel, id) });
+    if (type.endsWith("-end"))
+      return Effect.succeed(state);
+    const delta = p.delta ?? "", next = { ...state, entries: appendDelta(state.entries, channel, id, delta) };
+    return delta.length > 0 ? onDelta({ channel, id, delta }).pipe(Effect.as(next)) : Effect.succeed(next);
+  }
+  if (type === "finish") {
+    const usage = p.usage, carriesUsage = usage?.inputTokens !== void 0 || usage?.outputTokens !== void 0;
+    return Effect.succeed({
+      entries: [...state.entries, { kind: "part", part }],
+      finishReason: Option.orElse(state.finishReason, () => Option.some(p.reason ?? "unknown")),
+      usage: carriesUsage || Option.isNone(state.usage) ? Option.some(p.usage) : state.usage
+    });
+  }
+  return Effect.succeed({
+    ...state,
+    entries: [...state.entries, { kind: "part", part }]
+  });
+}).pipe(Effect.map((state) => ({
+  content: state.entries.flatMap(entryParts),
+  finishReason: Option.getOrElse(state.finishReason, () => "unknown"),
+  usage: Option.getOrUndefined(state.usage)
+})));

package/dist/loop/streamFold.test.d.ts

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

package/dist/mcp/bridge.d.ts

@@ -0,0 +1,51 @@
+import { Tool, Toolkit } from "@effect/ai";
+import { Context, Effect, Schema } from "effect";
+import { McpClient } from "../ports/mcp-client.port.js";
+import type { McpToolDescriptor } from "../ports/mcp-client.port.js";
+export declare const McpDescribe: Tool.Tool<"mcp_describe", {
+    readonly parameters: Schema.Struct<{
+        server: Schema.SchemaClass<string, string, never>;
+        tool: Schema.SchemaClass<string, string, never>;
+    }>;
+    readonly success: Schema.Struct<{
+        server: typeof Schema.String;
+        tool: typeof Schema.String;
+        description: typeof Schema.String;
+        inputSchema: typeof Schema.Unknown;
+    }>;
+    readonly failure: Schema.Struct<{
+        error: typeof Schema.String;
+        message: typeof Schema.String;
+    }>;
+    readonly failureMode: "return";
+}, never>;
+export declare const McpCall: Tool.Tool<"mcp_call", {
+    readonly parameters: Schema.Struct<{
+        server: Schema.SchemaClass<string, string, never>;
+        tool: Schema.SchemaClass<string, string, never>;
+        args: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+    }>;
+    readonly success: typeof Schema.Unknown;
+    readonly failure: Schema.Struct<{
+        error: typeof Schema.String;
+        message: typeof Schema.String;
+    }>;
+    readonly failureMode: "return";
+}, never>;
+/** The bridge's toolkit is the fixed describe/call pair, but typed loosely
+ *  (`Tool.Any`) so the populated toolkit and the empty one share one shape. */
+export type McpBridgedTool = Tool.Any;
+export interface McpBridge {
+    readonly toolkit: Toolkit.Toolkit<Record<string, McpBridgedTool>>;
+    /** The two tools' handlers, closed over the client + descriptor snapshot. */
+    readonly handlers: Context.Context<Tool.Handler<string>>;
+    /** Every configured tool, for the tier-1 prompt listing (names only). */
+    readonly descriptors: ReadonlyArray<McpToolDescriptor>;
+}
+export declare const emptyMcpBridge: McpBridge;
+/**
+ * Snapshot the configured servers' tools into the fixed describe/call toolkit
+ * (taken once per run — no `tools/list_changed` handling in v1). No servers,
+ * or no tools across them, yields the empty bridge (no tool cost at all).
+ */
+export declare const buildMcpBridge: Effect.Effect<McpBridge, never, McpClient>;

package/dist/mcp/bridge.js

@@ -0,0 +1,70 @@
+import { Tool, Toolkit } from "@effect/ai";
+import { Context, Effect, Option, Schema } from "effect";
+import { Failure } from "../domain/failure.entity.js";
+import { McpClient } from "../ports/mcp-client.port.js";
+const OUTPUT_CAP_CHARS = 16000, McpArgs = Schema.Record({ key: Schema.String, value: Schema.Unknown }), clipResult = (value) => {
+  const text = typeof value === "string" ? value : JSON.stringify(value) ?? "";
+  return text.length <= OUTPUT_CAP_CHARS ? value : `${text.slice(0, OUTPUT_CAP_CHARS)}
+[\u2026clipped ${text.length - OUTPUT_CAP_CHARS} chars\u2026]`;
+};
+export const McpDescribe = Tool.make("mcp_describe", {
+  description: "Reveal ONE external MCP tool's parameters. Pass the server + tool exactly as listed under 'External MCP tools'. Returns {server, tool, description, inputSchema} \u2014 the JSON Schema of the arguments mcp_call expects. Call this BEFORE mcp_call the first time you use a tool.",
+  parameters: {
+    server: Schema.String.annotations({ description: "The server name, as listed." }),
+    tool: Schema.String.annotations({ description: "The tool name, as listed." })
+  },
+  success: Schema.Struct({
+    server: Schema.String,
+    tool: Schema.String,
+    description: Schema.String,
+    inputSchema: Schema.Unknown
+  }),
+  failure: Failure,
+  failureMode: "return"
+}), McpCall = Tool.make("mcp_call", {
+  description: "Invoke an external MCP tool. Pass server + tool (as listed) and args as a JSON object matching the schema mcp_describe returned. A tool-level failure comes back as data (read it and adapt), not a dead turn. Returns the tool's result (clipped past 16k chars).",
+  parameters: {
+    server: Schema.String.annotations({ description: "The server name, as listed." }),
+    tool: Schema.String.annotations({ description: "The tool name, as listed." }),
+    args: McpArgs.annotations({
+      description: "The tool's arguments as a JSON object (see mcp_describe); {} if it takes none."
+    })
+  },
+  success: Schema.Unknown,
+  failure: Failure,
+  failureMode: "return"
+}), emptyMcpBridge = {
+  toolkit: Toolkit.make(),
+  handlers: Context.empty(),
+  descriptors: []
+}, buildMcpBridge = Effect.gen(function* () {
+  const client = yield* McpClient, descriptors = yield* client.listTools;
+  if (descriptors.length === 0)
+    return emptyMcpBridge;
+  const find = (server, tool) => Option.fromNullable(descriptors.find((d) => d.server === server && d.name === tool)), tools = [McpDescribe, McpCall], toolkit = Toolkit.make(...tools), handlerRecord = {
+    mcp_describe: (params) => Option.match(find(params.server, params.tool), {
+      onNone: () => Effect.fail({
+        error: "UnknownMcpTool",
+        message: `no MCP tool "${params.tool}" on server "${params.server}" \u2014 use one listed under 'External MCP tools'`
+      }),
+      onSome: (descriptor) => Effect.succeed({
+        server: descriptor.server,
+        tool: descriptor.name,
+        description: Option.getOrElse(descriptor.description, () => ""),
+        inputSchema: descriptor.inputSchema
+      })
+    }),
+    mcp_call: (params) => Option.isNone(find(params.server, params.tool)) ? Effect.fail({
+      error: "UnknownMcpTool",
+      message: `no MCP tool "${params.tool}" on server "${params.server}" \u2014 use one listed under 'External MCP tools'`
+    }) : client.callTool(params.server, params.tool, params.args).pipe(Effect.flatMap((outcome) => outcome.isError ? Effect.fail({
+      error: "McpToolError",
+      message: typeof outcome.result === "string" ? outcome.result.slice(0, 2000) : JSON.stringify(outcome.result).slice(0, 2000)
+    }) : Effect.succeed(clipResult(outcome.result))), Effect.catchTag("McpError", (error) => Effect.fail({ error: "McpTransportError", message: error.message })))
+  }, handlers = yield* toolkit.toContext(handlerRecord);
+  return {
+    toolkit,
+    handlers,
+    descriptors
+  };
+}).pipe(Effect.catchAllCause((cause) => Effect.logWarning(`MCP bridge unavailable \u2014 continuing without MCP tools: ${cause}`).pipe(Effect.as(emptyMcpBridge))));

package/dist/mcp/bridge.test.d.ts

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

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

@@ -0,0 +1,50 @@
+import { Context, Option, Schema } from "effect";
+import type { Effect, Redacted } from "effect";
+import type { ProviderId } from "../domain/model-selection.entity.js";
+/**
+ * A stored provider credential: a raw API key, an OAuth subscription (with
+ * refresh material and absolute expiry, epoch ms), or a local provider that
+ * needs no key. Matches the on-disk `auth.json` vocabulary the previous line
+ * established, so existing credentials keep working.
+ */
+export declare const Credential: Schema.Union<[Schema.Struct<{
+    type: Schema.Literal<["api_key"]>;
+    key: typeof Schema.String;
+}>, Schema.Struct<{
+    type: Schema.Literal<["oauth"]>;
+    access: typeof Schema.String;
+    refresh: typeof Schema.String;
+    expires: typeof Schema.Number;
+    accountId: Schema.optional<typeof Schema.String>;
+    installationId: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    type: Schema.Literal<["local"]>;
+    baseUrl: Schema.optional<typeof Schema.String>;
+}>]>;
+export type Credential = typeof Credential.Type;
+declare const AuthError_base: Schema.TaggedErrorClass<AuthError, "AuthError", {
+    readonly _tag: Schema.tag<"AuthError">;
+} & {
+    provider: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+export declare class AuthError extends AuthError_base {
+}
+declare const AuthStore_base: Context.TagClass<AuthStore, "@xandreed/core/AuthStore", {
+    readonly all: Effect.Effect<ReadonlyMap<string, Credential>, AuthError>;
+    readonly get: (p: ProviderId) => Effect.Effect<Option.Option<Credential>, AuthError>;
+    readonly resolveKey: (p: ProviderId) => Effect.Effect<Option.Option<Redacted.Redacted<string>>, AuthError>;
+    /** Persist a credential (the human's `:login` action). */
+    readonly set: (p: ProviderId, credential: Credential) => Effect.Effect<void, AuthError>;
+    /** Remove a provider's credential everywhere it is stored (`:logout`). */
+    readonly remove: (p: ProviderId) => Effect.Effect<void, AuthError>;
+}>;
+/**
+ * The credential store, read lazily per request: `resolveKey` returns a
+ * usable secret (refreshing + persisting a near-expiry OAuth token first),
+ * so a credential added mid-session takes effect on the next call with no
+ * restart. `None` means the provider is not configured.
+ */
+export declare class AuthStore extends AuthStore_base {
+}
+export {};

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

@@ -0,0 +1,18 @@
+import { Context, Option, Schema } from "effect";
+export const Credential = Schema.Union(Schema.Struct({ type: Schema.Literal("api_key"), key: Schema.String }), Schema.Struct({
+  type: Schema.Literal("oauth"),
+  access: Schema.String,
+  refresh: Schema.String,
+  expires: Schema.Number,
+  accountId: Schema.optional(Schema.String),
+  installationId: Schema.optional(Schema.String)
+}), Schema.Struct({ type: Schema.Literal("local"), baseUrl: Schema.optional(Schema.String) }));
+
+export class AuthError extends Schema.TaggedError()("AuthError", {
+  provider: Schema.String,
+  message: Schema.String
+}) {
+}
+
+export class AuthStore extends Context.Tag("@xandreed/core/AuthStore")() {
+}

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

@@ -0,0 +1,15 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+import type { CapabilityCatalog, CapabilitySelection } from "../harness/capability.entity.js";
+import type { HarnessError } from "../harness/plugin.entity.js";
+declare const Capabilities_base: Context.TagClass<Capabilities, "efferent/Capabilities", {
+    readonly catalog: CapabilityCatalog;
+}>;
+export declare class Capabilities extends Capabilities_base {
+}
+declare const IntentMatcher_base: Context.TagClass<IntentMatcher, "efferent/IntentMatcher", {
+    readonly match: (message: string, catalog: CapabilityCatalog) => Effect.Effect<CapabilitySelection, HarnessError>;
+}>;
+export declare class IntentMatcher extends IntentMatcher_base {
+}
+export {};

package/dist/ports/capability.port.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+export class Capabilities extends Context.Tag("efferent/Capabilities")() {
+}
+
+export class IntentMatcher extends Context.Tag("efferent/IntentMatcher")() {
+}