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

package/dist/index-DHcfIfh-.d.mts

@@ -0,0 +1,224 @@
+import { u as EmbeddingModel } from "./index-D7r0puBi.mjs";
+import { F as ArtifactStore, f as RunId, g as ToolSpec, h as ToolEventSource, l as JsonValue, o as ExecutionContext, s as JsonObject } from "./types-CckDlhYo.mjs";
+import { i as SandboxCapabilities, r as Sandbox } from "./index-DUhNa7IR.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/internal/exact-definition.d.ts
+type ExactDefinition<TInput, TShape> = TInput & { readonly [TKey in Exclude<keyof TInput, keyof TShape>]: never; };
+//#endregion
+//#region src/tools/tool.d.ts
+interface ToolExecutionContext {
+  runId: RunId;
+  toolCallId: string;
+  attempt: number;
+  idempotencyKey: string;
+  getCredential(name: string): Promise<string>;
+  sandbox?: Sandbox;
+  /** Optional artifact store; writes emit `artifact.created`. */
+  artifacts?: ArtifactStore;
+  context?: ExecutionContext;
+  signal?: AbortSignal;
+}
+type ToolRisk = 'read' | 'write' | 'sensitive' | 'destructive';
+type ToolApproval = 'never' | 'required';
+type ToolIdempotency = 'none' | 'keyed';
+interface ToolRetryPolicy {
+  maxAttempts: number;
+  backoffMs: number;
+  maxBackoffMs?: number;
+}
+interface ToolDefinition<TInput = unknown, TOutput = unknown> {
+  name: string;
+  label?: string;
+  description?: string;
+  inputSchema?: StandardSchemaV1<unknown, TInput>;
+  outputSchema?: StandardSchemaV1<unknown, TOutput>;
+  inputJsonSchema?: JsonObject;
+  outputJsonSchema?: JsonObject;
+  risk?: ToolRisk;
+  approval?: ToolApproval;
+  idempotency?: ToolIdempotency;
+  retry?: ToolRetryPolicy;
+  credentials?: string[];
+  sandbox?: SandboxCapabilities;
+  /** Maximum serialized bytes for one result. Use an artifact or `false` to opt out of the default cap. */
+  maxResultBytes?: number | false;
+  source?: ToolEventSource;
+  resolve?: (context?: ToolProviderContext) => Promise<ToolProviderTool | undefined>;
+  execute(input: TInput, context: ToolExecutionContext): TOutput | Promise<TOutput>;
+}
+type ToolWithSchemas<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1> = Omit<ToolDefinition<StandardSchemaV1.InferOutput<TInputSchema>, StandardSchemaV1.InferOutput<TOutputSchema>>, 'inputSchema' | 'outputSchema'> & {
+  inputSchema: TInputSchema;
+  outputSchema: TOutputSchema;
+};
+type ToolWithInputSchema<TInputSchema extends StandardSchemaV1> = Omit<ToolDefinition<StandardSchemaV1.InferOutput<TInputSchema>, unknown>, 'inputSchema'> & {
+  inputSchema: TInputSchema;
+};
+declare function defineTool<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TDefinition extends ToolWithSchemas<TInputSchema, TOutputSchema>>(tool: ToolWithSchemas<TInputSchema, TOutputSchema> & ExactDefinition<TDefinition, ToolWithSchemas<TInputSchema, TOutputSchema>>): TDefinition;
+declare function defineTool<TInputSchema extends StandardSchemaV1, TDefinition extends ToolWithInputSchema<TInputSchema>>(tool: ToolWithInputSchema<TInputSchema> & ExactDefinition<TDefinition, ToolWithInputSchema<TInputSchema>>): TDefinition;
+declare function defineTool<TDefinition extends ToolDefinition>(tool: ToolDefinition & ExactDefinition<TDefinition, ToolDefinition>): TDefinition;
+declare function toToolSpec(tool: ToolDefinition, inputSchema?: JsonObject): ToolSpec;
+type ToolResult = JsonValue;
+//#endregion
+//#region src/tools/connection.d.ts
+interface ToolProviderContext {
+  runId?: RunId;
+  toolCallId?: string;
+  attempt?: number;
+  idempotencyKey?: string;
+  context?: ExecutionContext;
+  signal?: AbortSignal;
+}
+interface ToolProviderTool {
+  name: string;
+  label?: string;
+  description?: string;
+  inputSchema?: JsonObject;
+  outputSchema?: JsonObject;
+}
+interface ToolProvider {
+  kind?: string;
+  listTools(context?: ToolProviderContext): Promise<ToolProviderTool[]>;
+  callTool(name: string, input: JsonValue, context: ToolProviderContext): JsonValue | Promise<JsonValue>;
+  close?(): Promise<void>;
+}
+type IntegrationErrorCategory = 'auth' | 'validation' | 'network' | 'remote' | 'timeout';
+/** Safe, provider-neutral error surfaced by connection adapters. */
+declare class IntegrationError extends Error {
+  readonly code: string;
+  readonly category: IntegrationErrorCategory;
+  readonly retryable: boolean;
+  readonly safeMessage: string;
+  readonly name = "IntegrationError";
+  constructor(code: string, category: IntegrationErrorCategory, retryable: boolean, safeMessage: string, options?: ErrorOptions & {
+    source?: ToolEventSource;
+  });
+  readonly source?: ToolEventSource;
+}
+interface ConnectionToolPolicy {
+  label?: string;
+  description?: string;
+  inputSchema?: JsonObject;
+  outputSchema?: JsonObject;
+  risk?: ToolRisk;
+  approval?: ToolApproval;
+  idempotency?: ToolIdempotency;
+  retry?: ToolRetryPolicy;
+  credentials?: string[];
+  maxResultBytes?: number | false;
+}
+interface ConnectionDefinition {
+  name: string;
+  provider: ToolProvider;
+  allowlist?: readonly string[];
+  tools?: {
+    allow: readonly string[];
+  } | Record<string, ConnectionToolPolicy>;
+  timeoutMs?: number;
+}
+declare function defineConnection<TDefinition extends ConnectionDefinition>(connection: TDefinition): TDefinition;
+//#endregion
+//#region src/tools/json-schema-profile.d.ts
+declare const FEVEX_JSON_SCHEMA_PROFILE_VERSION = "1";
+interface FevexJsonSchemaProfileLimits {
+  maxBytes?: number;
+  maxDepth?: number;
+  maxNodes?: number;
+  maxProperties?: number;
+}
+interface FevexJsonSchemaProfileOptions {
+  rootDocument?: JsonObject;
+  requireRootObject?: boolean;
+  limits?: FevexJsonSchemaProfileLimits;
+}
+interface FevexJsonSchemaValidator {
+  schema: JsonObject;
+  validate(value: unknown, path?: string): JsonValue;
+}
+declare function validateFevexJsonSchemaProfile(schema: JsonObject, options?: FevexJsonSchemaProfileOptions): JsonObject;
+declare function compileFevexJsonSchema(schema: JsonObject, options?: FevexJsonSchemaProfileOptions): FevexJsonSchemaValidator;
+//#endregion
+//#region src/tools/tool-index.d.ts
+/** Cache of tool embedding vectors keyed by content hash. */
+interface ToolEmbeddingCache {
+  get(key: string): number[] | undefined | Promise<number[] | undefined>;
+  set(key: string, vector: number[]): void | Promise<void>;
+  /** Optional batch read for durable caches with network/database latency. */
+  getMany?(keys: readonly string[]): Array<number[] | undefined> | Promise<Array<number[] | undefined>>;
+  /** Optional batch write for durable caches with network/database latency. */
+  setMany?(entries: ReadonlyArray<{
+    key: string;
+    vector: number[];
+  }>): void | Promise<void>;
+}
+interface InMemoryToolEmbeddingCacheOptions {
+  /** Maximum cached vectors. Defaults to 1,000. */
+  maxEntries?: number;
+}
+/** Bounded LRU cache for tool embeddings. */
+declare class InMemoryToolEmbeddingCache implements ToolEmbeddingCache {
+  #private;
+  constructor(options?: InMemoryToolEmbeddingCacheOptions);
+  get size(): number;
+  get(key: string): number[] | undefined;
+  set(key: string, vector: number[]): void;
+  getMany(keys: readonly string[]): Array<number[] | undefined>;
+  setMany(entries: ReadonlyArray<{
+    key: string;
+    vector: number[];
+  }>): void;
+}
+interface ToolEmbeddingIndexEntry {
+  tool: ToolSpec;
+  vector: number[];
+}
+interface ToolEmbeddingIndex {
+  modelId: string;
+  dimensions: number;
+  entries: ToolEmbeddingIndexEntry[];
+}
+interface BuildToolEmbeddingIndexOptions {
+  tools: readonly ToolSpec[];
+  embeddings: EmbeddingModel;
+  cache?: ToolEmbeddingCache;
+  /** Texts per embedding request. Defaults to 64. */
+  batchSize?: number;
+  signal?: AbortSignal;
+}
+interface ToolEmbeddingMatch {
+  tool: ToolSpec;
+  score: number;
+}
+/**
+ * Builds or refreshes a semantic index for a tool catalog. The content key is
+ * `sha256(embeddingModel.id + text)`, so changing the model or the tool text
+ * invalidates the cached vector.
+ */
+declare function buildToolEmbeddingIndex(options: BuildToolEmbeddingIndexOptions): Promise<ToolEmbeddingIndex>;
+/** Returns cosine matches above `minScore`, ordered by score. */
+declare function searchToolEmbeddingIndex(index: ToolEmbeddingIndex, query: readonly number[], limit: number, minScore?: number): ToolEmbeddingMatch[];
+/** Canonical text indexed for one tool: name, description and schema keywords. */
+declare function toolEmbeddingText(tool: ToolSpec): string;
+/** Extracts property names, descriptions, titles, required fields and enum values. */
+declare function schemaKeywords(schema: JsonObject | undefined): string;
+/** Stable content key for one embedding model and tool text. */
+declare function toolEmbeddingKey(modelId: string, text: string): Promise<string>;
+declare function cosineSimilarity(left: readonly number[], right: readonly number[]): number;
+//#endregion
+//#region src/tools/tool-reranker.d.ts
+/** One tool candidate passed to a reranker. */
+interface ToolSearchCandidate {
+  tool: ToolSpec;
+  /** Lexical/vector fusion score. Rerankers may ignore it. */
+  score: number;
+}
+/** Optional second-stage ranking over the top lexical/vector candidates. */
+interface ToolReranker {
+  rerank(input: {
+    query: string;
+    tools: ToolSearchCandidate[];
+    limit: number;
+    signal?: AbortSignal;
+  }): Promise<ToolSearchCandidate[]>;
+}
+//#endregion
+export { ToolApproval as A, ConnectionToolPolicy as C, ToolProviderContext as D, ToolProvider as E, ToolRetryPolicy as F, ToolRisk as I, defineTool as L, ToolExecutionContext as M, ToolIdempotency as N, ToolProviderTool as O, ToolResult as P, toToolSpec as R, ConnectionDefinition as S, IntegrationErrorCategory as T, FevexJsonSchemaProfileLimits as _, InMemoryToolEmbeddingCacheOptions as a, compileFevexJsonSchema as b, ToolEmbeddingIndexEntry as c, cosineSimilarity as d, schemaKeywords as f, FEVEX_JSON_SCHEMA_PROFILE_VERSION as g, toolEmbeddingText as h, InMemoryToolEmbeddingCache as i, ToolDefinition as j, defineConnection as k, ToolEmbeddingMatch as l, toolEmbeddingKey as m, ToolSearchCandidate as n, ToolEmbeddingCache as o, searchToolEmbeddingIndex as p, BuildToolEmbeddingIndexOptions as r, ToolEmbeddingIndex as s, ToolReranker as t, buildToolEmbeddingIndex as u, FevexJsonSchemaProfileOptions as v, IntegrationError as w, validateFevexJsonSchemaProfile as x, FevexJsonSchemaValidator as y, ExactDefinition as z };

