@xbbg/langgraph 1.2.7 → 1.3.0

package/README.md

@@ -140,12 +140,12 @@ Core Bloomberg request tools:
 - `xbbg_mktbar_snapshot` - bounded `//blp/mktbar` live bar observation for one ticker.
 - `xbbg_depth_snapshot` - bounded `//blp/mktdepthdata` market-depth observation for one ticker.
 
-For raw identifiers, ask for or pass Bloomberg's identifier syntax directly: `/isin/<ISIN>` for ISINs and `/cusip/<CUSIP>` for CUSIPs.
+Securities are passed through in the form the user supplied them: Bloomberg tickers as `<TICKER> <MARKET_SECTOR>` (for example `<TICKER> <EXCHANGE> Equity`, `<INDEX_TICKER> Index`, `<CCY_PAIR> Curncy`), raw ISINs as `/isin/<ISIN>`, raw CUSIPs as `/cusip/<CUSIP>`. The market sector ending is Bloomberg's yellow key — `Equity`, `Index`, `Curncy`, `Comdty`, `Corp`, `Govt`, `Muni`, `Mtge`, `M-Mkt`, or `Pfd` (preferred securities) — and request tools pass it through to Bloomberg unvalidated. The agent guidance and every securities/ticker field description instruct the model that the ticker format is a template, not authorization to construct one — identifiers are never converted into guessed tickers; `xbbg_resolve_isins` exists for explicit resolution. Note `xbbg_ext_ticker`'s `parse_ticker` is narrower than the request tools: it parses generic futures-style tickers only (`Index`/`Curncy`/`Comdty`/`Corp`, or `<ROOT><N> <EXCHANGE> Equity`) and rejects other sectors.
 BQL is passed as one complete expression string. Use placeholder shapes such as `get(<FIELD>) for('<TICKER> <MARKET_SECTOR>')`, `get(<FIELD_1>, <FIELD_2>) for(['<TICKER_1> <MARKET_SECTOR>', '<TICKER_2> <MARKET_SECTOR>'])`, `get(<FIELD>, <WEIGHT_FIELD>) for(holdings('<ETF_TICKER> <MARKET_SECTOR>'))`, or `get(<FIELD>) for(members('<INDEX_TICKER> <MARKET_SECTOR>')) with(...)`. Prefer `xbbg_bdp`/`xbbg_bdh` for simple reference or historical requests.
 
 Dealer quote / BQR workflows in xbbg use fixed-income identifiers with a quote source, for example `/isin/<ISIN>@<QUOTE_SOURCE> <MARKET_SECTOR>`; use `xbbg_bqr` for that workflow and `xbbg_bdtick` for raw intraday ticks.
 
-Streaming surfaces are intentionally exposed only as bounded snapshot tools. Each snapshot requires `maxUpdates`, applies the configured `maxStreamUpdates`/`maxStreamWaitMs` caps, stops on count, timeout, or stream completion, and calls `unsubscribe(false)` unless `drain: true` is explicitly provided. The package does not expose open-ended async subscription iterators as agent tools.
+Streaming surfaces are intentionally exposed only as bounded snapshot tools. Each snapshot requires `maxUpdates`, applies the configured `maxStreamUpdates`/`maxStreamWaitMs` caps, stops on count, timeout, or stream completion, and calls `unsubscribe(false)` unless `drain: true` is explicitly provided. The package does not expose open-ended async subscription iterators as agent tools. If collection succeeds but releasing the subscription fails, the snapshot result still returns the collected updates and reports the failure in an `unsubscribeError` field instead of discarding data.
 
 ```ts
 import { createBloombergTools, createBdpTool } from "@xbbg/langgraph";
@@ -180,6 +180,8 @@ const allTools = createAllBloombergTools({
 
 By default the first tool invocation lazily imports `@xbbg/core`, calls `connect(engineConfig)`, and reuses the resulting engine across the tool set. Parallel LangGraph tool calls share the same in-flight initialization promise.
 
+Lazily connected engines get a hard per-request timeout (`DEFAULT_ENGINE_REQUEST_TIMEOUT_MS`, 60s) because `@xbbg/core` disables request timeouts by default, which would let a wedged Terminal session hang tool calls forever. Pass `engineConfig: { requestTimeoutMs: ... }` to change it, or `0` to disable. A user-supplied `engine` is used as-is — its configuration and lifecycle (including disconnect) stay with the caller.
+
 ```ts
 import * as xbbg from "@xbbg/core";
 import { createBloombergTools } from "@xbbg/langgraph";
@@ -188,6 +190,10 @@ const engine = await xbbg.connect({ host: "localhost", port: 8194 });
 const tools = createBloombergTools({ engine });
 ```
 
+### Cancellation
+
+Tools honor the LangChain/LangGraph `AbortSignal` (`graph.invoke(input, { signal })`): an aborted call rejects immediately, already-cancelled calls never start Bloomberg work, and snapshot tools stop collecting and unsubscribe right away (skipping `drain`) instead of running out their timeout. In-flight Bloomberg request/response calls cannot be cancelled mid-flight; they are bounded by the engine request timeout above.
+
 ## Limits and outputs
 
 Defaults:
@@ -199,6 +205,12 @@ Defaults:
 - `maxStreamUpdates = 10`
 - `maxStreamWaitMs = 15000`
 
+Date inputs accept `YYYY-MM-DD` or `YYYYMMDD` strings, integer `YYYYMMDD` values (parsed as calendar dates), and epoch milliseconds; ambiguous numbers between those ranges and ambiguous `MM/DD/YYYY` strings are rejected with actionable schema errors. `Date` instances are deliberately not part of the wire contract: JSON tool calls cannot carry them and `z.date()` breaks JSON Schema conversion in zod v4.
+
+Schemas only advertise parameters the engine accepts: `format` exists on `xbbg_bdp`/`xbbg_bdh` only, because the engine rejects it for BulkData (`xbbg_bds`), BQL, search, field-info, and BEQS output; a model-sent `format` on those tools is stripped rather than forwarded. The exported `toolParameterJsonSchema(tool)` returns the provider-ready `$ref`-free JSON Schema used in each tool's embedded provider definition.
+
+Empty results are called out in the model-facing summary (`empty result; verify identifiers, fields, and date range before concluding no data exists`) so agents distinguish "no rows" from silent failure instead of inventing data.
+
 Each tool uses `backend: "json"` for finite request results and LangChain `content_and_artifact` output. The model-facing content starts with a short summary and then includes bounded JSON data:
 
 ```text

