@almadar/llm 2.59.0 → 2.60.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { L as LLMFinishReason, a as LLMClient, C as ChatCompletionMessage, b as ChatCompletionToolDef, c as LLMUsage } from './client-CZGQAqSM.js';
 export { A as ANTHROPIC_MODELS, d as CacheAwareLLMCallOptions, e as CacheableBlock, f as ChatCompletionChoice, g as ChatCompletionResponse, h as ChatCompletionRole, i as ChatCompletionToolCall, j as ChatCompletionUsage, D as DEEPSEEK_MODELS, K as KIMI_MODELS, k as LLMCallOptions, l as LLMClientOptions, m as LLMProvider, n as LLMResponse, o as LLMStreamChunk, p as LLMStreamOptions, q as LLM_PROVIDER_API_KEY_ENV, O as OPENAI_MODELS, r as OPENROUTER_MODELS, P as PROVIDER_CATALOG, s as ProviderCatalogEntry, t as ProviderConfig, V as VisionCallOptions, u as VisionImageMediaType, v as VisionImagePart, w as buildVisionMessageContent, x as createAnthropicClient, y as createCreativeClient, z as createDeepSeekClient, B as createFixClient, E as createKimiClient, F as createOpenAIClient, G as createOpenRouterClient, H as createRequirementsClient, I as createZhipuClient, J as getAvailableProvider, M as getSharedLLMClient, N as isProviderAvailable, Q as listLmstudioModels, R as listSelectableProviders, S as parseChatCompletionResponse, T as resetSharedLLMClient } from './client-CZGQAqSM.js';
 export { E as EstimateCostTokens, a as RateLimiter, R as RateLimiterOptions, b as TokenTracker, T as TokenUsage, e as estimateCostUSD, g as getGlobalRateLimiter, c as getGlobalTokenTracker, r as resetGlobalRateLimiter, d as resetGlobalTokenTracker } from './rate-limiter-Bz0iSJgZ.js';
-import { JsonValue, TraceActivity, ServiceParams, ServiceContract, ServiceParamsValue } from '@almadar/core';
+import { JsonValue, TraceActivity, ServiceParams, EventAddress, ServiceContract, ServiceParamsValue } from '@almadar/core';
 export { autoCloseJson, extractJsonFromText, isValidJson, parseJsonResponse, safeParseJson } from './json-parser.js';
 import { z } from 'zod';
 export { JsonSchema, STRUCTURED_OUTPUT_MODELS, StructuredGenerationOptions, StructuredGenerationResult, StructuredOutputClient, StructuredOutputOptions, getStructuredOutputClient, isStructuredOutputAvailable, resetStructuredOutputClient } from './structured-output.js';
@@ -388,11 +388,14 @@ interface AgentChatMessage extends ServiceParams {
  * What the model may use in `call-tools`. Exactly one of:
  * `event` — a declared external input, addressed like a `listens` source
  * (`EVENT`, `Trait.EVENT`, `Orbital.Trait.EVENT`), fired as the caller;
- * `read` — an entity whose rows the caller may read.
+ * `read` — an entity whose rows the caller may read;
+ * `scope: "declared"` — every declared external input of the program, plus one
+ * read tool over every persisted entity (rows still filtered by `@read`).
  */
 interface AgentTool extends ServiceParams {
-    event?: string;
+    event?: EventAddress;
     read?: string;
+    scope?: "declared";
 }
 /**
  * One thing a `call-tools` run did, in order: each model call (`llm_response`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/llm",
-  "version": "2.59.0",
+  "version": "2.60.0",
   "description": "Multi-provider LLM client with rate limiting, token tracking, structured outputs, and continuation handling",
   "type": "module",
   "main": "./dist/index.js",
@@ -36,7 +36,7 @@
     "src"
   ],
   "dependencies": {
-    "@almadar/logger": "^1.15.0",
+    "@almadar/logger": "^1.16.0",
     "@anthropic-ai/sdk": "^0.52.0",
     "@langchain/anthropic": "^1.3.23",
     "@langchain/core": "^1.1.32",
@@ -47,10 +47,10 @@
     "zod": "^3.22.0"
   },
   "peerDependencies": {
-    "@almadar/core": "^10.116.0"
+    "@almadar/core": "^10.117.0"
   },
   "devDependencies": {
-    "@almadar/core": "^10.116.0",
+    "@almadar/core": "^10.117.0",
     "@almadar/eslint-plugin": "^2.21.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/parser": "8.65.0",

package/src/contracts.ts

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 
-import type { ServiceContract, ServiceParams, ServiceParamsValue, TraceActivity } from "@almadar/core";
+import type { EventAddress, ServiceContract, ServiceParams, ServiceParamsValue, TraceActivity } from "@almadar/core";
 
 /**
  * JSON Schema definition for structured extraction.
@@ -47,11 +47,14 @@ export interface AgentChatMessage extends ServiceParams {
  * What the model may use in `call-tools`. Exactly one of:
  * `event` — a declared external input, addressed like a `listens` source
  * (`EVENT`, `Trait.EVENT`, `Orbital.Trait.EVENT`), fired as the caller;
- * `read` — an entity whose rows the caller may read.
+ * `read` — an entity whose rows the caller may read;
+ * `scope: "declared"` — every declared external input of the program, plus one
+ * read tool over every persisted entity (rows still filtered by `@read`).
  */
 export interface AgentTool extends ServiceParams {
-  event?: string;
+  event?: EventAddress;
   read?: string;
+  scope?: "declared";
 }
 
 /**