libfx 0.0.13 → 0.0.14

package/types/mcp.d.ts

@@ -0,0 +1,46 @@
+// `libfx/mcp` (mcp.js): tools and instructions from a host-owned MCP client.
+import type { FxAgentHostTool } from "./libfx.cjs";
+
+/**
+ * The parts of an MCP client the adapter calls, with the MCP TypeScript SDK
+ * v1 signatures. Transport, authentication, elicitation, and cleanup stay
+ * with the host.
+ */
+export interface McpClient {
+  /** Resolves to the tools array or `{ tools, nextCursor? }`. */
+  listTools(params?: { cursor: string }): unknown;
+  /** Called with the tool's original name, the model's arguments, and the turn's `signal` in `options`. */
+  callTool(params: { name: string; arguments?: unknown; _meta?: { "libfx/correlationId": string } }, resultSchema?: unknown, options?: { signal?: AbortSignal }): unknown;
+  getServerVersion?(): { name?: string } | undefined;
+  /** Required when `resources` is given. */
+  readResource?(params: { uri: string }): unknown;
+  /** Required when `prompts` is given. */
+  getPrompt?(params: { name: string; arguments?: Record<string, string> }): unknown;
+  close?(): unknown;
+}
+
+/** Options for `createMcpAdapter()`. */
+export interface McpAdapterOptions {
+  /** Local server identity for hook events. Defaults to the client's reported server name, or null. */
+  serverName?: string;
+  /** Send an opaque UUID as `_meta["libfx/correlationId"]`. Default false; doesn't request MCP progress notifications. */
+  propagateCorrelation?: boolean;
+  /** Prepended to each tool name: letters, digits, `_`, or `-`. */
+  prefix?: string;
+  /** Resource URIs whose text becomes instructions. */
+  resources?: readonly string[];
+  /** Prompts whose text becomes instructions: a name, or a `getPrompt()` request. */
+  prompts?: readonly (string | { name: string; arguments?: Record<string, string> })[];
+}
+
+/** What `createMcpAdapter()` resolves to. Pass `tools` and `instructions` to the agent. */
+export interface McpAdapter {
+  /** Each tool has `idempotent: false`; set it to `true` on a tool known to be safe to run twice. */
+  tools: FxAgentHostTool[];
+  instructions: string;
+  /** Closes the client once. */
+  close(): Promise<void>;
+}
+
+/** Adapts a host-owned MCP client into agent tools and instructions. */
+export declare function createMcpAdapter(client: McpClient, options?: McpAdapterOptions): Promise<McpAdapter>;

package/types/node.d.cts