package/dist/index.d.ts

@@ -24,7 +24,7 @@ interface BloombergToolsOptions {
 }
 interface NormalizedBloombergToolsOptions {
     readonly engine?: XbbgEngineLike;
-    readonly engineConfig?: xbbg.EngineConfig;
+    readonly engineConfig: xbbg.EngineConfig;
     readonly core?: XbbgCoreLike;
     readonly maxSecurities: number;
     readonly maxFields: number;
@@ -37,6 +37,13 @@ interface NormalizedBloombergToolsOptions {
     readonly validateFields: boolean | undefined;
     readonly disabledTools: ReadonlySet<BloombergToolName>;
 }
+/**
+ * Default hard per-request timeout applied to lazily connected engines.
+ * @xbbg/core disables request timeouts by default (`requestTimeoutMs: 0`),
+ * which would let a wedged Terminal session hang tool calls forever. An
+ * explicit `engineConfig.requestTimeoutMs` (including 0) always wins.
+ */
+declare const DEFAULT_ENGINE_REQUEST_TIMEOUT_MS = 60000;
 
 type BloombergTool = StructuredToolInterface;
 declare function createBdpTool(options?: BloombergToolsOptions): BloombergTool;
@@ -88,6 +95,22 @@ interface ToolEnvelope {
     readonly data: unknown;
 }
 
+/**
+ * Subset of the LangChain runnable config forwarded to tool functions.
+ * `signal` aborts the call: the LangChain wrapper rejects immediately, and
+ * Bloomberg tool functions use it to stop waiting and release subscriptions.
+ */
+interface ToolInvocationConfig {
+    readonly signal?: AbortSignal;
+}
+/**
+ * Provider-ready JSON Schema for a Bloomberg tool's input parameters, using
+ * the same conversion settings as the embedded provider tool definition
+ * ($ref-free, input-side of transforms). Exposed so consumers do not each
+ * reinvent zod -> JSON Schema conversion and sanitization.
+ */
+declare function toolParameterJsonSchema(toolInstance: StructuredToolInterface): Record<string, unknown>;
+
 declare function createAllBloombergTools(options?: BloombergToolsOptions): BloombergTool[];
 
-export { BLOOMBERG_EXT_TOOL_NAMES, BLOOMBERG_TOOL_INSTRUCTIONS, BLOOMBERG_TOOL_NAMES, type BloombergTool, type BloombergToolInstructionsOptions, type BloombergToolName, type BloombergToolsOptions, type NormalizedBloombergToolsOptions, type ToolEnvelope, createAllBloombergTools, createBdhTool, createBdibTool, createBdpTool, createBdsTool, createBdtickTool, createBeqsTool, createBfldsTool, createBloombergExtTools, createBloombergTools, createBqlTool, createBqrTool, createBsrchTool, createCorporateBondsTool, createDepthSnapshotTool, createEtfHoldingsTool, createExtBqlBuilderTool, createExtCalculateTool, createExtCdxTool, createExtColumnsTool, createExtConstantsTool, createExtCurrencyTool, createExtFuturesTool, createExtMarketSessionTool, createExtTickerTool, createExtYasOverridesTool, createIndexMembersTool, createIssuerIsinsTool, createMktbarSnapshotTool, createPreferredsTool, createResolveIsinsTool, createStreamSnapshotTool, createYasTool, getBloombergToolInstructions };
+export { BLOOMBERG_EXT_TOOL_NAMES, BLOOMBERG_TOOL_INSTRUCTIONS, BLOOMBERG_TOOL_NAMES, type BloombergTool, type BloombergToolInstructionsOptions, type BloombergToolName, type BloombergToolsOptions, DEFAULT_ENGINE_REQUEST_TIMEOUT_MS, type NormalizedBloombergToolsOptions, type ToolEnvelope, type ToolInvocationConfig, createAllBloombergTools, createBdhTool, createBdibTool, createBdpTool, createBdsTool, createBdtickTool, createBeqsTool, createBfldsTool, createBloombergExtTools, createBloombergTools, createBqlTool, createBqrTool, createBsrchTool, createCorporateBondsTool, createDepthSnapshotTool, createEtfHoldingsTool, createExtBqlBuilderTool, createExtCalculateTool, createExtCdxTool, createExtColumnsTool, createExtConstantsTool, createExtCurrencyTool, createExtFuturesTool, createExtMarketSessionTool, createExtTickerTool, createExtYasOverridesTool, createIndexMembersTool, createIssuerIsinsTool, createMktbarSnapshotTool, createPreferredsTool, createResolveIsinsTool, createStreamSnapshotTool, createYasTool, getBloombergToolInstructions, toolParameterJsonSchema };