@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/dist/types/hooks/types.d.ts

@@ -0,0 +1,320 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Closed set of hook lifecycle events supported by the hooks system.
+ *
+ * These mirror the subset of Claude Code's event surface that makes sense
+ * for a library context (no filesystem/CLI-specific events). See
+ * `docs/hooks-design-report.md` §3.2 for the mapping to existing
+ * `@illuma-ai/agents` emission points.
+ */
+export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
+export type ToolDecision = 'allow' | 'deny' | 'ask';
+/** Stop-loop decision; `block` means "do not stop, run another turn". Any `block` wins. */
+export type StopDecision = 'continue' | 'block';
+/**
+ * Fields shared by every `HookInput`. Discriminated by `hook_event_name`.
+ *
+ * - `runId` identifies the current agent run and is always present.
+ * - `threadId` identifies the conversation thread when the host has one.
+ * - `agentId` is only set when the hook fires inside a subagent scope.
+ */
+export interface BaseHookInput {
+    runId: string;
+    threadId?: string;
+    agentId?: string;
+}
+export interface RunStartHookInput extends BaseHookInput {
+    hook_event_name: 'RunStart';
+    messages: BaseMessage[];
+}
+export interface UserPromptSubmitHookInput extends BaseHookInput {
+    hook_event_name: 'UserPromptSubmit';
+    prompt: string;
+    attachments?: BaseMessage[];
+}
+/**
+ * Fires before a tool is invoked. Hook may return `deny`/`ask`/`allow` and/or
+ * an `updatedInput` that replaces the tool arguments before invocation.
+ *
+ * `toolInput` is intentionally typed as `Record<string, unknown>` because the
+ * SDK is tool-agnostic — concrete tool argument shapes are only known at the
+ * call site and are narrowed by the host. This is the one escape hatch in
+ * the hook type system.
+ */
+export interface PreToolUseHookInput extends BaseHookInput {
+    hook_event_name: 'PreToolUse';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    stepId?: string;
+    /**
+     * Number of times this tool has been invoked in prior batches within the
+     * current run. Within a single batch of parallel calls, all calls to the
+     * same tool share the same turn value — per-call discrimination within a
+     * batch is not supported in v1.
+     */
+    turn?: number;
+}
+export interface PostToolUseHookInput extends BaseHookInput {
+    hook_event_name: 'PostToolUse';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolOutput: unknown;
+    toolUseId: string;
+    stepId?: string;
+    turn?: number;
+}
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+    hook_event_name: 'PostToolUseFailure';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    error: string;
+    stepId?: string;
+    turn?: number;
+}
+export interface PermissionDeniedHookInput extends BaseHookInput {
+    hook_event_name: 'PermissionDenied';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    reason: string;
+}
+export interface SubagentStartHookInput extends BaseHookInput {
+    hook_event_name: 'SubagentStart';
+    parentAgentId?: string;
+    agentId: string;
+    agentType: string;
+    inputs: BaseMessage[];
+}
+export interface SubagentStopHookInput extends BaseHookInput {
+    hook_event_name: 'SubagentStop';
+    agentId: string;
+    agentType: string;
+    messages: BaseMessage[];
+}
+export interface StopHookInput extends BaseHookInput {
+    hook_event_name: 'Stop';
+    messages: BaseMessage[];
+    stopReason?: string;
+    stopHookActive: boolean;
+}
+export interface StopFailureHookInput extends BaseHookInput {
+    hook_event_name: 'StopFailure';
+    error: string;
+    lastAssistantMessage?: BaseMessage;
+}
+export interface PreCompactHookInput extends BaseHookInput {
+    hook_event_name: 'PreCompact';
+    messagesBeforeCount: number;
+    /**
+     * What triggered compaction. Matches `SummarizationTrigger.type` from the
+     * agent's summarization config. `'default'` means no trigger was
+     * configured and compaction fired because messages were pruned.
+     */
+    trigger: 'token_ratio' | 'remaining_tokens' | 'messages_to_refine' | 'default' | (string & {});
+}
+export interface PostCompactHookInput extends BaseHookInput {
+    hook_event_name: 'PostCompact';
+    summary: string;
+    /**
+     * Number of messages remaining after compaction. The summarize node
+     * returns a `removeAll` signal that clears all messages from state;
+     * the summary itself is injected into the system prompt, not as a
+     * message. This is `0` at the point of hook dispatch.
+     */
+    messagesAfterCount: number;
+}
+/** Discriminated union of every hook input shape. */
+export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
+/** Compile-time map from event name to its input shape. */
+export type HookInputByEvent = {
+    RunStart: RunStartHookInput;
+    UserPromptSubmit: UserPromptSubmitHookInput;
+    PreToolUse: PreToolUseHookInput;
+    PostToolUse: PostToolUseHookInput;
+    PostToolUseFailure: PostToolUseFailureHookInput;
+    PermissionDenied: PermissionDeniedHookInput;
+    SubagentStart: SubagentStartHookInput;
+    SubagentStop: SubagentStopHookInput;
+    Stop: StopHookInput;
+    StopFailure: StopFailureHookInput;
+    PreCompact: PreCompactHookInput;
+    PostCompact: PostCompactHookInput;
+};
+/**
+ * Fields common to every hook output. Hooks that have nothing to say simply
+ * return `{}` (or omit the fields below).
+ */
+export interface BaseHookOutput {
+    /** Context string to inject into the conversation. Accumulated across hooks. */
+    additionalContext?: string;
+    /** True to prevent the next model turn. Any hook can set this. */
+    preventContinuation?: boolean;
+    /** Reason reported alongside `preventContinuation`. */
+    stopReason?: string;
+}
+export type RunStartHookOutput = BaseHookOutput;
+export interface UserPromptSubmitHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+}
+export interface PreToolUseHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+    /**
+     * Replacement tool input. Merged into the pending tool call by the host.
+     *
+     * When multiple hooks set `updatedInput` within a single `executeHooks`
+     * call, the last writer in registration order wins (outer loop: matcher
+     * registration order; inner loop: hook position within the matcher). The
+     * winner is deterministic — `Promise.all` preserves input-array order.
+     * Consumers that need a single authoritative rewrite should still scope
+     * `updatedInput` to one hook per matcher to avoid confusing precedence.
+     */
+    updatedInput?: Record<string, unknown>;
+}
+export interface PostToolUseHookOutput extends BaseHookOutput {
+    /**
+     * Replacement tool output. Flows through the aggregated result so the
+     * host can substitute it before appending the tool result message.
+     * Ordering semantics match `PreToolUseHookOutput.updatedInput`:
+     * last-writer-wins in registration order.
+     */
+    updatedOutput?: unknown;
+}
+export type PostToolUseFailureHookOutput = BaseHookOutput;
+export type PermissionDeniedHookOutput = BaseHookOutput;
+export interface SubagentStartHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+}
+export type SubagentStopHookOutput = BaseHookOutput;
+export interface StopHookOutput extends BaseHookOutput {
+    decision?: StopDecision;
+    reason?: string;
+}
+export type StopFailureHookOutput = BaseHookOutput;
+export type PreCompactHookOutput = BaseHookOutput;
+export type PostCompactHookOutput = BaseHookOutput;
+/** Compile-time map from event name to its output shape. */
+export type HookOutputByEvent = {
+    RunStart: RunStartHookOutput;
+    UserPromptSubmit: UserPromptSubmitHookOutput;
+    PreToolUse: PreToolUseHookOutput;
+    PostToolUse: PostToolUseHookOutput;
+    PostToolUseFailure: PostToolUseFailureHookOutput;
+    PermissionDenied: PermissionDeniedHookOutput;
+    SubagentStart: SubagentStartHookOutput;
+    SubagentStop: SubagentStopHookOutput;
+    Stop: StopHookOutput;
+    StopFailure: StopFailureHookOutput;
+    PreCompact: PreCompactHookOutput;
+    PostCompact: PostCompactHookOutput;
+};
+/** Superset output shape used by the executor's fold loop. */
+export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
+/**
+ * A hook callback is a plain async function registered against a specific
+ * event. The `signal` is always supplied by `executeHooks` and combines the
+ * batch's parent signal with the per-hook timeout — callbacks that perform
+ * long-running work should observe it.
+ */
+export type HookCallback<E extends HookEvent = HookEvent> = (input: HookInputByEvent[E], signal: AbortSignal) => HookOutputByEvent[E] | Promise<HookOutputByEvent[E]>;
+/**
+ * A matcher groups one or more callbacks under a shared regex filter and
+ * shared timeout/once/internal flags. The generic `E` ties the callback
+ * types to the event the matcher is registered against.
+ */
+export interface HookMatcher<E extends HookEvent = HookEvent> {
+    /**
+     * Regex pattern matched against the event's primary query string (e.g.
+     * the tool name for `PreToolUse`, the agent type for `SubagentStart`).
+     *
+     * Omitted or empty means "always match". For events that do not supply a
+     * query string (`RunStart`, `Stop`, etc.), only wildcard matchers fire —
+     * a non-empty pattern on such events will never match.
+     *
+     * Patterns are treated as trusted input: `executeHooks` compiles them
+     * with `new RegExp(pattern)` without any sandbox, and a pathological
+     * pattern can block the event loop. Host registration code is expected
+     * to validate or length-bound patterns that originate from user input.
+     */
+    pattern?: string;
+    /** Callbacks that fire when the matcher hits. Executed in parallel. */
+    hooks: HookCallback<E>[];
+    /** Per-matcher timeout in ms. Defaults to the executor's batch timeout. */
+    timeout?: number;
+    /**
+     * Atomically remove the matcher before its first dispatch.
+     *
+     * `executeHooks` claims `once: true` matchers synchronously — between
+     * `getMatchers` and its first `await` — so two concurrent calls cannot
+     * both dispatch the same matcher. Whichever call runs its sync prefix
+     * first wins the matcher; the other sees an empty bucket.
+     *
+     * Semantics are "at most one dispatch, ever" — if every hook in the
+     * matcher throws, the matcher is still gone. Use `once` for
+     * fire-and-forget bootstrapping (registration, telemetry, setup). Hosts
+     * that need retry semantics should register a normal matcher and
+     * self-unregister via the callback returned from `registry.register`.
+     */
+    once?: boolean;
+    /** Internal hooks are excluded from telemetry and non-fatal error logging. */
+    internal?: boolean;
+}
+/**
+ * Storage shape for matchers keyed by event. Each event's matcher list is
+ * a generic array parameterized by that event type, so lookup via
+ * `HooksByEvent[E]` preserves type-safe callback signatures.
+ */
+export type HooksByEvent = {
+    [E in HookEvent]?: HookMatcher<E>[];
+};
+/**
+ * Aggregated result of a single `executeHooks` call. Fields are populated
+ * according to the fold rules in `executeHooks.ts`.
+ */
+export interface AggregatedHookResult {
+    /** Folded tool-gating decision; `deny > ask > allow`. */
+    decision?: ToolDecision;
+    /** Folded stop decision; any `block` wins. */
+    stopDecision?: StopDecision;
+    /** Reason from the hook that set the winning decision. */
+    reason?: string;
+    /**
+     * Replacement tool input from a `PreToolUse` hook.
+     *
+     * Last-writer-wins in **registration order**: `executeHooks` uses
+     * `Promise.all`, which preserves input-array order, so the fold iterates
+     * outcomes in the same order they were pushed — outer loop over matchers
+     * as they sit in the registry, inner loop over each matcher's `hooks`
+     * array. The winner is therefore deterministic but may not match the
+     * order in which hooks actually completed. Consumers that want a single
+     * authoritative rewrite should still register one `updatedInput`-setting
+     * hook per matcher to avoid subtle precedence bugs.
+     */
+    updatedInput?: Record<string, unknown>;
+    /**
+     * Replacement tool output from a `PostToolUse` hook.
+     *
+     * Same last-writer-wins-in-registration-order semantics as
+     * `updatedInput`. Present only when at least one hook set it; `undefined`
+     * means "use the original tool output".
+     */
+    updatedOutput?: unknown;
+    /** Accumulated `additionalContext` strings from every hook, in order. */
+    additionalContexts: string[];
+    /** True if any hook returned `preventContinuation`. */
+    preventContinuation?: boolean;
+    /**
+     * Reason recorded alongside `preventContinuation`. First winner wins:
+     * once a hook sets both flags, later hooks that also set
+     * `preventContinuation` do not overwrite the reason.
+     */
+    stopReason?: string;
+    /** Error messages from hooks that threw; always present (possibly empty). */
+    errors: string[];
+}

