deepagents 1.10.1 → 1.10.2

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import * as _messages from "@langchain/core/messages";
 import * as z$2 from "zod";
 import { z as z$1 } from "zod";
 import { Client } from "@langchain/langgraph-sdk";
+import { Client as Client$1 } from "langsmith";
 import { CaptureSnapshotOptions, CaptureSnapshotOptions as LangSmithCaptureSnapshotOptions, CreateSandboxOptions, Sandbox, Snapshot, Snapshot as LangSmithSnapshot, StartSandboxOptions, StartSandboxOptions as LangSmithStartSandboxOptions } from "langsmith/experimental/sandbox";
 import * as _$zod_v30 from "zod/v3";
 import { BaseCheckpointSaver, BaseStore } from "@langchain/langgraph-checkpoint";
@@ -1420,6 +1421,43 @@ declare class CompositeBackend implements BackendProtocolV2 {
   downloadFiles(paths: string[]): Promise<FileDownloadResponse[]>;
 }
 //#endregion
+//#region src/backends/context-hub.d.ts
+/**
+ * Backend that stores files in a LangSmith Hub agent repo (persistent).
+ */
+declare class ContextHubBackend implements BackendProtocolV2 {
+  private identifier;
+  private client;
+  private cache;
+  private linkedEntries;
+  private commitHash;
+  constructor(identifier: string, options?: {
+    client?: Client$1;
+  });
+  private static stripPrefix;
+  private static toHubUnavailableError;
+  private loadTree;
+  private ensureCache;
+  private commit;
+  /**
+   * Return linked-entry paths mapped to their repo handles.
+   */
+  getLinkedEntries(): Promise<Record<string, string>>;
+  /**
+   * Return true if the hub repo already exists with at least one commit.
+   */
+  hasPriorCommits(): Promise<boolean>;
+  ls(path?: string): Promise<LsResult>;
+  read(filePath: string, offset?: number, limit?: number): Promise<ReadResult>;
+  readRaw(filePath: string): Promise<ReadRawResult>;
+  grep(pattern: string, path?: string | null, glob?: string | null): Promise<GrepResult>;
+  glob(pattern: string, _path?: string): Promise<GlobResult>;
+  write(filePath: string, content: string): Promise<WriteResult>;
+  edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+  uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]>;
+  downloadFiles(paths: string[]): Promise<FileDownloadResponse[]>;
+}
+//#endregion
 //#region src/backends/local-shell.d.ts
 /**
  * Options for creating a LocalShellBackend instance.
@@ -3359,6 +3397,361 @@ declare class ConfigurationError extends Error {
   static isInstance(error: unknown): error is ConfigurationError;
 }
 //#endregion
+//#region src/profiles/harness/types.d.ts
+/**
+ * Middleware names that provide essential agent capabilities and cannot
+ * be excluded via `excludedMiddleware`.
+ *
+ * - `FilesystemMiddleware` backs all built-in file tools and enforces
+ *   filesystem permissions.
+ * - `SubAgentMiddleware` backs the `task` tool for subagent delegation.
+ */
+declare const REQUIRED_MIDDLEWARE_NAMES: Set<string>;
+/**
+ * Configuration for the auto-added general-purpose subagent.
+ *
+ * All fields use three-state semantics: `undefined` inherits the
+ * default, an explicit value overrides it. This allows model-level
+ * profiles to selectively override provider-level defaults without
+ * clobbering fields they don't care about.
+ */
+interface GeneralPurposeSubagentConfig {
+  /**
+   * Whether to auto-add the general-purpose subagent.
+   *
+   * - `undefined` — inherit the default (enabled).
+   * - `true` — force inclusion even if a provider profile disables it.
+   * - `false` — disable the GP subagent entirely.
+   *
+   * @default undefined
+   */
+  enabled?: boolean;
+  /**
+   * Override the default GP subagent description shown to the model.
+   *
+   * @default undefined (uses `DEFAULT_GENERAL_PURPOSE_DESCRIPTION`)
+   */
+  description?: string;
+  /**
+   * Override the default GP subagent system prompt.
+   *
+   * When both this and `HarnessProfile.baseSystemPrompt` are set, this
+   * more-specific value wins for the GP subagent.
+   *
+   * @default undefined (uses `DEFAULT_SUBAGENT_PROMPT`)
+   */
+  systemPrompt?: string;
+}
+/**
+ * User-facing options for creating a {@link HarnessProfile}.
+ *
+ * Accepts plain arrays and records; the factory function converts them
+ * to their frozen counterparts. All fields are optional — an empty
+ * object produces a no-op profile.
+ */
+interface HarnessProfileOptions {
+  /**
+   * Replaces the default `BASE_AGENT_PROMPT` when set.
+   *
+   * Use this when a model requires a fundamentally different base
+   * prompt rather than an additive suffix. Most profiles should prefer
+   * `systemPromptSuffix` instead.
+   *
+   * @default undefined (keeps the default base prompt)
+   */
+  baseSystemPrompt?: string;
+  /**
+   * Text appended to the assembled base prompt with a blank-line
+   * separator (`\n\n`).
+   *
+   * This is the primary mechanism for model-specific prompt tuning.
+   * Applied uniformly to the main agent, declarative subagents, and
+   * the auto-added general-purpose subagent.
+   *
+   * @default undefined (no suffix appended)
+   */
+  systemPromptSuffix?: string;
+  /**
+   * Per-tool description replacements keyed by tool name.
+   *
+   * Allows profiles to rewrite tool descriptions for models that
+   * respond better to different phrasing. Keys that don't match any
+   * tool in the final tool set are silently ignored.
+   *
+   * @default {} (no overrides)
+   */
+  toolDescriptionOverrides?: Record<string, string>;
+  /**
+   * Tool names to remove from the agent's visible tool set.
+   *
+   * Applied via a filtering middleware after all tool-injecting
+   * middleware have run, so it catches both user-provided and
+   * middleware-provided tools.
+   *
+   * @default [] (no tools excluded)
+   */
+  excludedTools?: string[];
+  /**
+   * Middleware names to remove from the assembled middleware stack.
+   *
+   * Matched against each middleware's `.name` property. Cannot include
+   * required scaffolding names (`FilesystemMiddleware`,
+   * `SubAgentMiddleware`) — attempting to do so throws at construction
+   * time.
+   *
+   * @default [] (no middleware excluded)
+   */
+  excludedMiddleware?: string[];
+  /**
+   * Additional middleware appended to the stack after user middleware.
+   *
+   * Can be a static array or a zero-arg factory that returns fresh
+   * instances per agent construction (important when middleware carries
+   * mutable state).
+   *
+   * @default [] (no extra middleware)
+   */
+  extraMiddleware?: AgentMiddleware[] | (() => AgentMiddleware[]);
+  /**
+   * Configuration for the auto-added general-purpose subagent.
+   *
+   * @default undefined (GP subagent uses all defaults)
+   */
+  generalPurposeSubagent?: GeneralPurposeSubagentConfig;
+}
+/**
+ * Frozen runtime harness profile that shapes agent behavior at
+ * assembly time.
+ *
+ * Created by {@link createHarnessProfile} from user-provided
+ * {@link HarnessProfileOptions}. Collection types are narrowed
+ * (arrays → `Set`, records frozen) and all fields are required.
+ * The object is frozen via `Object.freeze()` to prevent mutation
+ * after construction.
+ *
+ * Profiles are **orthogonal to model selection**: they control prompt
+ * assembly, tool visibility, middleware composition, and subagent
+ * configuration — not which model is used.
+ */
+interface HarnessProfile {
+  /**
+   * Replaces the default `BASE_AGENT_PROMPT` when set.
+   *
+   * Use this when a model requires a fundamentally different base
+   * prompt rather than an additive suffix. Most profiles should prefer
+   * `systemPromptSuffix` instead.
+   */
+  baseSystemPrompt: string | undefined;
+  /**
+   * Text appended to the assembled base prompt with a blank-line
+   * separator (`\n\n`).
+   *
+   * This is the primary mechanism for model-specific prompt tuning.
+   * Applied uniformly to the main agent, declarative subagents, and
+   * the auto-added general-purpose subagent.
+   */
+  systemPromptSuffix: string | undefined;
+  /**
+   * Per-tool description replacements keyed by tool name.
+   *
+   * Allows profiles to rewrite tool descriptions for models that
+   * respond better to different phrasing. Keys that don't match any
+   * tool in the final tool set are silently ignored.
+   */
+  toolDescriptionOverrides: Record<string, string>;
+  /**
+   * Tool names to remove from the agent's visible tool set.
+   *
+   * Applied via a filtering middleware after all tool-injecting
+   * middleware have run, so it catches both user-provided and
+   * middleware-provided tools.
+   */
+  excludedTools: Set<string>;
+  /**
+   * Middleware names to remove from the assembled middleware stack.
+   *
+   * Matched against each middleware's `.name` property. Cannot include
+   * required scaffolding names (`FilesystemMiddleware`,
+   * `SubAgentMiddleware`) — attempting to do so throws at construction
+   * time.
+   */
+  excludedMiddleware: Set<string>;
+  /**
+   * Additional middleware appended to the stack after user middleware.
+   *
+   * Can be a static array or a zero-arg factory that returns fresh
+   * instances per agent construction (important when middleware carries
+   * mutable state).
+   */
+  extraMiddleware: AgentMiddleware[] | (() => AgentMiddleware[]);
+  /**
+   * Configuration for the auto-added general-purpose subagent.
+   */
+  generalPurposeSubagent: GeneralPurposeSubagentConfig | undefined;
+}
+//#endregion
+//#region src/profiles/harness/create.d.ts
+/**
+ * Create a frozen {@link HarnessProfile} from user-provided options.
+ *
+ * Validates all fields, converts mutable collections to their
+ * frozen counterparts, and returns a frozen object.
+ * Empty options produce a no-op profile (all defaults).
+ *
+ * @param options - Partial profile configuration.
+ * @returns A frozen, validated `HarnessProfile`.
+ * @throws {Error} When any field violates validation rules (invalid
+ *   middleware names, scaffolding exclusion attempts).
+ *
+ * @example
+ * ```typescript
+ * const profile = createHarnessProfile({
+ *   systemPromptSuffix: "Think step by step.",
+ *   excludedTools: ["execute"],
+ * });
+ * ```
+ */
+declare function createHarnessProfile(options?: HarnessProfileOptions): HarnessProfile;
+/**
+ * An empty no-op profile used as the default when no registered
+ * profile matches. Avoids creating a new object on every miss.
+ */
+declare const EMPTY_HARNESS_PROFILE: HarnessProfile;
+//#endregion
+//#region src/profiles/harness/serialization.d.ts
+/**
+ * Zod schema for the general-purpose subagent config section of an
+ * external harness profile config file.
+ */
+declare const generalPurposeSubagentConfigSchema: z.ZodObject<{
+  enabled: z.ZodOptional<z.ZodBoolean>;
+  description: z.ZodOptional<z.ZodString>;
+  systemPrompt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Zod schema for parsing a harness profile from an external JSON or
+ * YAML config file.
+ *
+ * Uses `.strict()` to reject unknown keys (catches typos early). Array
+ * fields (`excludedTools`, `excludedMiddleware`) accept arrays of
+ * strings; the result is passed to {@link createHarnessProfile} which
+ * converts them to `Set`.
+ *
+ * Does not include `extraMiddleware` — middleware instances cannot be
+ * represented in JSON/YAML.
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from "fs";
+ * import YAML from "yaml";
+ *
+ * const raw = YAML.parse(readFileSync("profile.yaml", "utf-8"));
+ * const config = harnessProfileConfigSchema.parse(raw);
+ * const profile = createHarnessProfile(config);
+ * ```
+ */
+declare const harnessProfileConfigSchema: z.ZodObject<{
+  baseSystemPrompt: z.ZodOptional<z.ZodString>;
+  systemPromptSuffix: z.ZodOptional<z.ZodString>;
+  toolDescriptionOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  excludedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  excludedMiddleware: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  generalPurposeSubagent: z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    description: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * TypeScript type inferred from the Zod config schema.
+ *
+ * Represents the JSON/YAML-compatible shape of a harness profile. This
+ * is the type of data that comes out of `harnessProfileConfigSchema.parse()`.
+ */
+type HarnessProfileConfigData = z.infer<typeof harnessProfileConfigSchema>;
+/**
+ * Parse an untrusted JSON/YAML object into a validated
+ * {@link HarnessProfile}.
+ *
+ * Combines Zod schema validation with prototype-pollution protection
+ * and profile construction validation. Use this for any config data
+ * that originates from files, network, or user input.
+ *
+ * @param data - Raw object from `JSON.parse()` or `YAML.parse()`.
+ * @returns A frozen, validated `HarnessProfile`.
+ * @throws {z.ZodError} When the data fails schema validation.
+ * @throws {Error} When profile-level validation fails (e.g.,
+ *   scaffolding violation in `excludedMiddleware`).
+ */
+declare function parseHarnessProfileConfig(data: unknown): HarnessProfile;
+/**
+ * Serialize a {@link HarnessProfile} to a JSON-compatible object.
+ *
+ * Omits `undefined` fields and `extraMiddleware` (runtime-only).
+ * Throws if `extraMiddleware` contains instances — callers should
+ * strip it before serializing if they've set it.
+ *
+ * @param profile - The profile to serialize.
+ * @returns A plain object matching {@link HarnessProfileConfigData}.
+ * @throws {Error} When `extraMiddleware` is non-empty (cannot be
+ *   serialized to JSON).
+ */
+declare function serializeProfile(profile: HarnessProfile): HarnessProfileConfigData;
+//#endregion
+//#region src/profiles/harness/registry.d.ts
+/**
+ * Register a harness profile for a provider or specific model.
+ *
+ * Accepts either a pre-built {@link HarnessProfile} (from
+ * {@link createHarnessProfile}) or raw {@link HarnessProfileOptions}
+ * that will be validated and frozen automatically.
+ *
+ * Registrations are **additive**: if a profile already exists under
+ * `key`, the new profile is merged on top. The incoming profile's
+ * fields win on scalar conflicts; set fields union; middleware
+ * sequences merge by name.
+ *
+ * @param key - Either a bare provider (`"openai"`) for provider-wide
+ *   defaults, or `"provider:model"` for a per-model override.
+ * @param profile - A `HarnessProfile` or options to build one from.
+ * @throws {Error} When `key` is malformed or profile validation
+ *   fails.
+ *
+ * @example
+ * ```typescript
+ * import { registerHarnessProfile } from "@langchain/deepagents";
+ *
+ * registerHarnessProfile("openai", {
+ *   systemPromptSuffix: "Respond concisely.",
+ * });
+ *
+ * registerHarnessProfile("openai:gpt-5.4", {
+ *   excludedTools: ["execute"],
+ * });
+ * ```
+ */
+declare function registerHarnessProfile(key: string, profile: HarnessProfile | HarnessProfileOptions): void;
+/**
+ * Look up the {@link HarnessProfile} for a model spec string.
+ *
+ * Resolution order:
+ *
+ * 1. **Exact match** on `spec` (e.g., `"openai:gpt-5.4"`).
+ * 2. **Provider prefix** (everything before `:`) when `spec` contains
+ *    a colon and both halves are non-empty.
+ * 3. When both exist, they are **merged** (provider as base, exact as
+ *    override).
+ * 4. `undefined` when nothing matches.
+ *
+ * Malformed specs (empty, multiple colons, empty halves) return
+ * `undefined` without consulting the registry.
+ *
+ * @param spec - Model spec in `"provider:model"` format, or a bare
+ *   provider/model identifier.
+ * @returns The matching profile, or `undefined`.
+ */
+declare function getHarnessProfile(spec: string): HarnessProfile | undefined;
+//#endregion
 //#region src/config.d.ts
 /**
  * Configuration and settings for deepagents.
@@ -3564,5 +3957,5 @@ declare function parseSkillMetadata(skillMdPath: string, source: "user" | "proje
  */
 declare function listSkills(options: ListSkillsOptions): SkillMetadata[];
 //#endregion
-export { type AgentMemoryMiddlewareOptions, type AnyBackendProtocol, type AnySubAgent, type AsyncSubAgent, type AsyncSubAgentMiddlewareOptions, type AsyncTask, type AsyncTaskStatus, type BackendFactory, type BackendProtocol, type BackendProtocolV1, type BackendProtocolV2, type BackendRuntime, BaseSandbox, type CompiledSubAgent, type CompletionCallbackOptions, CompositeBackend, ConfigurationError, type ConfigurationErrorCode, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentRunStream, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FilesystemOperation, type FilesystemPermission, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GlobResult, type GrepMatch, type GrepResult, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type LangSmithCaptureSnapshotOptions, LangSmithSandbox, type LangSmithSandboxCreateOptions, type LangSmithSandboxOptions, type LangSmithSnapshot, type LangSmithStartSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, type LsResult, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type PermissionMode, type ReadRawResult, type ReadResult, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxBackendProtocolV1, type SandboxBackendProtocolV2, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, type StateAndStore, StateBackend, StoreBackend, type StoreBackendContext, type StoreBackendNamespaceFactory, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SubagentRunStream, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSubagentTransformer, createSummarizationMiddleware, filesValue, findProjectRoot, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseSkillMetadata, resolveBackend };
+export { type AgentMemoryMiddlewareOptions, type AnyBackendProtocol, type AnySubAgent, type AsyncSubAgent, type AsyncSubAgentMiddlewareOptions, type AsyncTask, type AsyncTaskStatus, type BackendFactory, type BackendProtocol, type BackendProtocolV1, type BackendProtocolV2, type BackendRuntime, BaseSandbox, type CompiledSubAgent, type CompletionCallbackOptions, CompositeBackend, ConfigurationError, type ConfigurationErrorCode, ContextHubBackend, type CreateDeepAgentParams, DEFAULT_GENERAL_PURPOSE_DESCRIPTION, DEFAULT_SUBAGENT_PROMPT, type DeepAgent, type DeepAgentRunStream, type DeepAgentTypeConfig, type DefaultDeepAgentTypeConfig, EMPTY_HARNESS_PROFILE, type EditResult, type ExecuteResponse, type ExtractSubAgentMiddleware, type FileData, type FileDownloadResponse, type FileInfo, type FileOperationError, type FileUploadResponse, FilesystemBackend, type FilesystemMiddlewareOptions, type FilesystemOperation, type FilesystemPermission, type FlattenSubAgentMiddleware, GENERAL_PURPOSE_SUBAGENT, type GeneralPurposeSubagentConfig, type GlobResult, type GrepMatch, type GrepResult, type HarnessProfile, type HarnessProfileConfigData, type HarnessProfileOptions, type InferDeepAgentSubagents, type InferDeepAgentType, type InferStructuredResponse, type InferSubAgentMiddlewareStates, type InferSubagentByName, type InferSubagentReactAgentType, type LangSmithCaptureSnapshotOptions, LangSmithSandbox, type LangSmithSandboxCreateOptions, type LangSmithSandboxOptions, type LangSmithSnapshot, type LangSmithStartSandboxOptions, type ListSkillsOptions, type SkillMetadata as LoaderSkillMetadata, LocalShellBackend, type LocalShellBackendOptions, type LsResult, MAX_SKILL_DESCRIPTION_LENGTH, MAX_SKILL_FILE_SIZE, MAX_SKILL_NAME_LENGTH, type MaybePromise, type MemoryMiddlewareOptions, type MergedDeepAgentState, type PermissionMode, REQUIRED_MIDDLEWARE_NAMES, type ReadRawResult, type ReadResult, type ResolveDeepAgentTypeConfig, type SandboxBackendProtocol, type SandboxBackendProtocolV1, type SandboxBackendProtocolV2, type SandboxDeleteOptions, SandboxError, type SandboxErrorCode, type SandboxGetOrCreateOptions, type SandboxInfo, type SandboxListOptions, type SandboxListResponse, type Settings, type SettingsOptions, type SkillMetadata$1 as SkillMetadata, type SkillsMiddlewareOptions, type StateAndStore, StateBackend, StoreBackend, type StoreBackendContext, type StoreBackendNamespaceFactory, type StoreBackendOptions, type SubAgent, type SubAgentMiddlewareOptions, type SubagentRunStream, type SupportedResponseFormat, TASK_SYSTEM_PROMPT, type WriteResult, adaptBackendProtocol, adaptSandboxProtocol, computeSummarizationDefaults, createAgentMemoryMiddleware, createAsyncSubAgentMiddleware, createCompletionCallbackMiddleware, createDeepAgent, createFilesystemMiddleware, createHarnessProfile, createMemoryMiddleware, createPatchToolCallsMiddleware, createSettings, createSkillsMiddleware, createSubAgentMiddleware, createSubagentTransformer, createSummarizationMiddleware, filesValue, findProjectRoot, generalPurposeSubagentConfigSchema, getHarnessProfile, harnessProfileConfigSchema, isAsyncSubAgent, isSandboxBackend, isSandboxProtocol, listSkills, parseHarnessProfileConfig, parseSkillMetadata, registerHarnessProfile, resolveBackend, serializeProfile };
 //# sourceMappingURL=index.d.ts.map