@langchain/quickjs 0.2.5 → 0.3.0

package/dist/index.d.ts

@@ -1,40 +1,26 @@
 import * as _$langchain from "langchain";
 import { AgentMiddleware } from "langchain";
 import { z } from "zod/v4";
-import { AnyBackendProtocol, BackendFactory, BackendProtocolV2 } from "deepagents";
+import { AnyBackendProtocol, BackendFactory, SkillMetadata } from "deepagents";
 import { StructuredToolInterface } from "@langchain/core/tools";
 
 //#region src/types.d.ts
 /**
- * Configuration options for the QuickJS REPL middleware.
+ * Configuration options for the REPL middleware.
  */
-interface QuickJSMiddlewareOptions {
-  /**
-   * Backend for file I/O (readFile/writeFile) inside the REPL.
-   * Accepts a AnyBackendProtocol instance or a BackendFactory function.
-   * Defaults to StateBackend (reads/writes LangGraph checkpoint state).
-   * @default StateBackend
-   */
-  backend?: AnyBackendProtocol | BackendFactory;
+interface REPLMiddlewareOptions {
   /**
    * Enable programmatic tool calling from within the REPL.
    *
-   * - `false` — disabled (default)
-   * - `true` — expose all agent tools except standard vfs tools
-   * - `string[]` — expose only these tools (alias for `{ include }`)
-   * - `{ include: string[] }` — expose only these tools
-   * - `{ exclude: string[] }` — expose all agent tools except these
+   * Array of tools to expose; strings are resolved from agent tools, instances
+   * are injected directly without needing to be registered on the agent.
    *
-   * @default false
+   * Omit to disable PTC entirely (default).
    */
-  ptc?: boolean | string[] | {
-    include: string[];
-  } | {
-    exclude: string[];
-  };
+  ptc?: (string | StructuredToolInterface)[];
   /**
    * Memory limit in bytes.
-   * @default 52428800 (50MB)
+   * @default 67108864 (64MB)
    */
   memoryLimitBytes?: number;
   /**
@@ -45,7 +31,7 @@ interface QuickJSMiddlewareOptions {
   /**
    * Execution timeout in milliseconds per evaluation.
    * Set to a negative value to disable the timeout entirely.
-   * @default 30000 (30s)
+   * @default 5000 (5s)
    */
   executionTimeoutMs?: number;
   /**
@@ -53,6 +39,45 @@ interface QuickJSMiddlewareOptions {
    * @default null (uses built-in prompt)
    */
   systemPrompt?: string | null;
+  /**
+   * Backend the REPL reads skill module sources from. When provided alongside
+   * `SkillsMiddleware`, skills with a `module:` key become dynamic-importable.
+   */
+  skillsBackend?: AnyBackendProtocol | BackendFactory;
+  /**
+   * Maximum number of `tools.*` bridge calls allowed per `eval()` invocation.
+   *
+   * Each call to any function in the `tools` namespace decrements the counter.
+   * Once exhausted the next call rejects with a `PTCCallBudgetExceeded` error.
+   * The budget resets to this value at the start of every new `eval()` call.
+   *
+   * Set to `null` to disable the limit entirely (unsafe — increases DoS risk).
+   * Must be >= 1 when provided as a number.
+   *
+   * @default 256
+   */
+  maxPtcCalls?: number | null;
+  /**
+   * Maximum characters to retain from console output per evaluation.
+   * Output exceeding this limit is dropped at capture time and a
+   * `[truncated N chars]` marker is appended to the tool response.
+   * The same limit also caps result and error strings in the formatted output.
+   *
+   * @default 4000
+   */
+  maxResultChars?: number;
+  /**
+   * Name of the tool exposed to the model.
+   * @default "eval"
+   */
+  toolName?: string;
+  /**
+   * If true, install a `console` object that buffers `console.log/warn/error`
+   * calls and emits them alongside the result. If false, console output is
+   * silently discarded.
+   * @default true
+   */
+  captureConsole?: boolean;
 }
 /**
  * Options for creating a ReplSession.
@@ -60,8 +85,11 @@ interface QuickJSMiddlewareOptions {
 interface ReplSessionOptions {
   memoryLimitBytes?: number;
   maxStackSizeBytes?: number;
-  backend?: AnyBackendProtocol;
   tools?: StructuredToolInterface[];
+  skillsEnabled?: boolean;
+  maxPtcCalls?: number | null;
+  maxResultChars?: number;
+  captureConsole?: boolean;
 }
 /**
  * Result of a single REPL evaluation.
@@ -75,34 +103,67 @@ interface ReplResult {
     stack?: string;
   };
   logs: string[];
+  logsDroppedChars: number;
 }
-//#endregion
-//#region src/middleware.d.ts
 /**
- * Backend-provided tools excluded from PTC by default.
- * These are redundant inside the REPL since VFS helpers (readFile/writeFile)
- * already cover file I/O against the agent's in-memory working set.
+ * Metadata + backend pair the session needs to resolve skill imports.
  */
-declare const DEFAULT_PTC_EXCLUDED_TOOLS: readonly ["ls", "read_file", "write_file", "edit_file", "glob", "grep", "execute"];
+interface SkillsContext {
+  /**
+   * Per-eval snapshot of `state.skillsMetadata`.
+   */
+  metadata: SkillMetadata[];
+  /**
+   * Backend the session fetches skill source files from.
+   */
+  backend: AnyBackendProtocol;
+}
+//#endregion
+//#region src/middleware.d.ts
 /**
- * Create the QuickJS REPL middleware.
+ * Create the REPL middleware.
  */
-declare function createQuickJSMiddleware(options?: QuickJSMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
+declare function createREPLMiddleware(options?: REPLMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
   code: z.ZodString;
 }, z.core.$strip>, {
   code: string;
 }, {
   code: string;
-}, string, unknown, "js_eval">]>;
+}, string, unknown, string>]>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Options for constructing a {@link PTCCallBudgetExceededError}.
+ */
+interface PTCCallBudgetExceededOptions {
+  /**
+   * The configured per-eval PTC call limit.
+   */
+  limit: number;
+  /**
+   * The call number that triggered the violation (always `limit + 1`).
+   */
+  attempted: number;
+  /**
+   * The name of the tool function that was called over budget.
+   */
+  functionName: string;
+}
+/**
+ * Thrown when a single eval exhausts its configured PTC call budget.
+ */
+declare class PTCCallBudgetExceededError extends Error {
+  readonly limit: number;
+  readonly attempted: number;
+  readonly functionName: string;
+  constructor(options: PTCCallBudgetExceededOptions);
+}
 //#endregion
 //#region src/session.d.ts
 declare const DEFAULT_MEMORY_LIMIT: number;
 declare const DEFAULT_MAX_STACK_SIZE: number;
