@fevex/core 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/index-26ilbzAs.d.mts

@@ -0,0 +1,50 @@
+import { z as ExactDefinition } from "./index-DHcfIfh-.mjs";
+import { o as ExecutionContext } from "./types-CckDlhYo.mjs";
+import { n as AgentLimits } from "./index-lCCFokc6.mjs";
+import { t as WorkflowAgentResult } from "./index-Btth7rdL.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/teams/team.d.ts
+interface TeamMember {
+  agent: string;
+  role: string;
+  description?: string;
+}
+interface TeamLimits extends AgentLimits {
+  maxDelegations?: number;
+  maxParallel?: number;
+}
+interface TeamDelegation<TInput = unknown> {
+  agent: string;
+  task: TInput;
+  context?: ExecutionContext;
+  limits?: AgentLimits;
+  expectedOutput?: string;
+  constraints?: string[];
+}
+interface TeamHandoff<TInput = unknown> extends Omit<TeamDelegation<TInput>, 'agent'> {
+  from: string;
+  to: string;
+  reason: string;
+}
+type TeamTaskResult<TOutput = unknown> = WorkflowAgentResult<TOutput> & {
+  delegationId: string;
+  agentName: string;
+};
+interface TeamStep {
+  delegate<TInput = unknown, TOutput = unknown>(delegationId: string, delegation: TeamDelegation<TInput>): Promise<TeamTaskResult<TOutput>>;
+  handoff<TInput = unknown, TOutput = unknown>(delegationId: string, handoff: TeamHandoff<TInput>): Promise<TeamTaskResult<TOutput>>;
+  parallel<TTasks extends Record<string, () => Promise<unknown>>>(stepId: string, tasks: TTasks): Promise<{ [TKey in keyof TTasks]: Awaited<ReturnType<TTasks[TKey]>>; }>;
+}
+interface TeamDefinition<TInput = unknown, TOutput = unknown> {
+  name: string;
+  version?: string;
+  supervisor: string;
+  members: TeamMember[];
+  limits?: TeamLimits;
+  inputSchema?: StandardSchemaV1<unknown, TInput>;
+  outputSchema?: StandardSchemaV1<unknown, TOutput>;
+  run(team: TeamStep, input: TInput): TOutput | Promise<TOutput>;
+}
+declare function defineTeam<T extends TeamDefinition>(team: ExactDefinition<T, TeamDefinition>): T;
+//#endregion
+export { TeamMember as a, defineTeam as c, TeamLimits as i, TeamDelegation as n, TeamStep as o, TeamHandoff as r, TeamTaskResult as s, TeamDefinition as t };

package/dist/index-B8EcvWeN.d.mts