@@ -0,0 +1,165 @@
+// `libfx` and `libfx/node` on Node.js, for `require` (node.cjs). The ESM entry,
+// node.d.ts, re-exports this file: node.cjs is built from node.js.
+import type {
+  FxAgent,
+  FxAgentOptions,
+  FxBackendInfo,
+  FxBackendInfoOptions,
+  FxEngine,
+  FxEngineOptions,
+  FxNodeBackendOptions,
+  FxTerminal,
+  FxTerminalOptions,
+} from "./libfx.cjs";
+
+export {
+  createMemoryPersistence,
+  encodeXtermKeyEvent,
+  FxFencedError,
+  FxJournalVersionError,
+  fxSdkApiVersion,
+  listModels,
+  memory,
+  supportsJspi,
+  wakeHandler,
+  xtermAdapter,
+} from "./libfx.cjs";
+
+export type {
+  Durability,
+  FxAccepted,
+  FxAgent,
+  FxAgentEvent,
+  FxAgentHostTool,
+  FxAgentKeyedTool,
+  FxAgentOptions,
+  FxAgentTool,
+  FxAgentTools,
+  FxApiKeyCredentials,
+  FxBackendAttempt,
+  FxBackendChoice,
+  FxBackendInfo,
+  FxBackendInfoOptions,
+  FxBackendReason,
+  FxBackendReasonCode,
+  FxBytes,
+  FxCheckpointMeta,
+  FxCodexProvider,
+  FxCustomProvider,
+  FxCustomProviderDefinition,
+  FxCustomProviderModel,
+  FxEffort,
+  FxEngine,
+  FxEngineEvent,
+  FxEngineOptions,
+  FxEnginePromptOptions,
+  FxEngineStorage,
+  FxEngineTurn,
+  FxEngineTurnResult,
+  FxErrorSummary,
+  FxFetch,
+  FxFollowUp,
+  FxGatewayProvider,
+  FxGrokProvider,
+  FxHostTool,
+  FxHooks,
+  FxHookEvent,
+  FxHookMessage,
+  FxHookToolCall,
+  FxIdleResult,
+  FxImageBlock,
+  FxJsonSchema,
+  FxKeyedTool,
+  FxKeyEventLike,
+  FxListModelsOptions,
+  FxModelCatalogEntry,
+  FxModelChoice,
+  FxModelOptions,
+  FxNodeBackendOptions,
+  FxNodeWasmSource,
+  FxOnAmbiguous,
+  FxPromptBlock,
+  FxPromptInput,
+  FxPromptOptions,
+  FxProviderCredentials,
+  FxProviderTool,
+  FxResizedImage,
+  FxResourceBlock,
+  FxResumeOptions,
+  FxResumeTurn,
+  FxSession,
+  FxSessionEvent,
+  FxSessionImageBlock,
+  FxSessionOptions,
+  FxSessionPromptInput,
+  FxSessionTurnEvent,
+  FxSharedOptions,
+  FxSteer,
+  FxSteerOptions,
+  FxSteered,
+  FxSteeringInput,
+  FxStopReason,
+  FxStreamLine,
+  FxTerminal,
+  FxTerminalAdapter,
+  FxTerminalEvent,
+  FxTerminalOptions,
+  FxTextBlock,
+  FxTool,
+  FxToolContext,
+  FxToolObservation,
+  FxWaitRequest,
+  FxWaitResponse,
+  FxToolImage,
+  FxToolResult,
+  FxTools,
+  FxTurn,
+  FxTurnEvent,
+  FxTurnResult,
+  FxTurnView,
+  FxUsage,
+  FxWasmModule,
+  FxWorkspace,
+  FxWorkspaceExecResult,
+  FxXtermLike,
+  JournalRecord,
+  JsonObject,
+  JsonValue,
+  MemoryOptions,
+  MemoryPersistence,
+  Persistence,
+  PersistenceLoadResult,
+} from "./libfx.cjs";
+
+/** Options for `createFxAgent()` on Node.js. */
+export type FxNodeAgentOptions = FxAgentOptions & FxNodeBackendOptions;
+
+/** Options for `createFxEngine()` on Node.js. */
+export type FxNodeEngineOptions = FxEngineOptions & FxNodeBackendOptions;
+
+/** Options for `createFxTerminal()` on Node.js. */
+export type FxNodeTerminalOptions = FxTerminalOptions & FxNodeBackendOptions;
+
+/**
+ * An agent whose sessions survive crashes, timeouts, and redeployments. It
+ * returns at once and does no I/O until a session runs a turn. Without
+ * `durability`, sessions live in Vercel's World on Vercel and in local files
+ * elsewhere.
+ */
+export declare function createFxAgent(options?: FxNodeAgentOptions): FxAgent;
+
+/**
+ * The kernel under `createFxAgent()`: one conversation, held in the memory of
+ * the process that runs it. `apiKey` is required, and it resolves once its
+ * backend has loaded.
+ */
+export declare function createFxEngine(options: FxNodeEngineOptions): Promise<FxEngine>;
+
+/** The interactive terminal harness. */
+export declare function createFxTerminal(options: FxNodeTerminalOptions): Promise<FxTerminal>;
+
+/** Inspects backend availability without creating an agent or terminal. */
+export declare function getBackendInfo(options?: FxBackendInfoOptions): Promise<FxBackendInfo>;
+
+/** The version of the libfx agent API. */
+export declare const libfxApiVersion: 3;

package/types/node.d.ts

@@ -0,0 +1,3 @@
+// `libfx` and `libfx/node` on Node.js, for `import` (node.js). The CommonJS
+// entry, node.cjs, is built from node.js, so both declare the same exports.
+export * from "./node.cjs";

package/types/skills-node.d.ts

@@ -0,0 +1,25 @@
+// `libfx/skills/node` (skills-node.js): loads a `SKILL.md` explicitly in
+// Node.js or Bun.
+import type { FxAgentTool } from "./libfx.cjs";
+import type { SkillRecord, SkillResource } from "./skills.js";
+
+export { createSkillsAdapter } from "./skills.js";
+export type { SkillRecord, SkillResource, SkillsAdapter } from "./skills.js";
+
+/** Options for `loadSkillFile()`. */
+export interface LoadSkillFileOptions {
+  /** Replaces `fs.promises.readFile`. */
+  readFile?: (path: string, encoding: "utf8") => string | Promise<string>;
+  resources?: readonly SkillResource[];
+  tools?: readonly FxAgentTool[];
+}
+
+/** A skill read from a `SKILL.md`: its frontmatter `name` and `description`, and its body as instructions. */
+export interface LoadedSkill extends SkillRecord {
+  description: string;
+  resources: readonly SkillResource[];
+  tools: readonly FxAgentTool[];
+}
+
+/** Reads one `SKILL.md`. Without a frontmatter `name`, the file name is the skill's name. */
+export declare function loadSkillFile(path: string, options?: LoadSkillFileOptions): Promise<LoadedSkill>;