package/dist/types/index.d.ts

@@ -7,6 +7,13 @@ export type { GuardrailTraceData, GuardrailOutcome, } from '@illuma-ai/observabi
 export * from './graphs';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BashExecutor';
+export * from './tools/BashProgrammaticToolCalling';
+export * from './tools/ReadFile';
+export * from './tools/SkillTool';
+export * from './tools/skillCatalog';
+export * from './tools/SubagentTool';
+export * from './tools/subagent';
 export * from './tools/BrowserTools';
 export * from './tools/ProgrammaticToolCalling';
 export * from './tools/ToolSearch';
@@ -16,15 +23,7 @@ export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './tools/memory';
-export * from './tools/fileSearch';
-export * from './tools/artifacts';
-export * from './tools/proxyTool';
-export * from './providers';
-export { ContentStore, CONTENT_TTL_MS } from './content/ContentStore';
-export { ArtifactStore, sanitizeName } from './content/ArtifactStore';
-export type { S3Strategy, FileModel, Logger as ContentLogger, } from './content/ArtifactStore';
-export { interceptMcpResult, extractUiMarkers, buildCachedResponse, } from './content/mcpAutoCache';
-export type { AutoCacheContext, AutoCacheResult } from './content/mcpAutoCache';
+export * from './hooks';
 export * from './memory';
 export { MEMORY_FLUSH_SYSTEM_PROMPT } from './prompts/memoryFlushPrompt';
 export { shouldFlushMemory, runMemoryFlush, } from './graphs/phases/memoryFlushPhase';
