@langchain/quickjs 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,14 +1,12 @@
-import * as _$langchain from "langchain";
 import { AgentMiddleware } from "langchain";
 import { z } from "zod/v4";
 import { StructuredToolInterface } from "@langchain/core/tools";
-import { AnyBackendProtocol, BackendFactory, SkillMetadata } from "deepagents";
 
 //#region src/types.d.ts
 /**
- * Configuration options for the REPL middleware.
+ * Configuration options for the Code Interpreter middleware.
  */
-interface REPLMiddlewareOptions {
+interface CodeInterpreterMiddlewareOptions {
   /**
    * Enable programmatic tool calling from within the REPL.
    *
@@ -39,11 +37,6 @@ interface REPLMiddlewareOptions {
    * @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.
    *
@@ -78,6 +71,43 @@ interface REPLMiddlewareOptions {
    * @default true
    */
   captureConsole?: boolean;
+  /**
+   * Expose the built-in `task()` global for subagent orchestration.
+   *
+   * When `true` (default) and subagent specs are available, a `task()`
+   * global is installed in the REPL that dispatches subagents
+   * programmatically with a fixed concurrency cap of 32.
+   * Set to `false` to require subagent dispatch through the normal
+   * `task` tool path.
+   *
+   * @default true
+   */
+  subagents?: boolean;
+}
+/**
+ * Configuration for the built-in subagent primitive.
+ *
+ * When provided to a ReplSession, a frozen `subagent()` global is
+ * installed in the QuickJS context. Calls are gated by a concurrency
+ * queue and forwarded to the dispatch callback.
+ */
+interface SubagentBridgeOptions {
+  /**
+   * Callback that invokes a subagent. Receives validated input from
+   * the QuickJS guest and returns the subagent's output — a string
+   * for text responses or an object for structured (responseSchema)
+   * responses.
+   */
+  dispatch: (input: {
+    description: string;
+    subagentType: string;
+    responseSchema?: Record<string, unknown>;
+  }) => Promise<unknown>;
+  /**
+   * Maximum number of concurrent subagent calls within a single eval.
+   * Excess calls queue and resolve as permits free up.
+   */
+  maxConcurrency: number;
 }
 /**
  * Options for creating a ReplSession.
@@ -86,10 +116,11 @@ interface ReplSessionOptions {
   memoryLimitBytes?: number;
   maxStackSizeBytes?: number;
   tools?: StructuredToolInterface[];
-  skillsEnabled?: boolean;
   maxPtcCalls?: number | null;
   maxResultChars?: number;
   captureConsole?: boolean;
+  sessionId?: string;
+  subagentBridge?: SubagentBridgeOptions;
 }
 /**
  * Result of a single REPL evaluation.
@@ -105,31 +136,18 @@ interface ReplResult {
   logs: string[];
   logsDroppedChars: number;
 }
-/**
- * Metadata + backend pair the session needs to resolve skill imports.
- */
-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 REPL middleware.
+ * Create the Code Interpreter middleware.
  */
-declare function createREPLMiddleware(options?: REPLMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
+declare function createCodeInterpreterMiddleware(options?: CodeInterpreterMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
   code: z.ZodString;
 }, z.core.$strip>, {
   code: string;
 }, {
   code: string;
-}, string, unknown, string>]>;
+}, string, unknown, string>], readonly []>;
 //#endregion
 //#region src/errors.d.ts
 /**
@@ -179,28 +197,22 @@ declare class ReplSession {
   private context;
   private consoleBuffer;
   private options;
-  private skillsContext;
-  private skillsLoaded;
-  private skillsFailed;
   private readonly maxPtcCalls;
   private ptcCallsRemaining;
-  constructor(id: string, options?: ReplSessionOptions);
-  private ensureStarted;
-  /**
-   * Load the skill into cache on first access and replay cached errors.
-   */
-  private ensureSkillLoaded;
-  private resolveSpecifier;
+  private subagentQueue;
+  private bridgeDispatchRef;
+  /** Allowed keys in the subagent input object. */
+  private static readonly SUBAGENT_ALLOWED_KEYS;
   /**
-   * 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.
+   * Reset the shared WASM module. Forces the next session to instantiate
+   * a fresh module. Only needed in tests where module state must be
+   * isolated between test files.
+   *
+   * @internal
    */
-  private installModuleLoader;
+  static resetSharedModule(): void;
+  constructor(id: string, options?: ReplSessionOptions);
+  private ensureStarted;
   /**
    * Initialise the per-eval PTC counter. Called at the top of every `eval()`.
    */
