@xandreed/core 0.4.0 → 0.8.0-next.0

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

@@ -1,10 +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;
+    readonly selection: 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"]>;
+    readonly label: Schema.optional<Schema.String>;
+    readonly provider: Schema.String;
+    readonly credential: Schema.Literals<readonly ["api_key", "oauth", "local"]>;
 }>;
 export type ModelCatalogEntry = typeof ModelCatalogEntry.Type;

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

@@ -3,5 +3,5 @@ export const ModelCatalogEntry = Schema.Struct({
   selection: Schema.String,
   label: Schema.optional(Schema.String),
   provider: Schema.String,
-  credential: Schema.Literal("api_key", "oauth", "local")
+  credential: Schema.Literals(["api_key", "oauth", "local"])
 });

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

@@ -4,21 +4,14 @@ import { Schema } from "effect";
  * 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 declare const ProviderId: Schema.brand<Schema.String, "ProviderId">;
 export type ProviderId = typeof ProviderId.Type;
-export declare const ModelId: Schema.brand<typeof Schema.String, "ModelId">;
+export declare const ModelId: Schema.brand<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">;
-}, {}, {}>;
+declare const ModelSelection_base: Schema.Class<ModelSelection, Schema.Struct<{
+    readonly provider: Schema.brand<Schema.String, "ProviderId">;
+    readonly modelId: Schema.brand<Schema.String, "ModelId">;
+}>, {}>;
 export declare class ModelSelection extends ModelSelection_base {
 }
 export {};

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

@@ -1,11 +1,11 @@
 import { Schema } from "effect";
-export declare const PromptId: Schema.brand<typeof Schema.NonEmptyTrimmedString, "PromptId">;
+export declare const PromptId: Schema.brand<Schema.Trimmed, "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;
+    readonly id: Schema.brand<Schema.Trimmed, "PromptId">;
+    readonly version: Schema.Trimmed;
+    readonly variant: Schema.Trimmed;
+    readonly modelOverride: Schema.OptionFromNullOr<Schema.String>;
+    readonly hash: Schema.Trimmed;
 }>;
 export type PromptProvenance = typeof PromptProvenance.Type;

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

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

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

@@ -1,9 +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;
+    readonly inputTokens: Schema.Number;
+    readonly outputTokens: Schema.Number;
+    readonly totalTokens: Schema.Number;
+    readonly cacheReadTokens: Schema.Number;
 }>;
 export type TokenUsage = typeof TokenUsage.Type;

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

@@ -1,61 +1,108 @@
 import { Schema } from "effect";
+/**
+ * What a host contributes to generic capability plugins. Tools, skills and
+ * prompt sections are DEFINED by the host; registration, discovery, the
+ * active set and prompt assembly belong to the plugins that consume them.
+ */
+export declare const ToolAnnotations: Schema.Struct<{
+    /** Read-only tools share a concurrency lane; others run exclusively. */
+    readonly readOnly: Schema.Boolean;
+    /** Repeat calls with unchanged results are expected (never "degenerate"). */
+    readonly pollable: Schema.Boolean;
+    /** The result survives every compaction verbatim. */
+    readonly pinned: Schema.Boolean;
+    /** Grants the run must hold for the tool to be callable. */
+    readonly permissions: Schema.$Array<Schema.String>;
+    readonly maxCallsPerRun: Schema.OptionFromNullOr<Schema.Int>;
+    /** Host display metadata, carried on invocation events. */
+    readonly labels: Schema.$Record<Schema.String, Schema.String>;
+    readonly stage: Schema.OptionFromNullOr<Schema.String>;
+}>;
+export type ToolAnnotations = typeof ToolAnnotations.Type;
+/** Tier 3: reference material a loaded skill may read on demand. */
+export declare const SkillReference: Schema.Struct<{
+    readonly id: Schema.Trimmed;
+    readonly title: Schema.Trimmed;
+    readonly text: Schema.String;
+}>;
+export type SkillReference = typeof SkillReference.Type;
+export declare const SkillDefinition: Schema.Struct<{
+    readonly id: Schema.Trimmed;
+    readonly version: Schema.Trimmed;
+    /** Tier 1: one line in the catalogue, always in context. */
+    readonly summary: Schema.Trimmed;
+    /** Tier 2: returned by load_skill together with the skill's tools. */
+    readonly instructions: Schema.String;
+    readonly tools: Schema.$Array<Schema.Trimmed>;
+    /** Active from the first step of every turn. */
+    readonly always: Schema.Boolean;
+    readonly permissions: Schema.$Array<Schema.String>;
+    readonly references: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly title: Schema.Trimmed;
+        readonly text: Schema.String;
+    }>>;
+}>;
+export type SkillDefinition = typeof SkillDefinition.Type;
+export declare const PromptTier: Schema.Literals<readonly ["static", "session", "turn"]>;
+export type PromptTier = typeof PromptTier.Type;
 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>;
