@librechat/agents 3.1.66 → 3.1.67-dev.0

package/src/tools/skillCatalog.ts

@@ -0,0 +1,126 @@
+// src/tools/skillCatalog.ts
+import type { SkillCatalogEntry } from '@/types';
+
+const HEADER = '## Available Skills';
+const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
+const DEFAULT_BUDGET_PERCENT = 0.01;
+const DEFAULT_MAX_ENTRY_CHARS = 250;
+const DEFAULT_MIN_DESC_LENGTH = 20;
+const DEFAULT_CHARS_PER_TOKEN = 4;
+
+export type SkillCatalogOptions = {
+  /** Total context window in tokens. Default: 200_000 */
+  contextWindowTokens?: number;
+  /** Fraction of context budget for catalog. Default: 0.01 (1%) */
+  budgetPercent?: number;
+  /** Max chars per entry description. Default: 250 */
+  maxEntryChars?: number;
+  /** Descriptions below this length trigger names-only fallback. Default: 20 */
+  minDescLength?: number;
+  /** Approximate chars per token for budget calculation. Default: 4 */
+  charsPerToken?: number;
+};
+
+/**
+ * Formats a skill catalog for injection into agent context.
+ * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
+ * Returns empty string for empty input.
+ */
+export function formatSkillCatalog(
+  skills: SkillCatalogEntry[],
+  opts?: SkillCatalogOptions
+): string {
+  if (skills.length === 0) return '';
+
+  const contextWindowTokens =
+    opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
+  const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;
+  const maxEntryChars = Math.max(
+    1,
+    opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS
+  );
+  const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;
+  const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+
+  const budgetChars = Math.floor(
+    contextWindowTokens * budgetPercent * charsPerToken
+  );
+
+  const capped = skills.map((s) => ({
+    name: s.name,
+    description:
+      s.description.length > maxEntryChars
+        ? s.description.slice(0, maxEntryChars - 1) + '\u2026'
+        : s.description,
+  }));
+
+  const fullOutput = formatEntries(capped);
+  if (fullOutput.length <= budgetChars) return fullOutput;
+
+  const headerLen = HEADER.length + 2;
+  const newlineChars = capped.length > 1 ? capped.length - 1 : 0;
+  const availableChars = budgetChars - headerLen - newlineChars;
+  const perEntryOverhead = 4;
+  const nameCharsTotal = capped.reduce(
+    (sum, s) => sum + s.name.length + perEntryOverhead,
+    0
+  );
+  const availableForDescs = availableChars - nameCharsTotal;
+
+  if (availableForDescs <= 0) {
+    return fitNamesOnly(capped, budgetChars);
+  }
+
+  const maxDescPerEntry = Math.floor(availableForDescs / capped.length);
+
+  if (maxDescPerEntry < minDescLength) {
+    return fitNamesOnly(capped, budgetChars);
+  }
+
+  const truncated = capped.map((s) => ({
+    name: s.name,
+    description:
+      s.description.length > maxDescPerEntry
+        ? s.description.slice(0, maxDescPerEntry - 1) + '\u2026'
+        : s.description,
+  }));
+
+  const result = formatEntries(truncated);
+  if (result.length <= budgetChars) return result;
+  return fitNamesOnly(capped, budgetChars);
+}
+
+function formatEntries(
+  entries: { name: string; description: string }[]
+): string {
+  const lines = entries.map((e) =>
+    e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`
+  );
+  return `${HEADER}\n\n${lines.join('\n')}`;
+}
+
+/** Names-only fallback that drops trailing entries if the list still exceeds budget. */
+function fitNamesOnly(
+  entries: { name: string }[],
+  budgetChars: number
+): string {
+  // Format: "HEADER\n\n- name1\n- name2\n..."
+  // Running sum avoids O(n²) repeated string construction.
+  const prefix = HEADER.length + 2; // "HEADER\n\n"
+  const entryOverhead = 2; // "- "
+  let total = prefix;
+  let fitCount = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;
+    if (total + added > budgetChars) break;
+    total += added;
+    fitCount = i + 1;
+  }
+
+  if (fitCount === 0) return '';
+  const namesOnly = entries
+    .slice(0, fitCount)
+    .map((s) => ({ name: s.name, description: '' }));
+  return formatEntries(namesOnly);
+}

package/src/tools/subagent/SubagentExecutor.ts

@@ -0,0 +1,344 @@
+import { nanoid } from 'nanoid';
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type {
+  AgentInputs,
+  StandardGraphInput,
+  ResolvedSubagentConfig,
+  SubagentConfig,
+  TokenCounter,
+} from '@/types';
+import type { AggregatedHookResult, HookRegistry } from '@/hooks';
+import type { AgentContext } from '@/agents/AgentContext';
+import type { StandardGraph } from '@/graphs/Graph';
+import { executeHooks } from '@/hooks';
+
+const DEFAULT_MAX_TURNS = 25;
+const RECURSION_MULTIPLIER = 3;
+const ERROR_MESSAGE_MAX_CHARS = 200;
+
+const HOOK_FALLBACK: AggregatedHookResult = Object.freeze({
+  additionalContexts: [] as string[],
+  errors: [] as string[],
+});
+
+export type SubagentExecuteParams = {
+  description: string;
+  subagentType: string;
+  threadId?: string;
+};
+
+export type SubagentExecuteResult = {
+  content: string;
+  messages: BaseMessage[];
+};
+
+/**
+ * Factory that constructs a child graph for subagent execution. Injected
+ * rather than imported so that `SubagentExecutor` does not have a runtime
+ * dependency on `StandardGraph` — this avoids a circular dependency between
+ * `src/graphs/Graph.ts` and `src/tools/subagent/` that would otherwise break
+ * Rollup's chunking under `preserveModules`.
+ */
+export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
+
+export type SubagentExecutorOptions = {
+  configs: Map<string, ResolvedSubagentConfig>;
+  parentSignal?: AbortSignal;
+  hookRegistry?: HookRegistry;
+  parentRunId: string;
+  parentAgentId?: string;
+  tokenCounter?: TokenCounter;
+  /** Remaining nesting budget. 0 or negative blocks execution. */
+  maxDepth?: number;
+  /**
+   * Factory for constructing the isolated child graph. Callers pass
+   * `(input) => new StandardGraph(input)` — injected to break a circular
+   * module dependency.
+   */
+  createChildGraph: ChildGraphFactory;
+};
+
+export class SubagentExecutor {
+  private readonly configs: Map<string, ResolvedSubagentConfig>;
+  private readonly parentSignal?: AbortSignal;
+  private readonly hookRegistry?: HookRegistry;
+  private readonly parentRunId: string;
+  private readonly parentAgentId?: string;
+  private readonly tokenCounter?: TokenCounter;
+  private readonly maxDepth: number;
+  private readonly createChildGraph: ChildGraphFactory;
+
+  constructor(options: SubagentExecutorOptions) {
+    this.configs = options.configs;
+    this.parentSignal = options.parentSignal;
+    this.hookRegistry = options.hookRegistry;
+    this.parentRunId = options.parentRunId;
+    this.parentAgentId = options.parentAgentId;
+    this.tokenCounter = options.tokenCounter;
+    this.maxDepth = options.maxDepth ?? 1;
+    this.createChildGraph = options.createChildGraph;
+  }
+
+  async execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult> {
+    const { description, subagentType, threadId } = params;
+    const config = this.configs.get(subagentType);
+
+    if (!config) {
+      const available = [...this.configs.keys()].join(', ');
+      return {
+        content: `Error: Unknown subagent type "${subagentType}". Available types: ${available}`,
+        messages: [],
+      };
+    }
+
+    if (this.maxDepth <= 0) {
+      return {
+        content: 'Error: Maximum subagent nesting depth exceeded.',
+        messages: [],
+      };
+    }
+
+    const childAgentId =
+      config.agentInputs.agentId ||
+      `${this.parentAgentId ?? 'agent'}_sub_${nanoid(8)}`;
+
+    if (
+      this.hookRegistry?.hasHookFor('SubagentStart', this.parentRunId) === true
+    ) {
+      const hookResult = await executeHooks({
+        registry: this.hookRegistry,
+        input: {
+          hook_event_name: 'SubagentStart',
+          runId: this.parentRunId,
+          threadId,
+          parentAgentId: this.parentAgentId,
+          agentId: childAgentId,
+          agentType: subagentType,
+          inputs: [new HumanMessage(description)],
+        },
+        sessionId: this.parentRunId,
+        matchQuery: subagentType,
+      }).catch((): AggregatedHookResult => HOOK_FALLBACK);
+
+      /**
+       * `ask` is treated identically to `deny` in the subagent context:
+       * subagents are non-interactive, so there is no prompt path for `ask`.
+       * Both decisions block execution and return a "Blocked" tool result.
+       */
+      if (hookResult.decision === 'deny' || hookResult.decision === 'ask') {
+        return {
+          content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,
+          messages: [],
+        };
+      }
+    }
+
+    const childInputs = buildChildInputs(config, childAgentId, this.maxDepth);
+    const childRunId = `${this.parentRunId}_sub_${nanoid(8)}`;
+    const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+
+    const childGraph = this.createChildGraph({
+      runId: childRunId,
+      signal: this.parentSignal,
+      agents: [childInputs],
+      tokenCounter: this.tokenCounter,
+    });
+
+    let result: { messages: BaseMessage[] };
+    try {
+      const workflow = childGraph.createWorkflow();
+      /**
+       * Detach the child invocation from the parent's callback chain.
+       * Without this, `streamEvents` in the parent's `Run.processStream`
+       * captures events from the child graph's LLM calls (e.g.
+       * `on_chat_model_stream` for the "researcher" agent) and delivers
+       * them to the parent's handlers. The parent then tries to resolve
+       * the child's agent ID in its own `agentContexts` map and throws
+       * "No agent context found for agent ID …". Setting `callbacks: []`
+       * overrides the inherited callbacks for this invoke; combined with
+       * the child's own empty `handlerRegistry`/`hookRegistry`, the child
+       * runs fully isolated.
+       *
+       * `runName` gives the child a distinct LangSmith trace root (avoids
+       * nested trace pollution).
+       */
+      result = await workflow.invoke(
+        { messages: [new HumanMessage(description)] },
+        {
+          recursionLimit: maxTurns * RECURSION_MULTIPLIER,
+          signal: this.parentSignal,
+          callbacks: [],
+          runName: `subagent:${subagentType}`,
+          configurable: {
+            thread_id: childRunId,
+          },
+        }
+      );
+    } catch (error) {
+      childGraph.clearHeavyState();
+      return {
+        content: `Subagent error: ${truncateErrorMessage(error)}`,
+        messages: [],
+      };
+    }
+
+    const filteredContent = filterSubagentResult(result.messages);
+
+    if (
+      this.hookRegistry?.hasHookFor('SubagentStop', this.parentRunId) === true
+    ) {
+      /**
+       * Awaited (not fire-and-forget) for deterministic test synchronization
+       * and consistency with PostCompact. The parent is already waiting on the
+       * tool result, so the small extra latency is acceptable. Errors are
+       * swallowed — SubagentStop is observational.
+       */
+      await executeHooks({
+        registry: this.hookRegistry,
+        input: {
+          hook_event_name: 'SubagentStop',
+          runId: this.parentRunId,
+          threadId,
+          agentId: childAgentId,
+          agentType: subagentType,
+          messages: result.messages,
+        },
+        sessionId: this.parentRunId,
+        matchQuery: subagentType,
+      }).catch(() => {
+        /* SubagentStop is observational — swallow errors */
+      });
+    }
+
+    childGraph.clearHeavyState();
+
+    return { content: filteredContent, messages: result.messages };
+  }
+}
+
+/**
+ * Walk messages from last to first, returning the text content of the most
+ * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
+ * redacted_thinking, tool_result) are stripped. If the last AIMessage is
+ * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
+ * continues to earlier AIMessages so partial progress is salvaged — this
+ * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
+ * Returns "Task completed" only when no AIMessage in the history contains
+ * any text.
+ */
+export function filterSubagentResult(messages: BaseMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i]._getType() !== 'ai') {
+      continue;
+    }
+
+    const content = messages[i].content;
+
+    if (typeof content === 'string') {
+      if (content) return content;
+      continue;
+    }
+
+    if (!Array.isArray(content)) {
+      continue;
+    }
+
+    const textParts: string[] = [];
+    for (const block of content) {
+      if (typeof block === 'string') {
+        textParts.push(block);
+      } else if ('type' in block && block.type === 'text' && 'text' in block) {
+        textParts.push(block.text as string);
+      }
+    }
+
+    if (textParts.length > 0) {
+      return textParts.join('\n');
+    }
+  }
+
+  return 'Task completed';
+}
+
+/**
+ * Resolve self-spawn configs by filling in agentInputs from the parent context.
+ * Returns configs with agentInputs guaranteed present. Throws on duplicate
+ * `type` values to prevent silent config shadowing.
+ */
+export function resolveSubagentConfigs(
+  configs: SubagentConfig[],
+  parentContext: AgentContext
+): ResolvedSubagentConfig[] {
+  const resolved = configs
+    .map((config) => {
+      if (config.agentInputs != null) {
+        return config as ResolvedSubagentConfig;
+      }
+      if (config.self !== true || parentContext._sourceInputs == null) {
+        return null;
+      }
+      return {
+        ...config,
+        agentInputs: { ...parentContext._sourceInputs },
+      } as ResolvedSubagentConfig;
+    })
+    .filter((c): c is ResolvedSubagentConfig => c != null);
+
+  const seenTypes = new Set<string>();
+  for (const config of resolved) {
+    if (seenTypes.has(config.type)) {
+      throw new Error(
+        `Duplicate subagent type "${config.type}". Each SubagentConfig must have a unique "type" field.`
+      );
+    }
+    seenTypes.add(config.type);
+  }
+
+  return resolved;
+}
+
+/**
+ * Build child AgentInputs from a resolved config, stripping nesting and
+ * event-driven fields. When `allowNested: true`, the child's
+ * `maxSubagentDepth` is decremented so that depth is consumed as the call
+ * chain deepens across graph boundaries — the parent's executor-level check
+ * alone cannot see into the child graph's separate executor.
+ *
+ * @remarks Advanced utility: exported primarily for testing and by
+ * {@link SubagentExecutor}. Host applications configuring subagents should
+ * not need to call this directly — it is invoked internally when a subagent
+ * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
+ * child's decremented `maxSubagentDepth` on the returned inputs) is the
+ * mechanism that bounds nesting across graph boundaries; callers must
+ * respect it.
+ */
+export function buildChildInputs(
+  config: ResolvedSubagentConfig,
+  childAgentId: string,
+  parentMaxDepth: number
+): AgentInputs {
+  const { agentInputs } = config;
+  const childInputs: AgentInputs = {
+    ...agentInputs,
+    agentId: childAgentId,
+    toolDefinitions: undefined,
+  };
+
+  if (config.allowNested === true) {
+    childInputs.maxSubagentDepth = Math.max(0, parentMaxDepth - 1);
+  } else {
+    childInputs.subagentConfigs = undefined;
+    childInputs.maxSubagentDepth = undefined;
+  }
+
+  return childInputs;
+}
+
+function truncateErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.length <= ERROR_MESSAGE_MAX_CHARS) {
+    return message;
+  }
+  return `${message.slice(0, ERROR_MESSAGE_MAX_CHARS)}...`;
+}

package/src/tools/subagent/index.ts

@@ -0,0 +1,12 @@
+export {
+  SubagentExecutor,
+  filterSubagentResult,
+  resolveSubagentConfigs,
+  buildChildInputs,
+} from './SubagentExecutor';
+export type {
+  SubagentExecuteParams,
+  SubagentExecuteResult,
+  SubagentExecutorOptions,
+  ChildGraphFactory,
+} from './SubagentExecutor';

package/src/types/graph.ts

@@ -388,6 +388,29 @@ export type MultiAgentGraphInput = StandardGraphInput & {
   edges: GraphEdge[];
 };
 
+/** Configuration for a subagent type that can be spawned by a parent agent. */
+export type SubagentConfig = {
+  /** Identifier used in the tool's `subagent_type` enum (e.g. 'researcher', 'coder'). */
+  type: string;
+  /** Human-readable display name. */
+  name: string;
+  /** What this subagent specializes in — shown to the LLM. */
+  description: string;
+  /** Full agent config for the child graph. Omit when `self` is true. */
+  agentInputs?: AgentInputs;
+  /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
+  self?: boolean;
+  /** Max AGENT→TOOLS cycles before forced stop (default: 25). */
+  maxTurns?: number;
+  /** Allow this subagent to spawn its own subagents (default: false). */
+  allowNested?: boolean;
+};
+
+/** SubagentConfig with agentInputs guaranteed present (self-spawn resolved). */
+export type ResolvedSubagentConfig = SubagentConfig & {
+  agentInputs: AgentInputs;
+};
+
 export interface AgentInputs {
   agentId: string;
   /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -431,6 +454,10 @@ export interface AgentInputs {
   maxToolResultChars?: number;
   /** Pre-computed tool schema token count (from cache). Skips recalculation when provided. */
   toolSchemaTokens?: number;
+  /** Subagent configurations for hierarchical delegation. Each defines a child agent type. */
+  subagentConfigs?: SubagentConfig[];
+  /** Maximum subagent nesting depth. Default 1 means top-level agents can spawn subagents but subagents cannot nest further. */
+  maxSubagentDepth?: number;
 }
 
 export interface ContextPruningConfig {

package/src/types/index.ts

@@ -2,6 +2,7 @@
 export * from './graph';
 export * from './llm';
 export * from './run';
+export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';

package/src/types/llm.ts

@@ -45,7 +45,20 @@ export type AzureClientOptions = Partial<OpenAIChatInput> &
   } & BaseChatModelParams & {
     configuration?: OAIClientOptions;
   };
-export type ThinkingConfig = AnthropicInput['thinking'];
+/**
+ * Controls whether Claude's reasoning content is returned in adaptive
+ * thinking responses. Added for Claude Opus 4.7, which omits thinking by
+ * default unless the caller opts in with `'summarized'`.
+ * @see https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7#thinking-content-omitted-by-default
+ */
+export type ThinkingDisplay = 'summarized' | 'omitted';
+export type ThinkingConfigAdaptive = {
+  type: 'adaptive';
+  display?: ThinkingDisplay;
+};
+export type ThinkingConfig =
+  | NonNullable<AnthropicInput['thinking']>
+  | ThinkingConfigAdaptive;
 export type ChatOpenAIToolType =
   | BindToolsInput
   | OpenAIClient.ChatCompletionTool;
@@ -60,7 +73,8 @@ export type GoogleThinkingConfig = {
   thinkingLevel?: string;
 };
 export type OpenAIClientOptions = ChatOpenAIFields;
-export type AnthropicClientOptions = AnthropicInput & {
+export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & {
+  thinking?: ThinkingConfig;
   promptCache?: boolean;
 };
 export type MistralAIClientOptions = ChatMistralAIInput;

package/src/types/run.ts

@@ -11,6 +11,8 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
+import type { ToolSessionMap } from '@/types/tools';
+import type { HookRegistry } from '@/hooks';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
@@ -112,6 +114,18 @@ export type RunConfig = {
   runId: string;
   graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
   customHandlers?: Record<string, g.EventHandler>;
+  /**
+   * Pre-constructed hook registry for this run. Hooks fire at lifecycle
+   * points in `processStream` (RunStart, UserPromptSubmit, Stop,
+   * StopFailure) and around tool calls (PreToolUse, PostToolUse,
+   * PostToolUseFailure, PermissionDenied).
+   *
+   * Pass `undefined` (the default) to skip all hook dispatch. When a
+   * registry is provided, the run attaches it to the `Graph` so internal
+   * nodes can fire hooks too, and clears the session in the `finally`
+   * block to prevent leaks.
+   */
+  hooks?: HookRegistry;
   returnContent?: boolean;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
@@ -126,6 +140,12 @@ export type RunConfig = {
   calibrationRatio?: number;
   /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
   skipCleanup?: boolean;
+  /**
+   * Initial session state to seed the Graph's ToolSessionMap.
+   * Used to carry over code environment sessions from skill file priming
+   * at run start, so ToolNode can inject session_id + files into tool calls.
+   */
+  initialSessions?: ToolSessionMap;
 };
 
 export type ProvidedCallbacks =

package/src/types/skill.ts

@@ -0,0 +1,11 @@
+// src/types/skill.ts
+
+/** Minimal skill metadata for catalog assembly. The host provides these from its own data layer. */
+export type SkillCatalogEntry = {
+  /** Kebab-case identifier (what the model passes to SkillTool) */
+  name: string;
+  /** One-line description for the catalog listing */
+  description: string;
+  /** Optional human-readable label (UI only, not shown to model) */
+  displayTitle?: string;
+};

package/src/types/tools.ts

@@ -2,7 +2,8 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { ToolErrorData } from './stream';
+import type { HookRegistry } from '@/hooks';
+import type { MessageContentComplex, ToolErrorData } from './stream';
 import { EnvVar } from '@/common';
 
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
@@ -49,6 +50,12 @@ export type ToolNodeOptions = {
   agentId?: string;
   /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
   directToolNames?: Set<string>;
+  /**
+   * Hook registry for PreToolUse/PostToolUse lifecycle hooks.
+   * Only fires for event-driven tool calls (`dispatchToolEvents`). Tools
+   * routed through `directToolNames` bypass hook dispatch entirely.
+   */
+  hookRegistry?: HookRegistry;
   /** Max context tokens for the agent — used to compute tool result truncation limits. */
   maxContextTokens?: number;
   /**
@@ -186,6 +193,26 @@ export type ToolExecuteBatchRequest = {
   reject: (error: Error) => void;
 };
 
+/**
+ * A message injected into graph state by any tool execution handler.
+ * Generic mechanism: any tool returning `injectedMessages` in its `ToolExecuteResult`
+ * will have these appended to state after the ToolMessage for this call.
+ */
+export type InjectedMessage = {
+  /** 'user' for skill body injection, 'system' for context hints.
+   *  Both are converted to HumanMessage at runtime; the original role
+   *  is preserved in additional_kwargs.role. */
+  role: 'user' | 'system';
+  /** Message content: string for simple text, array for complex multi-part content */
+  content: string | MessageContentComplex[];
+  /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
+  isMeta?: boolean;
+  /** Origin tag for downstream consumers (UI, pruner, compaction) */
+  source?: 'skill' | 'hook' | 'system';
+  /** Only set when source is 'skill', for compaction preservation */
+  skillName?: string;
+};
+
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
   /** Matches ToolCallRequest.id */
@@ -198,6 +225,13 @@ export type ToolExecuteResult = {
   status: 'success' | 'error';
   /** Error message if status is 'error' */
   errorMessage?: string;
+  /**
+   * Messages to inject into graph state after the ToolMessage for this call.
+   * Placed after tool results to respect provider message ordering (tool_call -> tool_result adjacency).
+   * The host's message formatter may merge injected user messages with the preceding tool_result turn.
+   * Generic mechanism: any tool execution handler can use this.
+   */
+  injectedMessages?: InjectedMessage[];
 };
 
 /** Map of tool names to tool definitions */
@@ -318,6 +352,12 @@ export type ProgrammaticExecutionArtifact = {
   files?: FileRefs;
 };
 
+/** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
+export type BashExecutionToolParams = CodeExecutionToolParams;
+
+/** Parameters for creating a bash programmatic tool calling tool (same API as PTC, bash-only) */
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
+
 /**
  * Initialization parameters for the PTC tool
  */