@@ -0,0 +1,103 @@
+import { f as RunId, o as ExecutionContext, s as JsonObject, t as AgentEvent } from "./types-CckDlhYo.mjs";
+import { et as SessionId, j as ElicitationRequest, x as AgentRun } from "./index-lCCFokc6.mjs";
+import { t as Fevex } from "./fevex-_KOsOsB8.mjs";
+//#region src/channels/channel.d.ts
+interface ChannelMessage {
+  id: string;
+  deliveryId: string;
+  conversationId: string;
+  threadId?: string;
+  content: string;
+  actor?: ExecutionContext['actor'];
+  metadata?: JsonObject;
+}
+interface ChannelOutput {
+  deliveryId: string;
+  conversationId: string;
+  threadId?: string;
+  content: string;
+  metadata?: JsonObject;
+}
+interface ChannelContext {
+  signal?: AbortSignal;
+}
+interface ChannelElicitationContext extends ChannelContext {
+  /** Stable key for transport-level idempotency, preserved across delivery retries. */
+  deliveryId: string;
+  runId: RunId;
+  sessionId: SessionId;
+  conversationId: string;
+  threadId?: string;
+}
+interface ChannelAdapter<TInput = unknown, TOutput = unknown> {
+  name: string;
+  parse(input: TInput, context: ChannelContext): Promise<ChannelMessage | null>;
+  deliver(output: ChannelOutput, context: ChannelContext): Promise<TOutput>;
+  deliverElicitation?(request: ElicitationRequest, context: ChannelElicitationContext): Promise<TOutput>;
+}
+type ChannelEventType = 'channel.received' | 'channel.delivered' | 'channel.failed';
+type ChannelFailurePhase = 'parse' | 'run' | 'deliver';
+interface ChannelEventBase {
+  id: string;
+  timestamp: string;
+  adapter: string;
+  messageId?: string;
+  deliveryId?: string;
+  conversationId?: string;
+  threadId?: string;
+  runId?: RunId;
+  requestId?: string;
+}
+type ChannelEvent = (ChannelEventBase & {
+  type: 'channel.received';
+  actor?: ExecutionContext['actor'];
+}) | (ChannelEventBase & {
+  type: 'channel.delivered';
+}) | (ChannelEventBase & {
+  type: 'channel.failed';
+  phase: ChannelFailurePhase;
+  error: string;
+});
+type ChannelRunEvent = ChannelEvent | AgentEvent;
+declare class ChannelError extends Error {
+  readonly code: string;
+  readonly safeMessage: string;
+  readonly name = "ChannelError";
+  readonly runId?: RunId;
+  constructor(code: string, safeMessage: string, options?: ErrorOptions & {
+    runId?: RunId;
+  });
+}
+interface ChannelDeliveryOptions<TInput = unknown, TDelivery = unknown> {
+  fevex: Fevex;
+  adapter: ChannelAdapter<TInput, TDelivery>;
+  onEvent?: (event: ChannelEvent) => void;
+  signal?: AbortSignal;
+}
+interface ChannelRunOptions<TInput = unknown, TDelivery = unknown> extends ChannelDeliveryOptions<TInput, TDelivery> {
+  agentName: string;
+  resolveSessionId?: (message: ChannelMessage) => SessionId | undefined | Promise<SessionId | undefined>;
+}
+type ChannelRunResult<TDelivery = unknown> = {
+  ignored: true;
+  events: ChannelRunEvent[];
+} | {
+  ignored: false;
+  message: ChannelMessage;
+  run: AgentRun;
+  output: ChannelOutput;
+  delivery: TDelivery;
+  /** Present when the agent is waiting for external information. */
+  elicitation?: ElicitationRequest;
+  events: ChannelRunEvent[];
+};
+//#endregion
+//#region src/channels/handle-channel-input.d.ts
+/** Parses one channel input, runs the configured agent, and delivers its result or elicitation. */
+declare function handleChannelInput<TInput, TDelivery>(input: TInput, options: ChannelRunOptions<TInput, TDelivery>): Promise<ChannelRunResult<TDelivery>>;
+/** Delivers a stored agent result or elicitation without executing the agent again. */
+declare function deliverChannelRun<TInput, TDelivery>(runId: RunId, message: ChannelMessage, options: ChannelDeliveryOptions<TInput, TDelivery>): Promise<Exclude<ChannelRunResult<TDelivery>, {
+  ignored: true;
+}>>;
+//#endregion
+export { ChannelDeliveryOptions as a, ChannelEvent as c, ChannelMessage as d, ChannelOutput as f, ChannelRunResult as h, ChannelContext as i, ChannelEventType as l, ChannelRunOptions as m, handleChannelInput as n, ChannelElicitationContext as o, ChannelRunEvent as p, ChannelAdapter as r, ChannelError as s, deliverChannelRun as t, ChannelFailurePhase as u };

package/dist/index-BEqYWean.d.mts

