@soat/sdk 0.110.0 → 0.111.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -851,7 +851,7 @@ var Agents = class {
851
851
  /**
852
852
  * Submit tool outputs for a paused generation
853
853
  *
854
- * Resumes a generation that was paused due to client tool calls. Provide tool outputs for each pending tool call.
854
+ * Resumes a generation that was paused due to client tool calls. Provide tool outputs for each pending tool call. Requires `agents:CreateAgentGeneration` on the agent in addition to `generations:ResumeGeneration` on the generation. The resumed segment runs under the generation's stored authority held to the caller's, so a resume never widens what the turn may do.
855
855
  *
856
856
  */
857
857
  static submitAgentToolOutputs(options) {
@@ -4036,7 +4036,7 @@ var Playbooks = class {
4036
4036
  *
4037
4037
  * Creates a playbook at version 1. The definition is refused with `400 PLAYBOOK_VALIDATION_FAILED` when it holds a duplicate node or input, an input reading a missing node or field, an `execute` node without an executor or another kind with one, transformations on a non-final node, or a cycle; `meta.problems` lists every one. A duplicate `name` in the project is `409 NAME_CONFLICT`.
4038
4038
  *
4039
- * The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 ACTION_NOT_HELD`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). An executor cannot be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), nor a transformation's tool a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
4039
+ * The version's executors run under `policy_ids`, required and non-empty (`400 VALIDATION_FAILED`). The caller must hold every grant of each policy it names (`403 POLICY_GRANT_NOT_HELD`) and be allowed to start every executor the definition names (`403 ACTION_NOT_HELD`), and each must exist in the project, or be an agent or tool shared with it (`400 PLAYBOOK_VALIDATION_FAILED`, an `EXECUTOR_NOT_FOUND` problem). A `tool` executor on an `mcp` tool must name in `operation_id` an action the tool's binding allows (`EXECUTOR_ACTION_REQUIRED`, `EXECUTOR_ACTION_UNAVAILABLE`). An executor cannot be a `client` tool (`EXECUTOR_TOOL_UNSUPPORTED`), nor a transformation's tool a `client` or `mcp` tool (`TRANSFORMATION_TOOL_UNSUPPORTED`).
4040
4040
  */
4041
4041
  static createPlaybook(options) {
4042
4042
  return (options.client ?? client).post({
@@ -4090,9 +4090,9 @@ var Playbooks = class {
4090
4090
  /**
4091
4091
  * Update a playbook
4092
4092
  *
4093
- * Updates any of `name`, `description` and `definition`. Only a change to `definition` archives a new version; a rename or a rewrite of the definition the playbook already holds leaves `version` where it is. A case keeps the version it was created on.
4093
+ * Updates any of `name`, `description`, `definition` and `policy_ids`. Only a change to `definition` or `policy_ids` archives a new version; a rename or a rewrite the playbook already holds leaves `version` where it is. A case keeps the version it was created on.
4094
4094
  *
4095
- * A new version is authored by the caller, checked as on create: `403 ACTION_NOT_HELD` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `EXECUTOR_TOOL_UNSUPPORTED` for a `client` tool executor, `TRANSFORMATION_TOOL_UNSUPPORTED` for a `client` or `mcp` transformation tool, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
4095
+ * Every write is checked as on create against the playbook as it stands after it: `400 VALIDATION_FAILED` for one left without `policy_ids`, `403 POLICY_GRANT_NOT_HELD` for a policy whose grants the caller does not hold, `403 ACTION_NOT_HELD` for an executor it may not start, an `EXECUTOR_NOT_FOUND` problem for one that does not exist, `EXECUTOR_ACTION_REQUIRED` or `EXECUTOR_ACTION_UNAVAILABLE` for an `mcp` tool action a run could not call, `EXECUTOR_TOOL_UNSUPPORTED` for a `client` tool executor, `TRANSFORMATION_TOOL_UNSUPPORTED` for a `client` or `mcp` transformation tool.
4096
4096
  */
4097
4097
  static updatePlaybook(options) {
4098
4098
  return (options.client ?? client).patch({
@@ -4129,7 +4129,7 @@ var Playbooks = class {
4129
4129
  /**
4130
4130
  * Restore an archived playbook version
4131
4131
  *
4132
- * Writes an archived definition back as the playbook's live one, which archives it again as a new version rather than rewinding the counter. Restoring the definition the playbook already holds is a no-op. The caller authors the new version, checked as on create.
4132
+ * Writes an archived definition back as the playbook's live one, which archives it again as a new version rather than rewinding the counter. Restoring the definition the playbook already holds is a no-op. The archived `policy_ids` are restored with it, the playbook's own when the version archived none; the write is checked as an update.
4133
4133
  */
4134
4134
  static restorePlaybookVersion(options) {
4135
4135
  return (options.client ?? client).post({
@@ -4229,7 +4229,7 @@ var Playbooks = class {
4229
4229
  /**
4230
4230
  * Run a node of a case
4231
4231
  *
4232
- * Runs one node now. The cascade already runs every node whose inputs are set once a write, a settle or a resume makes it runnable, and never reruns a `failed` or `done` one: this is how a failed node is retried, and how a `done` node is recomputed after an upgrade changed its executor. A `collect` node takes its own input values as its output, any other node starts its executor with the node's input values mapped through the executor's `input`. The executor runs as the author of the case's playbook version, whose permission to start it is checked again here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`); an author that no longer exists is `409 WORK_AUTHORITY_MISSING`. Only a `ready`, `stale`, `failed` or `done` node with every required input set runs; anything else is `409 PLAYBOOK_NODE_NOT_RUNNABLE`. A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`.
4232
+ * Runs one node now. The cascade already runs every node whose inputs are set once a write, a settle or a resume makes it runnable, and never reruns a `failed` or `done` one: this is how a failed node is retried, and how a `done` node is recomputed after an upgrade changed its executor. A `collect` node takes its own input values as its output, any other node starts its executor with the node's input values mapped through the executor's `input`. The executor runs under the `policy_ids` of the case's playbook version, which must allow starting it (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). Only a `ready`, `stale`, `failed` or `done` node with every required input set runs; anything else is `409 PLAYBOOK_NODE_NOT_RUNNABLE`. A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`.
4233
4233
  *
4234
4234
  * An `upstream` node has no executor: running it pulls the current output of the node it names in the bound case, which must be `done`. This is the only way to refresh one that an upstream change left `stale`.
4235
4235
  *
@@ -4274,7 +4274,7 @@ var Playbooks = class {
4274
4274
  *
4275
4275
  * Renders one revision of a final node as files, one export per transformation: each transformation's tool is called with the case's `case_id` and `subject`, the `node_id`, the `revision` and that revision's `output`, and must answer a file (`execute.response_mode: base64`) of its `format`'s content type. The file is kept in the project's files under `/.system/playbooks/`. An export never feeds a node.
4276
4276
  *
4277
- * Without `revision` the node's current output is exported, which needs the node `done` (`409 PLAYBOOK_NODE_NOT_EXPORTABLE`); a `revision` names an earlier output or confirmation of the node. Each tool runs as the author of the case's playbook version, whose permission to call it is checked here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`.
4277
+ * Without `revision` the node's current output is exported, which needs the node `done` (`409 PLAYBOOK_NODE_NOT_EXPORTABLE`); a `revision` names an earlier output or confirmation of the node. Each tool runs under the `policy_ids` of the case's playbook version, which must allow calling it (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). A paused case is `409 PLAYBOOK_CASE_PAUSED`, and a case in a paused project `409 PROJECT_PAUSED`.
4278
4278
  *
4279
4279
  * Without `wait` every export answers `running` and settles in the background; with `wait: true` it answers once each has its file or its error.
4280
4280
  */
@@ -4506,7 +4506,7 @@ var Projects = class {
4506
4506
  /**
4507
4507
  * Update a project
4508
4508
  *
4509
- * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires projects:UpdateProject on the project, which a project-scoped policy can grant. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail.
4509
+ * Updates a project's name, its attached guardrails (`guardrail_ids` — the project-scope baseline governing every tool call by every agent in the project), the policies capping every agent turn in it (`agent_policy_ids`), its orchestration concurrency limit (`max_concurrent_runs`), its continuation-chain ceiling (`max_chain_generations`), its orchestration nesting bound (`max_orchestration_run_depth`), its inherited model route (`default_model_route_id`), its read-auditing opt-in (`audit_reads_enabled`), its priced-model requirement (`require_priced_model`), its trace-content retention window (`trace_content_retention_days`), and/or its zero-retention setting (`trace_content_mode`). At least one field is required. Requires projects:UpdateProject on the project, which a project-scoped policy can grant. Detaching a guardrail (removing an id) additionally requires guardrails:DetachGuardrail. The caller must hold every grant `agent_policy_ids` carries, else `403 POLICY_GRANT_NOT_HELD`.
4510
4510
  */
4511
4511
  static updateProject(options) {
4512
4512
  return (options.client ?? client).patch({
@@ -4808,7 +4808,7 @@ var Sessions = class {
4808
4808
  /**
4809
4809
  * Submit tool outputs
4810
4810
  *
4811
- * Submits client tool outputs for a generation that returned requires_action. The agent continues its loop and returns the final or next requires_action result. A generation that did not run in the session's conversation is 404 (GENERATION_NOT_FOUND) and receives no outputs.
4811
+ * Submits client tool outputs for a generation that returned requires_action. The agent continues its loop and returns the final or next requires_action result. A generation that did not run in the session's conversation is 404 (GENERATION_NOT_FOUND) and receives no outputs. Requires `generations:ResumeGeneration` on the generation in addition to `agents:SubmitSessionToolOutputs`; the resumed segment runs under the generation's stored authority held to the caller's.
4812
4812
  *
4813
4813
  */
4814
4814
  static submitSessionToolOutputs(options) {