@@ -36,6 +35,7 @@ export * from './nodes';
 export * from './common';
 export * from './utils';
 export type * from './types';
+export * from './langchain';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';
 export type { OpenRouterReasoning, OpenRouterReasoningEffort, ChatOpenRouterCallOptions, } from './llm/openrouter';

package/dist/types/langchain/google-common.d.ts

@@ -0,0 +1 @@
+export type { GoogleAIToolType } from '@langchain/google-common';

package/dist/types/langchain/index.d.ts

@@ -0,0 +1,8 @@
+export * from './messages';
+export * from './prompts';
+export * from './runnables';
+export * from './tools';
+export * from './google-common';
+export * from './language_models/chat_models';
+export * from './messages/tool';
+export * from './openai';

package/dist/types/langchain/language_models/chat_models.d.ts

@@ -0,0 +1 @@
+export type { BindToolsInput } from '@langchain/core/language_models/chat_models';

package/dist/types/langchain/messages/tool.d.ts

@@ -0,0 +1 @@
+export type { InvalidToolCall, ToolCall, ToolCallChunk, } from '@langchain/core/messages/tool';

package/dist/types/langchain/messages.d.ts

@@ -0,0 +1,2 @@
+export { AIMessage, AIMessageChunk, BaseMessage, BaseMessageChunk, HumanMessage, SystemMessage, ToolMessage, getBufferString, isAIMessage, isBaseMessage, isToolMessage, } from '@langchain/core/messages';
+export type { BaseMessageFields, MessageContent, MessageContentText, MessageContentImageUrl, UsageMetadata, } from '@langchain/core/messages';