+    readonly id: Schema.Trimmed;
+    readonly version: Schema.Trimmed;
+    readonly description: Schema.Trimmed;
+    readonly returns: Schema.Trimmed;
+    readonly permissions: Schema.$Array<Schema.String>;
+    readonly inputSchema: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly outputSchema: Schema.$Record<Schema.String, 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>;
+    readonly id: Schema.Trimmed;
+    readonly version: Schema.Trimmed;
+    readonly instructions: Schema.Trimmed;
+    readonly tools: Schema.$Array<Schema.Trimmed>;
 }>;
 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>;
+    readonly version: Schema.Trimmed;
+    readonly recipes: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly version: Schema.Trimmed;
+        readonly instructions: Schema.Trimmed;
+        readonly tools: Schema.$Array<Schema.Trimmed>;
     }>>;
-    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>;
+    readonly tools: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly version: Schema.Trimmed;
+        readonly description: Schema.Trimmed;
+        readonly returns: Schema.Trimmed;
+        readonly permissions: Schema.$Array<Schema.String>;
+        readonly inputSchema: Schema.$Record<Schema.String, Schema.Unknown>;
+        readonly outputSchema: Schema.$Record<Schema.String, 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>;
+    readonly recipes: Schema.$Array<Schema.String>;
+    readonly tools: Schema.$Array<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>;
+    readonly catalogVersion: Schema.String;
+    readonly recipes: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly version: Schema.Trimmed;
+        readonly instructions: Schema.Trimmed;
+        readonly tools: Schema.$Array<Schema.Trimmed>;
     }>>;
-    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>;
+    readonly tools: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly version: Schema.Trimmed;
+        readonly description: Schema.Trimmed;
+        readonly returns: Schema.Trimmed;
+        readonly permissions: Schema.$Array<Schema.String>;
+        readonly inputSchema: Schema.$Record<Schema.String, Schema.Unknown>;
+        readonly outputSchema: Schema.$Record<Schema.String, Schema.Unknown>;
     }>>;
 }>;
 export type ResolvedCapabilities = typeof ResolvedCapabilities.Type;

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

@@ -1,6 +1,35 @@
+import type { Tool } from "effect/ai";
 import { Effect } from "effect";
-import type { CapabilityCatalog, CapabilitySelection, ResolvedCapabilities } from "./capability.entity.js";
+import type { Capability, RegisteredTool, ToolDefinition, ToolViewInput } from "../ports/capability.port.js";
+import type { CapabilityCatalog, CapabilitySelection, ResolvedCapabilities, SkillDefinition, ToolAnnotations } from "./capability.entity.js";
 import { HarnessError } from "./plugin.entity.js";
