@deepraxis/cli 0.2.0-dev.39dae15 → 0.2.0-dev.45236ef

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/COMMANDS.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Generated by `bun run commands`. DO NOT EDIT.
4
4
 
5
- 421 HTTP operations; 423 commands including aliases.
5
+ 428 HTTP operations; 430 commands including aliases.
6
6
 
7
7
  Environment: `PRAXIS_ENV=develop|production` (dev package defaults to `develop`; stable package defaults to `production`). No `--env` option.
8
8
 
@@ -142,6 +142,11 @@ Handwritten commands: `login`, `logout`, `whoami`, `org list`, `org switch <orga
142
142
  | `praxis api automation action rollback <name>` | `automation.actions.rollback` | POST `/automation/v1/actions/{ns}/{name}/rollback` | `--action`, `--revision`, `--message` |
143
143
  | `praxis api automation action update <name>` | `automation.actions.update` | PUT `/automation/v1/actions/{ns}/{name}` | `--action`, `--dry-run`, `--description`, `--timeout-ms`, `--message` |
144
144
  | `praxis api automation hook send <token>` | `automation.hooks.send` | POST `/automation/v1/hooks/{trigger_id}/{token}` | `--hook` |
145
+ | `praxis api automation human-task cancel <id>` | `automation.humanTasks.cancel` | POST `/automation/v1/human-tasks/{id}/cancel` | `--reason` |
146
+ | `praxis api automation human-task delegate <id>` | `automation.humanTasks.delegate` | POST `/automation/v1/human-tasks/{id}/delegate` | `--to-user` |
147
+ | `praxis api automation human-task get <id>` | `automation.humanTasks.retrieve` | GET `/automation/v1/human-tasks/{id}` | |
148
+ | `praxis api automation human-task list` | `automation.humanTasks.list` | GET `/automation/v1/human-tasks` | `--param-limit`, `--param-cursor`, `--status`, `--run-id`, `--scope` |
149
+ | `praxis api automation human-task respond <id>` | `automation.humanTasks.respond` | POST `/automation/v1/human-tasks/{id}/respond` | `--action-id`, `--comment` |
145
150
  | `praxis api automation resolve get` | `automation.resolve.retrieve` | GET `/automation/v1/resolve` | `--target` |
146
151
  | `praxis api automation run artifact list` | `automation.runs.artifacts.list` | GET `/automation/v1/runs/{id}/artifacts` | `--run`, `--param-limit`, `--param-cursor` |
147
152
  | `praxis api automation run call list` | `automation.runs.calls.list` | GET `/automation/v1/runs/{id}/calls` | `--run`, `--param-limit`, `--param-cursor` |
@@ -294,6 +299,8 @@ Handwritten commands: `login`, `logout`, `whoami`, `org list`, `org switch <orga
294
299
  | `praxis api media library search-semantic` | `media.libraries.search.semantic.create` | POST `/media/v1/libraries/{library_id}/search/semantic` | `--library`, `--query`, `--filter`, `--top-k`, `--mode` |
295
300
  | `praxis api media library search-visual` | `media.libraries.search.visual.create` | POST `/media/v1/libraries/{library_id}/search/visual` | `--library`, `--asset-id`, `--top-k`, `--filter` |
296
301
  | `praxis api media library update <library_id>` | `media.libraries.update` | PATCH `/media/v1/libraries/{library_id}` | `--name` |
302
+ | `praxis api meta doc get <path>` | `meta.docs.retrieve` | GET `/meta/v1/docs/{path}` | `--lang` |
303
+ | `praxis api meta doc search` | `meta.docs.search` | GET `/meta/v1/docs/search` | `--q`, `--param-limit`, `--lang` |
297
304
  | `praxis api meta health get` | `meta.health.retrieve` | GET `/meta/v1/health` | |
298
305
  | `praxis api meta method get <name>` | `meta.methods.retrieve` | GET `/meta/v1/methods/{name}` | |
299
306
  | `praxis api meta method list` | `meta.methods.list` | GET `/meta/v1/methods` | `--q`, `--param-limit`, `--after-id` |