package/dist/types/langchain/openai.d.ts

@@ -0,0 +1 @@
+export type { AzureOpenAIInput } from '@langchain/openai';

package/dist/types/langchain/prompts.d.ts

@@ -0,0 +1 @@
+export { PromptTemplate } from '@langchain/core/prompts';

package/dist/types/langchain/runnables.d.ts

@@ -0,0 +1,2 @@
+export { Runnable, RunnableLambda, RunnableSequence, } from '@langchain/core/runnables';
+export type { RunnableConfig } from '@langchain/core/runnables';

package/dist/types/langchain/tools.d.ts

@@ -0,0 +1,2 @@
+export { DynamicStructuredTool, StructuredTool, Tool, tool, } from '@langchain/core/tools';
+export type { StructuredToolInterface } from '@langchain/core/tools';

package/dist/types/langchain/utils/env.d.ts

@@ -0,0 +1 @@
+export { getEnvironmentVariable } from '@langchain/core/utils/env';

package/dist/types/llm/bedrock/cacheSupport.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bedrock prompt-cache model support detection.
+ * ===============================================
+ *
+ * Bedrock prompt caching (via `cachePoint` blocks) is only supported on
+ * specific model families. Other families silently reject or ignore the
+ * markers. We maintain an allowlist instead of a substring heuristic so
+ * a future model with an unfortunate name (e.g. `llama-claude-killer`)
+ * doesn't accidentally match.
+ *
+ * Consumers can extend the allowlist with `bedrockCacheModelPatterns` in
+ * `clientOptions` for proprietary or pre-release model IDs not yet in
+ * the reference library.
+ */
+/**
+ * Default allowlist of Bedrock model ID patterns that support cachePoint.
+ * Sourced from AWS Bedrock documentation (verified against us-east-1
+ * 2026-05).
+ *
+ * Adding a new model: append a RegExp here AND add a regression test in
+ * `cacheSupport.test.ts` covering at least one full model ID for that
+ * family. Removing a model: do not remove without operator confirmation
+ * — silent removal would suddenly stop emitting cachePoint markers and
+ * regress cost savings.
+ */
+export declare const DEFAULT_BEDROCK_CACHE_MODEL_PATTERNS: readonly RegExp[];
+/**
+ * Returns true when the given Bedrock model ID belongs to a family that
+ * supports cachePoint blocks. `additionalPatterns` lets consumers extend
+ * the allowlist for models the library doesn't know about yet.
+ *
+ * @param modelId  Bedrock model ID (e.g. `us.anthropic.claude-sonnet-4-5-20250929-v1:0`)
+ * @param additionalPatterns  Extra patterns from consumer config
+ */
+export declare function isBedrockCacheSupported(modelId: string | undefined, additionalPatterns?: readonly RegExp[]): boolean;

