@soat/cli 0.51.0 → 0.53.0

package/dist/index.mjs

@@ -13,7 +13,7 @@ import * as os from "node:os";
 import { createHmac, timingSafeEqual } from "node:crypto";
 
 //#region package.json
-var version = "0.51.0";
+var version = "0.53.0";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -145,7 +145,7 @@ var describeDeployReason = args => {
 * The server answers 2xx here on purpose — the operation ran, and partial
 * failure is modelled on the resource — so the body's `status` is the only
 * signal that anything went wrong. Turning it into a non-zero exit is what
-* stops `&&` chains from reporting a deploy that deployed nothing (#1028).
+* stops `&&` chains from reporting a deploy that deployed nothing.
 */
 var describeFailedDeploy = args => {
   const {
@@ -832,7 +832,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "boundary_policy",
-      "description": "",
+      "description": "Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -996,7 +996,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "boundary_policy",
-      "description": "",
+      "description": "Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -1144,7 +1144,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "boundary_policy",
-      "description": "",
+      "description": "Restricts which SOAT actions the agent may invoke. Evaluated as the intersection with the caller's own policy, so it can only narrow.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -1306,12 +1306,6 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
-    }, {
-      "name": "extract",
-      "description": "Per-turn override of the agent's `knowledge_config.extraction` default. Omit to follow the agent's stored config. Set `false` to suppress automatic memory store extraction for this turn (e.g. an operational or tool-listing turn that would only add noise to a curated memory store). Set `true` to force extraction on for this turn even when the agent does not enable it by default, provided the agent has a `write_memory_store_id`. Has no effect on streaming or `requires_action` turns, which never extract.",
-      "required": false,
-      "type": "boolean",
-      "in": "body"
     }, {
       "name": "knowledge_config",
       "description": "Per-generation knowledge retrieval override. Array filters (memory_store_ids, document_ids, document_paths) are unioned with the agent's stored knowledge_config; `tags` pairs are merged with the override winning per key; scalar fields (min_score, limit) use the per-generation value when present.",
@@ -4321,7 +4315,7 @@ var routes = {
   "list-generations": {
     serviceClass: "Generations",
     operationId: "listGenerations",
-    description: "Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. Replaces the former per-trace generations endpoint (use the trace_id query filter). Filtering by `orchestration_run_id` is the supported way to get from an orchestration run to the generations its agent nodes produced: a node execution record carries no generation id, so the pointer lives here, alongside the run's other attribution columns.",
+    description: "Returns generations the caller can access, optionally filtered by agent, trace, orchestration run, node, and status. The generations of one trace are the `trace_id` filter. Filtering by `orchestration_run_id` is the supported way to get from an orchestration run to the generations its agent nodes produced: a node execution record carries no generation id, so the pointer lives here, alongside the run's other attribution columns.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/generations",
     httpMethod: "get",
     pathParams: [],
@@ -4990,12 +4984,6 @@ var routes = {
       "required": false,
       "type": "number",
       "in": "body"
-    }, {
-      "name": "min_score",
-      "description": "Deprecated alias for `min_similarity`, with identical behavior. While ranking was single-signal `score` equaled `similarity_score`, so this has only ever filtered cosine and an existing value keeps returning the same results. `min_similarity` wins when both are sent. Removed in v2.",
-      "required": false,
-      "type": "number",
-      "in": "body"
     }, {
       "name": "rrf_k",
       "description": "The `k` in the reciprocal rank fusion term `1 / (k + rank)`, which sets how steeply a result's contribution decays with its position in each ranked list. A smaller value weights the very top of each list more heavily. Defaults to the deployment's `KNOWLEDGE_RRF_K`, itself 60 by default. Only applies when `query` is provided.",
@@ -5004,7 +4992,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "recency_half_life_days",
-      "description": "Half-life, in days, of a recency decay applied to **memory store** results after fusion: a result's `score` is multiplied by `2 ^ (-age_in_days / recency_half_life_days)`, where age is measured from its `updated_at`. Document results are never decayed. `0` — the default, and the default of the deployment's `KNOWLEDGE_RECENCY_HALF_LIFE_DAYS` — disables the blend entirely; it is a switch, not a lower bound, and sending `0` turns off a deployment-wide decay for this one request. Accepts fractions (`0.5` is twelve hours). How many ranks a given half-life costs depends on `rrf_k`. Only applies when `query` is provided.",
+      "description": "Half-life, in days, of a recency decay applied to **memory store** results after fusion: a result's `score` is multiplied by `2 ^ (-age_in_days / recency_half_life_days)`, where age is measured from its `updated_at`. Document results are never decayed. `0` — the default, and the default of the deployment's `KNOWLEDGE_RECENCY_HALF_LIFE_DAYS` — disables the blend entirely; it is a switch, not a lower bound, and sending `0` turns off a deployment-wide decay for this one request. Accepts fractions (`0.5` is twelve hours). How many ranks a given half-life costs depends on `rrf_k`. Only applies when `query` is provided. **No value is known to be safe in general**: every half-life measured against the reference corpus that lifted recency-sensitive queries also cost relevance-sensitive ones, which is why this ships disabled. Measure against your own corpus before setting it — see the Retrieval Quality guide.",
       "required": false,
       "type": "number",
       "in": "body"
@@ -5014,6 +5002,18 @@ var routes = {
       "required": false,
       "type": "integer",
       "in": "body"
+    }, {
+      "name": "include_documents",
+      "description": "Set `false` to leave the document store out of this search. A `query` names no store, so it reaches both; the store-specific filters narrow *within* a store rather than choosing between them. This is the switch, and a filter naming the other store never overrides it. `false` for both stores is `400`.",
+      "required": false,
+      "type": "boolean",
+      "in": "body"
+    }, {
+      "name": "include_memories",
+      "description": "Set `false` to leave the memory store out of this search. The mirror of `include_documents`, for a caller that wants documents alone.",
+      "required": false,
+      "type": "boolean",
+      "in": "body"
     }, {
       "name": "memory_store_ids",
       "description": "Search memories within these specific memory stores",
@@ -5034,7 +5034,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "tags",
-      "description": "Filter results to documents and memories whose `tags` contain every one of these key-value pairs (exact, case-sensitive match). The only filter that scopes both stores, so passing it alone searches both. For memories it matches at memory granularity: a memory is returned when its parent memory store's tags match or its own do.",
+      "description": "Filter results to documents and memories whose `tags` contain every one of these key-value pairs (exact, case-sensitive match). Scopes both stores, so passing it alone searches both — as `query` does. For memories it matches at memory granularity: a memory is returned when its parent memory store's tags match or its own do.",
       "required": false,
       "type": "object",
       "in": "body"
@@ -5083,7 +5083,7 @@ var routes = {
   "create-memory": {
     serviceClass: "Memories",
     operationId: "createMemory",
-    description: "Writes a fact to the specified memory store through the standard write algorithm: the content is embedded (or matched to text the store already holds), compared against the most similar currently-valid memory, and resolved to exactly one of three outcomes — `skipped` at or above `duplicate_threshold`, `superseded` at or above `supersede_threshold`, `created` below it. Every call records one assertion, whatever the outcome.",
+    description: "Writes a fact to the specified memory store through the standard write algorithm: the content is embedded (or matched to text the store already holds), compared against the most similar currently-valid memory, and resolved to exactly one of three outcomes — `skipped` at or above `duplicate_threshold`, `superseded` at or above `supersede_threshold`, `created` below it. `supersedes` overrides that comparison entirely, retiring the memory it names. Every call records one assertion, whatever the outcome.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memories",
     httpMethod: "post",
     pathParams: [],
@@ -5124,6 +5124,12 @@ var routes = {
       "required": false,
       "type": "object",
       "in": "body"
+    }, {
+      "name": "supersedes",
+      "description": "The memory this write replaces, named outright. The declaration outranks the thresholds in both directions: the target is retired and the write returns `superseded` however similar or distant the two texts are. This is what reaches a contradiction cosine cannot see (\"The office is in Lisbon\" then \"We closed the Lisbon office\"). The target must be a still-valid memory in the same memory store, and the caller needs `memories:UpdateMemory` on it as well as `memories:CreateMemory` on the store.",
+      "required": false,
+      "type": "string",
+      "in": "body"
     }, {
       "name": "duplicate_threshold",
       "description": "Cosine similarity at or above which the incoming content is a duplicate of an existing memory and the write is skipped. Overrides the store's `duplicate_threshold` for this call; falls back to the store's value, then to `0.95`.",
@@ -5280,6 +5286,224 @@ var routes = {
       "in": "path"
     }]
   },
+  "list-memory-rules": {
+    serviceClass: "MemoryRules",
+    operationId: "listMemoryRules",
+    description: "Returns memory rules, newest first. Narrow to one store with `memory_store_id` — that form is authorized against the store itself, so it answers \"what feeds this store?\" in one call.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-rules",
+    httpMethod: "get",
+    pathParams: [],
+    queryParams: ["memory_store_id", "project_id", "limit", "offset"],
+    flags: [{
+      "name": "memory_store_id",
+      "description": "Only the rules of this memory store",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "project_id",
+      "description": "Project ID (required if not using project key auth)",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "limit",
+      "description": "Number of results per page",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }]
+  },
+  "create-memory-rule": {
+    serviceClass: "MemoryRules",
+    operationId: "createMemoryRule",
+    description: "Creates an ingestion rule on a memory store. With neither `agent_id` nor `tool_id` the built-in extractor runs, configurable through `prompt`, `ai_provider_id` and `model`.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-rules",
+    httpMethod: "post",
+    pathParams: [],
+    queryParams: [],
+    flags: [{
+      "name": "memory_store_id",
+      "description": "The destination store, and the rule's owning scope",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "on",
+      "description": "The event a firing reads. `agents.generation.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversations.message.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "source_agent_ids",
+      "description": "Agents whose turns this rule reads. Omit or send `null` for every agent in the store's project.",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "agent_id",
+      "description": "Handler agent (mutually exclusive with tool_id)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tool_id",
+      "description": "Handler tool (mutually exclusive with agent_id)",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "action",
+      "description": "Operation id, for a tool handler",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "preset_parameters",
+      "description": "Merged into a tool handler's input before invocation. The turn's own fields are reserved and win.",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "prompt",
+      "description": "Replaces the built-in extractor's task instructions. The JSON response contract and the transcript are always appended. Not valid with a handler.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "ai_provider_id",
+      "description": "Provider override for the built-in extractor's completion. Not valid with a handler.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "model",
+      "description": "Model override for the built-in extractor's completion. Not valid with a handler.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "enabled",
+      "description": "A disabled rule is kept and never fires",
+      "required": false,
+      "type": "boolean",
+      "in": "body"
+    }]
+  },
+  "get-memory-rule": {
+    serviceClass: "MemoryRules",
+    operationId: "getMemoryRule",
+    description: "Returns a specific memory rule",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-rules",
+    httpMethod: "get",
+    pathParams: ["memory_rule_id"],
+    queryParams: [],
+    flags: [{
+      "name": "memory_rule_id",
+      "description": "Memory rule ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
+  "update-memory-rule": {
+    serviceClass: "MemoryRules",
+    operationId: "updateMemoryRule",
+    description: "Updates a memory rule. Validation runs against the rule as it would stand after the change, so a one-field update cannot pair a handler with a stored extractor override from the side.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-rules",
+    httpMethod: "patch",
+    pathParams: ["memory_rule_id"],
+    queryParams: [],
+    flags: [{
+      "name": "memory_rule_id",
+      "description": "Memory rule ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }, {
+      "name": "on",
+      "description": "The event a firing reads. `agents.generation.completed` fires once per completed turn whatever the transport, and is the only event the built-in extractor may bind to. `conversations.message.generated` fires per persisted assistant reply and is conversation-backed, so it is for custom handlers.",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "source_agent_ids",
+      "description": "Send `null` to widen the rule to every agent in the project",
+      "required": false,
+      "type": "array",
+      "in": "body"
+    }, {
+      "name": "agent_id",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "tool_id",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "action",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "preset_parameters",
+      "description": "",
+      "required": false,
+      "type": "object",
+      "in": "body"
+    }, {
+      "name": "prompt",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "ai_provider_id",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "model",
+      "description": "",
+      "required": false,
+      "type": "string",
+      "in": "body"
+    }, {
+      "name": "enabled",
+      "description": "",
+      "required": false,
+      "type": "boolean",
+      "in": "body"
+    }]
+  },
+  "delete-memory-rule": {
+    serviceClass: "MemoryRules",
+    operationId: "deleteMemoryRule",
+    description: "Deletes a memory rule. The assertions it wrote are kept; their `rule_id` becomes null.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/memory-rules",
+    httpMethod: "delete",
+    pathParams: ["memory_rule_id"],
+    queryParams: [],
+    flags: [{
+      "name": "memory_rule_id",
+      "description": "Memory rule ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "list-memory-stores": {
     serviceClass: "MemoryStores",
     operationId: "listMemoryStores",
@@ -6169,7 +6393,7 @@ var routes = {
   "list-policies": {
     serviceClass: "Policies",
     operationId: "listPolicies",
-    description: "Returns global policies. Requires admin role. Pass user_id to list only the policies attached to that user (replaces the former per-user policies endpoint).",
+    description: "Returns global policies. Requires admin role. Pass user_id to list only the policies attached to that user.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/policies",
     httpMethod: "get",
     pathParams: [],
@@ -7526,7 +7750,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "context_keys",
-      "description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
+      "description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -7636,7 +7860,7 @@ var routes = {
       "in": "body"
     }, {
       "name": "context_keys",
-      "description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded — the behavior of every tool created before this field existed. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
+      "description": "Optional allowlist of `tool_context` keys that may be forwarded to this tool as prefixed context headers (`X-Soat-Context-<key>` by default). When `null` or omitted, every key in the caller's `tool_context` is forwarded. When set, only the listed keys are, so a per-user credential in `tool_context` can be confined to the tools that need it; `[]` forwards none. The server-pinned identity keys (`session_id`, `actor_id`, `actor_external_id`) are always forwarded. A key consumed by a `{{context:<key>}}` token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.",
       "required": false,
       "type": "array",
       "in": "body"
@@ -9159,7 +9383,7 @@ var kebabToSnake = s => {
 * (e.g. project_id → project-id). Kebab-case is the documented canonical CLI
 * flag convention (see the generated docs pages and tutorials); the parser is
 * lenient and accepts snake/kebab/camel alike via `toCanonical`, so this only
-* affects how flags are printed (#610).
+* affects how flags are printed.
 */
 var toKebab = s => {
   return s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase();
@@ -9227,14 +9451,27 @@ var findUnknownFlags = args => {
 
 //#endregion
 //#region src/webhookSignature.ts
+/**
+* Verification of the signature on a payload the local `soat listen` listener
+* receives. The listener takes two kinds, both under `X-Soat-Signature`,
+* distinguished by the value's own prefix rather than by header name:
+*
+* - A **webhook delivery** carries `t=<unix>,v1=<hex>` — a digest over
+*   `<t>.<raw body>`, so the timestamp is authenticated and a subscriber can
+*   bound a replay by age.
+* - A **trigger** payload carries `sha256=<hex>`, a digest over the bare
+*   body, which is the scheme a webhook-type trigger's sender signs with.
+*/
+/** Only the timestamped scheme starts this way; everything else is bare-body. */
+var TIMESTAMPED_PREFIX = "t=";
 var digestMatches = args => {
   const expectedBuffer = Buffer.from(args.expected, "utf8");
   const actualBuffer = Buffer.from(args.actual, "utf8");
   if (expectedBuffer.length !== actualBuffer.length) return false;
   return timingSafeEqual(expectedBuffer, actualBuffer);
 };
-/** Deprecated scheme: `sha256=<hex>` over the bare body. */
-var verifyLegacySignature = args => {
+/** The trigger scheme: `sha256=<hex>` over the bare body. */
+var verifyBareBodySignature = args => {
   const expected = createHmac("sha256", args.secret).update(args.payload).digest("hex");
   return digestMatches({
     expected,
@@ -9271,10 +9508,8 @@ var headerValue = value => {
 * Picks the scheme a delivery used and verifies it, when a secret is supplied.
 */
 var inspectDeliverySignature = args => {
-  const timestamped = headerValue(args.headers["x-soat-signature-v2"]);
-  const legacy = headerValue(args.headers["x-soat-signature"]);
-  const scheme = timestamped ? "v2" : "v1";
-  const signature = timestamped || legacy;
+  const signature = headerValue(args.headers["x-soat-signature"]);
+  const scheme = signature.startsWith(TIMESTAMPED_PREFIX) ? "v2" : "v1";
   if (!args.secret) return {
     signature,
     scheme,
@@ -9286,11 +9521,11 @@ var inspectDeliverySignature = args => {
     valid: scheme === "v2" ? verifyTimestampedSignature({
       secret: args.secret,
       payload: args.payload,
-      header: timestamped
-    }) : verifyLegacySignature({
+      header: signature
+    }) : verifyBareBodySignature({
       secret: args.secret,
       payload: args.payload,
-      header: legacy
+      header: signature
     })
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "CLI for SOAT — open-source infrastructure for production-ready AI agents.",
   "keywords": [
     "ai-agents",
@@ -22,7 +22,7 @@
   "dependencies": {
     "@inquirer/input": "^5.1.6",
     "@inquirer/password": "^5.2.2",
-    "@soat/sdk": "0.51.0",
+    "@soat/sdk": "0.53.0",
     "@ttoss/logger": "^0.8.20",
     "commander": "^15.0.0",
     "js-yaml": "^5.4.2"