package/dist/praxis.js CHANGED
@@ -11,7 +11,7 @@ var operations = [
11
11
  resource: "agent.agents",
12
12
  method: "list",
13
13
  summary: "List agents",
14
- description: "List the agents of the workspace behind your API key, newest first, in pages of at most 100 (default 20). Use it to find an agent id before creating a session; to read one agent use agents.retrieve, to see its history use agents.versions.list. Archived agents are hidden unless include_archived is true. Filter kind=personal for durable-computer agents or kind=service for per-session environments. Pass next_page from the response as page to read the next page; a null next_page means the end.",
14
+ description: "List the agents of the workspace behind your API key, newest first, in pages of at most 100 (default 20). Use it to find an agent id before creating a session; to read one agent use agents.retrieve, to see its history use agents.versions.list. Archived agents are hidden unless include_archived is true. Filter kind=general or kind=personal for durable-computer agents or kind=service for per-session environments. Pass next_page from the response as page to read the next page; a null next_page means the end.",
15
15
  http: "GET",
16
16
  path: "/agent/v1/agents",
17
17
  streaming: "no",
@@ -56,6 +56,7 @@ var operations = [
56
56
  name: "kind",
57
57
  type: "string",
58
58
  enum: [
59
+ "general",
59
60
  "personal",
60
61
  "service"
61
62
  ],
@@ -141,17 +142,18 @@ across all toolsets allowed.`
141
142
  type: "array",
142
143
  itemType: "object",
143
144
  required: false,
144
- description: "Platform resources and services this service agent's codemode may reach, as one list of typed bindings. Only kind=service accepts a nonempty list; personal agents return 400. There are two kinds. A resource binding names one resource with id and access: database (id db_..., read_only or read_write), vector_store (id vs_..., read_only or read_write), file (id file- plus 24 letters or digits, as the File API returns it; read_only), media_library (any id without ':' or whitespace, read_only or read_write), model (a model catalog id, invoke), workflow and script (id <namespace>/<name>, invoke). A service binding opens a whole service and carries only enabled: search or browser. At most 20 bindings per type, no repeated type and id, and each service type at most once. A session is authorized by the agent version it runs: newly added bindings apply only to new sessions, and a version saved with apply=false changes no access until it is applied. Applying a version that disables, removes or downgrades a binding revokes it immediately in running sessions on older versions. A resource that is not bound returns 404, a service that is not opened returns 403, and a write to a resource bound read_only returns 403 BINDING_READ_ONLY. Unknown types, fields on the wrong kind (id, access or instructions on a service binding), wrong access and malformed ids return 400. The former databases, vector_stores and files fields are removed and return 400. Omit on create for no bindings. Saving checks added or changed database, vector_store, media_library and file bindings in the organization: unknown or deleted ids return 400. If an owner is unavailable or takes more than 3 seconds, saving succeeds with verified=false for the affected bindings. Unchanged bindings keep their previous verification result and are not rechecked. workflow and script ids are not verified at save time."
145
+ description: "Platform resources and services this service agent's codemode may reach, as one list of typed bindings. Only kind=service accepts a nonempty list; general and personal agents return 400. There are two kinds. A resource binding names one resource with id and access: database (id db_..., read_only or read_write), vector_store (id vs_..., read_only or read_write), file (id file- plus 24 letters or digits, as the File API returns it; read_only), media_library (any id without ':' or whitespace, read_only or read_write), model (a model catalog id, invoke), workflow and script (id <namespace>/<name>, invoke). A service binding opens a whole service and carries only enabled: search or browser. At most 20 bindings per type, no repeated type and id, and each service type at most once. A session is authorized by the agent version it runs: newly added bindings apply only to new sessions, and a version saved with apply=false changes no access until it is applied. Applying a version that disables, removes or downgrades a binding revokes it immediately in running sessions on older versions. A resource that is not bound returns 404, a service that is not opened returns 403, and a write to a resource bound read_only returns 403 BINDING_READ_ONLY. Unknown types, fields on the wrong kind (id, access or instructions on a service binding), wrong access and malformed ids return 400. The former databases, vector_stores and files fields are removed and return 400. Omit on create for no bindings. Saving checks added or changed database, vector_store, media_library and file bindings in the organization: unknown or deleted ids return 400. If an owner is unavailable or takes more than 3 seconds, saving succeeds with verified=false for the affected bindings. Unchanged bindings keep their previous verification result and are not rechecked. workflow and script ids are not verified at save time."
145
146
  },
146
147
  {
147
148
  name: "kind",
148
149
  type: "string",
149
150
  enum: [
151
+ "general",
150
152
  "personal",
151
153
  "service"
152
154
  ],
153
155
  required: false,
154
- description: "Immutable agent kind. personal requires computer_id; service cannot bind a computer. Omit on create to infer from computer_id. On update, the same kind is ignored; changing kind or crossing its computer binding returns 400 invalid_request_error."
156
+ description: "Immutable agent kind. general and personal require computer_id; service cannot bind a computer. Omit on create to infer from computer_id (general with a computer, service without). On update, the same kind is ignored; changing kind or crossing its computer binding returns 400 invalid_request_error."
155
157
  },
156
158
  {
157
159
  name: "computer_id",
@@ -201,7 +203,7 @@ across all toolsets allowed.`
201
203
  name: "avatar",
202
204
  type: "string",
203
205
  required: false,
204
- description: "Avatar image of the agent: an absolute https URL of at most 2048 characters, without credentials; any other value returns 400 avatar must be an https URL. It is the default picture in agent lists, the agent detail, the chat header and embedded chat when the embed appearance sets none. Saved with the agent version like other configuration, so apply=false keeps the previous avatar in effect until that version is applied. Omit on create for no avatar; on update, omit to keep it and send null to clear it. Both personal and service agents accept it. /agent/v1 only; /anthropic neither accepts nor returns it."
206
+ description: "Avatar image of the agent: an absolute https URL of at most 2048 characters, without credentials; any other value returns 400 avatar must be an https URL. It is the default picture in agent lists, the agent detail, the chat header and embedded chat when the embed appearance sets none. Saved with the agent version like other configuration, so apply=false keeps the previous avatar in effect until that version is applied. Omit on create for no avatar; on update, omit to keep it and send null to clear it. General, personal and service agents accept it. /agent/v1 only; /anthropic neither accepts nor returns it."
205
207
  },
206
208
  {
207
209
  name: "environment_id",
@@ -365,11 +367,12 @@ toolsets allowed.`
365
367
  name: "kind",
366
368
  type: "string",
367
369
  enum: [
370
+ "general",
368
371
  "personal",
369
372
  "service"
370
373
  ],
371
374
  required: false,
372
- description: "Immutable agent kind. personal requires computer_id; service cannot bind a computer. Omit on create to infer from computer_id. On update, the same kind is ignored; changing kind or crossing its computer binding returns 400 invalid_request_error."
375
+ description: "Immutable agent kind. general and personal require computer_id; service cannot bind a computer. Omit on create to infer from computer_id (general with a computer, service without). On update, the same kind is ignored; changing kind or crossing its computer binding returns 400 invalid_request_error."
373
376
  },
374
377
  {
375
378
  name: "computer_id",
@@ -419,7 +422,7 @@ toolsets allowed.`
419
422
  name: "avatar",
420
423
  type: "string",
421
424
  required: false,
422
- description: "Avatar image of the agent: an absolute https URL of at most 2048 characters, without credentials; any other value returns 400 avatar must be an https URL. It is the default picture in agent lists, the agent detail, the chat header and embedded chat when the embed appearance sets none. Saved with the agent version like other configuration, so apply=false keeps the previous avatar in effect until that version is applied. Omit on create for no avatar; on update, omit to keep it and send null to clear it. Both personal and service agents accept it. /agent/v1 only; /anthropic neither accepts nor returns it."
425
+ description: "Avatar image of the agent: an absolute https URL of at most 2048 characters, without credentials; any other value returns 400 avatar must be an https URL. It is the default picture in agent lists, the agent detail, the chat header and embedded chat when the embed appearance sets none. Saved with the agent version like other configuration, so apply=false keeps the previous avatar in effect until that version is applied. Omit on create for no avatar; on update, omit to keep it and send null to clear it. General, personal and service agents accept it. /agent/v1 only; /anthropic neither accepts nor returns it."
423
426
  },
424
427
  {
425
428
  name: "environment_id",
@@ -958,7 +961,7 @@ Praxis extension: MA only has session-scoped temporary containers and memory_sto
958
961
  resource: "agent.computers",
959
962
  method: "create",
960
963
  summary: "Create Computer",
961
- description: `Create a durable computer: a named machine whose files outlive sessions, for personal agents.
964
+ description: `Create a durable computer: a named machine whose files outlive sessions, for general and personal agents.
962
965
 
963
966
  Praxis extension: MA only has session-scoped temporary containers and memory_stores, not durable browsable computers. Archived files remain readable, but new sessions cannot bind them. environment_id is an optional recipe reference; computers start with a light sandbox and expose the public SDK sandbox_id. Lists include archived computers.`,
964
967
  http: "POST",
@@ -1409,7 +1412,7 @@ archived).`
1409
1412
  resource: "agent.deployments",
1410
1413
  method: "create",
1411
1414
  summary: "Create deployment",
1412
- description: "Freeze session parameters as a deployment; this operation does not open a session. Pass an agent id or versioned reference, a name, 1–50 user.message initial events and an environment_id from environments.list. Unlike Anthropic Managed Agents, /agent/v1 also accepts agent_with_overrides (model, permission_mode and cwd) and target=computer for personal agents, with environment_id omitted. Cron schedules use five POSIX fields and an IANA timezone. File resources are accepted. Supports vault_ids, up to 50, owned by the current organization and not archived; credential injection is deferred to a later version. Active schedules run every minute when due; session creation errors pause the deployment. Unsupported tools, mcp_servers, system and skills overrides return 400.",
1415
+ description: "Freeze session parameters as a deployment; this operation does not open a session. Pass an agent id or versioned reference, a name, 1–50 user.message initial events and an environment_id from environments.list. Unlike Anthropic Managed Agents, /agent/v1 also accepts agent_with_overrides (model, permission_mode and cwd) and target=computer for general and personal agents, with environment_id omitted. Cron schedules use five POSIX fields and an IANA timezone. File resources are accepted. Supports vault_ids, up to 50, owned by the current organization and not archived; credential injection is deferred to a later version. Active schedules run every minute when due; session creation errors pause the deployment. Unsupported tools, mcp_servers, system and skills overrides return 400.",
1413
1416
  http: "POST",
1414
1417
  path: "/agent/v1/deployments",
1415
1418
  streaming: "no",
@@ -1490,7 +1493,7 @@ created from this deployment. Maximum 50.`
1490
1493
  name: "target",
1491
1494
  type: "object",
1492
1495
  required: false,
1493
- description: "Execution target. environment (default) requires an existing, unarchived environment_id. computer is available only for personal agents and permits environment_id to be omitted."
1496
+ description: "Execution target. environment (default) requires an existing, unarchived environment_id. computer is available only for general and personal agents and permits environment_id to be omitted."
1494
1497
  }
1495
1498
  ]
1496
1499
  }
@@ -1607,7 +1610,7 @@ null to clear. Maximum 50.`
1607
1610
  name: "target",
1608
1611
  type: "object",
1609
1612
  required: false,
1610
- description: "Execution target. environment (default) requires an existing, unarchived environment_id. computer is available only for personal agents and permits environment_id to be omitted."
1613
+ description: "Execution target. environment (default) requires an existing, unarchived environment_id. computer is available only for general and personal agents and permits environment_id to be omitted."
1611
1614
  }
1612
1615
  ]
1613
1616
  }
@@ -2277,7 +2280,7 @@ Own-face extension. No request body is required. Uses the same stop implementati
2277
2280
  summary: "Compact Session (Extension)",
2278
2281
  description: `Request session context compaction and retrieve an operation receipt.
2279
2282
 
2280
- Available only on /agent/v1. The body may be omitted or {}. Optional instructions must be a string and is forwarded unchanged. Idempotency-Key is forwarded unchanged; a UUID is generated when absent. Returns { type: session_compaction, id, status, reason? }, where id is the operation ID. queued/running return 202; skipped/succeeded/failed return 200. Non-string instructions return 400 invalid_request_error. Missing or inaccessible managed sessions return 404 not_found_error.`,
2283
+ Available only on /agent/v1. The body may be omitted or {}. Optional instructions must be a string and is forwarded unchanged. Idempotency-Key is forwarded unchanged; a UUID is generated when absent. Returns { type: session_compaction, id, status, reason? }, where id is the operation ID. queued/running return 202; skipped/succeeded/failed/cancelled return 200. Non-string instructions return 400 invalid_request_error. Missing or inaccessible managed sessions return 404 not_found_error.`,
2281
2284
  http: "POST",
2282
2285
  path: "/agent/v1/sessions/{session_id}/compact",
2283
2286
  streaming: "no",
@@ -2333,7 +2336,7 @@ Available only on /agent/v1. Returns { type: session_compaction, id, status, rea
2333
2336
  summary: "List Session Compactions (Extension)",
2334
2337
  description: `Read session compaction history and summaries.
2335
2338
 