@@ -232,12 +244,6 @@ declare class ReplSession {
    * 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.
    *
@@ -262,6 +268,23 @@ declare class ReplSession {
   static clearCache(): void;
   private setupConsole;
   private injectTools;
+  /**
+   * Install the `task` global on the QuickJS context.
+   *
+   * Registers the host function directly as `globalThis.task`,
+   * then freezes it via `evalCode`. Structured results (when
+   * responseSchema is provided) are marshaled into native QuickJS
+   * objects on the host side — no JS wrapper needed.
+   */
+  /**
+   * Replace the active bridge dispatch with a fresh one.
+   *
+   * Call this before each eval so the dispatch closure carries
+   * the current invocation's config (tracing callbacks, run ID, etc.)
+   * rather than the stale config from session creation.
+   */
+  updateBridgeDispatch(dispatch: SubagentBridgeOptions["dispatch"]): void;
+  private injectSubagentBridge;
 }
 //#endregion
 //#region src/utils.d.ts
@@ -273,10 +296,6 @@ 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
 /**
@@ -310,51 +329,14 @@ declare function transformForEval(code: string): string;
  */
 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>;
+//#region src/subagent-dispatch.d.ts
 /**
- * Extract skill names referenced by `"@/skills/<name>"` literals in source.
+ * Validate that a response schema does not exceed size, depth, or
+ * property-count limits.
  *
- * Used as a pre-eval scan so the middleware can surface `SkillNotAvailable`
- * before evaluation starts. Dynamic imports with computed specifiers are
- * not detected.
+ * @throws Error if any limit is exceeded.
  */
-declare function scanSkillReferences(source: string): Set<string>;
+declare function validateResponseSchema(schema: Record<string, unknown>): void;
 //#endregion
-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 };
+export { type CodeInterpreterMiddlewareOptions, DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, PTCCallBudgetExceededError, type ReplResult, ReplSession, type ReplSessionOptions, type SubagentBridgeOptions, createCodeInterpreterMiddleware, formatReplResult, stripTypeSyntax, toCamelCase, transformForEval, validateResponseSchema };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,14 +1,12 @@
-import * as _$langchain from "langchain";
 import { AgentMiddleware } from "langchain";
 import { z } from "zod/v4";
-import { AnyBackendProtocol, BackendFactory, SkillMetadata } from "deepagents";
 import { StructuredToolInterface } from "@langchain/core/tools";
 
 //#region src/types.d.ts
 /**
- * Configuration options for the REPL middleware.
+ * Configuration options for the Code Interpreter middleware.
  */