+export declare const defaultAnnotations: ToolAnnotations;
+/** Author a tool with its handler, model view and annotations; the registry erases it. */
+export declare const defineTool: <T extends Tool.Any, R>(definition: {
+    readonly tool: T;
+    readonly handler: ToolDefinition<T, R>["handler"];
+    readonly view?: ToolViewInput<Tool.Success<T>, Tool.Parameters<T>>;
+    readonly annotations?: Partial<ToolAnnotations>;
+}) => RegisteredTool;
+export declare const defineSkill: (skill: {
+    readonly id: string;
+    readonly summary: string;
+    readonly instructions?: string;
+    readonly tools: ReadonlyArray<string>;
+    readonly version?: string;
+    readonly always?: boolean;
+    readonly permissions?: ReadonlyArray<string>;
+    readonly references?: SkillDefinition["references"];
+}) => SkillDefinition;
+export declare const defineCapability: (capability: {
+    readonly id: string;
+    readonly version: string;
+    readonly tools?: Capability["tools"];
+    readonly skills?: Capability["skills"];
+    readonly promptSections?: Capability["promptSections"];
+}) => Capability;
+/** The resolver's catalogue: skills are recipes, registered tools are capability tools. */
+export declare const catalogOf: (version: string, capabilities: ReadonlyArray<Capability>) => CapabilityCatalog;
 /** 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

@@ -1,6 +1,59 @@
-import { Effect } from "effect";
+import { Effect, Option } from "effect";
+import { strictJsonSchema, toolParametersSchema } from "../loop/toolSchema.js";
 import { HarnessError } from "./plugin.entity.js";
-export const resolveCapabilities = (catalog, requested, permissions) => Effect.gen(function* () {
+export const defaultAnnotations = {
+  readOnly: !1,
+  pollable: !1,
+  pinned: !1,
+  permissions: [],
+  maxCallsPerRun: Option.none(),
+  labels: {},
+  stage: Option.none()
+}, defineTool = (definition) => ({
+  tool: definition.tool,
+  handler: definition.handler,
+  view: Option.map(Option.fromNullishOr(definition.view), (view) => ({
+    version: view.version,
+    render: view.render,
+    compact: Option.fromNullishOr(view.compact),
+    subjects: view.subjects ?? (() => []),
+    artifacts: view.artifacts ?? (() => []),
+    digest: Option.fromNullishOr(view.digest)
+  })),
+  annotations: { ...defaultAnnotations, ...definition.annotations }
+}), defineSkill = (skill) => ({
+  id: skill.id,
+  version: skill.version ?? "1",
+  summary: skill.summary,
+  instructions: skill.instructions ?? "",
+  tools: skill.tools,
+  always: skill.always ?? !1,
+  permissions: skill.permissions ?? [],
+  references: skill.references ?? []
+}), defineCapability = (capability) => ({
+  id: capability.id,
+  version: capability.version,
+  tools: capability.tools ?? [],
+  skills: capability.skills ?? [],
+  promptSections: capability.promptSections ?? []
+}), catalogOf = (version, capabilities) => ({
+  version,
+  recipes: capabilities.flatMap((capability) => capability.skills).map((skill) => ({
+    id: skill.id,
+    version: skill.version,
+    instructions: skill.instructions.length > 0 ? skill.instructions : skill.summary,
+    tools: skill.tools
+  })),
+  tools: capabilities.flatMap((capability) => capability.tools).map((registered) => ({
+    id: registered.tool.name,
+    version: "1",
+    description: registered.tool.description ?? registered.tool.name,
+    returns: "tool result",
+    permissions: registered.annotations.permissions,
+    inputSchema: { ...toolParametersSchema(registered.tool) },
+    outputSchema: { ...strictJsonSchema(registered.tool.successSchema) }
+  }))
+}), 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" }));

package/dist/harness/capability.entity.js

@@ -1,19 +1,40 @@
 import { Schema } from "effect";
-export const CapabilityTool = Schema.Struct({
-  id: Schema.NonEmptyTrimmedString,
-  version: Schema.NonEmptyTrimmedString,
-  description: Schema.NonEmptyTrimmedString,
-  returns: Schema.NonEmptyTrimmedString,
+export const ToolAnnotations = Schema.Struct({
+  readOnly: Schema.Boolean,
+  pollable: Schema.Boolean,
+  pinned: Schema.Boolean,
   permissions: Schema.Array(Schema.String),
-  inputSchema: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
-  outputSchema: Schema.Record({ key: Schema.String, value: Schema.Unknown })
+  maxCallsPerRun: Schema.OptionFromNullOr(Schema.Int),
+  labels: Schema.Record(Schema.String, Schema.String),
+  stage: Schema.OptionFromNullOr(Schema.String)
+}), SkillReference = Schema.Struct({
+  id: Schema.Trimmed.check(Schema.isNonEmpty()),
+  title: Schema.Trimmed.check(Schema.isNonEmpty()),
+  text: Schema.String
+}), SkillDefinition = Schema.Struct({
+  id: Schema.Trimmed.check(Schema.isNonEmpty()),
+  version: Schema.Trimmed.check(Schema.isNonEmpty()),
+  summary: Schema.Trimmed.check(Schema.isNonEmpty()),
+  instructions: Schema.String,
+  tools: Schema.Array(Schema.Trimmed.check(Schema.isNonEmpty())),
+  always: Schema.Boolean,
+  permissions: Schema.Array(Schema.String),
+  references: Schema.Array(SkillReference)
+}), PromptTier = Schema.Literals(["static", "session", "turn"]), CapabilityTool = Schema.Struct({
+  id: Schema.Trimmed.check(Schema.isNonEmpty()),
+  version: Schema.Trimmed.check(Schema.isNonEmpty()),
+  description: Schema.Trimmed.check(Schema.isNonEmpty()),
+  returns: Schema.Trimmed.check(Schema.isNonEmpty()),
+  permissions: Schema.Array(Schema.String),
+  inputSchema: Schema.Record(Schema.String, Schema.Unknown),
+  outputSchema: Schema.Record(Schema.String, Schema.Unknown)
 }), CapabilityRecipe = Schema.Struct({
-  id: Schema.NonEmptyTrimmedString,
-  version: Schema.NonEmptyTrimmedString,
-  instructions: Schema.NonEmptyTrimmedString,
-  tools: Schema.Array(Schema.NonEmptyTrimmedString)
+  id: Schema.Trimmed.check(Schema.isNonEmpty()),
+  version: Schema.Trimmed.check(Schema.isNonEmpty()),
+  instructions: Schema.Trimmed.check(Schema.isNonEmpty()),
+  tools: Schema.Array(Schema.Trimmed.check(Schema.isNonEmpty()))
 }), CapabilityCatalog = Schema.Struct({
-  version: Schema.NonEmptyTrimmedString,
+  version: Schema.Trimmed.check(Schema.isNonEmpty()),
   recipes: Schema.Array(CapabilityRecipe),
   tools: Schema.Array(CapabilityTool)
 }), CapabilitySelection = Schema.Struct({

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

@@ -1,44 +1,44 @@
 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>>;
+    readonly id: Schema.NonEmptyString;
+    readonly use: Schema.NonEmptyString;
+    readonly enabled: Schema.optional<Schema.Boolean>;
+    readonly options: Schema.optional<Schema.$Record<Schema.String, 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>>;
+    readonly plugins: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly id: Schema.NonEmptyString;
+        readonly use: Schema.NonEmptyString;
+        readonly enabled: Schema.optional<Schema.Boolean>;
+        readonly options: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
     }>>>;
-    bindings: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-    system: Schema.optional<typeof Schema.String>;
+    readonly bindings: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly system: Schema.optional<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>>;
+    readonly version: Schema.Literal<1>;
+    readonly profile: Schema.optional<Schema.String>;
+    readonly plugins: Schema.optional<Schema.$Array<Schema.Struct<{
+        readonly id: Schema.NonEmptyString;
+        readonly use: Schema.NonEmptyString;
+        readonly enabled: Schema.optional<Schema.Boolean>;
+        readonly options: Schema.optional<Schema.$Record<Schema.String, 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>>;
+    readonly bindings: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly profiles: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly plugins: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly id: Schema.NonEmptyString;
+            readonly use: Schema.NonEmptyString;
+            readonly enabled: Schema.optional<Schema.Boolean>;
+            readonly options: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
         }>>>;
-        bindings: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.String>>;
-        system: Schema.optional<typeof Schema.String>;
+        readonly bindings: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        readonly system: Schema.optional<Schema.String>;
     }>>>;
-    system: Schema.optional<typeof Schema.String>;
+    readonly system: Schema.optional<Schema.String>;
 }>;
 export type HarnessConfig = typeof HarnessConfig.Type;
 export interface AgentDefinition {

package/dist/harness/config.entity.js

@@ -3,16 +3,16 @@ 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 }))
+  options: Schema.optional(Schema.Record(Schema.String, Schema.Unknown))
 }), Profile = Schema.Struct({
   plugins: Schema.optional(Schema.Array(PluginEntry)),
-  bindings: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+  bindings: Schema.optional(Schema.Record(Schema.String, 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 })),
+  bindings: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  profiles: Schema.optional(Schema.Record(Schema.String, Profile)),
   system: Schema.optional(Schema.String)
 });

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

@@ -0,0 +1,24 @@
+import { Layer } from "effect";
+import { Capabilities } from "../ports/capability.port.js";
+import type { Capability } from "../ports/capability.port.js";
+/** The host's own bundles as a layer: the bottom of a plugin stack (see `stackPlugins`). */
+export declare const CapabilitiesLive: (...bundles: ReadonlyArray<Capability>) => Layer.Layer<Capabilities>;
+/**
+ * Stack one plugin layer on the layers below it, as the plugin graph
+ * activates them: `next` is built over everything `base` provides; the two
+ * Capabilities arrays concatenate, base first (activateGraph's order); any
+ * other service of `next` wins.
+ *
+ * ```ts
+ * const plugins = CapabilitiesLive(host).pipe(
+ *   stackPlugins(MemoryWindowLive()),   // + the recall tool
+ *   stackPlugins(ToolDiscoveryLive()),  // registry over [host, recall]; + the catalogue
+ * )
+ * ```
+ *
+ * Capabilities is a multi-provider key. `Layer.merge`/`Layer.mergeAll`
+ * keep one array and silently drop the other layer's tools, skills and
+ * sections, and a layer merged beside another cannot see what it
+ * contributes: never merge layers that contribute; stack them.
+ */
+export declare const stackPlugins: <A2, E2, R2>(next: Layer.Layer<A2, E2, R2>) => <A1, E1, R1>(base: Layer.Layer<A1, E1, R1>) => Layer.Layer<A1 | A2, E1 | E2, R1 | Exclude<R2, A1>>;

