@fevex/core 0.1.0-alpha.6 → 0.1.0-alpha.7

package/README.md

@@ -978,6 +978,33 @@ const app = createFevex({
 });
 ```
 
+For longer instructions, keep them in an explicit `SKILL.md` file. Only the
+frontmatter metadata enters the prompt; the body loads on demand:
+
+```ts
+import { createAgentsMdContextProvider, loadSkillFile } from '@fevex/core';
+
+const refunds = await loadSkillFile('./skills/refunds/SKILL.md');
+
+const app = createFevex({
+  models,
+  contextProviders: [refunds, createAgentsMdContextProvider('./AGENTS.md')],
+  agents: [
+    defineAgent({
+      name: 'support',
+      instructions: 'Answer with business context.',
+      skills: ['refunds'],
+      context: ['agents-md'],
+    }),
+  ],
+});
+```
+
+`SKILL.md` uses `name` and `description` frontmatter. The reserved
+`fevex__load_skill` tool loads the body and lists files under `references/`,
+`scripts/` and `assets/`; scripts are not executed by the runtime. Paths are
+explicit, with no automatic discovery.
+
 Context providers are lazy per run. Memory is a replaceable store; the built-in
 store is in-memory substring search, not embeddings, vector search or durable
 storage.

package/dist/channels/index.d.mts

@@ -1,2 +1,2 @@
-import { a as ChannelDeliveryOptions, c as ChannelEvent, d as ChannelMessage, f as ChannelOutput, h as ChannelRunResult, i as ChannelContext, l as ChannelEventType, m as ChannelRunOptions, n as handleChannelInput, o as ChannelElicitationContext, p as ChannelRunEvent, r as ChannelAdapter, s as ChannelError, t as deliverChannelRun, u as ChannelFailurePhase } from "../index-DVw0zOc_.mjs";
+import { a as ChannelDeliveryOptions, c as ChannelEvent, d as ChannelMessage, f as ChannelOutput, h as ChannelRunResult, i as ChannelContext, l as ChannelEventType, m as ChannelRunOptions, n as handleChannelInput, o as ChannelElicitationContext, p as ChannelRunEvent, r as ChannelAdapter, s as ChannelError, t as deliverChannelRun, u as ChannelFailurePhase } from "../index-BTD1c4Ys.mjs";
 export { ChannelAdapter, ChannelContext, ChannelDeliveryOptions, ChannelElicitationContext, ChannelError, ChannelEvent, ChannelEventType, ChannelFailurePhase, ChannelMessage, ChannelOutput, ChannelRunEvent, ChannelRunOptions, ChannelRunResult, deliverChannelRun, handleChannelInput };

package/dist/evals/index.d.mts

@@ -1,7 +1,7 @@
 import { l as JsonValue, o as ExecutionContext, t as AgentEvent } from "../types-B8laW1hM.mjs";
 import { r as ModelMetadata, s as ModelUsage } from "../index-BgKFd9yw.mjs";
 import { t as CostCalculator, u as TraceCost } from "../index-CpLDt6Rw.mjs";
-import { t as Fevex } from "../fevex-B4QY5Z6e.mjs";
+import { t as Fevex } from "../fevex-CVMLnZsk.mjs";
 //#region src/evals/canonical-json.d.ts
 /** Serializes JSON-like data with stable object-key ordering. */
 declare function serializeCanonical(value: unknown): string;

package/dist/{fevex-B4QY5Z6e.d.mts → fevex-CVMLnZsk.d.mts}

@@ -1,7 +1,7 @@
 import { F as ArtifactStore, f as RunId, o as ExecutionContext, t as AgentEvent } from "./types-B8laW1hM.mjs";
 import { t as ModelGateway } from "./index-BgKFd9yw.mjs";
 import { B as TeamRun, C as PurgeRunsResult, F as RunStore, I as Session, J as WorkflowRun, L as SessionId, M as RunRequest, N as RunResult, S as PurgeRunsOptions, a as AgentRun, b as ListEventsOptions, f as CredentialStore, j as RunRecord, t as AgentDefinition, w as ResumeRunResolution } from "./index-CzAi2Y_Z.mjs";
-import { r as ContextProvider, s as MemoryStore } from "./index-BJktlD4E.mjs";
+import { c as ContextProvider, f as MemoryStore } from "./index-B0AdFbgr.mjs";
 import { i as ObservabilityStats, r as ObservabilityOptions } from "./index-CpLDt6Rw.mjs";
 import { r as Sandbox } from "./index-Df84VWmN.mjs";
 import { g as ToolDefinition, s as ConnectionDefinition } from "./index-5p3q2yIp.mjs";

package/dist/http/index.d.mts

@@ -1,7 +1,7 @@
 import { D as ArtifactCatalog, F as ArtifactStore, f as RunId, k as ArtifactDescriptor, l as JsonValue, o as ExecutionContext, t as AgentEvent } from "../types-B8laW1hM.mjs";
 import { c as ReasoningEffort } from "../index-BgKFd9yw.mjs";
 import { B as TeamRun, J as WorkflowRun, L as SessionId, a as AgentRun, j as RunRecord } from "../index-CzAi2Y_Z.mjs";
-import { t as Fevex } from "../fevex-B4QY5Z6e.mjs";
+import { t as Fevex } from "../fevex-CVMLnZsk.mjs";
 //#region src/http/protocol.d.ts
 declare const FEVEX_HTTP_PROTOCOL_VERSION = "3";
 declare const FEVEX_HTTP_PROTOCOL_VERSION_HEADER = "Fevex-Protocol-Version";

package/dist/index-B0AdFbgr.d.mts

@@ -0,0 +1,116 @@
+import { l as JsonValue, o as ExecutionContext, s as JsonObject } from "./types-B8laW1hM.mjs";
+import { L as SessionId } from "./index-CzAi2Y_Z.mjs";
+//#region src/knowledge/knowledge.d.ts
+/** Runtime context supplied to knowledge providers and memory stores. */
+interface KnowledgeContext {
+  agentName: string;
+  input: string;
+  sessionId: SessionId;
+  context?: ExecutionContext;
+  signal?: AbortSignal;
+}
+interface ContextBlock {
+  id: string;
+  content: string;
+  metadata?: JsonObject;
+}
+interface ContextProvider {
+  name: string;
+  read(context: KnowledgeContext): Promise<ContextBlock[]>;
+}
+interface MemoryQuery {
+  query: string;
+  limit?: number;
+  agentName?: string;
+  sessionId?: SessionId;
+  namespace?: string;
+  actor?: ExecutionContext['actor'];
+}
+interface MemoryWrite {
+  content: string;
+  agentName?: string;
+  sessionId?: SessionId;
+  namespace?: string;
+  actor?: ExecutionContext['actor'];
+  metadata?: JsonObject;
+}
+interface MemoryRecord extends MemoryWrite {
+  id: string;
+  createdAt: string;
+}
+interface MemoryStore {
+  search(query: MemoryQuery, context: KnowledgeContext): Promise<MemoryRecord[]>;
+  write(record: MemoryWrite, context: KnowledgeContext): Promise<MemoryRecord>;
+}
+interface SkillDefinition {
+  name: string;
+  instructions: string;
+  resources?: Array<string | JsonValue | {
+    id?: string;
+    content: string | JsonValue;
+    metadata?: JsonObject;
+  }>;
+}
+/**
+ * Context provider that advertises a skill's metadata and defers its full
+ * instructions until the model calls the reserved load-skill tool.
+ *
+ * The provider name is the skill name referenced from `agent.skills`.
+ */
+interface ProgressiveSkillProvider extends ContextProvider {
+  /** Short description shown to the model before the skill is loaded. */
+  readonly description: string;
+  /** Loads the full instructions, or one resource when `resource` is set. */
+  load(context: KnowledgeContext, resource?: string): Promise<ContextBlock[]>;
+}
+declare function isProgressiveSkillProvider(provider: ContextProvider): provider is ProgressiveSkillProvider;
+declare function defineContextProvider<T extends ContextProvider>(provider: T): T;
+declare function defineSkill(skill: SkillDefinition): ContextProvider;
+declare function createMemoryContextProvider(options: {
+  name?: string;
+  store: MemoryStore;
+  limit?: number;
+}): ContextProvider;
+//#endregion
+//#region src/knowledge/agents-md.d.ts
+interface AgentsMdOptions {
+  /** Explicit path to an `AGENTS.md` file. */
+  path: string;
+  /** Context provider name; defaults to `agents-md`. */
+  name?: string;
+  maxBytes?: number;
+}
+/**
+ * Reads one explicit `AGENTS.md` file as context.
+ *
+ * Fevex never walks the filesystem looking for `AGENTS.md`; register one
+ * provider per file and reference its name from `agent.context`.
+ */
+declare function createAgentsMdContextProvider(options: AgentsMdOptions | string): ContextProvider;
+//#endregion
+//#region src/knowledge/in-memory-memory-store.d.ts
+/** Volatile keyword-search memory store for tests and local development. */
+declare class InMemoryMemoryStore implements MemoryStore {
+  #private;
+  search(query: MemoryQuery, context: KnowledgeContext): Promise<MemoryRecord[]>;
+  write(record: MemoryWrite, context: KnowledgeContext): Promise<MemoryRecord>;
+}
+//#endregion
+//#region src/knowledge/skill-file.d.ts
+interface LoadSkillFileOptions {
+  /** Maximum size of the `SKILL.md` file. */
+  maxBytes?: number;
+  /** Maximum size of one resource loaded on demand. */
+  maxResourceBytes?: number;
+}
+/**
+ * Loads one explicit `SKILL.md` file.
+ *
+ * Only `name` and `description` are advertised up front. The body and any
+ * files under `references/`, `scripts/` or `assets/` load on demand.
+ */
+declare function loadSkillFile(path: string, options?: LoadSkillFileOptions): Promise<ProgressiveSkillProvider>;
+/** Loads several explicit `SKILL.md` files; it never scans directories. */
+declare function loadSkillFiles(paths: readonly string[], options?: LoadSkillFileOptions): Promise<ProgressiveSkillProvider[]>;
+//#endregion
+export { defineContextProvider as _, AgentsMdOptions as a, ContextProvider as c, MemoryRecord as d, MemoryStore as f, createMemoryContextProvider as g, SkillDefinition as h, InMemoryMemoryStore as i, KnowledgeContext as l, ProgressiveSkillProvider as m, loadSkillFile as n, createAgentsMdContextProvider as o, MemoryWrite as p, loadSkillFiles as r, ContextBlock as s, LoadSkillFileOptions as t, MemoryQuery as u, defineSkill as v, isProgressiveSkillProvider as y };

package/dist/{index-DVw0zOc_.d.mts → index-BTD1c4Ys.d.mts}

@@ -1,6 +1,6 @@
 import { f as RunId, o as ExecutionContext, s as JsonObject, t as AgentEvent } from "./types-B8laW1hM.mjs";
 import { L as SessionId, a as AgentRun, h as ElicitationRequest } from "./index-CzAi2Y_Z.mjs";
-import { t as Fevex } from "./fevex-B4QY5Z6e.mjs";
+import { t as Fevex } from "./fevex-CVMLnZsk.mjs";
 //#region src/channels/channel.d.ts
 interface ChannelMessage {
   id: string;

package/dist/index.d.mts

@@ -1,14 +1,14 @@
 import { A as ArtifactError, C as FileSystemArtifactStore, D as ArtifactCatalog, E as CatalogedArtifactStoreOptions, F as ArtifactStore, I as ArtifactStoreContext, L as ArtifactWrite, M as ArtifactId, N as ArtifactQuery, O as ArtifactContent, P as ArtifactRecord, R as artifactTenantId, S as InMemoryArtifactCatalog, T as CatalogedArtifactStore, _ as S3ArtifactStore, a as AgentMessageRole, b as InMemoryArtifactStore, c as JsonPrimitive, d as PROVIDER_SCHEMA_UNSUPPORTED, f as RunId, g as ToolSpec, h as ToolEventSource, i as AgentMessage, j as ArtifactErrorCode, k as ArtifactDescriptor, l as JsonValue, m as ToolCall, n as AgentEventPayloads, o as ExecutionContext, p as SCHEMA_NOT_TRANSPORTABLE, r as AgentEventType, s as JsonObject, t as AgentEvent, u as PROVIDER_REASONING_UNSUPPORTED, v as S3ArtifactStoreOptions, w as FileSystemArtifactStoreOptions, x as InMemoryArtifactStoreOptions, y as S3ObjectClient, z as assertArtifactId } from "./types-B8laW1hM.mjs";
 import { a as ModelResult, c as ReasoningEffort, i as ModelRef, l as ToolChoice, n as ModelInput, o as ModelStreamEvent, r as ModelMetadata, s as ModelUsage, t as ModelGateway } from "./index-BgKFd9yw.mjs";
 import { $ as validateListEventsOptions, A as RunPause, B as TeamRun, C as PurgeRunsResult, D as RunCheckpoint, E as RetainableRunStore, F as RunStore, G as WorkflowBudgetUsage, H as ToolExecutionRecord, I as Session, J as WorkflowRun, K as WorkflowCheckpoint, L as SessionId, M as RunRequest, N as RunResult, O as RunCorrelation, P as RunStatus, Q as isRetainableRunStore, R as StoredRunCheckpoint, S as PurgeRunsOptions, T as RetainableRunStatus, U as ToolExecutionResolution, V as TimerResolution, W as ToolExecutionStatus, X as WorkflowWaitRecord, Y as WorkflowStepRecord, Z as isDurableRunStore, _ as EventResolution, a as AgentRun, b as ListEventsOptions, c as ApprovalRequest, d as CoordinatorRun, et as validatePurgeRunsOptions, f as CredentialStore, g as ElicitationResolution, h as ElicitationRequest, i as InMemoryRunStore, j as RunRecord, k as RunLease, l as ApprovalResolution, m as ElicitationMode, n as AgentLimits, o as AgentRunPause, p as DurableRunStore, q as WorkflowCompensationRecord, r as defineAgent, s as ApprovalMode, t as AgentDefinition, u as CoordinatorCheckpoint, v as ExecutionCommit, w as ResumeRunResolution, x as PendingToolExecution, y as ExecutionCreate, z as TeamCheckpoint } from "./index-CzAi2Y_Z.mjs";
-import { a as MemoryQuery, c as MemoryWrite, d as defineContextProvider, f as defineSkill, i as KnowledgeContext, l as SkillDefinition, n as ContextBlock, o as MemoryRecord, r as ContextProvider, s as MemoryStore, t as InMemoryMemoryStore, u as createMemoryContextProvider } from "./index-BJktlD4E.mjs";
+import { _ as defineContextProvider, a as AgentsMdOptions, c as ContextProvider, d as MemoryRecord, f as MemoryStore, g as createMemoryContextProvider, h as SkillDefinition, i as InMemoryMemoryStore, l as KnowledgeContext, m as ProgressiveSkillProvider, n as loadSkillFile, o as createAgentsMdContextProvider, p as MemoryWrite, r as loadSkillFiles, s as ContextBlock, t as LoadSkillFileOptions, u as MemoryQuery, v as defineSkill, y as isProgressiveSkillProvider } from "./index-B0AdFbgr.mjs";
 import { a as SandboxError, c as sandboxResultToJson, i as SandboxCapabilities, n as createLocalSandbox, o as SandboxRunRequest, r as Sandbox, s as SandboxRunResult, t as LocalSandboxOptions } from "./index-Df84VWmN.mjs";
 import { C as toToolSpec, S as defineTool, _ as ToolExecutionContext, a as compileFevexJsonSchema, b as ToolRetryPolicy, c as ConnectionToolPolicy, d as ToolProvider, f as ToolProviderContext, g as ToolDefinition, h as ToolApproval, i as FevexJsonSchemaValidator, l as IntegrationError, m as defineConnection, n as FevexJsonSchemaProfileLimits, o as validateFevexJsonSchemaProfile, p as ToolProviderTool, r as FevexJsonSchemaProfileOptions, s as ConnectionDefinition, t as FEVEX_JSON_SCHEMA_PROFILE_VERSION, u as IntegrationErrorCategory, v as ToolIdempotency, x as ToolRisk, y as ToolResult } from "./index-5p3q2yIp.mjs";
 import { i as definePolicy, n as PolicyDecision, r as PolicyDefinition, t as PolicyAuthorization } from "./index-CbACw6xZ.mjs";
 import { a as WorkflowStep, c as defineWorkflow, i as WorkflowEventResult, n as WorkflowDefinition, o as WorkflowStepContext, r as WorkflowEventDefinition, s as WorkflowStepOptions, t as WorkflowAgentResult } from "./index-CseuTR-F.mjs";
 import { a as TeamMember, c as defineTeam, i as TeamLimits, n as TeamDelegation, o as TeamStep, r as TeamHandoff, s as TeamTaskResult, t as TeamDefinition } from "./index-1cHr7KB_.mjs";
-import { a as FevexLimits, c as createFevex, i as FevexConfig, n as FevexAdmission, o as FevexShutdownOptions, r as FevexAdmissionRequest, s as FevexShutdownResult, t as Fevex } from "./fevex-B4QY5Z6e.mjs";
-import { a as ChannelDeliveryOptions, c as ChannelEvent, d as ChannelMessage, f as ChannelOutput, h as ChannelRunResult, i as ChannelContext, l as ChannelEventType, m as ChannelRunOptions, n as handleChannelInput, o as ChannelElicitationContext, p as ChannelRunEvent, r as ChannelAdapter, s as ChannelError, t as deliverChannelRun, u as ChannelFailurePhase } from "./index-DVw0zOc_.mjs";
+import { a as FevexLimits, c as createFevex, i as FevexConfig, n as FevexAdmission, o as FevexShutdownOptions, r as FevexAdmissionRequest, s as FevexShutdownResult, t as Fevex } from "./fevex-CVMLnZsk.mjs";
+import { a as ChannelDeliveryOptions, c as ChannelEvent, d as ChannelMessage, f as ChannelOutput, h as ChannelRunResult, i as ChannelContext, l as ChannelEventType, m as ChannelRunOptions, n as handleChannelInput, o as ChannelElicitationContext, p as ChannelRunEvent, r as ChannelAdapter, s as ChannelError, t as deliverChannelRun, u as ChannelFailurePhase } from "./index-BTD1c4Ys.mjs";
 //#region src/configuration-error.d.ts
 /**
  * Composition error codes.
@@ -39,4 +39,4 @@ declare class RunPausedError extends FevexRunError {
   constructor(runId: RunId, pause: RunPause);
 }
 //#endregion
-export { AgentDefinition, AgentEvent, AgentEventPayloads, AgentEventType, AgentLimits, AgentMessage, AgentMessageRole, AgentRun, AgentRunPause, ApprovalMode, ApprovalRequest, ApprovalResolution, ArtifactCatalog, ArtifactContent, ArtifactDescriptor, ArtifactError, ArtifactErrorCode, ArtifactId, ArtifactQuery, ArtifactRecord, ArtifactStore, ArtifactStoreContext, ArtifactWrite, CatalogedArtifactStore, CatalogedArtifactStoreOptions, ChannelAdapter, ChannelContext, ChannelDeliveryOptions, ChannelElicitationContext, ChannelError, ChannelEvent, ChannelEventType, ChannelFailurePhase, ChannelMessage, ChannelOutput, ChannelRunEvent, ChannelRunOptions, ChannelRunResult, ConnectionDefinition, ConnectionToolPolicy, ContextBlock, ContextProvider, CoordinatorCheckpoint, CoordinatorRun, CredentialStore, DurableRunStore, ElicitationMode, ElicitationRequest, ElicitationResolution, EventResolution, ExecutionCommit, ExecutionContext, ExecutionCreate, FEVEX_JSON_SCHEMA_PROFILE_VERSION, Fevex, FevexAdmission, FevexAdmissionRequest, FevexConfig, FevexConfigurationError, FevexConfigurationErrorCode, FevexJsonSchemaProfileLimits, FevexJsonSchemaProfileOptions, FevexJsonSchemaValidator, FevexLimits, FevexRunError, FevexRunErrorCode, FevexShutdownOptions, FevexShutdownResult, FileSystemArtifactStore, FileSystemArtifactStoreOptions, InMemoryArtifactCatalog, InMemoryArtifactStore, InMemoryArtifactStoreOptions, InMemoryMemoryStore, InMemoryRunStore, IntegrationError, IntegrationErrorCategory, JsonObject, JsonPrimitive, JsonValue, KnowledgeContext, ListEventsOptions, LocalSandboxOptions, MemoryQuery, MemoryRecord, MemoryStore, MemoryWrite, ModelGateway, ModelInput, ModelMetadata, ModelRef, ModelResult, ModelStreamEvent, ModelUsage, PROVIDER_REASONING_UNSUPPORTED, PROVIDER_SCHEMA_UNSUPPORTED, PendingToolExecution, PolicyAuthorization, PolicyDecision, PolicyDefinition, PurgeRunsOptions, PurgeRunsResult, ReasoningEffort, ResumeRunResolution, RetainableRunStatus, RetainableRunStore, RunCheckpoint, RunCorrelation, RunId, RunLease, RunPause, RunPausedError, RunRecord, RunRequest, RunResult, RunStatus, RunStore, S3ArtifactStore, S3ArtifactStoreOptions, S3ObjectClient, SCHEMA_NOT_TRANSPORTABLE, Sandbox, SandboxCapabilities, SandboxError, SandboxRunRequest, SandboxRunResult, Session, SessionId, SkillDefinition, StoredRunCheckpoint, TeamCheckpoint, type TeamDefinition, type TeamDelegation, type TeamHandoff, type TeamLimits, type TeamMember, TeamRun, type TeamStep, type TeamTaskResult, TimerResolution, ToolApproval, ToolCall, ToolChoice, ToolDefinition, ToolEventSource, ToolExecutionContext, ToolExecutionRecord, ToolExecutionResolution, ToolExecutionStatus, ToolIdempotency, ToolProvider, ToolProviderContext, ToolProviderTool, ToolResult, ToolRetryPolicy, ToolRisk, ToolSpec, WorkflowAgentResult, WorkflowBudgetUsage, WorkflowCheckpoint, WorkflowCompensationRecord, WorkflowDefinition, WorkflowEventDefinition, WorkflowEventResult, WorkflowRun, WorkflowStep, WorkflowStepContext, WorkflowStepOptions, WorkflowStepRecord, WorkflowWaitRecord, artifactTenantId, assertArtifactId, compileFevexJsonSchema, createFevex, createLocalSandbox, createMemoryContextProvider, defineAgent, defineConnection, defineContextProvider, definePolicy, defineSkill, defineTeam, defineTool, defineWorkflow, deliverChannelRun, handleChannelInput, isDurableRunStore, isRetainableRunStore, sandboxResultToJson, toToolSpec, validateFevexJsonSchemaProfile, validateListEventsOptions, validatePurgeRunsOptions };
+export { AgentDefinition, AgentEvent, AgentEventPayloads, AgentEventType, AgentLimits, AgentMessage, AgentMessageRole, AgentRun, AgentRunPause, AgentsMdOptions, ApprovalMode, ApprovalRequest, ApprovalResolution, ArtifactCatalog, ArtifactContent, ArtifactDescriptor, ArtifactError, ArtifactErrorCode, ArtifactId, ArtifactQuery, ArtifactRecord, ArtifactStore, ArtifactStoreContext, ArtifactWrite, CatalogedArtifactStore, CatalogedArtifactStoreOptions, ChannelAdapter, ChannelContext, ChannelDeliveryOptions, ChannelElicitationContext, ChannelError, ChannelEvent, ChannelEventType, ChannelFailurePhase, ChannelMessage, ChannelOutput, ChannelRunEvent, ChannelRunOptions, ChannelRunResult, ConnectionDefinition, ConnectionToolPolicy, ContextBlock, ContextProvider, CoordinatorCheckpoint, CoordinatorRun, CredentialStore, DurableRunStore, ElicitationMode, ElicitationRequest, ElicitationResolution, EventResolution, ExecutionCommit, ExecutionContext, ExecutionCreate, FEVEX_JSON_SCHEMA_PROFILE_VERSION, Fevex, FevexAdmission, FevexAdmissionRequest, FevexConfig, FevexConfigurationError, FevexConfigurationErrorCode, FevexJsonSchemaProfileLimits, FevexJsonSchemaProfileOptions, FevexJsonSchemaValidator, FevexLimits, FevexRunError, FevexRunErrorCode, FevexShutdownOptions, FevexShutdownResult, FileSystemArtifactStore, FileSystemArtifactStoreOptions, InMemoryArtifactCatalog, InMemoryArtifactStore, InMemoryArtifactStoreOptions, InMemoryMemoryStore, InMemoryRunStore, IntegrationError, IntegrationErrorCategory, JsonObject, JsonPrimitive, JsonValue, KnowledgeContext, ListEventsOptions, LoadSkillFileOptions, LocalSandboxOptions, MemoryQuery, MemoryRecord, MemoryStore, MemoryWrite, ModelGateway, ModelInput, ModelMetadata, ModelRef, ModelResult, ModelStreamEvent, ModelUsage, PROVIDER_REASONING_UNSUPPORTED, PROVIDER_SCHEMA_UNSUPPORTED, PendingToolExecution, PolicyAuthorization, PolicyDecision, PolicyDefinition, ProgressiveSkillProvider, PurgeRunsOptions, PurgeRunsResult, ReasoningEffort, ResumeRunResolution, RetainableRunStatus, RetainableRunStore, RunCheckpoint, RunCorrelation, RunId, RunLease, RunPause, RunPausedError, RunRecord, RunRequest, RunResult, RunStatus, RunStore, S3ArtifactStore, S3ArtifactStoreOptions, S3ObjectClient, SCHEMA_NOT_TRANSPORTABLE, Sandbox, SandboxCapabilities, SandboxError, SandboxRunRequest, SandboxRunResult, Session, SessionId, SkillDefinition, StoredRunCheckpoint, TeamCheckpoint, type TeamDefinition, type TeamDelegation, type TeamHandoff, type TeamLimits, type TeamMember, TeamRun, type TeamStep, type TeamTaskResult, TimerResolution, ToolApproval, ToolCall, ToolChoice, ToolDefinition, ToolEventSource, ToolExecutionContext, ToolExecutionRecord, ToolExecutionResolution, ToolExecutionStatus, ToolIdempotency, ToolProvider, ToolProviderContext, ToolProviderTool, ToolResult, ToolRetryPolicy, ToolRisk, ToolSpec, WorkflowAgentResult, WorkflowBudgetUsage, WorkflowCheckpoint, WorkflowCompensationRecord, WorkflowDefinition, WorkflowEventDefinition, WorkflowEventResult, WorkflowRun, WorkflowStep, WorkflowStepContext, WorkflowStepOptions, WorkflowStepRecord, WorkflowWaitRecord, artifactTenantId, assertArtifactId, compileFevexJsonSchema, createAgentsMdContextProvider, createFevex, createLocalSandbox, createMemoryContextProvider, defineAgent, defineConnection, defineContextProvider, definePolicy, defineSkill, defineTeam, defineTool, defineWorkflow, deliverChannelRun, handleChannelInput, isDurableRunStore, isProgressiveSkillProvider, isRetainableRunStore, loadSkillFile, loadSkillFiles, sandboxResultToJson, toToolSpec, validateFevexJsonSchemaProfile, validateListEventsOptions, validatePurgeRunsOptions };

package/dist/index.mjs

@@ -2,7 +2,7 @@ import { defineAgent } from "./agents/index.mjs";
 import { a as CatalogedArtifactStore, c as assertArtifactId, i as FileSystemArtifactStore, n as InMemoryArtifactStore, o as ArtifactError, r as InMemoryArtifactCatalog, s as artifactTenantId, t as S3ArtifactStore } from "./artifacts-gUzemET7.mjs";
 import { n as RunPausedError, t as FevexRunError } from "./run-error-Cr17wPGH.mjs";
 import { ChannelError, deliverChannelRun, handleChannelInput } from "./channels/index.mjs";
-import { InMemoryMemoryStore, createMemoryContextProvider, defineContextProvider, defineSkill } from "./knowledge/index.mjs";
+import { InMemoryMemoryStore, createAgentsMdContextProvider, createMemoryContextProvider, defineContextProvider, defineSkill, isProgressiveSkillProvider, loadSkillFile, loadSkillFiles } from "./knowledge/index.mjs";
 import { n as teamAsWorkflow, t as defineTeam } from "./teams-Ctz676G4.mjs";
 import { InMemoryRunStore, isDurableRunStore, isRetainableRunStore, validateListEventsOptions, validatePurgeRunsOptions } from "./runtime/index.mjs";
 import { FEVEX_JSON_SCHEMA_PROFILE_VERSION, IntegrationError, compileFevexJsonSchema, defineConnection, defineTool, toToolSpec, validateFevexJsonSchemaProfile } from "./tools/index.mjs";
@@ -649,6 +649,8 @@ const LEASE_MS = 3e4;
 const LEASE_RENEW_MS = 1e4;
 /** Reserved name of the internal elicitation tool exposed to the model. */
 const ELICIT_TOOL_NAME = "fevex__elicit";
+/** Reserved name of the internal progressive skill loader exposed to the model. */
+const LOAD_SKILL_TOOL_NAME = "fevex__load_skill";
 //#endregion
 //#region src/internal/run-helpers.ts
 function redact(message, secrets) {
@@ -1179,26 +1181,50 @@ function createAgentEngine(composition, core) {
 					description: remote.description
 				} : tool, inputSchema);
 			}));
-			const allTools = currentElicitationMode === "pause" ? [...agentTools, {
-				name: ELICIT_TOOL_NAME,
-				description: "Request external information required to continue this run. Use prompt for explanatory text shown outside the form. Put short field labels in responseSchema property titles and optional field help in property descriptions.",
+			const progressiveSkills = (agent.skills ?? []).map((skillName) => contextProviders.get(skillName)).filter((provider) => provider !== void 0 && isProgressiveSkillProvider(provider));
+			const skillTool = progressiveSkills.length === 0 ? void 0 : {
+				name: LOAD_SKILL_TOOL_NAME,
+				description: `Load the full instructions for one of this agent's skills. Available skills: ${progressiveSkills.map((skill) => skill.name).join(", ")}. Pass a resource path from the loaded skill to read one resource.`,
 				inputSchema: {
 					type: "object",
 					properties: {
-						prompt: {
+						name: {
 							type: "string",
-							description: "Explanatory text for the user; do not duplicate field labels here."
+							enum: progressiveSkills.map((skill) => skill.name)
 						},
-						responseSchema: {
-							type: "object",
-							description: "JSON Schema for the expected response. Each property should include a short title for the form label and may include a description for field help."
-						},
-						expiresAt: { type: "string" }
+						resource: {
+							type: "string",
+							description: "Optional resource path returned by a previous load."
+						}
 					},
-					required: ["prompt", "responseSchema"],
+					required: ["name"],
 					additionalProperties: false
 				}
-			}] : agentTools;
+			};
+			const allTools = [
+				...agentTools,
+				...skillTool === void 0 ? [] : [skillTool],
+				...currentElicitationMode === "pause" ? [{
+					name: ELICIT_TOOL_NAME,
+					description: "Request external information required to continue this run. Use prompt for explanatory text shown outside the form. Put short field labels in responseSchema property titles and optional field help in property descriptions.",
+					inputSchema: {
+						type: "object",
+						properties: {
+							prompt: {
+								type: "string",
+								description: "Explanatory text for the user; do not duplicate field labels here."
+							},
+							responseSchema: {
+								type: "object",
+								description: "JSON Schema for the expected response. Each property should include a short title for the form label and may include a description for field help."
+							},
+							expiresAt: { type: "string" }
+						},
+						required: ["prompt", "responseSchema"],
+						additionalProperties: false
+					}
+				}] : []
+			];
 			const effectiveLimits = state.checkpoint?.limits ?? combineLimits(agent.limits, request.limits);
 			const maxSteps = effectiveLimits?.maxSteps ?? 8;
 			const maxToolCalls = effectiveLimits?.maxToolCalls ?? 16;