2336
- Available only on /agent/v1. Returns { data: [...] }. Each entry contains type, id, event_id, trigger, status, model, compacted_message_count, input_tokens_before, input_tokens_after, summary, error and created_at, as recorded by the service. Missing or inaccessible managed sessions return 404 not_found_error.`,
2339
+ Available only on /agent/v1. Returns { data: [...], active }. active is the queued or running compaction ({ type: session_compaction, id, status, trigger: manual|auto|idle }), or null when none; manual work takes precedence. Each data entry contains type, id, event_id, trigger, status, model, compacted_message_count, input_tokens_before, input_tokens_after, summary, error and created_at, as recorded by the service. Missing or inaccessible managed sessions return 404 not_found_error.`,
2337
2340
  http: "GET",
2338
2341
  path: "/agent/v1/sessions/{session_id}/compactions",
2339
2342
  streaming: "no",
@@ -3926,7 +3929,7 @@ file at the root of that directory.`
3926
3929
  resource: "automation.actions",
3927
3930
  method: "list",
3928
3931
  summary: "List actions",
3929
- description: "Discover callable Actions and their ns/name references without executing them. Combine each returned namespace and name as ns/name; Action calls use the current revision and do not accept @version or @tag. Filter by name or description; results include seven-day statistics and revision summaries without implementation source. Archived actions are excluded by default.",
3932
+ description: 'Discover callable Actions and their ns/name references without executing them. Combine each returned namespace and name as ns/name; Action calls use the current revision and do not accept @version or @tag. Filter by name or description; results include seven-day statistics and revision summaries without implementation source. Archived actions are excluded by default. List items carry no input contract: get the action and read current_revision.input_schema. Call it with call("ns/name", input) in a script or call: ns/name with with: in a workflow.',
3930
3933
  http: "GET",
3931
3934
  path: "/automation/v1/actions",
3932
3935
  streaming: "no",
@@ -4095,7 +4098,7 @@ file at the root of that directory.`
4095
4098
  resource: "automation.actions",
4096
4099
  method: "retrieve",
4097
4100
  summary: "Get an Action with its current input and output JSON Schemas",
4098
- description: 'Read the Action and its full current implementation, with input and output JSON Schemas at current_revision.input_schema and current_revision.output_schema. To read a built-in Action, use ns=praxis and name=<bare name>, for example name=ocr; invoke it in a script with call("ocr", input). The response ETag is the current revision ID for conditional updates.',
4101
+ description: 'Read the Action and its full current implementation, with input and output JSON Schemas at current_revision.input_schema and current_revision.output_schema. To read a built-in Action, use ns=praxis and name=<bare name>, for example name=ocr; invoke it in a script with call("ocr", input) or in a workflow step with call: ocr and with:. Input that breaks the contract returns INPUT_INVALID, with the fields in errors[]. The response ETag is the current revision ID for conditional updates.',
4099
4102
  http: "GET",
4100
4103
  path: "/automation/v1/actions/{ns}/{name}",
4101
4104
  streaming: "no",
@@ -4511,6 +4514,177 @@ file at the root of that directory.`
4511
4514
  fields: []
4512
4515
  }
4513
4516
  },
4517
+ {
4518
+ resource: "automation.humanTasks",
4519
+ method: "list",
4520
+ summary: "List human tasks",
4521
+ description: "List the human tasks that praxis/approval workflow steps opened, newest first. By default it returns only open tasks assigned to the caller: their approval inbox. scope=all lists every task of the organization, and status and run_id narrow the list. Use a returned id with retrieve for details and respond to decide. Read-only: listing never changes a task.",
4522
+ http: "GET",
4523
+ path: "/automation/v1/human-tasks",
4524
+ streaming: "no",
4525
+ pagination: true,
4526
+ pathParams: [],
4527
+ query: [
4528
+ {
4529
+ name: "limit",
4530
+ type: "integer",
4531
+ required: false,
4532
+ description: "Page size, 1–100, default 50."
4533
+ },
4534
+ {
4535
+ name: "cursor",
4536
+ type: "string",
4537
+ required: false,
4538
+ description: "The next_cursor of the previous page; omit for the first page."
4539
+ },
4540
+ {
4541
+ name: "status",
4542
+ type: "array",
4543
+ itemType: "string",
4544
+ enum: [
4545
+ "open",
4546
+ "completed",
4547
+ "expired",
4548
+ "cancelled"
4549
+ ],
4550
+ required: false,
4551
+ description: "Filter by status, comma-separated: open, completed, expired, cancelled. Defaults to open."
4552
+ },
4553
+ {
4554
+ name: "run_id",
4555
+ type: "string",
4556
+ required: false,
4557
+ description: "Only tasks opened by this run (run_)."
4558
+ },
4559
+ {
4560
+ name: "scope",
4561
+ type: "string",
4562
+ enum: [
4563
+ "assigned",
4564
+ "all"
4565
+ ],
4566
+ required: false,
4567
+ description: "assigned (default) lists only tasks assigned to the caller; all lists every task of the organization."
4568
+ }
4569
+ ]
4570
+ },
4571
+ {
4572
+ resource: "automation.humanTasks",
4573
+ method: "retrieve",
4574
+ summary: "Retrieve a human task",
4575
+ description: "Read one human task - title, Markdown body, context, actions, form, assignees, mode, due time, responses and outcome - so an assignee can choose an action and fill the form. Read-only; the Console approval page /automation/tasks/{id} reads the same resource.",
4576
+ http: "GET",
4577
+ path: "/automation/v1/human-tasks/{id}",
4578
+ streaming: "no",
4579
+ pagination: false,
4580
+ pathParams: [
4581
+ {
4582
+ name: "id",
4583
+ sdkName: "id",
4584
+ description: "Human task ID (htask_), from the list or the run's waits."
4585
+ }
4586
+ ],
4587
+ query: []
4588
+ },
4589
+ {
4590
+ resource: "automation.humanTasks",
4591
+ method: "cancel",
4592
+ summary: "Cancel a human task",
4593
+ description: "Cancel an open human task; only the person who started the run or an organization API key may cancel. The task becomes cancelled and the waiting workflow step raises a runtime error with code HUMAN_TASK_CANCELLED, which try/catch can catch. Open tasks are cancelled automatically when their run ends, so this call is not needed then.",
4594
+ http: "POST",
4595
+ path: "/automation/v1/human-tasks/{id}/cancel",
4596
+ streaming: "no",
4597
+ pagination: false,
4598
+ pathParams: [
4599
+ {
4600
+ name: "id",
4601
+ sdkName: "id",
4602
+ description: "Human task ID (htask_)."
4603
+ }
4604
+ ],
4605
+ query: [],
4606
+ body: {
4607
+ required: false,
4608
+ fields: [
4609
+ {
4610
+ name: "reason",
4611
+ type: "string",
4612
+ required: false,
4613
+ description: "Optional cancellation reason, at most 500 characters."
4614
+ }
4615
+ ]
4616
+ }
4617
+ },
4618
+ {
4619
+ resource: "automation.humanTasks",
4620
+ method: "delegate",
4621
+ summary: "Delegate a human task",
4622
+ description: "An assignee who has not responded hands their place to another user (to_user), replacing their entry in assignees.users in place, so sequential order is kept. The new user cannot already be an assignee, nor the initiator unless self-approval is allowed. The task must still be open.",
4623
+ http: "POST",
4624
+ path: "/automation/v1/human-tasks/{id}/delegate",
4625
+ streaming: "no",
4626
+ pagination: false,
4627
+ pathParams: [
4628
+ {
4629
+ name: "id",
4630
+ sdkName: "id",
4631
+ description: "Human task ID (htask_)."
4632
+ }
4633
+ ],
4634
+ query: [],
4635
+ body: {
4636
+ required: true,
4637
+ fields: [
4638
+ {
4639
+ name: "to_user",
4640
+ type: "string",
4641
+ required: true,
4642
+ description: "User ID taking over; cannot already be an assignee, nor the initiator unless self-approval is allowed."
4643
+ }
4644
+ ]
4645
+ }
4646
+ },
4647
+ {
4648
+ resource: "automation.humanTasks",
4649
+ method: "respond",
4650
+ summary: "Respond to a human task",
4651
+ description: "Submit an action (action_id), form values (values) and a comment as the calling user. Depending on the task's mode the response either decides it (status becomes completed, outcome is set, and the waiting workflow resumes with outcome as the step output) or is recorded while other assignees are awaited. When two assignees respond at once, exactly one decides and the other gets TASK_CLOSED. An agent may respond only if the workflow set allow_agent_decision. Send an Idempotency-Key to retry safely.",
4652
+ http: "POST",
4653
+ path: "/automation/v1/human-tasks/{id}/respond",
4654
+ streaming: "no",
4655
+ pagination: false,
4656
+ pathParams: [
4657
+ {
4658
+ name: "id",
4659
+ sdkName: "id",
4660
+ description: "Human task ID (htask_)."
4661
+ }
4662
+ ],
4663
+ query: [],
4664
+ body: {
4665
+ required: true,
4666
+ fields: [
4667
+ {
4668
+ name: "action_id",
4669
+ type: "string",
4670
+ required: true,
4671
+ description: "The chosen action ID from the task's actions, for example approve."
4672
+ },
4673
+ {
4674
+ name: "values",
4675
+ type: "object",
4676
+ required: false,
4677
+ description: "Any JSON object whose keys are strings and whose values are any JSON value."
4678
+ },
4679
+ {
4680
+ name: "comment",
4681
+ type: "string",
4682
+ required: false,
4683
+ description: "Comment of at most 4000 characters; required when the action has require_comment true."
4684
+ }
4685
+ ]
4686
+ }
4687
+ },
4514
4688
  {
4515
4689
  resource: "automation.resolve",
4516
4690
  method: "retrieve",
@@ -4691,7 +4865,7 @@ file at the root of that directory.`
4691
4865
  resource: "automation.runs",
