@naturali/sdk 0.57.0 → 0.58.1

package/dist/index.d.cts

@@ -2143,6 +2143,16 @@ type StartRunRequest = {
   input?: {
     [key: string]: unknown;
   };
+  /**
+   * Write-only. Per-run context forwarded to the run's tool calls: every entry is sent as an `X-Naturali-Context-<key>` request header on each `http`/`mcp` tool call the run's agent nodes make, including those of a `loop` or `sub_orchestration` child run. This is how a per-user credential reaches a tool endpoint without being written into the prompt — the endpoint reads it from a header it can trust rather than from model output.
+   *
+   * The bag is stored on the run, so it survives an `awaiting_input` pause, a durable wait and a restart. It is never returned on a read: any principal on the project can read the project's runs.
+   *
+   * A key becomes an HTTP header name verbatim — no character is re-cased, so `ocaToken` and `oca_token` are two different keys — and must contain only letters, digits and `!#$%&'*+-.^_`|~`; two keys that differ only in case are rejected, since HTTP folds them into one. To land a value in a header the target already expects (usually `Authorization`), have the tool declare it with a `{{context:<key>}}` reference in its own `headers`, and set the tool's `context_keys` so the value reaches that tool alone.
+   */
+  tool_context?: {
+    [key: string]: string;
+  };
   /**
    * When true, block until the run reaches a terminal or `awaiting_input` state and return the settled run. When false (default), return immediately with `status: "queued"`.
    */
@@ -2559,7 +2569,9 @@ type SessionGeneration = {
   } | null;
 };
 /**
- * Key-value string headers injected into every tool call made during the session or generation.
+ * Context forwarded to every `http`/`mcp` tool call made during the session or generation: each entry is sent as an `X-Naturali-Context-<key>` request header, so a per-user credential can reach a tool endpoint without being written into the prompt.
+ *
+ * A key becomes an HTTP header name verbatim — no character is re-cased, so `ocaToken` and `oca_token` are two different keys — and must contain only letters, digits and `!#$%&'*+-.^_`|~`; two keys that differ only in case are rejected, since HTTP folds them into one. To land a value in a header the target already expects (usually `Authorization`), have the tool declare it with a `{{context:<key>}}` reference in its own `headers`, and set the tool's `context_keys` so the value reaches that tool alone.
  *
  */
 type ToolContext = {
@@ -2746,6 +2758,8 @@ type HttpExecute = {
   /**
    * Write-only. Auth headers sent to the target (e.g. Authorization). Accepted on write, never returned — reads report only `has_headers`.
    *
+   * A value may carry a `{{context:<key>}}` reference, resolved per call from the caller's `tool_context` (see the `tool_context` field on starting an orchestration run). That is how a per-user credential lands in the header the target already expects — `Authorization: "Bearer {{context:ocaToken}}"` — instead of only in the prefixed `X-Naturali-Context-<key>` header. A reference is legal in `headers` and nowhere else, `url` included: a context value comes from the caller, so it must not be able to steer the outbound request. A key missing from the `tool_context` at call time fails the tool call rather than sending an empty credential.
+   *
    */
   headers?: {
     [key: string]: string;
@@ -2759,6 +2773,8 @@ type McpConfig = {
   /**
    * Write-only. Auth headers sent to the MCP server. Accepted on write, never returned — reads report only `has_headers`.
    *
+   * As with an http tool's headers, a value may carry a `{{context:<key>}}` reference — `Authorization: "Bearer {{context:ocaToken}}"` — resolved per call from the caller's `tool_context`, so an MCP server can read a per-user credential from the standard bearer header it already expects.
+   *
    */
   headers?: {
     [key: string]: string;
@@ -2816,6 +2832,10 @@ type Tool = {
    * mcp tools only — denylist of MCP tool names to hide.
    */
   denied_actions?: Array<string> | null;
+  /**
+   * Which `tool_context` keys may reach this tool as `X-Naturali-Context-<key>` headers. `null` forwards every key the caller supplied; a list forwards only those, and `[]` forwards none. Key *names* are returned — the values never are.
+   */
+  context_keys: Array<string> | null;
   /**
    * Whether auth headers are on file (their values are never returned).
    */
@@ -2863,6 +2883,10 @@ type ToolCreate = {
    * mcp only — denylist of MCP tool names to hide.
    */
   denied_actions?: Array<string>;
+  /**
+   * Allowlist of `tool_context` keys forwarded to this tool as `X-Naturali-Context-<key>` headers. Omit (or `null`) to forward every key the caller supplied; `[]` forwards none. Set it on the tools that need a given credential and the credential stops egressing to the rest of the agent's tool set — a key a tool consumes through a `{{context:<key>}}` reference in its own `headers` is substituted either way, since the tool declared that header itself.
+   */
+  context_keys?: Array<string> | null;
 };
 /**
  * At least one field must be present. The tool `type` is immutable.
@@ -2883,6 +2907,10 @@ type ToolUpdate = {
   mcp?: McpConfig;
   actions?: Array<string>;
   denied_actions?: Array<string>;
+  /**
+   * Replace the allowlist of `tool_context` keys forwarded to this tool. `null` clears it (every key is forwarded again) — unlike omitting the field, which leaves the current allowlist alone.
+   */
+  context_keys?: Array<string> | null;
   status?: 'active' | 'disabled';
 };
 type ToolList = {

package/dist/index.d.mts

@@ -2143,6 +2143,16 @@ type StartRunRequest = {
   input?: {
     [key: string]: unknown;
   };
+  /**
+   * Write-only. Per-run context forwarded to the run's tool calls: every entry is sent as an `X-Naturali-Context-<key>` request header on each `http`/`mcp` tool call the run's agent nodes make, including those of a `loop` or `sub_orchestration` child run. This is how a per-user credential reaches a tool endpoint without being written into the prompt — the endpoint reads it from a header it can trust rather than from model output.
+   *
+   * The bag is stored on the run, so it survives an `awaiting_input` pause, a durable wait and a restart. It is never returned on a read: any principal on the project can read the project's runs.
+   *
+   * A key becomes an HTTP header name verbatim — no character is re-cased, so `ocaToken` and `oca_token` are two different keys — and must contain only letters, digits and `!#$%&'*+-.^_`|~`; two keys that differ only in case are rejected, since HTTP folds them into one. To land a value in a header the target already expects (usually `Authorization`), have the tool declare it with a `{{context:<key>}}` reference in its own `headers`, and set the tool's `context_keys` so the value reaches that tool alone.
+   */
+  tool_context?: {
+    [key: string]: string;
+  };
   /**
    * When true, block until the run reaches a terminal or `awaiting_input` state and return the settled run. When false (default), return immediately with `status: "queued"`.
    */
@@ -2559,7 +2569,9 @@ type SessionGeneration = {
   } | null;
 };
 /**
- * Key-value string headers injected into every tool call made during the session or generation.
+ * Context forwarded to every `http`/`mcp` tool call made during the session or generation: each entry is sent as an `X-Naturali-Context-<key>` request header, so a per-user credential can reach a tool endpoint without being written into the prompt.
+ *
+ * A key becomes an HTTP header name verbatim — no character is re-cased, so `ocaToken` and `oca_token` are two different keys — and must contain only letters, digits and `!#$%&'*+-.^_`|~`; two keys that differ only in case are rejected, since HTTP folds them into one. To land a value in a header the target already expects (usually `Authorization`), have the tool declare it with a `{{context:<key>}}` reference in its own `headers`, and set the tool's `context_keys` so the value reaches that tool alone.
  *
  */
 type ToolContext = {
@@ -2746,6 +2758,8 @@ type HttpExecute = {
   /**
    * Write-only. Auth headers sent to the target (e.g. Authorization). Accepted on write, never returned — reads report only `has_headers`.
    *
+   * A value may carry a `{{context:<key>}}` reference, resolved per call from the caller's `tool_context` (see the `tool_context` field on starting an orchestration run). That is how a per-user credential lands in the header the target already expects — `Authorization: "Bearer {{context:ocaToken}}"` — instead of only in the prefixed `X-Naturali-Context-<key>` header. A reference is legal in `headers` and nowhere else, `url` included: a context value comes from the caller, so it must not be able to steer the outbound request. A key missing from the `tool_context` at call time fails the tool call rather than sending an empty credential.
+   *
    */
   headers?: {
     [key: string]: string;
@@ -2759,6 +2773,8 @@ type McpConfig = {
   /**
    * Write-only. Auth headers sent to the MCP server. Accepted on write, never returned — reads report only `has_headers`.
    *
+   * As with an http tool's headers, a value may carry a `{{context:<key>}}` reference — `Authorization: "Bearer {{context:ocaToken}}"` — resolved per call from the caller's `tool_context`, so an MCP server can read a per-user credential from the standard bearer header it already expects.
+   *
    */
   headers?: {
     [key: string]: string;
@@ -2816,6 +2832,10 @@ type Tool = {
    * mcp tools only — denylist of MCP tool names to hide.
    */
   denied_actions?: Array<string> | null;
+  /**
+   * Which `tool_context` keys may reach this tool as `X-Naturali-Context-<key>` headers. `null` forwards every key the caller supplied; a list forwards only those, and `[]` forwards none. Key *names* are returned — the values never are.
+   */
+  context_keys: Array<string> | null;
   /**
    * Whether auth headers are on file (their values are never returned).
    */
@@ -2863,6 +2883,10 @@ type ToolCreate = {
    * mcp only — denylist of MCP tool names to hide.
    */
   denied_actions?: Array<string>;
+  /**
+   * Allowlist of `tool_context` keys forwarded to this tool as `X-Naturali-Context-<key>` headers. Omit (or `null`) to forward every key the caller supplied; `[]` forwards none. Set it on the tools that need a given credential and the credential stops egressing to the rest of the agent's tool set — a key a tool consumes through a `{{context:<key>}}` reference in its own `headers` is substituted either way, since the tool declared that header itself.
+   */
+  context_keys?: Array<string> | null;
 };
 /**
  * At least one field must be present. The tool `type` is immutable.
@@ -2883,6 +2907,10 @@ type ToolUpdate = {
   mcp?: McpConfig;
   actions?: Array<string>;
   denied_actions?: Array<string>;
+  /**
+   * Replace the allowlist of `tool_context` keys forwarded to this tool. `null` clears it (every key is forwarded again) — unlike omitting the field, which leaves the current allowlist alone.
+   */
+  context_keys?: Array<string> | null;
   status?: 'active' | 'disabled';
 };
 type ToolList = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.57.0",
+  "version": "0.58.1",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "sideEffects": false,
@@ -37,7 +37,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/api": "0.57.0"
+    "@naturali/api": "0.58.1"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",