-interface REPLMiddlewareOptions {
+interface CodeInterpreterMiddlewareOptions {
   /**
    * Enable programmatic tool calling from within the REPL.
    *
@@ -39,11 +37,6 @@ interface REPLMiddlewareOptions {
    * @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.
    *
@@ -78,6 +71,43 @@ interface REPLMiddlewareOptions {
    * @default true
    */
   captureConsole?: boolean;
+  /**
+   * Expose the built-in `task()` global for subagent orchestration.
+   *
+   * When `true` (default) and subagent specs are available, a `task()`
+   * global is installed in the REPL that dispatches subagents
+   * programmatically with a fixed concurrency cap of 32.
+   * Set to `false` to require subagent dispatch through the normal
+   * `task` tool path.
+   *
+   * @default true
+   */
+  subagents?: boolean;
+}
+/**
+ * Configuration for the built-in subagent primitive.
+ *
+ * When provided to a ReplSession, a frozen `subagent()` global is
+ * installed in the QuickJS context. Calls are gated by a concurrency
+ * queue and forwarded to the dispatch callback.
+ */
+interface SubagentBridgeOptions {
+  /**
+   * Callback that invokes a subagent. Receives validated input from
+   * the QuickJS guest and returns the subagent's output — a string
+   * for text responses or an object for structured (responseSchema)
+   * responses.
+   */
+  dispatch: (input: {
+    description: string;
+    subagentType: string;
+    responseSchema?: Record<string, unknown>;
+  }) => Promise<unknown>;
+  /**
+   * Maximum number of concurrent subagent calls within a single eval.
+   * Excess calls queue and resolve as permits free up.
+   */
+  maxConcurrency: number;
 }
 /**
  * Options for creating a ReplSession.
@@ -86,10 +116,11 @@ interface ReplSessionOptions {
   memoryLimitBytes?: number;
   maxStackSizeBytes?: number;
   tools?: StructuredToolInterface[];
-  skillsEnabled?: boolean;
   maxPtcCalls?: number | null;
   maxResultChars?: number;
   captureConsole?: boolean;
+  sessionId?: string;
+  subagentBridge?: SubagentBridgeOptions;
 }
 /**
  * Result of a single REPL evaluation.
@@ -105,31 +136,18 @@ interface ReplResult {
   logs: string[];
   logsDroppedChars: number;
 }
-/**
- * Metadata + backend pair the session needs to resolve skill imports.
- */
-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 REPL middleware.
+ * Create the Code Interpreter middleware.
  */
-declare function createREPLMiddleware(options?: REPLMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [_$langchain.DynamicStructuredTool<z.ZodObject<{
+declare function createCodeInterpreterMiddleware(options?: CodeInterpreterMiddlewareOptions): AgentMiddleware<undefined, undefined, unknown, readonly [import("langchain").DynamicStructuredTool<z.ZodObject<{
   code: z.ZodString;
 }, z.core.$strip>, {
   code: string;
 }, {
   code: string;
-}, string, unknown, string>]>;
+}, string, unknown, string>], readonly []>;
 //#endregion
 //#region src/errors.d.ts
 /**
@@ -179,28 +197,22 @@ declare class ReplSession {
   private context;
   private consoleBuffer;
   private options;
-  private skillsContext;
-  private skillsLoaded;
-  private skillsFailed;
   private readonly maxPtcCalls;
   private ptcCallsRemaining;
-  constructor(id: string, options?: ReplSessionOptions);
-  private ensureStarted;
-  /**
-   * Load the skill into cache on first access and replay cached errors.
-   */
-  private ensureSkillLoaded;
-  private resolveSpecifier;
+  private subagentQueue;
+  private bridgeDispatchRef;
+  /** Allowed keys in the subagent input object. */
+  private static readonly SUBAGENT_ALLOWED_KEYS;
   /**
-   * 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.
+   * Reset the shared WASM module. Forces the next session to instantiate
+   * a fresh module. Only needed in tests where module state must be
+   * isolated between test files.
+   *
+   * @internal
    */
-  private installModuleLoader;
+  static resetSharedModule(): void;
+  constructor(id: string, options?: ReplSessionOptions);
+  private ensureStarted;
   /**
    * Initialise the per-eval PTC counter. Called at the top of every `eval()`.
    */
@@ -232,12 +244,6 @@ declare class ReplSession {
    * 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.
    *
@@ -262,6 +268,23 @@ declare class ReplSession {
   static clearCache(): void;
   private setupConsole;
   private injectTools;
+  /**
+   * Install the `task` global on the QuickJS context.
+   *
+   * Registers the host function directly as `globalThis.task`,
+   * then freezes it via `evalCode`. Structured results (when
+   * responseSchema is provided) are marshaled into native QuickJS
+   * objects on the host side — no JS wrapper needed.
+   */
+  /**
+   * Replace the active bridge dispatch with a fresh one.
+   *
+   * Call this before each eval so the dispatch closure carries
+   * the current invocation's config (tracing callbacks, run ID, etc.)
+   * rather than the stale config from session creation.
+   */
+  updateBridgeDispatch(dispatch: SubagentBridgeOptions["dispatch"]): void;
+  private injectSubagentBridge;
 }
 //#endregion
 //#region src/utils.d.ts
@@ -273,10 +296,6 @@ 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
 /**
@@ -310,51 +329,14 @@ declare function transformForEval(code: string): string;
  */
 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>;
+//#region src/subagent-dispatch.d.ts
 /**
- * Extract skill names referenced by `"@/skills/<name>"` literals in source.
+ * Validate that a response schema does not exceed size, depth, or
+ * property-count limits.
  *
- * Used as a pre-eval scan so the middleware can surface `SkillNotAvailable`
- * before evaluation starts. Dynamic imports with computed specifiers are
- * not detected.
+ * @throws Error if any limit is exceeded.
  */
-declare function scanSkillReferences(source: string): Set<string>;
+declare function validateResponseSchema(schema: Record<string, unknown>): void;
 //#endregion
-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 };
+export { type CodeInterpreterMiddlewareOptions, DEFAULT_EXECUTION_TIMEOUT, DEFAULT_MAX_PTC_CALLS, DEFAULT_MAX_STACK_SIZE, DEFAULT_MEMORY_LIMIT, PTCCallBudgetExceededError, type ReplResult, ReplSession, type ReplSessionOptions, type SubagentBridgeOptions, createCodeInterpreterMiddleware, formatReplResult, stripTypeSyntax, toCamelCase, transformForEval, validateResponseSchema };
 //# sourceMappingURL=index.d.ts.map