4692
4866
  method: "create",
4693
4867
  summary: "Run a published target or execute draft source",
4694
- description: 'Execute a published script or workflow with target, or test unpublished code directly with source and language (ts for TypeScript, yaml for workflow YAML), without first saving or publishing a definition. Minimal script: `export default async ({ file_id }: { file_id: string }) => { const result = await call("ocr", { document: { type: "file", file_id } }); return result; }`; send it as source with language="ts", input={"file_id":"<uploaded file ID>"} and wait=0, using a PDF or image already uploaded to your account. To call a platform API directly in the same script, use the praxis SDK object, for example `praxis.model.ocr.create({ body: { model: "glm-ocr", document: { type: "file", file_id } } })`; Action IDs are strings passed to call(), not SDK methods such as praxis.ocr(...). praxis, call, invoke, console and codemode are module-scope bindings, not on globalThis, and need no import; invoke("namespace/name", input) starts a child run. target and source are mutually exclusive; target accepts ns/name@version, @tag or @range and defaults to latest when @ is omitted. Source/input validation precedes run creation, so a separate validate call is optional. input defaults to {} and must match the input schema and fit within 1 MiB. wait is 0–60 seconds (default 0): a terminal run returns 200, otherwise 202. Use the returned id with praxis.automation.runs.retrieve and inspect status, output and error; acceptance does not mean successful completion. For long-running, background or batch work, use wait: 0 and poll the run, or split work into child runs or a workflow; wait only controls the response wait and does not extend execution limits. Actions time out after 30 s (run-sandbox after 10 min); scripts have a 5 min wall-clock limit and a 30 s CPU limit; workflows default to 24 h and allow up to 7 days. Each run can start at most 100 child runs, with at most 20 active at once; nesting depth is limited to 10. Idempotency-Key is scoped to tenant, method and path for 24 hours, excluding wait from the fingerprint; replay returns the current run with Idempotent-Replayed: true, changed contents return 422 and an in-flight request returns 409. New non-deterministic run IDs contain 78 characters, compared with 46 for legacy random IDs; treat IDs as opaque strings. Historical and deterministic IDs remain valid; same-millisecond order is not guaranteed.',
4868
+ description: 'Execute a published script or workflow with target, or test unpublished code directly with source and language (ts for TypeScript, yaml for workflow YAML), without first saving or publishing a definition. Minimal script: `export default async ({ file_id }: { file_id: string }) => { const result = await call("ocr", { document: { type: "file", file_id } }); return result; }`; send it as source with language="ts", input={"file_id":"<uploaded file ID>"} and wait=0, using a PDF or image already uploaded to your account. To call a platform API directly in the same script, use the praxis SDK object, for example `praxis.model.ocr.create({ body: { model: "glm-ocr", document: { type: "file", file_id } } })`; Action IDs are strings passed to call(), not SDK methods such as praxis.ocr(...). praxis, call, invoke, console and codemode are module-scope bindings, not on globalThis, and need no import; invoke("namespace/name", input) starts a child run. target and source are mutually exclusive; target accepts ns/name@version, @tag or @range and defaults to latest when @ is omitted. Source/input validation precedes run creation, so a separate validate call is optional. input defaults to {} and must match the input schema and fit within 1 MiB. wait is 0–60 seconds (default 0): a terminal run returns 200, otherwise 202. Use the returned id with praxis.automation.runs.retrieve and inspect status, output and error; acceptance does not mean successful completion. For long-running, background or batch work, use wait: 0 and poll the run, or split work into child runs or a workflow; wait only controls the response wait and does not extend execution limits. Actions time out after 30 s (run-sandbox after 10 min); scripts have a 5 min wall-clock limit and a 30 s CPU limit; workflows default to 24 h and allow up to 30 days. Each run can start at most 100 child runs, with at most 20 active at once; nesting depth is limited to 10. Idempotency-Key is scoped to tenant, method and path for 24 hours, excluding wait from the fingerprint; replay returns the current run with Idempotent-Replayed: true, changed contents return 422 and an in-flight request returns 409. With language=yaml, source is a workflow YAML: the run input is . in the first step, and the shape is described in create workflow. Error details are in errors[] (pointer, detail, hint). New non-deterministic run IDs contain 78 characters, compared with 46 for legacy random IDs; treat IDs as opaque strings. Historical and deterministic IDs remain valid; same-millisecond order is not guaranteed.',
4695
4869
  http: "POST",
4696
4870
  path: "/automation/v1/runs",
4697
4871
  streaming: "no",
@@ -5183,7 +5357,7 @@ file at the root of that directory.`
5183
5357
  resource: "automation.scripts",
5184
5358
  method: "create",
5185
5359
  summary: "Create a script",
5186
- description: 'Save a TypeScript script as an editable draft for later reuse; this does not publish or start a run. Choose your own namespace without registering it first; praxis is reserved for built-in Actions. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. The draft is a source string with a default-exported function, for example `export default async (input: {name: string}) => ({greeting: "Hello, " + input.name});`. Scripts provide praxis, call, invoke, console and codemode as module-scope bindings, not on globalThis, with no import needed: praxis.<domain>.<resource>.<method>(...) calls a platform API, call("ocr", input) calls a built-in Action, and invoke("namespace/name", input) starts a child run. Action IDs are strings (bare names for built-ins, namespace/name for your own Actions); praxis.ocr(...) does not exist. To test it, pass that source and language=ts to praxis.automation.runs.create without publishing. To publish later, use the returned draft.revision as expected_draft_revision.',
5360
+ description: 'Save a TypeScript script as an editable draft for later reuse; this does not publish or start a run. Choose your own namespace without registering it first; praxis is reserved for built-in Actions. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. The draft is a source string with a default-exported function, for example `export default async (input: {name: string}) => ({greeting: "Hello, " + input.name});`. Scripts provide praxis, call, invoke, console and codemode as module-scope bindings, not on globalThis, with no import needed: praxis.<domain>.<resource>.<method>(...) calls a platform API, call("ocr", input) calls a built-in Action, and invoke("namespace/name", input) starts a child run. Action IDs are strings (bare names for built-ins, namespace/name for your own Actions); praxis.ocr(...) does not exist. The return value is limited to 1 MiB: write large results to a file with call("write-file", ...) and return the file ID. A call error carries errors[] (pointer, detail, hint); String(e) is only the summary. To test it, pass that source and language=ts to praxis.automation.runs.create without publishing. To publish later, use the returned draft.revision as expected_draft_revision.',
5187
5361
  http: "POST",
5188
5362
  path: "/automation/v1/scripts",
5189
5363
  streaming: "no",
@@ -6132,7 +6306,7 @@ file at the root of that directory.`
6132
6306
  resource: "automation.validate",
6133
6307
  method: "create",
6134
6308
  summary: "Validate a definition",