-declare const DEFAULT_EXECUTION_TIMEOUT = 30000;
-interface PendingWrite {
-  path: string;
-  content: string;
-}
+declare const DEFAULT_EXECUTION_TIMEOUT = 5000;
+declare const DEFAULT_MAX_PTC_CALLS = 256;
 /**
  * Sandboxed JavaScript REPL session backed by QuickJS WASM.
  *
@@ -110,23 +171,45 @@ interface PendingWrite {
  * The QuickJS runtime is lazily started on the first `.eval()` call
  * and reconnected if a session with the same id already exists.
  * This makes it safe to store in LangGraph state across interrupts.
- *
- * File writes are buffered during execution and flushed via
- * `flushWrites(backend)` after eval completes.
  */
 declare class ReplSession {
   private static sessions;
   readonly id: string;
-  readonly pendingWrites: PendingWrite[];
   private runtime;
   private context;
-  private logs;
-  private _options;
-  private _backend;
+  private consoleBuffer;
+  private options;
+  private skillsContext;
+  private skillsLoaded;
+  private skillsFailed;
+  private readonly maxPtcCalls;
+  private ptcCallsRemaining;
   constructor(id: string, options?: ReplSessionOptions);
-  get backend(): BackendProtocolV2 | null;
-  set backend(b: AnyBackendProtocol | null);
   private ensureStarted;
+  /**
+   * Load the skill into cache on first access and replay cached errors.
+   */
+  private ensureSkillLoaded;
+  private resolveSpecifier;
+  /**
+   * Canonicalize an `import` specifier. Bare specifiers pass through;
+   * relative specifiers are resolved against the importing module's path.
+   * Traversal out of a skill's `@/skills/<name>/` namespace is rejected.
+   */
+  private normalizeSpecifier;
+  /**
+   * Wire the QuickJS module loader and normalizer on this session's runtime.
+   */
+  private installModuleLoader;
+  /**
+   * Initialise the per-eval PTC counter. Called at the top of every `eval()`.
+   */
+  private resetPtcBudget;
+  /**
+   * Decrement the PTC call counter and throw if the budget is exhausted.
+   * `null` budget means unlimited — returns immediately without decrementing.
+   */
+  private consumePtcBudget;
   /**
    * Get or create a session for the given id.
    *
@@ -139,6 +222,22 @@ declare class ReplSession {
    * Retrieve an existing session by id, or null if none exists.
    */
   static get(id: string): ReplSession | null;
+  /**
+   * Returns true if any session exists whose key equals `threadId` or starts
+   * with `threadId:`. Useful for tests that need to confirm a session was
+   * created without knowing the full `threadId:middlewareId` key.
+   */
+  static hasAnyForThread(threadId: string): boolean;
+  /**
+   * Dispose and remove the session with the given key, if it exists.
+   */
+  static deleteSession(key: string): void;
+  /**
+   * Push the current skills metadata + backend into the session.
+   * Called by the middleware once per `eval` invocation, before eval runs.
+   * Pass `undefined` to clear the context (no skill imports will resolve).
+   */
+  setSkillsContext(ctx?: SkillsContext): void;
   /**
    * Evaluate code in this session.
    *
@@ -149,7 +248,6 @@ declare class ReplSession {
    * async IIFE.
    */
   eval(code: string, timeoutMs: number): Promise<ReplResult>;
-  flushWrites(backend: AnyBackendProtocol): Promise<void>;
   dispose(): void;
   toJSON(): {
     id: string;
@@ -163,7 +261,6 @@ declare class ReplSession {
    */
   static clearCache(): void;
   private setupConsole;
-  private injectVfs;
   private injectTools;
 }
 //#endregion
@@ -176,6 +273,10 @@ declare function toCamelCase(name: string): string;
  * Format the result of a REPL evaluation for the agent.
  */
 declare function formatReplResult(result: ReplResult): string;
+/**
+ * Render a pre-eval error when referenced skills are not available on the agent.
+ */
+declare function formatSkillNotAvailable(missing: readonly string[]): string;
 //#endregion
 //#region src/transform.d.ts
 /**
@@ -199,6 +300,61 @@ declare function formatReplResult(result: ReplResult): string;
  * - Wraps in async IIFE for top-level await support
  */
 declare function transformForEval(code: string): string;
+/**
+ * Strip TypeScript type syntax from an ES-module source so QuickJS can
+ * evaluate it as a standard JS module.
+ *
+ * Unlike `transformForEval`, this keeps `import`/`export` declarations,
+ * does not hoist to `globalThis`, and does not wrap in an IIFE.
+ * On parse failure the original source is returned unchanged.
+ */
+declare function stripTypeSyntax(code: string): string;
+//#endregion
+//#region src/skills.d.ts
+/**
+ * File extensions the loader will enumerate from a skill directory.
+ */
+declare const SKILL_MODULE_EXTENSIONS: string[];
+/**
+ * Hard cap on total bytes pulled for one skill's bundle (1 MiB).
+ */
+declare const MAX_SKILL_BUNDLE_BYTES: number;
+/**
+ * Install-ready state for a single skill, produced by `loadSkill`.
+ */
+interface LoadedSkill {
+  /**
+   * Spec-validated kebab-case skill name.
+   */
+  name: string;
+  /**
+   * Bare specifier the skill installs under: `"@/skills/<name>"`.
+   */
+  specifier: string;
+  /**
+   * Relative POSIX path of the entrypoint file (e.g. `"index.ts"`).
+   */
+  entryRel: string;
+  /**
+   * File contents keyed by relative POSIX path, with TS syntax stripped.
+   */
+  files: Map<string, string>;
+}
+/**
+ * Build a `LoadedSkill` from a skill's metadata and a backend handle.
+ *
+ * Enumerates code files under the skill directory, downloads them,
+ * strips TypeScript syntax, and validates the entrypoint is present.
+ */
+declare function loadSkill(metadata: SkillMetadata, backend: AnyBackendProtocol): Promise<LoadedSkill>;
+/**
+ * Extract skill names referenced by `"@/skills/<name>"` literals in source.
+ *
+ * Used as a pre-eval scan so the middleware can surface `SkillNotAvailable`
+ * before evaluation starts. Dynamic imports with computed specifiers are
+ * not detected.
+ */
+declare function scanSkillReferences(source: string): Set<string>;
 //#endregion
-export { DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, DEFAULT_PTC_EXCLUDED_TOOLS, type PendingWrite, type QuickJSMiddlewareOptions, type ReplResult, ReplSession, type ReplSessionOptions, createQuickJSMiddleware, formatReplResult, toCamelCase, transformForEval };
+export { DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, type LoadedSkill, MAX_SKILL_BUNDLE_BYTES, PTCCallBudgetExceededError, type REPLMiddlewareOptions, type ReplResult, ReplSession, type ReplSessionOptions, SKILL_MODULE_EXTENSIONS, createREPLMiddleware, formatReplResult, formatSkillNotAvailable, loadSkill, scanSkillReferences, stripTypeSyntax, toCamelCase, transformForEval };
 //# sourceMappingURL=index.d.ts.map