package/dist/harness/plugin-stack.adapter.js

@@ -0,0 +1,8 @@
+import { Context, Effect, Layer, Option } from "effect";
+import { Capabilities } from "../ports/capability.port.js";
+export const CapabilitiesLive = (...bundles) => Layer.succeed(Capabilities, bundles);
+const capabilitiesOf = (context) => Option.getOrElse(Context.getOption(context, Capabilities), () => []);
+export const stackPlugins = (next) => (base) => Layer.effectContext(Effect.gen(function* () {
+  const scope = yield* Effect.scope, lower = yield* Layer.buildWithScope(base, scope), upper = yield* Layer.buildWithScope(next, scope).pipe(Effect.provide(lower)), merged = Context.merge(lower, upper);
+  return lower.mapUnsafe.has(Capabilities.key) || upper.mapUnsafe.has(Capabilities.key) ? Context.makeUnsafe(new Map([...merged.mapUnsafe, [Capabilities.key, [...capabilitiesOf(lower), ...capabilitiesOf(upper)]]])) : merged;
+}));

package/dist/harness/plugin-stack.adapter.test.d.ts

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

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

@@ -1,6 +1,11 @@
 import { Layer, Schema } from "effect";
-import type { Plugin } from "./plugin.entity.js";
-/** Layers retain their native types until the validated dynamic loading edge. */
+import type { TypedPlugin } from "./plugin.entity.js";
+/**
+ * Layers retain their native types until the validated dynamic loading edge.
+ * `build` (the graph's) and `live` (a host's own composition) share one
+ * decode: the options merged over the defaults, extra keys refused — so a
+ * graph caller, whose options already hold the defaults, decodes the same.
+ */
 export declare const definePlugin: <A extends Readonly<Record<string, unknown>>, I, Out, E, In>(definition: {
     readonly id: string;
     readonly version: string;
@@ -12,7 +17,13 @@ export declare const definePlugin: <A extends Readonly<Record<string, unknown>>,
     readonly provides: ReadonlyArray<{
         readonly key: string;
     }>;
-    readonly config: Schema.Schema<A, I>;
+    readonly contributes?: ReadonlyArray<{
+        readonly key: string;
+    }>;
+    readonly optional?: ReadonlyArray<{
+        readonly key: string;
+    }>;
+    readonly config: Schema.Codec<A, I>;
     readonly defaults: A;
     readonly layer: (config: A) => Layer.Layer<Out, E, In>;
-}) => Plugin;
+}) => TypedPlugin<A, I, Out, E, In>;