6135
- description: "Check source without executing it when you need diagnostics, inferred schemas or references. This is optional before praxis.automation.runs.create, which also validates source before execution. Actions, scripts and workflows are supported; results include validity without saving. Invalid source is reported with valid=false. Script/action output schemas are inferred from return types: Promise unwrapping, Record, intersections and Date. Unknown types yield an empty schema and a warning in warnings. Source diagnostics use /source or /implementation/source with 1-based line/column. For kind=action the same admission checks as action creation apply (no external imports, platform operations only as direct call(praxis/<api>.<op>, input) calls, no agent or automation calls), so source that validates is not rejected at creation.",
6309
+ description: "Check source without executing it when you need diagnostics, inferred schemas or references. This is optional before praxis.automation.runs.create, which also validates source before execution. Actions, scripts and workflows are supported; results include validity without saving. Invalid source is reported with valid=false. Script/action output schemas are inferred from return types: Promise unwrapping, Record, intersections and Date. Unknown types yield an empty schema and a warning in warnings. Source diagnostics use /source or /implementation/source with 1-based line/column. For kind=action the same admission checks as action creation apply (no external imports, platform operations only as direct call(praxis/<api>.<op>, input) calls, no agent or automation calls), so source that validates is not rejected at creation. For kind=workflow the YAML needs document (dsl, namespace, name, version) and do; each problem is one entry in errors[] (pointer, detail, hint), so read the first one. A listen outside the supported subset (to.all, inside a fork) and emit are not reported here and fail with DEFINITION_INVALID only when a run is created. Workflow syntax reference: https://deepraxis.com/docs/developers/automation/reference/workflow-syntax.",
6136
6310
  http: "POST",
6137
6311
  path: "/automation/v1/validate",
6138
6312
  streaming: "no",
@@ -6239,7 +6413,7 @@ file at the root of that directory.`
6239
6413
  resource: "automation.workflows",
6240
6414
  method: "create",
6241
6415
  summary: "Create a workflow",
6242
- description: "Save a YAML workflow as an editable draft without publishing or starting a run. Choose your own namespace without registering it first; praxis is reserved for built-in Actions. To test the draft, send its source and language=yaml to praxis.automation.runs.create. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. run.workflow accepts ns/name@range or {namespace, name, version, input}; run.script uses the same reference shape as a platform extension. Object namespace, name and version are required; version accepts an exact version, dist-tag or range, locked at publication. Object input defaults to {} and supports expressions; string references retain task-level with. run.await defaults to true and returns the child output. With false, the child uses detach and the task immediately returns {run_id}; parent cancellation does not cascade. Inline script.code returns DEFINITION_INVALID with a detail asking you to save a script and reference it first. raise.error retains its type URI, status, title and detail in the run error.",
6416
+ description: 'Workflow syntax reference: https://deepraxis.com/docs/developers/automation/reference/workflow-syntax. Save a YAML workflow as an editable draft; this does not validate, publish or run it, so check it with validate (kind=workflow) first. Minimal draft: document with dsl ("1.0.3"), namespace, name and version, plus a do list of steps, for example document: {dsl: "1.0.3", namespace: demo, name: add, version: "1.0.0"} and do: [{first: {call: demo/add-one, with: {n: "${ .n }"}}}]. call: <ns/name> calls an Action directly (bare name for built-ins such as ocr) and with is the Action input; the input contract is at current_revision.input_schema in the get-action response. run: starts a saved script or child workflow. The run input is . in the first step, and expressions are jq written as a whole ${ ... } string. Limits: Action 30 s (run-sandbox 10 min), workflow 24 h by default and 30 days at most, payload 1 MiB. Test the draft by sending its source and language=yaml to praxis.automation.runs.create. Guide: /docs/developers/automation/guides/write-workflow. Error details are in the errors[] of the response (pointer, detail, hint). Choose your own namespace without registering it first; praxis is reserved for built-in Actions. Scripts and workflows share names within the tenant; a duplicate returns NAME_TAKEN. run.workflow accepts ns/name@range or {namespace, name, version, input}; run.script uses the same reference shape as a platform extension. Object namespace, name and version are required; version accepts an exact version, dist-tag or range, locked at publication. Object input defaults to {} and supports expressions; string references retain task-level with. run.await defaults to true and returns the child output. With false, the child uses detach and the task immediately returns {run_id}; parent cancellation does not cascade. Inline script.code returns DEFINITION_INVALID with a detail asking you to save a script and reference it first. raise.error retains its type URI, status, title and detail in the run error.',
6243
6417
  http: "POST",
6244
6418
  path: "/automation/v1/workflows",
6245
6419
  streaming: "no",
@@ -6309,7 +6483,7 @@ file at the root of that directory.`
6309
6483
  resource: "automation.workflows",
6310
6484
  method: "update",
6311
6485
  summary: "Update a workflow draft",
6312
- description: "Update description, labels or draft with the current draft revision in If-Match. Even metadata-only updates create a new draft revision.",
6486
+ description: "Update description, labels or draft with the current draft revision in If-Match, taken from draft.revision in the get-workflow response. Even metadata-only updates create a new draft revision. A mismatch returns 412 PRECONDITION_FAILED; read the draft again, merge and retry. The draft is not validated here, so check it with validate (kind=workflow) before publishing. Error details are in errors[]. See the workflow syntax reference at https://deepraxis.com/docs/developers/automation/reference/workflow-syntax.",
6313
6487
  http: "PATCH",
6314
6488
  path: "/automation/v1/workflows/{ns}/{name}",
6315
6489
  streaming: "no",