@@ -0,0 +1,118 @@
+import { r as ModelMetadata, s as ModelUsage } from "./index-D7r0puBi.mjs";
+import { f as RunId, l as JsonValue, s as JsonObject } from "./types-CckDlhYo.mjs";
+import { et as SessionId } from "./index-lCCFokc6.mjs";
+//#region src/observability/trace.d.ts
+/** Final state represented by an exported run trace. */
+type TraceStatus = 'completed' | 'failed' | 'cancelled';
+/** Kind of run that produced a trace. Absent means `agent` for older traces. */
+type TraceRunKind = 'agent' | 'workflow' | 'team';
+/** Model and tool calls are agent spans; steps belong to workflow and team traces. */
+type TraceSpanKind = 'model' | 'tool' | 'step';
+type TraceContentKind = 'run.output' | 'model.output' | 'error.message';
+interface TraceCost {
+  amount: number;
+  currency: string;
+}
+interface TraceContent {
+  kind: TraceContentKind;
+  value: JsonValue;
+}
+interface TraceAnnotation {
+  name: string;
+  timestamp: string;
+  attributes?: JsonObject;
+}
+interface TraceSpan {
+  id: string;
+  /** Run or span that contains this span. */
+  parentId: string;
+  kind: TraceSpanKind;
+  name: string;
+  startedAt: string;
+  endedAt: string;
+  durationMs: number;
+  status: TraceStatus;
+  attributes: JsonObject;
+  annotations: TraceAnnotation[];
+  usage?: ModelUsage;
+  cost?: TraceCost;
+  content?: TraceContent[];
+}
+interface RunTrace {
+  schemaVersion: '1';
+  /** Absent on traces produced before coordinator traces existed; treat as `agent`. */
+  kind?: TraceRunKind;
+  traceId: string;
+  runId: RunId;
+  sessionId: SessionId;
+  /** Agent, workflow or team name. */
+  agentName: string;
+  /** Run that created this one, when it belongs to a workflow or team. */
+  parentRunId?: RunId;
+  /** Top-level run in the correlation tree. Defaults to `runId`. */
+  rootRunId?: RunId;
+  /** Only present on agent traces. */
+  modelRegistryName?: string;
+  model?: ModelMetadata;
+  startedAt: string;
+  endedAt: string;
+  durationMs: number;
+  status: TraceStatus;
+  attributes: JsonObject;
+  annotations: TraceAnnotation[];
+  spans: TraceSpan[];
+  usage?: ModelUsage;
+  cost?: TraceCost;
+  content?: TraceContent[];
+}
+interface CostCalculatorInput {
+  modelRegistryName: string;
+  model?: ModelMetadata;
+  usage: ModelUsage;
+}
+type CostCalculator = (input: CostCalculatorInput) => TraceCost | undefined;
+interface TraceRedactorInput {
+  kind: TraceContentKind;
+  value: JsonValue;
+}
+type TraceRedactor = (input: TraceRedactorInput) => JsonValue | undefined;
+interface TraceContentPolicy {
+  include: readonly TraceContentKind[];
+  redact?: TraceRedactor;
+}
+interface TraceExporter {
+  export(trace: Readonly<RunTrace>): void | Promise<void>;
+}
+interface TraceExportQueueOptions {
+  /** Traces exported at once. Defaults to 4. */
+  concurrency?: number;
+  /** Traces waiting for an export slot before new traces are dropped. Defaults to 100. */
+  maxQueued?: number;
+  /** Deadline for each exporter call. Defaults to 30 seconds. */
+  timeoutMs?: number;
+  /** Failures retained for the next `flushObservability` call. Defaults to 100. */
+  maxFailures?: number;
+}
+/** Queue and failure counters for the runtime's trace exporters. */
+interface ObservabilityStats {
+  /** Traces exported successfully since the runtime started. */
+  exported: number;
+  /** Failed exports and dropped traces since the runtime started. */
+  failed: number;
+  /** Traces dropped because the queue was full. */
+  dropped: number;
+  /** Traces waiting for an export slot. */
+  queued: number;
+  /** Traces currently being exported. */
+  active: number;
+  /** Failures retained for the next flush. */
+  retainedFailures: number;
+}
+interface ObservabilityOptions {
+  exporters: readonly TraceExporter[];
+  calculateCost?: CostCalculator;
+  content?: TraceContentPolicy;
+  exportQueue?: TraceExportQueueOptions;
+}
+//#endregion
+export { TraceSpanKind as _, RunTrace as a, TraceContentKind as c, TraceExportQueueOptions as d, TraceExporter as f, TraceSpan as g, TraceRunKind as h, ObservabilityStats as i, TraceContentPolicy as l, TraceRedactorInput as m, CostCalculatorInput as n, TraceAnnotation as o, TraceRedactor as p, ObservabilityOptions as r, TraceContent as s, CostCalculator as t, TraceCost as u, TraceStatus as v };