package/dist/harness/plugin.adapter.js

@@ -1,13 +1,20 @@
 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) }))))
-});
+export const definePlugin = (definition) => {
+  const decodeOptions = (options) => Schema.decodeUnknownEffect(definition.config)(typeof options === "object" && options !== null ? { ...definition.defaults, ...options } : options ?? definition.defaults, { onExcessProperty: "error" });
+  return {
+    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),
+    contributes: (definition.contributes ?? []).map((tag) => tag.key),
+    optional: (definition.optional ?? []).map((tag) => tag.key),
+    schema: definition.config,
+    config: definition.config,
+    defaults: definition.defaults,
+    build: (options, services) => decodeOptions(options).pipe(Effect.flatMap((config) => Layer.build(Layer.fresh(definition.layer(config))).pipe(Effect.provide(Context.makeUnsafe(services.mapUnsafe)), Effect.map((built) => Context.makeUnsafe(Context.omit(Layer.CurrentMemoMap)(built).mapUnsafe)))), Effect.mapError((error) => new HarnessError({ code: "plugin.activation", plugin: definition.id, message: String(error) })), Effect.catchDefect((error) => Effect.fail(new HarnessError({ code: "plugin.defect", plugin: definition.id, message: String(error) })))),
+    live: (options) => Layer.unwrap(decodeOptions(options).pipe(Effect.mapError((error) => new HarnessError({ code: "config.options", plugin: definition.id, message: String(error) })), Effect.map(definition.layer)))
+  };
+};

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

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