@@ -6547,7 +6721,7 @@ file at the root of that directory.`
6547
6721
  "publish"
6548
6722
  ],
6549
6723
  summary: "Publish a workflow version",
6550
- description: "Publish a saved definition from its draft or an ad hoc run as a reusable version for named runs or triggers, validating the definition and locking dependencies. To test unpublished code, use praxis.automation.runs.create with source and language instead. Use draft.revision from create or retrieve as expected_draft_revision. The draft must match expected_draft_revision; an ad hoc run requires from_run and expected_source_sha256. The same version and contents return the existing version; different contents return VERSION_EXISTS, prereleases require an explicit tag (not latest, URL-safe characters only, not a version or range; violations return TAG_REQUIRED or TAG_INVALID with the complete rules in hint), and invalid definitions return DEFINITION_INVALID. Stable releases automatically advance latest only above the highest existing stable version; workflows becoming latest synchronize their declared schedule. String and object run.workflow/run.script references share version resolution and dependency locking. Publishing removes +build metadata from the version number.",
6724
+ description: "Publish a saved definition from its draft or an ad hoc run as a reusable version for named runs or triggers, validating the definition and locking dependencies. To test unpublished code, use praxis.automation.runs.create with source and language instead. Use draft.revision from create or retrieve as expected_draft_revision. The draft must match expected_draft_revision; an ad hoc run requires from_run and expected_source_sha256. The same version and contents return the existing version; different contents return VERSION_EXISTS, prereleases require an explicit tag (not latest, URL-safe characters only, not a version or range; violations return TAG_REQUIRED or TAG_INVALID with the complete rules in hint), and invalid definitions return DEFINITION_INVALID. Stable releases automatically advance latest only above the highest existing stable version; workflows becoming latest synchronize their declared schedule. String and object run.workflow/run.script references share version resolution and dependency locking. Publishing removes +build metadata from the version number. For a workflow, document namespace, name and version must equal the publish target, otherwise DEFINITION_IDENTITY_MISMATCH; where a DEFINITION_INVALID failure sits is listed in errors[] (pointer, detail, hint).",
6551
6725
  http: "POST",
6552
6726
  path: "/automation/v1/workflows/{ns}/{name}/versions",
6553
6727
  streaming: "no",
@@ -8234,7 +8408,7 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
8234
8408
  resource: "file.files",
8235
8409
  method: "create",
8236
8410
  summary: "Upload file",
8237
- description: 'Upload a file to reuse in conversations or attach to a knowledge base. Unlike OpenAI Files, uploads must be nonempty and at most 100000000 bytes, and only user_data, assistants and vision purposes are accepted. Send file bytes as a multipart file part, not a filename or file ID; in the SDK use a File or Blob, for example new File(["Return within 23 days."], "policy.txt", { type: "text/plain" }). Content determines the MIME type. Supported uploads include PDF, DOCX/XLSX/PPTX, PNG/JPEG/GIF/WebP, MP3/WAV/FLAC/OGG/M4A, MP4/WebM, and UTF-8 JSON/NDJSON/CSV/Markdown/plain text; empty, unsupported, oversized files and unsupported purposes return 400. Use Uploads for larger files. The purpose vision accepts only PNG, JPEG, GIF and WebP, while conversation images require user_data. The returned ID belongs to your tenant; upload alone does not ingest the file into Knowledge. Knowledge attachment has a lower limit of 100000000 bytes. Optionally set expires_after[anchor]=created_at with expires_after[seconds] (3600–2592000), or praxis[expires_in_seconds] (3600–7776000), never both. Without expiry, the file persists until deleted.',
8411
+ description: 'Upload a file to reuse in conversations or attach to a knowledge base. Unlike OpenAI Files, uploads must be nonempty and at most 100000000 bytes, and only user_data and vision purposes are accepted. Send file bytes as a multipart file part, not a filename or file ID; in the SDK use a File or Blob, for example new File(["Return within 23 days."], "policy.txt", { type: "text/plain" }). Content determines the MIME type. Supported uploads include PDF, DOCX/XLSX/PPTX, PNG/JPEG/GIF/WebP, MP3/WAV/FLAC/OGG/M4A, MP4/WebM, and UTF-8 JSON/NDJSON/CSV/Markdown/plain text; empty, unsupported, oversized files and unsupported purposes return 400. Use Uploads for larger files. The purpose vision accepts only PNG, JPEG, GIF and WebP, while conversation images require user_data. The returned ID belongs to your tenant; upload alone does not ingest the file into Knowledge. Knowledge attachment has a lower limit of 100000000 bytes. Optionally set expires_after[anchor]=created_at with expires_after[seconds] (3600–7776000). Without expiry, the file persists until deleted.',
8238
8412
  http: "POST",
8239
8413
  path: "/file/v1/files",
8240
8414
  streaming: "no",
@@ -8256,23 +8430,16 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
8256
8430
  type: "string",
8257
8431
  enum: [
8258
8432
  "user_data",
8259
- "assistants",
8260
8433
  "vision"
8261
8434
  ],
8262
8435
  required: true,
8263
- description: "Purpose label stored with the file: user_data, assistants or vision. The vision purpose accepts only PNG, JPEG, GIF and WebP images. Conversation image references require user_data."
8436
+ description: "Purpose label stored with the file: user_data or vision. The vision purpose accepts only PNG, JPEG, GIF and WebP images. Conversation image references require user_data."
8264
8437
  },
8265
8438
  {
8266
8439
  name: "expires_after",
8267
8440
  type: "object",
8268
8441
  required: false,
8269
8442
  description: "Optional expiry relative to created_at. Files without an expiry persist until deleted."
8270
- },
8271
- {
8272
- name: "praxis",
8273
- type: "object",
8274
- required: false,
8275
- description: "Own-face extensions. Use at most one expiry setting."
8276
8443
  }
8277
8444
  ]
8278
8445
  }
@@ -8335,7 +8502,7 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
8335
8502
  resource: "file.uploads",
8336
8503
  method: "create",
8337
8504
  summary: "Create an upload",
8338
- description: "Start a multipart upload for a file larger than the 100000000-byte direct-upload limit. Supply the exact byte length, filename, MIME type and purpose. Unlike OpenAI, uploads accept at most 2 GiB (2147483648 bytes) and only user_data, assistants and vision purposes. Add parts of at most 64000000 bytes and complete within one hour. Optional part_size enables fixed-size, retryable parts. expires_after applies to the resulting file (3600–7776000 seconds on this own face); without it the file persists until deleted.",
8505
+ description: "Start a multipart upload for a file larger than the 100000000-byte direct-upload limit. Supply the exact byte length, filename, MIME type and purpose. Unlike OpenAI, uploads accept at most 2 GiB (2147483648 bytes) and only user_data and vision purposes. Add parts of at most 64000000 bytes and complete within one hour. Optional part_size enables fixed-size, retryable parts. expires_after applies to the resulting file (3600–7776000 seconds on this own face); without it the file persists until deleted.",
8339
8506
  http: "POST",
8340
8507
  path: "/file/v1/uploads",
8341
8508
  streaming: "no",
@@ -8368,11 +8535,10 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
8368
8535
  type: "string",
8369
8536
  enum: [
8370
8537
  "user_data",
8371
- "assistants",
8372
8538
  "vision"
8373
8539
  ],
8374
8540
  required: true,
8375
- description: "Use user_data for conversation attachments, assistants for assistant files, or vision for PNG, JPEG, GIF and WebP images."
8541
+ description: "Use user_data for conversation attachments, or vision for PNG, JPEG, GIF and WebP images."
8376
8542
  },
8377
8543
  {
8378
8544
  name: "expires_after",
@@ -9552,7 +9718,7 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
9552
9718
  name: "overwrite",
9553
9719
  type: "boolean",
9554
9720
  required: false,
9555
- description: "Allow replacing an existing public_id, preserving its asset_id and increasing its version. False returns the existing resource without replacing it; defaults to true."
9721
+ description: "Allow replacing an existing public_id, preserving its asset_id and increasing its version. Only the latest version is deliverable; old version URLs return 404. Create a new public_id to retain old deliveries. False returns the existing resource without replacing it; defaults to true."
9556
9722
  },
9557
9723
  {
9558
9724
  name: "tags",
@@ -9611,7 +9777,7 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
9611
9777
  name: "file_id",
9612
9778
  type: "string",
9613
9779
  required: true,
9614
- description: "File ID to copy into this library; passed as the upload source instead of file bytes."
9780
+ description: "File ID to copy into this library; passed as the upload source instead of file bytes. This creates an independent public copy readable without authentication. Deleting the source File does not delete this asset; do not import confidential content."
9615
9781
  },
9616
9782
  {
9617
9783
  name: "public_id",
@@ -9665,7 +9831,7 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
9665
9831
  name: "overwrite",
9666
9832
  type: "boolean",
9667
9833
  required: false,
9668
- description: "Allow replacing an existing public_id, preserving its asset_id and increasing its version. False returns the existing resource without replacing it; defaults to true."
9834
+ description: "Allow replacing an existing public_id, preserving its asset_id and increasing its version. Only the latest version is deliverable; old version URLs return 404. Create a new public_id to retain old deliveries. False returns the existing resource without replacing it; defaults to true."
9669
9835
  },
9670
9836
  {
9671
9837
  name: "tags",
@@ -10182,7 +10348,7 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
10182
10348
  name: "expression",
10183
10349
  type: "string",
10184
10350
  required: false,
10185
- description: "Asset filter expression supporting field comparisons, AND, OR, NOT, parentheses and suffix wildcards. An empty expression matches all assets."
10351
+ description: 'Asset filter expression supporting field comparisons, AND, OR, NOT, parentheses and suffix wildcards. An empty expression matches all assets. For business metadata use context.sku=KETTLE-RED AND context.revision=2; request with_field: ["context"] to include context.'
10186
10352
  },
10187
10353
  {
10188
10354
  name: "sort_by",
@@ -10328,6 +10494,70 @@ The default is return=minimal: success returns HTTP 201 with an empty body. Send
10328
10494
  ]
10329
10495
  }
10330
10496
  },
10497
+ {
10498
+ resource: "meta.docs",
10499
+ method: "search",
10500
+ summary: "Search platform documentation",
10501
+ description: "Find guides and references by keyword before reading them with praxis.meta.docs.retrieve. Public; no API key required. Matches documentation titles, headings and page text without case sensitivity; all query words must occur. q is required; limit defaults to 20 and accepts 1–50. lang defaults to zh or use en for English. Returns paths, page titles, canonical URLs and short matching snippets; no matches returns an empty array.",
10502
+ http: "GET",
10503
+ path: "/meta/v1/docs/search",
10504
+ streaming: "no",
10505
+ pagination: false,
10506
+ pathParams: [],
10507
+ query: [
10508
+ {
10509
+ name: "q",
10510
+ type: "string",
10511
+ required: true,
10512
+ description: "Keywords describing the syntax or guide needed, for example export or workflow."
10513
+ },
10514
+ {
10515
+ name: "limit",
10516
+ type: "integer",
10517
+ required: false,
10518
+ description: "Maximum number of matching pages returned; integer 1–50, default 20."
10519
+ },
10520
+ {
10521
+ name: "lang",
10522
+ type: "string",
10523
+ enum: [
10524
+ "zh",
10525
+ "en"
10526
+ ],
10527
+ required: false,
10528
+ description: "Documentation language: zh for Chinese (default), en for English."
10529
+ }
10530
+ ]
10531
+ },
10532
+ {
10533
+ resource: "meta.docs",
10534
+ method: "retrieve",
10535
+ summary: "Read documentation Markdown",
10536
+ description: "Read a platform guide or reference before implementing an unfamiliar capability. Public; no API key required. Take path from praxis.meta.docs.search, or use developers/automation/guides/write-workflow. Append #heading-id to path to read only that section, including its subsections. Encode the hash as %23 over HTTP; SDK callers pass it in the path string. lang defaults to zh; en selects the English page. Unknown pages or anchors return DOC_NOT_FOUND; search again for a valid path.",
10537
+ http: "GET",
10538
+ path: "/meta/v1/docs/{path}",
10539
+ streaming: "no",
10540
+ pagination: false,
10541
+ pathParams: [
10542
+ {
10543
+ name: "path",
10544
+ sdkName: "path",
10545
+ description: "Slash-separated documentation path from docs.search; optionally append #heading-id to select a section."
10546
+ }
10547
+ ],
10548
+ query: [
10549
+ {
10550
+ name: "lang",
10551
+ type: "string",
10552
+ enum: [
10553
+ "zh",
10554
+ "en"
10555
+ ],
10556
+ required: false,
10557
+ description: "Documentation language: zh for Chinese (default), en for English."
10558
+ }
10559
+ ]
10560
+ },
10331
10561
  {
10332
10562
  resource: "meta.health",
10333
10563
  method: "retrieve",
@@ -18931,6 +19161,8 @@ var fileCancelUpload = (options) => (options.client ?? client).post({
18931
19161
  var healthCheck = (options) => (options?.client ?? client).get({ url: "/meta/v1/health", ...options });
18932
19162
  var metaMethodsSearch = (options) => (options?.client ?? client).get({ url: "/meta/v1/methods", ...options });
18933
19163
  var metaMethodsRetrieve = (options) => (options.client ?? client).get({ url: "/meta/v1/methods/{name}", ...options });
19164
+ var metaDocsRetrieve = (options) => (options.client ?? client).get({ url: "/meta/v1/docs/{path}", ...options });
19165
+ var metaDocsSearch = (options) => (options.client ?? client).get({ url: "/meta/v1/docs/search", ...options });
18934
19166
  var listModels = (options) => (options?.client ?? client).get({
18935
19167
  querySerializer: { parameters: {
18936
19168
  supported_api: { array: { explode: false } },
@@ -21707,6 +21939,84 @@ var automationHooksReceive = (options) => (options.client ?? client).post({
21707
21939
  ...options.headers
21708
21940
  }
21709
21941
  });
21942
+ var automationHumanTasksList = (options) => (options?.client ?? client).get({
21943
+ querySerializer: { parameters: { status: { array: { explode: false } } } },
21944
+ security: [{
21945
+ key: "BearerAuth",
21946
+ scheme: "bearer",
21947
+ type: "http"
21948
+ }, {
21949
+ key: "ApiKeyAuth",
21950
+ name: "X-API-Key",
21951
+ type: "apiKey"
21952
+ }],
21953
+ url: "/automation/v1/human-tasks",
21954
+ ...options
21955
+ });
21956
+ var automationHumanTasksGet = (options) => (options.client ?? client).get({
21957
+ security: [{
21958
+ key: "BearerAuth",
21959
+ scheme: "bearer",
21960
+ type: "http"
21961
+ }, {
21962
+ key: "ApiKeyAuth",
21963
+ name: "X-API-Key",
21964
+ type: "apiKey"
21965
+ }],
21966
+ url: "/automation/v1/human-tasks/{id}",
21967
+ ...options
21968
+ });
21969
+ var automationHumanTasksRespond = (options) => (options.client ?? client).post({
21970
+ security: [{
21971
+ key: "BearerAuth",
21972
+ scheme: "bearer",
21973
+ type: "http"
21974
+ }, {
21975
+ key: "ApiKeyAuth",
21976
+ name: "X-API-Key",
21977
+ type: "apiKey"
21978
+ }],
21979
+ url: "/automation/v1/human-tasks/{id}/respond",
21980
+ ...options,
21981
+ headers: {
21982
+ "Content-Type": "application/json",
21983
+ ...options.headers
21984
+ }
21985
+ });
21986
+ var automationHumanTasksCancel = (options) => (options.client ?? client).post({
21987
+ security: [{
21988
+ key: "BearerAuth",
21989
+ scheme: "bearer",
21990
+ type: "http"
21991
+ }, {
21992
+ key: "ApiKeyAuth",
21993
+ name: "X-API-Key",
21994
+ type: "apiKey"
21995
+ }],
21996
+ url: "/automation/v1/human-tasks/{id}/cancel",
21997
+ ...options,
21998
+ headers: {
21999
+ "Content-Type": "application/json",
22000
+ ...options.headers
22001
+ }
22002
+ });
22003
+ var automationHumanTasksDelegate = (options) => (options.client ?? client).post({
22004
+ security: [{
22005
+ key: "BearerAuth",
22006
+ scheme: "bearer",
22007
+ type: "http"
22008
+ }, {
22009
+ key: "ApiKeyAuth",
22010
+ name: "X-API-Key",
22011
+ type: "apiKey"
22012
+ }],
22013
+ url: "/automation/v1/human-tasks/{id}/delegate",
22014
+ ...options,
22015
+ headers: {
22016
+ "Content-Type": "application/json",
22017
+ ...options.headers
22018
+ }
22019
+ });
21710
22020
  var databaseListDatabases = (options) => (options?.client ?? client).get({
21711
22021
  security: [{
21712
22022
  key: "database-bearerAuth",
@@ -24177,6 +24487,13 @@ function createAutomation(transport) {
24177
24487
  hooks: {
24178
24488
  send: bind(transport, automationHooksReceive)
24179
24489
  },
24490
+ humanTasks: {
24491
+ cancel: bind(transport, automationHumanTasksCancel),
24492
+ delegate: bind(transport, automationHumanTasksDelegate),
24493
+ list: bindPage(transport, automationHumanTasksList),
24494
+ respond: bind(transport, automationHumanTasksRespond),
24495
+ retrieve: bind(transport, automationHumanTasksGet)
24496
+ },
24180
24497
  resolve: {
24181
24498
  retrieve: bind(transport, automationResolveResolve)
24182
24499
  },
@@ -24467,6 +24784,10 @@ function createMedia(transport) {
24467
24784
  }
24468
24785
  function createMeta(transport) {
24469
24786
  return {
24787
+ docs: {
24788
+ retrieve: bind(transport, metaDocsRetrieve),
24789
+ search: bind(transport, metaDocsSearch)
24790
+ },
24470
24791
  health: {
24471
24792
  retrieve: bind(transport, healthCheck)
24472
24793
  },
@@ -24958,7 +25279,7 @@ function assertKnownOptions(options) {
24958
25279
  class Transport {
24959
25280
  config;
24960
25281
  constructor(options) {
24961
- this.config = { timeoutMs: 60000, maxRetries: 2, fetch: globalThis.fetch, ...options };
25282
+ this.config = { timeoutMs: 600000, maxRetries: 2, fetch: globalThis.fetch, ...options };
24962
25283
  this.validate(this.config.timeoutMs, this.config.maxRetries);
24963
25284
  }
24964
25285
  validate(timeout, retries) {
@@ -26430,8 +26751,9 @@ function jwtFetch(fetchImpl, token) {
26430
26751
  function credentials(config, vars, ports) {
26431
26752
  const path = ports.path ?? tokenPath(config.env);
26432
26753
  const store = ports.store ?? createTokenStore(config.env, path, ports.secretStore);
26754
+ const source = credentialSource(vars);
26433
26755
  const apiKey = vars.PRAXIS_API_KEY;
26434
- const machineToken = credentialSource(vars) === "machine-token" ? vars.PRAXIS_API_TOKEN : undefined;
26756
+ const machineToken = source === "machine-token" ? vars.PRAXIS_API_TOKEN : undefined;
26435
26757
  const remember = ports.remember ?? (() => {});
26436
26758
  if (apiKey)
26437
26759
  remember(apiKey);
@@ -26493,6 +26815,7 @@ function credentials(config, vars, ports) {
26493
26815
  }
26494
26816
  }
26495
26817
  return {
26818
+ source,
26496
26819
  get,
26497
26820
  requireLogin,
26498
26821
  async client(org) {
@@ -26548,13 +26871,13 @@ function skillDocument(commands) {
26548
26871
  "## General rules",
26549
26872
  "",
26550
26873
  "- Select the environment only with `PRAXIS_ENV`; there is no `--env` option. The dev package defaults to develop.",
26551
- "- Authenticate with `PRAXIS_API_KEY`, `PRAXIS_API_TOKEN` (a machine token, sent in the Authorization header; computers have it set) or `praxis login`, in that order. API keys and machine tokens determine the organization; login sessions can use `--org <organization_id>`. `PRAXIS_API_URL` overrides the API base and must be an https deepraxis.com URL.",
26874
+ "- Authenticate with `PRAXIS_API_KEY`, `PRAXIS_API_TOKEN` (a machine token, sent in the Authorization header; computers have it set) or `praxis login`, in that order. Login saves the session even when an environment credential takes precedence; unset the named variable in its warning to use the saved login. API keys and machine tokens determine the organization; login sessions can use `--org <organization_id>`. `PRAXIS_API_URL` overrides the API base and must be an https deepraxis.com URL.",
26552
26875
  "- AI mode is enabled automatically in supported agent environments. Use `--format agent` to select it explicitly.",
26553
26876
  "- Use `--json` for the complete JSON response without presentation truncation. Successful JSON output goes to stdout; errors go to stderr.",
26554
26877
  "- Supply bodies with `--data JSON`, `--data @file.json`, or `--data -` for stdin. Scalar field options override matching JSON fields. Structured fields require `--data`.",
26555
26878
  "- Deletion requires `--yes` in AI mode. Confirm the intended resource before using it.",
26556
26879
  "- Use `--limit N` to limit a server page for SDK-paginated commands. Other lists apply it only to displayed rows; `--param-limit` still sends the API parameter when available. `--all` follows supported pagination and cannot be combined with `--limit`.",
26557
- "- Error JSON has an `error` object: `code` identifies the failure, `message` describes it, `hint` suggests recovery, `env` identifies the environment, `command` identifies the command, `status` is the HTTP status, and `request_id` correlates diagnostics. Unavailable fields are null. Exit codes: 0 success, 1 runtime/API error, 2 usage error.",
26880
+ "- Error JSON has an `error` object: `code` identifies the failure, `message` describes it, `hint` suggests recovery, `env` identifies the environment, `command` identifies the command, `status` is the HTTP status, and `request_id` correlates diagnostics. Authentication failures also include `credential_source` (api-key, machine-token, or login); follow the source-specific hint. Unavailable fields are null. Exit codes: 0 success, 1 runtime/API error, 2 usage error.",
26558
26881
  "- Append `--help` to a command for its optional parameters. Required scalar body options below can also be supplied as fields in `--data`.",
26559
26882
  "- Two layers: top-level commands (`login`, `org`, `skill`, …) are workflows and session commands; every API operation is under `praxis api <domain> …`. `praxis api <METHOD> <path>` sends a raw request (the method is uppercase).",
26560
26883
  "",
@@ -26685,7 +27008,12 @@ Enter code: ${code.user_code}` });
26685
27008
  const location = await (ports.store ?? createTokenStore(config.env, path)).save(toStored(flow.tokens, ports.now()));