package/dist/index-Btth7rdL.d.mts

@@ -0,0 +1,58 @@
+import { z as ExactDefinition } from "./index-DHcfIfh-.mjs";
+import { f as RunId, l as JsonValue, o as ExecutionContext, s as JsonObject } from "./types-CckDlhYo.mjs";
+import { J as RunRequest, Y as RunResult, et as SessionId, n as AgentLimits } from "./index-lCCFokc6.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/workflows/workflow.d.ts
+/** Context shared with workflow steps and compensation handlers. */
+interface WorkflowStepContext {
+  runId: RunId;
+  sessionId: SessionId;
+  stepId: string;
+  context?: ExecutionContext;
+  signal: AbortSignal;
+}
+interface WorkflowStepOptions<TResult = unknown> {
+  compensate?(result: TResult, context: WorkflowStepContext): void | Promise<void>;
+  /** Metadata persisted with the step and its lifecycle events. */
+  metadata?: JsonObject;
+}
+type WorkflowAgentResult<TOutput = unknown> = Omit<RunResult<TOutput>, 'events'>;
+interface WorkflowEventResult<TPayload extends JsonValue = JsonValue> {
+  payload?: TPayload;
+  actor?: NonNullable<ExecutionContext['actor']>;
+  receivedAt: string;
+}
+interface WorkflowEventDefinition<TPayload extends JsonValue = JsonValue> {
+  payloadSchema?: StandardSchemaV1<unknown, TPayload>;
+  requireActor?: boolean;
+}
+interface WorkflowStep {
+  agent<TInput = unknown, TOutput = unknown>(stepId: string, agentName: string, request: RunRequest<TInput, TOutput>, options?: WorkflowStepOptions<WorkflowAgentResult<TOutput>>): Promise<WorkflowAgentResult<TOutput>>;
+  parallel<TTasks extends Record<string, () => Promise<unknown>>>(stepId: string, tasks: TTasks, options?: WorkflowStepOptions<{ [TKey in keyof TTasks]: Awaited<ReturnType<TTasks[TKey]>>; }>): Promise<{ [TKey in keyof TTasks]: Awaited<ReturnType<TTasks[TKey]>>; }>;
+  waitUntil(stepId: string, resumeAt: string | Date): Promise<void>;
+  waitForEvent<TPayload extends JsonValue = JsonValue>(stepId: string, eventName: string): Promise<WorkflowEventResult<TPayload>>;
+}
+interface WorkflowDefinition<TInput = unknown, TOutput = unknown> {
+  name: string;
+  inputSchema?: StandardSchemaV1<unknown, TInput>;
+  outputSchema?: StandardSchemaV1<unknown, TOutput>;
+  events?: Record<string, WorkflowEventDefinition>;
+  limits?: AgentLimits;
+  /**
+   * Semantic version of `run`, defaults to `"1"`.
+   *
+   * A paused run only resumes against the same version. Bump it whenever a
+   * change to `run` — or to anything `run` calls — would make replaying an
+   * in-flight run incorrect: reordered steps, a reused `stepId` that now means
+   * something else, or a changed business rule.
+   *
+   * The runtime cannot infer this. Hashing the source of `run` would break on
+   * every minified redeploy while still missing changes in the functions `run`
+   * closes over, so the decision belongs to the author.
+   */
+  version?: string;
+  run(step: WorkflowStep, input: TInput): TOutput | Promise<TOutput>;
+}
+declare function defineWorkflow<T extends WorkflowDefinition>(workflow: ExactDefinition<T, WorkflowDefinition>): T;
+//#endregion
+export { WorkflowStep as a, defineWorkflow as c, WorkflowEventResult as i, WorkflowDefinition as n, WorkflowStepContext as o, WorkflowEventDefinition as r, WorkflowStepOptions as s, WorkflowAgentResult as t };