package/dist/index-DUhNa7IR.d.mts

@@ -0,0 +1,73 @@
+import { f as RunId, l as JsonValue, o as ExecutionContext } from "./types-CckDlhYo.mjs";
+//#region src/sandbox/sandbox.d.ts
+interface SandboxCapabilities {
+  process?: {
+    commands?: readonly string[];
+    timeoutMs?: number;
+  };
+  filesystem?: {
+    cwd?: string;
+    read?: readonly string[];
+    write?: readonly string[];
+  };
+  network?: false | {
+    allow?: readonly string[];
+  };
+  resources?: {
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+  };
+}
+interface SandboxRunRequest {
+  command: string;
+  args?: readonly string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  input?: string;
+  timeoutMs?: number;
+  maxOutputBytes?: number;
+  capabilities?: SandboxCapabilities;
+  runId?: RunId;
+  toolCallId?: string;
+  attempt?: number;
+  idempotencyKey?: string;
+  context?: ExecutionContext;
+  signal?: AbortSignal;
+}
+interface SandboxRunResult {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+  timedOut: boolean;
+}
+interface Sandbox {
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+  /**
+   * Release per-run resources (containers, workspaces) after a terminal run.
+   * Paired runs may keep their resources so a resume can continue.
+   */
+  cleanupRun?(runId: RunId): void | Promise<void>;
+  /** Release provider-wide resources during runtime shutdown. */
+  dispose?(): void | Promise<void>;
+}
+declare class SandboxError extends Error {
+  readonly code: string;
+  readonly safeMessage: string;
+  readonly name = "SandboxError";
+  constructor(code: string, safeMessage: string, options?: ErrorOptions);
+}
+declare function sandboxResultToJson(result: SandboxRunResult): JsonValue;
+//#endregion
+//#region src/sandbox/local-sandbox.d.ts
+interface LocalSandboxOptions {
+  rootDir: string;
+  commands: readonly string[];
+  defaultTimeoutMs?: number;
+  maxOutputBytes?: number;
+  env?: Record<string, string>;
+}
+/** Creates a subprocess sandbox restricted to a root directory and command allowlist. */
+declare function createLocalSandbox(options: LocalSandboxOptions): Sandbox;
+//#endregion
+export { SandboxError as a, sandboxResultToJson as c, SandboxCapabilities as i, createLocalSandbox as n, SandboxRunRequest as o, Sandbox as r, SandboxRunResult as s, LocalSandboxOptions as t };