package/types/skills.d.ts

@@ -0,0 +1,28 @@
+// `libfx/skills` (skills.js): instructions and tools from already-loaded
+// skill records.
+import type { FxAgentTool } from "./libfx.cjs";
+
+/** A resource whose text joins its skill's instructions. */
+export interface SkillResource {
+  uri: string;
+  text: string;
+}
+
+/** An already-loaded skill. */
+export interface SkillRecord {
+  name: string;
+  instructions: string;
+  description?: string;
+  resources?: readonly SkillResource[];
+  /** Each host tool sets `idempotent`, as `createFxAgent()` requires. */
+  tools?: readonly FxAgentTool[];
+}
+
+/** What `createSkillsAdapter()` returns: spread it into the agent options. */
+export interface SkillsAdapter {
+  instructions: string;
+  tools: FxAgentTool[];
+}
+
+/** Turns up to 64 skill records into instructions and tools. */
+export declare function createSkillsAdapter(records: readonly SkillRecord[]): SkillsAdapter;

package/types/wasm.d.ts

@@ -0,0 +1,106 @@
+// `libfx/wasm` (fx-sdk.js): the WebAssembly SDK with no packaged asset paths,
+// so every factory takes its `wasm` explicitly.
+import type { FxEngine, FxEngineOptions, FxTerminal, FxTerminalOptions, FxWasmSource } from "./libfx.cjs";
+
+export {
+  createMemoryPersistence,
+  encodeXtermKeyEvent,
+  FxFencedError,
+  FxJournalVersionError,
+  fxSdkApiVersion,
+  listModels,
+  supportsJspi,
+  xtermAdapter,
+} from "./libfx.cjs";
+
+export type {
+  FxApiKeyCredentials,
+  FxBytes,
+  FxCheckpointMeta,
+  FxCodexProvider,
+  FxCustomProvider,
+  FxCustomProviderDefinition,
+  FxCustomProviderModel,
+  FxEffort,
+  FxEngine,
+  FxEngineEvent,
+  FxEngineOptions,
+  FxEnginePromptOptions,
+  FxEngineStorage,
+  FxEngineTurn,
+  FxEngineTurnResult,
+  FxErrorSummary,
+  FxFetch,
+  FxFollowUp,
+  FxGatewayProvider,
+  FxGrokProvider,
+  FxHostTool,
+  FxHooks,
+  FxHookEvent,
+  FxHookMessage,
+  FxHookToolCall,
+  FxImageBlock,
+  FxJsonSchema,
+  FxKeyedTool,
+  FxKeyEventLike,
+  FxListModelsOptions,
+  FxModelCatalogEntry,
+  FxModelChoice,
+  FxModelOptions,
+  FxOnAmbiguous,
+  FxPromptBlock,
+  FxPromptInput,
+  FxProviderCredentials,
+  FxProviderTool,
+  FxResizedImage,
+  FxResourceBlock,
+  FxResumeOptions,
+  FxSharedOptions,
+  FxSteer,
+  FxSteeringInput,
+  FxStopReason,
+  FxTerminal,
+  FxTerminalAdapter,
+  FxTerminalEvent,
+  FxTerminalOptions,
+  FxTextBlock,
+  FxTool,
+  FxToolContext,
+  FxToolObservation,
+  FxWaitRequest,
+  FxWaitResponse,
+  FxToolImage,
+  FxToolResult,
+  FxTools,
+  FxTurnEvent,
+  FxUsage,
+  FxWasmModule,
+  FxWasmSource,
+  FxWorkspace,
+  FxWorkspaceExecResult,
+  FxXtermLike,
+  JournalRecord,
+  JsonObject,
+  JsonValue,
+  MemoryPersistence,
+  Persistence,
+  PersistenceLoadResult,
+} from "./libfx.cjs";
+
+/** Options for `createFxEngine()` from `libfx/wasm`. */
+export type FxWasmEngineOptions = FxEngineOptions & {
+  /** The `fx-core.wasm` asset. */
+  wasm: FxWasmSource;
+};
+
+/** Options for `createFxTerminal()` from `libfx/wasm`. */
+export type FxWasmTerminalOptions = FxTerminalOptions & {
+  /** The `fx-term.wasm` asset. */
+  wasm: FxWasmSource;
+};
+
+/** One session on one fx core, with no durability of its own. Requires JSPI. */
+export declare function createFxEngine(options: FxWasmEngineOptions): Promise<FxEngine>;
+
+/** The interactive terminal harness on WebAssembly. Requires JSPI. */
+export declare function createFxTerminal(options: FxWasmTerminalOptions): Promise<FxTerminal>;