package/dist/{index-QTkd6a7C.d.mts → index-CFzrvDQ0.d.mts}

@@ -1,6 +1,7 @@
-import { f as RunId, l as JsonValue, o as ExecutionContext } from "./index-C_Zpr13f.mjs";
-import { s as ToolRisk } from "./index-CZGyhNIQ.mjs";
-//#region src/policies/index.d.ts
+import { I as ToolRisk } from "./index-DHcfIfh-.mjs";
+import { f as RunId, l as JsonValue, o as ExecutionContext } from "./types-CckDlhYo.mjs";
+//#region src/policies/policy.d.ts
+/** Authorization outcome returned by a policy. */
 type PolicyDecision = 'allow' | 'deny' | 'require_approval';
 interface PolicyAuthorization {
   runId: RunId;

package/dist/index-CIHWc5V1.d.mts

@@ -0,0 +1,116 @@
+import { l as JsonValue, o as ExecutionContext, s as JsonObject } from "./types-CckDlhYo.mjs";
+import { et as SessionId } from "./index-lCCFokc6.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-D7r0puBi.d.mts

@@ -0,0 +1,64 @@
+import { g as ToolSpec, i as AgentMessage, l as JsonValue, m as ToolCall, s as JsonObject } from "./types-CckDlhYo.mjs";
+//#region src/models/embedding.d.ts
+/** Provider-neutral embedding model used to index tools and queries. */
+interface EmbeddingModel {
+  /** Stable identity: provider, model and dimensions. Used in cache keys. */
+  readonly id: string;
+  /** Expected vector dimensions. Optional; inferred from the first result. */
+  readonly dimensions?: number;
+  embed(input: {
+    texts: string[];
+    signal?: AbortSignal;
+  }): Promise<number[][]>;
+}
+//#endregion
+//#region src/models/model.d.ts
+/** Provider-neutral reasoning levels accepted by model gateways. */
+type ReasoningEffort = 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+interface ModelUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+type ToolChoice = 'auto' | 'required' | 'none' | {
+  name: string;
+};
+interface ModelInput {
+  messages: AgentMessage[];
+  tools?: ToolSpec[];
+  toolChoice?: ToolChoice;
+  reasoning?: ReasoningEffort;
+  modelOptions?: Record<string, unknown>;
+  outputSchema?: JsonObject;
+  maxOutputTokens?: number;
+  providerState?: unknown;
+  signal?: AbortSignal;
+}
+interface ModelResult<TOutput = unknown> {
+  output?: TOutput;
+  toolCalls?: ToolCall[];
+  usage?: ModelUsage;
+  providerState?: unknown;
+}
+interface ModelMetadata {
+  provider?: string;
+  model?: string;
+}
+interface ModelGateway {
+  stream(input: ModelInput): AsyncIterable<ModelStreamEvent>;
+  metadata?: ModelMetadata;
+  stateCodec?: {
+    serialize(state: unknown): JsonValue;
+    restore(state: JsonValue): unknown;
+  };
+}
+type ModelStreamEvent<TOutput = unknown> = {
+  type: 'output.delta';
+  delta: string;
+} | {
+  type: 'completed';
+  result: ModelResult<TOutput>;
+};
+type ModelRef = string | ModelGateway;
+//#endregion
+export { ModelResult as a, ReasoningEffort as c, ModelRef as i, ToolChoice as l, ModelInput as n, ModelStreamEvent as o, ModelMetadata as r, ModelUsage as s, ModelGateway as t, EmbeddingModel as u };