package/dist/types/llm/bedrock/index.d.ts

@@ -41,18 +41,65 @@ import type { ChatBedrockConverseInput } from '@langchain/aws';
  * @see https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html
  */
 export type ServiceTierType = 'priority' | 'default' | 'flex' | 'reserved';
+/**
+ * Tool cachePoint allocation strategy.
+ *
+ *   - 'single':  one cachePoint at the END of the tools array (whole array
+ *                cached as one unit). Lightest budget use (1 cachePoint).
+ *   - 'split':   split tools into groups via `toolGroupSelector`. Each
+ *                non-empty group gets its own cachePoint. Use when groups
+ *                have different volatility (e.g. stable core tools vs
+ *                volatile MCP tools). Costs more cachePoint budget.
+ *   - 'none':    no cachePoint on tools array. Use when tool definitions
+ *                change every request anyway.
+ */
+export type ToolCacheStrategy = 'single' | 'split' | 'none';
+/**
+ * Group selector for `toolCacheStrategy: 'split'`. Receives the tool name
+ * and returns a stable group key — tools with the same key are grouped
+ * together. Group order in the output array follows first-encounter order.
+ */
+export type ToolGroupSelector = (toolName: string) => string;
+/**
+ * Default group selector — puts all tools in a single group named 'core'.
+ * Equivalent to 'single' strategy but explicit. Consumers override this
+ * to enable per-source grouping (e.g. by inspecting tool-name substrings
+ * to separate stable framework tools from volatile MCP-sourced tools).
+ */
+export declare const DEFAULT_TOOL_GROUP_SELECTOR: ToolGroupSelector;
 /**
  * Extended input interface with additional features:
  * - promptCache: Enable Bedrock prompt caching for tool definitions
  * - applicationInferenceProfile: Use an inference profile ARN instead of model ID
  * - serviceTier: Specify service tier (Priority, Standard, Flex, Reserved)
+ * - toolCacheStrategy: How to allocate cachePoints across tools array
+ * - toolGroupSelector: Group key resolver for the 'split' strategy
  */
 export interface IllumaBedrockConverseInput extends ChatBedrockConverseInput {
     /**
      * Enable Bedrock prompt caching for tool definitions.
-     * When true, adds cachePoint markers to tools array.
+     * When true, adds cachePoint marker(s) to tools array per
+     * `toolCacheStrategy`. Defaults to 'single'.
      */
     promptCache?: boolean;
+    /**
+     * Tool cachePoint allocation. Defaults to 'single' — one cachePoint at
+     * the end of the tools array. Set to 'split' (with `toolGroupSelector`)
+     * when different tool groups have different volatility.
+     */
+    toolCacheStrategy?: ToolCacheStrategy;
+    /**
+     * Group selector for 'split' strategy. Receives a tool name, returns
+     * a stable group key. Defaults to a one-group selector (equivalent
+     * to 'single').
+     */
+    toolGroupSelector?: ToolGroupSelector;
+    /**
+     * Additional model ID patterns to consider Bedrock-cache-supported.
+     * Defaults are in `src/llm/bedrock/cacheSupport.ts`. Use this when
+     * AWS adds a new model family before the next library release.
+     */
+    bedrockCacheModelPatterns?: readonly RegExp[];
     /**
      * Application Inference Profile ARN to use for the model.
      * For example, "arn:aws:bedrock:eu-west-1:123456789102:application-inference-profile/fm16bt65tzgx"
@@ -90,6 +137,12 @@ export declare class IllumaBedrockConverse extends ChatBedrockConverse {
     applicationInferenceProfile?: string;
     /** Service tier for model invocation */
     serviceTier?: ServiceTierType;
+    /** Tool cachePoint allocation strategy. */
+    toolCacheStrategy: ToolCacheStrategy;
+    /** Group selector for 'split' strategy. */
+    toolGroupSelector: ToolGroupSelector;
+    /** Optional consumer extensions to the cache-supported model allowlist. */
+    bedrockCacheModelPatterns?: readonly RegExp[];
     constructor(fields?: IllumaBedrockConverseInput);
     static lc_name(): string;
     /**

package/dist/types/llm/openai/index.d.ts

@@ -102,7 +102,7 @@ export interface XAIUsageMetadata extends OpenAIClient.Completions.CompletionUsa
     num_sources_used?: number;
 }
 export declare class ChatMoonshot extends ChatOpenAI {
-    static lc_name(): 'LibreChatMoonshot';
+    static lc_name(): 'IllumaMoonshot';
     protected _convertMessages(messages: BaseMessage[]): OpenAICompletionParam[];
     _generate(messages: BaseMessage[], options: this['ParsedCallOptions'], runManager?: CallbackManagerForLLMRun): Promise<ChatResult>;
     protected _convertResponseToMessage(choice: OpenAIClient.Chat.Completions.ChatCompletion.Choice, data: OpenAIClient.Chat.Completions.ChatCompletion): AIMessage;

package/dist/types/memory/citations.d.ts

@@ -1,7 +1,7 @@
 /**
  * Citation decoration — Phase 2.
  *
- * Ported from upstream `extensions/memory-core/src/tools.citations.ts`.
+ * Ported from a reference implementation `extensions/memory-core/src/tools.citations.ts`.
  * Decorates memory_search hits with `[path#L{start}-L{end}]` markers so
  * the model can attribute claims back to specific memory files when it
  * uses them in its answer.
@@ -10,7 +10,7 @@
  * compute line ranges from the returned content block on the fly:
  *   - `startLine` = 1 (line 1 of the file)
  *   - `endLine`   = total number of lines in the block
- * This matches upstream's output format exactly while keeping the pg
+ * This matches the standard output format exactly while keeping the pg
  * schema chunk-free.
  */
 export type MemoryCitationsMode = 'on' | 'off' | 'auto';
@@ -24,7 +24,7 @@ export interface CitationCandidate {
     citation?: string;
 }
 /**
- * Decorate each hit with a citation marker. Mirrors upstream's behavior:
+ * Decorate each hit with a citation marker. Mirrors the standard behavior:
  * appends `\n\nSource: <citation>` to the content and sets `citation`.
  * When `include=false`, clears any existing citation field.
  */
@@ -32,7 +32,7 @@ export declare function decorateCitations<T extends CitationCandidate>(hits: T[]
 /**
  * Whether citations should be emitted for this call.
  *
- * Upstream keys `auto` off the session type (direct/group/channel). In
+ * The reference implementation keys `auto` off the session type (direct/group/channel). In
  * Phase 1 we only have direct chat, so `auto` => `on`. Callers that
  * later distinguish session types can pass `mode` explicitly.
  */

package/dist/types/memory/constants.d.ts

@@ -19,14 +19,14 @@ export declare const DEFAULT_MEMORY_SCHEMA = "public";
 export declare const MEMORY_PHASE_NORMAL = "normal";
 export declare const MEMORY_PHASE_FLUSHING = "memory_flushing";
 /**
- * Search defaults — aligned with upstream's upstream defaults.
+ * Search defaults — aligned with the standard defaults.
  *
  * Sources:
- * - `upstream reference` → maxResults=6
- * - `upstream reference` → maxInjectedChars=4000
+ * - `reference` → maxResults=6
+ * - `reference` → maxInjectedChars=4000
  *
- * Keeping these in lockstep with upstream means the mandatory-recall tool
- * description, budget clamps, and eval corpora line up with upstream's
+ * Keeping these in lockstep with means the mandatory-recall tool
+ * description, budget clamps, and eval corpora line up with the standard
  * tuning — we inherit their calibration instead of re-tuning from scratch.
  */
 export declare const DEFAULT_MAX_SEARCH_RESULTS = 6;
@@ -36,11 +36,11 @@ export declare const DEFAULT_MAX_INJECTED_CHARS = 4000;
 export declare const HYBRID_VECTOR_WEIGHT = 0.7;
 export declare const HYBRID_TEXT_WEIGHT = 0.3;
 /**
- * Phase 2 rerank defaults — ported from upstream.
+ * Phase 2 rerank defaults — ported from a reference implementation.
  *
  * Sources:
- * - `upstream reference` → lambda=0.7
- * - `upstream reference` → halfLifeDays=30
+ * - `reference` → lambda=0.7
+ * - `reference` → halfLifeDays=30
  *
  * Both features are opt-in (enabled=false by default) — the Phase 2
  * features are layered on top of hybrid search and don't change default
@@ -53,11 +53,11 @@ export declare const DEFAULT_TEMPORAL_DECAY_HALF_LIFE_DAYS = 30;
 export declare const DEFAULT_RECALL_TRACKING_ENABLED = false;
 export declare const DEFAULT_CITATIONS_MODE: "auto";
 /**
- * Flush trigger margins (token counts) — aligned with upstream upstream.
+ * Flush trigger margins (token counts) — aligned with standard.
  *
  * Sources:
- * - `upstream reference` → softThreshold=4000
- * - `upstream reference` → reserveFloor=20000
+ * - `reference` → softThreshold=4000
+ * - `reference` → reserveFloor=20000
  */
 export declare const DEFAULT_FLUSH_SOFT_THRESHOLD_TOKENS = 4000;
 export declare const DEFAULT_FLUSH_RESERVE_FLOOR_TOKENS = 20000;
@@ -67,7 +67,7 @@ export declare const DEFAULT_MAX_APPENDS_PER_FLUSH = 20;
  * Hard cap on agentic loop iterations inside {@link runMemoryFlush}.
  *
  * Each iteration = one model.invoke() followed by execution of any
- * `memory_append` tool_calls it emits. Mirrors upstream's flush-plan
+ * `memory_append` tool_calls it emits. Mirrors the standard flush-plan
  * loop cap; 8 is enough for ~2–3 reflections of batched notes while
  * protecting against runaway cycles if the model refuses to stop.
  */
@@ -82,21 +82,21 @@ export declare const MEMORY_APPEND_TOOL_NAME = "memory_append";
  * Mandatory-recall description — the single most load-bearing line in the
  * whole memory system. Do not soften, shorten, or reword without an eval run.
  *
- * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:186`.
+ * Ported VERBATIM from a reference implementation `extensions/memory-core/src/tools.ts:186`.
  * The wiki/corpus clause is retained even though Phase 1 doesn't ship
- * compiled-wiki supplements — keeping the string identical means upstream's
+ * compiled-wiki supplements — keeping the string identical means the standard
  * eval corpora remain drop-in valid.
  */
 export declare const MEMORY_SEARCH_DESCRIPTION: string;
 /**
- * Ported VERBATIM from upstream `extensions/memory-core/src/tools.ts:322`.
+ * Ported VERBATIM from a reference implementation `extensions/memory-core/src/tools.ts:322`.
  */
 export declare const MEMORY_GET_DESCRIPTION: string;
 /**
  * `memory_append` tool description.
  *
  * Phase 1 historically wrote to a single date-keyed file
- * (`memory/YYYY-MM-DD.md`), ported verbatim from upstream. That scheme
+ * (`memory/YYYY-MM-DD.md`), ported verbatim from a reference implementation. That scheme
  * is now replaced by an 8-path canonical whitelist — see
  * {@link ./paths.MEMORY_ALL_PATHS}. The tool description no longer
  * names a specific file; the flush-turn prompt renders the full rubric
@@ -105,7 +105,7 @@ export declare const MEMORY_GET_DESCRIPTION: string;
 export declare const MEMORY_APPEND_DESCRIPTION: string;
 /**
  * Reply token that signals the flush turn produced no user-visible output.
- * Ported VERBATIM from upstream `src/auto-reply/tokens.ts:4`.
+ * Ported VERBATIM from a reference implementation `src/auto-reply/tokens.ts:4`.
  */
 export declare const SILENT_REPLY_TOKEN = "NO_REPLY";
 /**