@@ -1287,6 +1313,57 @@ function createAgentEngine(composition, core) {
 					assertContinuationBudget(name, "maxInputTokens", "inputTokens", effectiveLimits?.maxInputTokens, usage);
 					assertContinuationBudget(name, "maxOutputTokens", "outputTokens", effectiveLimits?.maxOutputTokens, usage);
 					if (result.toolCalls.length > maxToolCalls - toolCallCount) throw new Error(`Agent "${name}" exceeded maxToolCalls limit of ${maxToolCalls}`);
+					const loadSkillCall = progressiveSkills.length === 0 ? void 0 : result.toolCalls.find((call) => call.name === LOAD_SKILL_TOOL_NAME);
+					if (loadSkillCall) {
+						if (result.toolCalls.length !== 1) throw new Error(`${LOAD_SKILL_TOOL_NAME} must be the only tool call in a model turn`);
+						if (!loadSkillCall.id?.trim()) throw new Error("Tool call id cannot be empty");
+						if (seenToolCallIds.has(loadSkillCall.id)) throw new Error(`Tool call id "${loadSkillCall.id}" is duplicated in run "${state.run.id}"`);
+						if (toolCallCount + 1 > maxToolCalls) throw new Error(`Agent "${name}" exceeded maxToolCalls limit of ${maxToolCalls}`);
+						const rawInput = toJsonValue(loadSkillCall.input, `Input for tool "${LOAD_SKILL_TOOL_NAME}" must be JSON-serializable`);
+						const skillInput = readSkillInput(rawInput);
+						const skill = progressiveSkills.find((item) => item.name === skillInput.name);
+						if (!skill) throw new Error(`Skill "${skillInput.name}" is not available to agent "${name}"`);
+						seenToolCallIds.add(loadSkillCall.id);
+						messages.push({
+							role: "assistant",
+							content: result.output === void 0 ? "" : serializeValue(result.output, `Model output for agent "${name}" must be serializable`),
+							toolCalls: [{
+								...loadSkillCall,
+								input: rawInput
+							}]
+						});
+						yield await emit("tool.started", {
+							step,
+							toolCallId: loadSkillCall.id,
+							toolName: LOAD_SKILL_TOOL_NAME
+						});
+						let blocks;
+						try {
+							blocks = await abortable(() => skill.load(knowledgeContext(state, inputContent), skillInput.resource), request.signal);
+						} catch (error) {
+							yield await emit("tool.failed", {
+								step,
+								toolCallId: loadSkillCall.id,
+								toolName: LOAD_SKILL_TOOL_NAME,
+								error: toErrorMessage(error)
+							});
+							throw new Error(`Skill provider "${skill.name}" failed: ${toErrorMessage(error)}`, { cause: error });
+						}
+						messages.push({
+							role: "tool",
+							name: LOAD_SKILL_TOOL_NAME,
+							toolCallId: loadSkillCall.id,
+							content: blocks.filter((block) => block.content.trim()).map((block) => `[Skill: ${skill.name}/${block.id}]\n${block.content}`).join("\n\n")
+						});
+						yield await emit("tool.completed", {
+							step,
+							toolCallId: loadSkillCall.id,
+							toolName: LOAD_SKILL_TOOL_NAME
+						});
+						toolCallCount += 1;
+						step += 1;
+						continue;
+					}
 					const elicitationCall = result.toolCalls.find(isElicitationToolCall);
 					if (elicitationCall) {
 						if (!isDurableRunStore(runStore)) throw new FevexRunError("DURABLE_STORE_REQUIRED", "Elicitation requires a DurableRunStore", state.run.id);
@@ -2036,6 +2113,18 @@ function createAgentEngine(composition, core) {
 		cancelStoredAgent
 	};
 }
+function readSkillInput(input) {
+	if (typeof input !== "object" || input === null || Array.isArray(input)) throw new TypeError(`${LOAD_SKILL_TOOL_NAME} input must be an object`);
+	const record = input;
+	const name = record.name;
+	const resource = record.resource;
+	if (typeof name !== "string" || !name.trim()) throw new TypeError(`${LOAD_SKILL_TOOL_NAME} name must be a non-empty string`);
+	if (resource !== void 0 && (typeof resource !== "string" || !resource.trim())) throw new TypeError(`${LOAD_SKILL_TOOL_NAME} resource must be a non-empty string`);
+	return {
+		name: name.trim(),
+		...resource === void 0 ? {} : { resource: resource.trim() }
+	};
+}
 function scopedArtifacts(store, options) {
 	const scopedContext = (value) => {
 		const contextTenant = options.request.context?.attributes?.tenantId;
@@ -4344,4 +4433,4 @@ function createFevex(config) {
 	return createRuntime(createComposition(config));
 }
 //#endregion
-export { ArtifactError, CatalogedArtifactStore, ChannelError, FEVEX_JSON_SCHEMA_PROFILE_VERSION, FevexConfigurationError, FevexRunError, FileSystemArtifactStore, InMemoryArtifactCatalog, InMemoryArtifactStore, InMemoryMemoryStore, InMemoryRunStore, IntegrationError, PROVIDER_REASONING_UNSUPPORTED, PROVIDER_SCHEMA_UNSUPPORTED, RunPausedError, S3ArtifactStore, SCHEMA_NOT_TRANSPORTABLE, SandboxError, artifactTenantId, assertArtifactId, compileFevexJsonSchema, createFevex, createLocalSandbox, createMemoryContextProvider, defineAgent, defineConnection, defineContextProvider, definePolicy, defineSkill, defineTeam, defineTool, defineWorkflow, deliverChannelRun, handleChannelInput, isDurableRunStore, isRetainableRunStore, sandboxResultToJson, toToolSpec, validateFevexJsonSchemaProfile, validateListEventsOptions, validatePurgeRunsOptions };
+export { ArtifactError, CatalogedArtifactStore, ChannelError, FEVEX_JSON_SCHEMA_PROFILE_VERSION, FevexConfigurationError, FevexRunError, FileSystemArtifactStore, InMemoryArtifactCatalog, InMemoryArtifactStore, InMemoryMemoryStore, InMemoryRunStore, IntegrationError, PROVIDER_REASONING_UNSUPPORTED, PROVIDER_SCHEMA_UNSUPPORTED, RunPausedError, S3ArtifactStore, SCHEMA_NOT_TRANSPORTABLE, SandboxError, artifactTenantId, assertArtifactId, compileFevexJsonSchema, createAgentsMdContextProvider, createFevex, createLocalSandbox, createMemoryContextProvider, defineAgent, defineConnection, defineContextProvider, definePolicy, defineSkill, defineTeam, defineTool, defineWorkflow, deliverChannelRun, handleChannelInput, isDurableRunStore, isProgressiveSkillProvider, isRetainableRunStore, loadSkillFile, loadSkillFiles, sandboxResultToJson, toToolSpec, validateFevexJsonSchemaProfile, validateListEventsOptions, validatePurgeRunsOptions };

package/dist/knowledge/index.d.mts

@@ -1,2 +1,2 @@
-import { a as MemoryQuery, c as MemoryWrite, d as defineContextProvider, f as defineSkill, i as KnowledgeContext, l as SkillDefinition, n as ContextBlock, o as MemoryRecord, r as ContextProvider, s as MemoryStore, t as InMemoryMemoryStore, u as createMemoryContextProvider } from "../index-BJktlD4E.mjs";
-export { ContextBlock, ContextProvider, InMemoryMemoryStore, KnowledgeContext, MemoryQuery, MemoryRecord, MemoryStore, MemoryWrite, SkillDefinition, createMemoryContextProvider, defineContextProvider, defineSkill };
+import { _ as defineContextProvider, a as AgentsMdOptions, c as ContextProvider, d as MemoryRecord, f as MemoryStore, g as createMemoryContextProvider, h as SkillDefinition, i as InMemoryMemoryStore, l as KnowledgeContext, m as ProgressiveSkillProvider, n as loadSkillFile, o as createAgentsMdContextProvider, p as MemoryWrite, r as loadSkillFiles, s as ContextBlock, t as LoadSkillFileOptions, u as MemoryQuery, v as defineSkill, y as isProgressiveSkillProvider } from "../index-B0AdFbgr.mjs";
+export { AgentsMdOptions, ContextBlock, ContextProvider, InMemoryMemoryStore, KnowledgeContext, LoadSkillFileOptions, MemoryQuery, MemoryRecord, MemoryStore, MemoryWrite, ProgressiveSkillProvider, SkillDefinition, createAgentsMdContextProvider, createMemoryContextProvider, defineContextProvider, defineSkill, isProgressiveSkillProvider, loadSkillFile, loadSkillFiles };

package/dist/knowledge/index.mjs

@@ -1,39 +1,10 @@
-//#region src/knowledge/in-memory-memory-store.ts
-/** Volatile keyword-search memory store for tests and local development. */
-var InMemoryMemoryStore = class {
-	#records = /* @__PURE__ */ new Map();
-	async search(query, context) {
-		context.signal?.throwIfAborted();
-		const terms = query.query.toLowerCase().split(/\s+/).filter(Boolean);
-		const scored = [...this.#records.values()].filter((record) => matchesScope(record, query)).map((record) => ({
-			record,
-			score: score(record.content, terms)
-		})).filter(({ score }) => !terms.length || score > 0).sort((left, right) => right.score - left.score || right.record.createdAt.localeCompare(left.record.createdAt));
-		return scored.slice(0, query.limit ?? scored.length).map(({ record }) => structuredClone(record));
-	}
-	async write(record, context) {
-		context.signal?.throwIfAborted();
-		const saved = {
-			id: crypto.randomUUID(),
-			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-			...structuredClone(record)
-		};
-		this.#records.set(saved.id, saved);
-		return structuredClone(saved);
-	}
-};
-function matchesScope(record, query) {
-	return matches(record.agentName, query.agentName) && matches(record.sessionId, query.sessionId) && matches(record.namespace, query.namespace) && matches(record.actor?.id, query.actor?.id);
-}
-function matches(left, right) {
-	return right === void 0 || left === void 0 || left === right;
-}
-function score(content, terms) {
-	const text = content.toLowerCase();
-	return terms.reduce((total, term) => total + (text.includes(term) ? 1 : 0), 0);
-}
-//#endregion
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 //#region src/knowledge/knowledge.ts
+function isProgressiveSkillProvider(provider) {
+	const candidate = provider;
+	return typeof candidate.load === "function" && typeof candidate.description === "string";
+}
 function defineContextProvider(provider) {
 	return provider;
 }
@@ -86,4 +57,233 @@ function stringifyKnowledge(value) {
 	return typeof value === "string" ? value : JSON.stringify(value);
 }
 //#endregion
-export { InMemoryMemoryStore, createMemoryContextProvider, defineContextProvider, defineSkill };
+//#region src/knowledge/agents-md.ts
+const DEFAULT_MAX_BYTES$1 = 256 * 1024;
+/**
+* Reads one explicit `AGENTS.md` file as context.
+*
+* Fevex never walks the filesystem looking for `AGENTS.md`; register one
+* provider per file and reference its name from `agent.context`.
+*/
+function createAgentsMdContextProvider(options) {
+	const path = typeof options === "string" ? options : options.path;
+	const name = ((typeof options === "string" ? void 0 : options.name) ?? "agents-md").trim();
+	const maxBytes = (typeof options === "string" ? void 0 : options.maxBytes) ?? DEFAULT_MAX_BYTES$1;
+	if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new TypeError("AGENTS.md maxBytes must be a positive safe integer");
+	if (!name.trim()) throw new TypeError("AGENTS.md provider name cannot be empty");
+	return defineContextProvider({
+		name,
+		async read() {
+			if ((await stat(path)).size > maxBytes) throw new Error(`AGENTS.md file "${path}" exceeds ${maxBytes} bytes`);
+			const content = await readFile(path, "utf8");
+			if (Buffer.byteLength(content) > maxBytes) throw new Error(`AGENTS.md file "${path}" exceeds ${maxBytes} bytes`);
+			return content.trim() ? [{
+				id: "agents-md",
+				content
+			}] : [];
+		}
+	});
+}
+//#endregion
+//#region src/knowledge/in-memory-memory-store.ts
+/** Volatile keyword-search memory store for tests and local development. */
+var InMemoryMemoryStore = class {
+	#records = /* @__PURE__ */ new Map();
+	async search(query, context) {
+		context.signal?.throwIfAborted();
+		const terms = query.query.toLowerCase().split(/\s+/).filter(Boolean);
+		const scored = [...this.#records.values()].filter((record) => matchesScope(record, query)).map((record) => ({
+			record,
+			score: score(record.content, terms)
+		})).filter(({ score }) => !terms.length || score > 0).sort((left, right) => right.score - left.score || right.record.createdAt.localeCompare(left.record.createdAt));
+		return scored.slice(0, query.limit ?? scored.length).map(({ record }) => structuredClone(record));
+	}
+	async write(record, context) {
+		context.signal?.throwIfAborted();
+		const saved = {
+			id: crypto.randomUUID(),
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			...structuredClone(record)
+		};
+		this.#records.set(saved.id, saved);
+		return structuredClone(saved);
+	}
+};
+function matchesScope(record, query) {
+	return matches(record.agentName, query.agentName) && matches(record.sessionId, query.sessionId) && matches(record.namespace, query.namespace) && matches(record.actor?.id, query.actor?.id);
+}
+function matches(left, right) {
+	return right === void 0 || left === void 0 || left === right;
+}
+function score(content, terms) {
+	const text = content.toLowerCase();
+	return terms.reduce((total, term) => total + (text.includes(term) ? 1 : 0), 0);
+}
+//#endregion
+//#region src/knowledge/skill-file.ts
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const DEFAULT_MAX_RESOURCE_BYTES = 256 * 1024;
+const MAX_RESOURCES = 200;
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RESOURCE_DIRECTORIES = [
+	"references",
+	"scripts",
+	"assets"
+];
+/**
+* Loads one explicit `SKILL.md` file.
+*
+* Only `name` and `description` are advertised up front. The body and any
+* files under `references/`, `scripts/` or `assets/` load on demand.
+*/
+async function loadSkillFile(path, options = {}) {
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+	const maxResourceBytes = options.maxResourceBytes ?? DEFAULT_MAX_RESOURCE_BYTES;
+	assertPositiveInteger(maxBytes, "maxBytes");
+	assertPositiveInteger(maxResourceBytes, "maxResourceBytes");
+	const absolute = await realpath(resolve(path));
+	if ((await stat(absolute)).size > maxBytes) throw new Error(`Skill file "${path}" exceeds ${maxBytes} bytes`);
+	const source = (await readFile(absolute, "utf8")).replace(/^\uFEFF/, "");
+	if (Buffer.byteLength(source) > maxBytes) throw new Error(`Skill file "${path}" exceeds ${maxBytes} bytes`);
+	const skill = parseSkillFile(source, path);
+	const root = dirname(absolute);
+	return defineContextProvider({
+		name: skill.name,
+		description: skill.description,
+		async read() {
+			return [{
+				id: `${skill.name}:metadata`,
+				content: skill.description
+			}];
+		},
+		async load(_context, resource) {
+			if (resource !== void 0) return [{
+				id: `${skill.name}:resource:${resource}`,
+				content: await readResource(root, resource, maxResourceBytes)
+			}];
+			const blocks = [{
+				id: `${skill.name}:instructions`,
+				content: skill.instructions
+			}];
+			const resources = await listResources(root);
+			if (resources.length) blocks.push({
+				id: `${skill.name}:resources`,
+				content: [
+					"Resources:",
+					...resources.map((item) => `- ${item.path} (${formatBytes(item.size)})`),
+					"Load one by passing its path as the resource argument.",
+					...resources.some((item) => item.path.startsWith("scripts/")) ? ["Scripts are for reference only and are not executed by this runtime."] : []
+				].join("\n")
+			});
+			return blocks;
+		}
+	});
+}
+/** Loads several explicit `SKILL.md` files; it never scans directories. */
+function loadSkillFiles(paths, options = {}) {
+	return Promise.all(paths.map((path) => loadSkillFile(path, options)));
+}
+function parseSkillFile(source, path) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(source);
+	if (!match) throw new Error(`Skill file "${path}" must start with --- frontmatter`);
+	const fields = parseFrontmatter(match[1]);
+	const name = fields.name?.trim();
+	const description = fields.description?.trim();
+	const instructions = match[2].trim();
+	if (!name) throw new Error(`Skill file "${path}" must define a name`);
+	if (name.length > 64 || !SKILL_NAME.test(name) || name.startsWith("fevex__")) throw new Error(`Skill file "${path}" has an invalid name; use lowercase letters, numbers and hyphens, up to 64 characters`);
+	if (!description) throw new Error(`Skill file "${path}" must define a description`);
+	if (!instructions) throw new Error(`Skill file "${path}" must contain instructions`);
+	return {
+		name,
+		description,
+		instructions
+	};
+}
+function parseFrontmatter(source) {
+	const fields = {};
+	const lines = source.split(/\r?\n/);
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index];
+		if (!line.trim() || line.trimStart().startsWith("#")) continue;
+		if (/^\s/.test(line)) continue;
+		const colon = line.indexOf(":");
+		if (colon <= 0) continue;
+		const key = line.slice(0, colon).trim();
+		let value = line.slice(colon + 1).trim();
+		if (value === "|" || value === ">" || value === "|-" || value === ">-") {
+			const block = [];
+			while (index + 1 < lines.length) {
+				const next = lines[index + 1];
+				if (next.trim() && !/^\s/.test(next)) break;
+				index += 1;
+				block.push(next.replace(/^\s+/, ""));
+			}
+			while (block.length && !block[block.length - 1]) block.pop();
+			value = value.startsWith(">") ? block.filter(Boolean).join(" ") : block.join("\n");
+		} else if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		fields[key] = value;
+	}
+	return fields;
+}
+async function listResources(root) {
+	const resources = [];
+	for (const directory of RESOURCE_DIRECTORIES) await walkResources(resolve(root, directory), root, resources);
+	return resources.sort((left, right) => left.path.localeCompare(right.path)).slice(0, MAX_RESOURCES);
+}
+async function walkResources(directory, root, resources) {
+	if (resources.length >= MAX_RESOURCES) return;
+	let entries;
+	try {
+		entries = await readdir(directory, { withFileTypes: true });
+	} catch (error) {
+		if (isMissing(error)) return;
+		throw error;
+	}
+	for (const entry of entries) {
+		if (resources.length >= MAX_RESOURCES) return;
+		if (entry.isSymbolicLink()) continue;
+		const target = resolve(directory, entry.name);
+		if (entry.isDirectory()) {
+			await walkResources(target, root, resources);
+			continue;
+		}
+		if (!entry.isFile()) continue;
+		const info = await stat(target);
+		resources.push({
+			path: relative(root, target).split("\\").join("/"),
+			size: info.size
+		});
+	}
+}
+async function readResource(root, resource, maxBytes) {
+	if (resource.includes("\0")) throw new Error("Skill resource path is invalid");
+	const requested = resolve(root, resource);
+	const requestedPath = relative(root, requested);
+	if (!requestedPath || requestedPath.startsWith("..") || isAbsolute(requestedPath)) throw new Error(`Skill resource "${resource}" is outside the skill directory`);
+	let target;
+	try {
+		target = await realpath(requested);
+	} catch {
+		throw new Error(`Skill resource "${resource}" was not found`);
+	}
+	const path = relative(root, target);
+	if (!path || path.startsWith("..") || isAbsolute(path)) throw new Error(`Skill resource "${resource}" is outside the skill directory`);
+	const info = await stat(target);
+	if (!info.isFile()) throw new Error(`Skill resource "${resource}" is not a file`);
+	if (info.size > maxBytes) throw new Error(`Skill resource "${resource}" exceeds ${maxBytes} bytes`);
+	const buffer = await readFile(target);
+	if (buffer.includes(0)) throw new Error(`Skill resource "${resource}" is not UTF-8 text`);
+	return buffer.toString("utf8");
+}
+function formatBytes(bytes) {
+	return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} KB`;
+}
+function assertPositiveInteger(value, name) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`Skill ${name} must be a positive safe integer`);
+}
+function isMissing(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+export { InMemoryMemoryStore, createAgentsMdContextProvider, createMemoryContextProvider, defineContextProvider, defineSkill, isProgressiveSkillProvider, loadSkillFile, loadSkillFiles };

package/dist/testing/index.d.mts

@@ -1,9 +1,9 @@
 import { m as ToolCall } from "../types-B8laW1hM.mjs";
 import { a as ModelResult, n as ModelInput, t as ModelGateway } from "../index-BgKFd9yw.mjs";
 import { h as ElicitationRequest, p as DurableRunStore } from "../index-CzAi2Y_Z.mjs";
-import { s as MemoryStore } from "../index-BJktlD4E.mjs";
+import { f as MemoryStore } from "../index-B0AdFbgr.mjs";
 import { d as ToolProvider } from "../index-5p3q2yIp.mjs";
-import { d as ChannelMessage, f as ChannelOutput, o as ChannelElicitationContext, r as ChannelAdapter } from "../index-DVw0zOc_.mjs";
+import { d as ChannelMessage, f as ChannelOutput, o as ChannelElicitationContext, r as ChannelAdapter } from "../index-BTD1c4Ys.mjs";
 //#region src/testing/contracts.d.ts
 interface ModelGatewayContract {
   output?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fevex/core",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "description": "Agent Engineering Framework for code-first, provider-neutral AI agents.",
   "type": "module",
   "license": "Apache-2.0",

package/dist/index-BJktlD4E.d.mts

@@ -1,70 +0,0 @@
-import { l as JsonValue, o as ExecutionContext, s as JsonObject } from "./types-B8laW1hM.mjs";
-import { L as SessionId } from "./index-CzAi2Y_Z.mjs";
-//#region src/knowledge/knowledge.d.ts
-/** Runtime context supplied to knowledge providers and memory stores. */
-interface KnowledgeContext {
-  agentName: string;
-  input: string;
-  sessionId: SessionId;
-  context?: ExecutionContext;
-  signal?: AbortSignal;
-}
-interface ContextBlock {
-  id: string;
-  content: string;
-  metadata?: JsonObject;
-}
-interface ContextProvider {
-  name: string;
-  read(context: KnowledgeContext): Promise<ContextBlock[]>;
-}
-interface MemoryQuery {
-  query: string;
-  limit?: number;
-  agentName?: string;
-  sessionId?: SessionId;
-  namespace?: string;
-  actor?: ExecutionContext['actor'];
-}
-interface MemoryWrite {
-  content: string;
-  agentName?: string;
-  sessionId?: SessionId;
-  namespace?: string;
-  actor?: ExecutionContext['actor'];
-  metadata?: JsonObject;
-}
-interface MemoryRecord extends MemoryWrite {
-  id: string;
-  createdAt: string;
-}
-interface MemoryStore {
-  search(query: MemoryQuery, context: KnowledgeContext): Promise<MemoryRecord[]>;
-  write(record: MemoryWrite, context: KnowledgeContext): Promise<MemoryRecord>;
-}
-interface SkillDefinition {
-  name: string;
-  instructions: string;
-  resources?: Array<string | JsonValue | {
-    id?: string;
-    content: string | JsonValue;
-    metadata?: JsonObject;
-  }>;
-}
-declare function defineContextProvider<T extends ContextProvider>(provider: T): T;
-declare function defineSkill(skill: SkillDefinition): ContextProvider;
-declare function createMemoryContextProvider(options: {
-  name?: string;
-  store: MemoryStore;
-  limit?: number;
-}): ContextProvider;
-//#endregion
-//#region src/knowledge/in-memory-memory-store.d.ts
-/** Volatile keyword-search memory store for tests and local development. */
-declare class InMemoryMemoryStore implements MemoryStore {
-  #private;
-  search(query: MemoryQuery, context: KnowledgeContext): Promise<MemoryRecord[]>;
-  write(record: MemoryWrite, context: KnowledgeContext): Promise<MemoryRecord>;
-}
-//#endregion
-export { MemoryQuery as a, MemoryWrite as c, defineContextProvider as d, defineSkill as f, KnowledgeContext as i, SkillDefinition as l, ContextBlock as n, MemoryRecord as o, ContextProvider as r, MemoryStore as s, InMemoryMemoryStore as t, createMemoryContextProvider as u };