26686
27009
  if (location !== "keychain")
26687
27010
  ports.emit({ kind: "message", channel: "stderr", text: "stored in a file (no system keychain available)" });
27011
+ const shadowedBy = ports.source === "api-key" ? "PRAXIS_API_KEY" : ports.source === "machine-token" ? "PRAXIS_API_TOKEN" : undefined;
26688
27012
  ports.emit({ kind: "message", text: `Logged in (${config.env}).` });
27013
+ if (shadowedBy)
27014
+ ports.emit({ kind: "message", channel: "stderr", text: `Note: ${shadowedBy} is set and takes precedence over this login. Unset it (unset ${shadowedBy}) to use the login.` });
27015
+ if (ports.json)
27016
+ ports.emit({ kind: "object", data: { env: config.env, ...shadowedBy ? { shadowed_by: shadowedBy } : {} } });
26689
27017
  }
26690
27018
  async function whoami(auth, env, org) {
26691
27019
  const credential = await auth.get(org);
@@ -27487,7 +27815,7 @@ ${usage ? `usage: ${JSON.stringify(usage)}
27487
27815
 
27488
27816
  // src/output/render.ts
27489
27817
  function errorJSON(result, ctx) {
27490
- return JSON.stringify({ error: { code: result.code, message: result.message, hint: result.hint ?? null, env: result.env, command: ctx.command ?? null, status: result.status ?? null, request_id: result.request_id ?? null } }) + `
27818
+ return JSON.stringify({ error: { code: result.code, message: result.message, hint: result.hint ?? null, env: result.env, command: ctx.command ?? null, status: result.status ?? null, request_id: result.request_id ?? null, ...result.credential_source ? { credential_source: result.credential_source } : {} } }) + `
27491
27819
  `;
27492
27820
  }
27493
27821
  function render(result, ctx) {
@@ -27628,6 +27956,16 @@ var humanize = (code) => {
27628
27956
  const words = code.toLowerCase().split("_").filter(Boolean).join(" ");
27629
27957
  return words.charAt(0).toUpperCase() + words.slice(1);
27630
27958
  };
27959
+ function authHint(source) {
27960
+ switch (source) {
27961
+ case "api-key":
27962
+ return "The API key from PRAXIS_API_KEY was rejected; check or replace it, or unset it to use `praxis login`.";
27963
+ case "machine-token":
27964
+ return "The machine token from PRAXIS_API_TOKEN was rejected (it may have expired); unset it to use `praxis login`, or refresh it.";
27965
+ case "login":
27966
+ return "Run `praxis login` or set PRAXIS_API_KEY.";
27967
+ }
27968
+ }
27631
27969
  function errorInput(error, ctx) {
27632
27970
  const sdk = error instanceof PraxisError ? error : undefined;
27633
27971
  const raw = record(sdk?.raw), nested = record(raw.error);
@@ -27642,11 +27980,13 @@ function errorInput(error, ctx) {
27642
27980
  if (stripped)
27643
27981
  message = `${humanize(code)}${message ? `: ${message}` : ""}`;
27644
27982
  const status = sdk?.status, request_id = sdk?.requestId;
27983
+ const authFailure = status === 401 || ["NOT_LOGGED_IN", "UNAUTHENTICATED", "TOKEN_REVOKED", "LOGIN_FAILED"].includes(code);
27984
+ const source = ctx.credentialSource ?? "login";
27645
27985
  let hint = genericHint;
27646
27986
  if (error instanceof UsageError)
27647
27987
  hint = error.hint;
27648
- else if (status === 401 || ["NOT_LOGGED_IN", "UNAUTHENTICATED", "TOKEN_REVOKED", "LOGIN_FAILED"].includes(code))
27649
- hint = "Run `praxis login` or set PRAXIS_API_KEY.";
27988
+ else if (authFailure)
27989
+ hint = authHint(source);
27650
27990
  else if (status === 404)
27651
27991
  hint = ctx.listCommand ? `Check the id; list existing ones with \`${ctx.listCommand}\`` : "Check the id.";
27652
27992
  else if (status === 403)
@@ -27655,7 +27995,7 @@ function errorInput(error, ctx) {
27655
27995
  hint = "Rate limited; retry later.";
27656
27996
  else if (status !== undefined && status >= 500)
27657
27997
  hint = `Server error; retry later.${request_id ? ` Request id: ${request_id}.` : ""}`;
27658
- return { kind: "error", code, message, hint, env: ctx.env, ...status !== undefined ? { status } : {}, ...request_id ? { request_id } : {} };
27998
+ return { kind: "error", code, message, hint, env: ctx.env, ...authFailure ? { credential_source: source } : {}, ...status !== undefined ? { status } : {}, ...request_id ? { request_id } : {} };
27659
27999
  }
27660
28000
 
27661
28001
  // src/output/progress.ts
@@ -27685,7 +28025,7 @@ function startProgress(ctx, write = (text) => writeOutput({ stderr: text })) {
27685
28025
  }
27686
28026
 
27687
28027
  // src/main.ts
27688
- var version = "0.2.0-dev.39dae15";
28028
+ var version = "0.2.0-dev.45236ef";
27689
28029
  var commands = commandTree(operations);
27690
28030
  var manual = [...workflows.map((w) => w.words), [API_WORD]];
27691
28031
  function route(argv) {
@@ -27880,6 +28220,7 @@ Examples:
27880
28220
  const auth = credentials(config, ports.env, { fetch: wireFetch, now: ports.now, path, store, remember: (s) => {
27881
28221
  secrets.push(s);
27882
28222
  } });
28223
+ ctx.credentialSource = auth.source;
27883
28224
  const org = flags.org;
27884
28225
  const confirm = (method) => confirmOperation(method, { yes: Boolean(flags.yes), noInput: Boolean(flags["no-input"]) || ctx.mode === "agent", stdinIsTTY: ports.stdinIsTTY, ask: async () => {
27885
28226
  stopProgress();
@@ -27946,7 +28287,8 @@ Examples:
27946
28287
  case "login":
27947
28288
  if (flags["no-input"] || quiet)
27948
28289
  throw new UsageError("login requires displaying a device code", "Remove --no-input / --quiet or set PRAXIS_API_KEY for scripts.");
27949
- await login(config, path, { ...ports, store, fetch: wireFetch, emit, remember: (s) => secrets.push(s) });
28290
+ ctx.credentialSource = "login";
28291
+ await login(config, path, { ...ports, source: auth.source, json: ctx.mode === "json", store, fetch: wireFetch, emit, remember: (s) => secrets.push(s) });
27950
28292
  break;
27951
28293
  case "logout":
27952
28294
  emit({ kind: "message", text: await store.delete() ? "Logged out." : "Not logged in." });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deepraxis/cli",
3
- "version": "0.2.0-dev.39dae15",
3
+ "version": "0.2.0-dev.45236ef",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "praxis": "dist/praxis.js"