@knowledge-stack/ksapi 1.132.0 → 1.133.0

package/docs/{WorkflowsApi.md → SystemJobsApi.md}

@@ -1,14 +1,14 @@
-# WorkflowsApi
+# SystemJobsApi
 
 All URIs are relative to *http://localhost:8000*
 
 | Method | HTTP request | Description |
 |------------- | ------------- | -------------|
-| [**cancelTemporalWorkflow**](WorkflowsApi.md#canceltemporalworkflow) | **DELETE** /v1/workflows/{workflow_id} | Cancel Temporal Workflow Handler |
-| [**dvWorkflowRerun**](WorkflowsApi.md#dvworkflowrerun) | **POST** /v1/workflows/document_versions/{workflow_id} | Dv Workflow Rerun Handler |
-| [**getDvWorkflow**](WorkflowsApi.md#getdvworkflow) | **GET** /v1/workflows/document_versions/{workflow_id} | Get Dv Workflow Handler |
-| [**getTemporalWorkflowStatus**](WorkflowsApi.md#gettemporalworkflowstatus) | **GET** /v1/workflows/{workflow_id} | Get Temporal Workflow Status Handler |
-| [**listDvWorkflows**](WorkflowsApi.md#listdvworkflows) | **GET** /v1/workflows/document_versions | List Dv Workflows Handler |
+| [**cancelTemporalWorkflow**](SystemJobsApi.md#canceltemporalworkflow) | **DELETE** /v1/system-jobs/{workflow_id} | Cancel Temporal Workflow Handler |
+| [**dvWorkflowRerun**](SystemJobsApi.md#dvworkflowrerun) | **POST** /v1/system-jobs/document_versions/{workflow_id} | Dv Workflow Rerun Handler |
+| [**getDvWorkflow**](SystemJobsApi.md#getdvworkflow) | **GET** /v1/system-jobs/document_versions/{workflow_id} | Get Dv Workflow Handler |
+| [**getTemporalWorkflowStatus**](SystemJobsApi.md#gettemporalworkflowstatus) | **GET** /v1/system-jobs/{workflow_id} | Get Temporal Workflow Status Handler |
+| [**listDvWorkflows**](SystemJobsApi.md#listdvworkflows) | **GET** /v1/system-jobs/document_versions | List Dv Workflows Handler |
 
 
 
@@ -25,7 +25,7 @@ Cancel any Temporal workflow owned by the caller\'s tenant.  No status guard
 ```ts
 import {
   Configuration,
-  WorkflowsApi,
+  SystemJobsApi,
 } from '@knowledge-stack/ksapi';
 import type { CancelTemporalWorkflowRequest } from '@knowledge-stack/ksapi';
 
@@ -37,7 +37,7 @@ async function example() {
     // Configure HTTP bearer authorization: bearerAuth
     accessToken: "YOUR BEARER TOKEN",
   });
-  const api = new WorkflowsApi(config);
+  const api = new SystemJobsApi(config);
 
   const body = {
     // string
@@ -100,7 +100,7 @@ Rerun a workflow. USER role requires ``can_write`` on the do
 ```ts
 import {
   Configuration,
-  WorkflowsApi,
+  SystemJobsApi,
 } from '@knowledge-stack/ksapi';
 import type { DvWorkflowRerunRequest } from '@knowledge-stack/ksapi';
 
@@ -112,7 +112,7 @@ async function example() {
     // Configure HTTP bearer authorization: bearerAuth
     accessToken: "YOUR BEARER TOKEN",
   });
-  const api = new WorkflowsApi(config);
+  const api = new SystemJobsApi(config);
 
   const body = {
     // string
@@ -175,7 +175,7 @@ Get single workflow detail with live Temporal status.
 ```ts
 import {
   Configuration,
-  WorkflowsApi,
+  SystemJobsApi,
 } from '@knowledge-stack/ksapi';
 import type { GetDvWorkflowRequest } from '@knowledge-stack/ksapi';
 
@@ -187,7 +187,7 @@ async function example() {
     // Configure HTTP bearer authorization: bearerAuth
     accessToken: "YOUR BEARER TOKEN",
   });
-  const api = new WorkflowsApi(config);
+  const api = new SystemJobsApi(config);
 
   const body = {
     // string
@@ -250,7 +250,7 @@ Get live Temporal status for any workflow owned by the caller\'s tenant.
 ```ts
 import {
   Configuration,
-  WorkflowsApi,
+  SystemJobsApi,
 } from '@knowledge-stack/ksapi';
 import type { GetTemporalWorkflowStatusRequest } from '@knowledge-stack/ksapi';
 
@@ -262,7 +262,7 @@ async function example() {
     // Configure HTTP bearer authorization: bearerAuth
     accessToken: "YOUR BEARER TOKEN",
   });
-  const api = new WorkflowsApi(config);
+  const api = new SystemJobsApi(config);
 
   const body = {
     // string
@@ -325,7 +325,7 @@ List all workflows for the current tenant (paginated, DB-backed).  ADMIN/OWNER s
 ```ts
 import {
   Configuration,
-  WorkflowsApi,
+  SystemJobsApi,
 } from '@knowledge-stack/ksapi';
 import type { ListDvWorkflowsRequest } from '@knowledge-stack/ksapi';
 
@@ -337,7 +337,7 @@ async function example() {
     // Configure HTTP bearer authorization: bearerAuth
     accessToken: "YOUR BEARER TOKEN",
   });
-  const api = new WorkflowsApi(config);
+  const api = new SystemJobsApi(config);
 
   const body = {
     // number | Number of items per page (optional)

package/docs/TableSearchResult.md

@@ -0,0 +1,47 @@
+
+# TableSearchResult
+
+A modeled table matched by summary search, with its query coordinates.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`dataSourceId` | string
+`tableId` | string
+`schemaName` | string
+`tableName` | string
+`name` | string
+`summary` | string
+`score` | number
+
+## Example
+
+```typescript
+import type { TableSearchResult } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "dataSourceId": null,
+  "tableId": null,
+  "schemaName": null,
+  "tableName": null,
+  "name": null,
+  "summary": null,
+  "score": null,
+} satisfies TableSearchResult
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as TableSearchResult
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/TestConnectionRequest.md

@@ -0,0 +1,41 @@
+
+# TestConnectionRequest
+
+Test a connection without persisting it.  Exactly one mode must be supplied: fresh creds (``engine`` + ``connection_config`` + ``parent_path_part_id``) or a stored connector (``data_source_id``). The handler rejects zero or both modes with a 400.  Fresh mode requires ``parent_path_part_id`` and is gated by write access to that folder — the same permission as creating a connector there. This stops an authenticated user from turning the probe into an arbitrary-host reachability scanner (SSRF) against internal networks.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`dataSourceId` | string
+`engine` | [DataSourceEngine](DataSourceEngine.md)
+`connectionConfig` | [ConnectionConfig](ConnectionConfig.md)
+`parentPathPartId` | string
+
+## Example
+
+```typescript
+import type { TestConnectionRequest } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "dataSourceId": null,
+  "engine": null,
+  "connectionConfig": null,
+  "parentPathPartId": null,
+} satisfies TestConnectionRequest
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as TestConnectionRequest
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/TestConnectionResponse.md

@@ -0,0 +1,37 @@
+
+# TestConnectionResponse
+
+Connection-test outcome carried in the body (200 either way).  ``error`` holds the failure detail when ``success`` is false so the FE can render inline validation instead of handling a 400.
+
+## Properties
+
+Name | Type
+------------ | -------------
+`success` | boolean
+`error` | string
+
+## Example
+
+```typescript
+import type { TestConnectionResponse } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+  "success": null,
+  "error": null,
+} satisfies TestConnectionResponse
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as TestConnectionResponse
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/TextPartOrReasoningPartOrToolPartOrDocEditPart.md

@@ -21,6 +21,7 @@ Name | Type
 `isError` | boolean
 `durationMs` | number
 `extras` | { [key: string]: any; }
+`displayType` | [ToolDisplayType](ToolDisplayType.md)
 `documentId` | string
 `baseVersionId` | string
 `newVersionId` | string
@@ -49,6 +50,7 @@ const example = {
   "isError": null,
   "durationMs": null,
   "extras": null,
+  "displayType": null,
   "documentId": null,
   "baseVersionId": null,
   "newVersionId": null,

package/docs/ToolDisplayType.md

@@ -0,0 +1,33 @@
+
+# ToolDisplayType
+
+Language-neutral render category for a completed tool call.  The frontend keys its activity-card registry on this token and localizes the label itself (zh/en) — the server never emits human prose here. Unknown or unmapped tools fall back to ``GENERIC`` so a new/dev tool degrades to the generic card instead of breaking rendering.
+
+## Properties
+
+Name | Type
+------------ | -------------
+
+## Example
+
+```typescript
+import type { ToolDisplayType } from '@knowledge-stack/ksapi'
+
+// TODO: Update the object below with actual values
+const example = {
+} satisfies ToolDisplayType
+
+console.log(example)
+
+// Convert the instance to a JSON string
+const exampleJSON: string = JSON.stringify(example)
+console.log(exampleJSON)
+
+// Parse the JSON string back to an object
+const exampleParsed = JSON.parse(exampleJSON) as ToolDisplayType
+console.log(exampleParsed)
+```
+
+[[Back to top]](#) [[Back to API list]](../README.md#api-endpoints) [[Back to Model list]](../README.md#models) [[Back to README]](../README.md)
+
+

package/docs/ToolPart.md

@@ -19,6 +19,7 @@ Name | Type
 `isError` | boolean
 `durationMs` | number
 `extras` | { [key: string]: any; }
+`displayType` | [ToolDisplayType](ToolDisplayType.md)
 
 ## Example
 
@@ -40,6 +41,7 @@ const example = {
   "isError": null,
   "durationMs": null,
   "extras": null,
+  "displayType": null,
 } satisfies ToolPart
 
 console.log(example)

package/docs/UpdateDataSourceRequest.md

@@ -1,7 +1,7 @@
 
 # UpdateDataSourceRequest
 
-Rename and/or move a connector (PATCH). Both fields optional.  A body with both ``None`` is rejected as a no-op 400. ``name`` renames the connector path_part; ``parent_path_part_id`` moves it under a new FOLDER (the move cascades ``materialized_path`` to the modeled-table children). Connection credentials and engine are not editable here.
+Rename, move, and/or re-credential a connector (PATCH). All optional.  A body with every field ``None`` is rejected as a no-op 400. ``name`` renames the connector path_part; ``parent_path_part_id`` moves it under a new FOLDER (the move cascades ``materialized_path`` to the modeled-table children). ``connection_config`` supplies a full, fresh credential set (never a partial patch — the stored password is never read back or echoed); it is re-validated before persisting. ``engine`` stays immutable: changing it would invalidate every modeled table\'s dialect assumptions.
 
 ## Properties
 
@@ -9,6 +9,7 @@ Name | Type
 ------------ | -------------
 `name` | string
 `parentPathPartId` | string
+`connectionConfig` | [ConnectionConfig](ConnectionConfig.md)
 
 ## Example
 
@@ -19,6 +20,7 @@ import type { UpdateDataSourceRequest } from '@knowledge-stack/ksapi'
 const example = {
   "name": null,
   "parentPathPartId": null,
+  "connectionConfig": null,
 } satisfies UpdateDataSourceRequest
 
 console.log(example)

package/docs/UpdateTableRequest.md

@@ -7,7 +7,6 @@ Field-modeling update for a modeled table (PATCH).
 
 Name | Type
 ------------ | -------------
-`description` | string
 `columnConfig` | [Array<ColumnConfig>](ColumnConfig.md)
 
 ## Example
@@ -17,7 +16,6 @@ import type { UpdateTableRequest } from '@knowledge-stack/ksapi'
 
 // TODO: Update the object below with actual values
 const example = {
-  "description": null,
   "columnConfig": null,
 } satisfies UpdateTableRequest
 

package/docs/UserMessageResponse.md

@@ -7,6 +7,7 @@
 Name | Type
 ------------ | -------------
 `workflowId` | string
+`userMessageId` | string
 
 ## Example
 
@@ -16,6 +17,7 @@ import type { UserMessageResponse } from '@knowledge-stack/ksapi'
 // TODO: Update the object below with actual values
 const example = {
   "workflowId": null,
+  "userMessageId": null,
 } satisfies UserMessageResponse
 
 console.log(example)

package/docs/WorkflowRunAsset.md

@@ -1,7 +1,7 @@
 
 # WorkflowRunAsset
 
-One input or output file/reference of a run, actionable in one call.  ``id`` is the PDO id (``path_part.metadata_obj_id``); ``path_part_id`` is the underlying path part (kept for approval-state / path-part lookups). Route on ``part_type`` to pick the API that takes ``id``: ``DOCUMENT`` → download_document / bulk-download (active version); ``DOCUMENT_VERSION`` → download_document_version (a version-pinned input, e.g. a cloned run\'s inputs); ``FOLDER`` / ``DATA_SOURCE`` / ``API_CONNECTION`` → list/query via that type\'s endpoint. Output assets are always ``DOCUMENT``.  ``origin`` tags an input asset\'s provenance (definition common file vs run reference vs upload) so the FE can group them; it is ``None`` on output assets.
+One input or output file/reference of a run, actionable in one call.  ``id`` is the PDO id (``path_part.metadata_obj_id``); ``path_part_id`` is the underlying path part (kept for approval-state / path-part lookups). Route on ``part_type`` to pick the API that takes ``id``: ``DOCUMENT`` → download_document / bulk-download (active version); ``DOCUMENT_VERSION`` → download_document_version (a version-pinned input, e.g. a cloned run\'s inputs); ``FOLDER`` / ``DATA_SOURCE`` / ``API_CONNECTION`` → list/query via that type\'s endpoint. Output assets are always ``DOCUMENT``.  ``origin`` tags an input\'s provenance. A ``DEFINITION_COMMON`` document is surfaced as a ``DOCUMENT`` (resolved from its pinned version to the parent document) so it routes to the doc page like a run-picked reference.
 
 ## Properties
 

package/docs/WorkflowRunResponse.md

@@ -24,14 +24,9 @@ Name | Type
 `error` | string
 `autoStart` | boolean
 `autoStartUserMessage` | string
-`inputsPathPartId` | string
-`outputsPathPartId` | string
-`discussionsPathPartId` | string
-`inputPathPartIds` | Array<string>
-`outputAssets` | [Array<WorkflowRunAsset>](WorkflowRunAsset.md)
-`inputAssets` | [Array<WorkflowRunAsset>](WorkflowRunAsset.md)
-`inputsPath` | string
-`outputsPath` | string
+`inputs` | [RunFolder](RunFolder.md)
+`outputs` | [RunFolder](RunFolder.md)
+`discussions` | [RunFolderRef](RunFolderRef.md)
 `excludedCommonFiles` | [Array<ExcludedCommonFile>](ExcludedCommonFile.md)
 `runThreadId` | string
 `owner` | [UserInfo](UserInfo.md)
@@ -63,14 +58,9 @@ const example = {
   "error": null,
   "autoStart": null,
   "autoStartUserMessage": null,
-  "inputsPathPartId": null,
-  "outputsPathPartId": null,
-  "discussionsPathPartId": null,
-  "inputPathPartIds": null,
-  "outputAssets": null,
-  "inputAssets": null,
-  "inputsPath": null,
-  "outputsPath": null,
+  "inputs": null,
+  "outputs": null,
+  "discussions": null,
   "excludedCommonFiles": null,
   "runThreadId": null,
   "owner": null,

package/docs/WorkflowRunsApi.md

@@ -449,7 +449,7 @@ example().catch(console.error);
 
 Retry Workflow Run Handler
 
-Re-run a FAILED run (including a user-stopped one) in place.  Flips ``FAILED -> IN_PROGRESS`` against the run\'s existing snapshot and re-dispatches the agent. 409 if the run is not FAILED (NOT_STARTED/PENDING use Start; COMPLETED is cloned) or was never started. Triggerer or OWNER/ADMIN only.
+Re-run a FAILED run (including a user-stopped one) in place.  Flips ``FAILED -> IN_PROGRESS`` against the run\'s existing snapshot and re-dispatches the agent. 409 if the run is not FAILED (NOT_STARTED/PENDING use Start; COMPLETED is cloned) or was never started. Triggerer or OWNER/ADMIN only.  Runs in the background — poll ``GET /v1/workflow-runs/{run_id}`` (also given in the ``Location`` header) until ``execution_state`` is COMPLETED or FAILED.
 
 ### Example
 
@@ -511,7 +511,7 @@ example().catch(console.error);
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **202** | Successful Response |  -  |
+| **202** | Successful Response |  * Location - Poll this run resource until &#x60;&#x60;execution_state&#x60;&#x60; is COMPLETED or FAILED. <br>  |
 | **422** | Validation Error |  -  |
 | **0** | Error response. |  -  |
 
@@ -602,7 +602,7 @@ example().catch(console.error);
 
 Start Workflow Run Handler
 
-Flip a NOT_STARTED run to IN_PROGRESS and dispatch its agent run.  Idempotent on IN_PROGRESS (returns the row). Terminal states → 409. Inputs still ingesting or in a failed terminal state → 409. The snapshot is built at this point (KB DOCUMENTs resolve to active versions, uploaded DVs are walked from inputs/, KB FOLDERs stay live).  The body is optional; &#x60;&#x60;user_message&#x60;&#x60; (when sent) is pinned into the snapshot and shown in the run thread (see &#x60;&#x60;StartWorkflowRunRequest&#x60;&#x60;).
+Flip a NOT_STARTED run to IN_PROGRESS and dispatch its agent run.  Idempotent on IN_PROGRESS (returns the row). Terminal states → 409. Inputs still ingesting or in a failed terminal state → 409. The snapshot is built at this point (KB DOCUMENTs resolve to active versions, uploaded DVs are walked from inputs/, KB FOLDERs stay live).  The body is optional; &#x60;&#x60;user_message&#x60;&#x60; (when sent) is pinned into the snapshot and shown in the run thread (see &#x60;&#x60;StartWorkflowRunRequest&#x60;&#x60;).  The run executes in the background — poll &#x60;&#x60;GET /v1/workflow-runs/{run_id}&#x60;&#x60; (also given in the &#x60;&#x60;Location&#x60;&#x60; header) until &#x60;&#x60;execution_state&#x60;&#x60; is COMPLETED or FAILED. There is no completion webhook.
 
 ### Example
 
@@ -667,7 +667,7 @@ example().catch(console.error);
 ### HTTP response details
 | Status code | Description | Response headers |
 |-------------|-------------|------------------|
-| **202** | Successful Response |  -  |
+| **202** | Successful Response |  * Location - Poll this run resource until &#x60;&#x60;execution_state&#x60;&#x60; is COMPLETED or FAILED. <br>  |
 | **422** | Validation Error |  -  |
 | **0** | Error response. |  -  |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledge-stack/ksapi",
-  "version": "1.132.0",
+  "version": "1.133.0",
   "description": "OpenAPI client for @knowledge-stack/ksapi",
   "author": "OpenAPI-Generator",
   "repository": {

package/src/apis/AgentApi.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 /**
  * Knowledge Stack API
- * Knowledge Stack backend API for authentication and knowledge management
+ * Knowledge Stack backend API for authentication and knowledge management.  ## Integrating (RPA / machine clients)  **Base URL.** Knowledge Stack is self-hosted — point at your own deployment host (see `servers`). The `localhost` entry is for local development only.  **Authentication.** Send `Authorization: Bearer <api-key>` on every request. Mint an API key once via `POST /v1/api-keys` from a signed-in browser session; the raw `sk-user-...` secret is returned **only** at creation, so store it then. A key inherits its owning user\'s live tenant role and path permissions — create RPA keys from a least-privilege user, and set `expires_at` for rotation. The `ks_uat` cookie scheme is browser-only and cannot be used by headless clients.  **Async work is polled, not pushed.** There are no outbound webhooks. - `POST /v1/documents/ingest` returns `201` immediately with a `workflow_id`;   poll `GET /v1/system-jobs/document_versions/{workflow_id}` until `status` is   terminal (anything other than `pending`/`processing`). The `Location` response   header points at this poll resource. - `POST /v1/workflow-runs/{run_id}/start` returns `202`; poll   `GET /v1/workflow-runs/{run_id}` until `execution_state` is `COMPLETED` or   `FAILED`. The `Location` header points at the run resource. - `POST /v1/agent/ask` is **synchronous** — it blocks until the agent finishes   and returns the answer inline. Use a generous HTTP timeout.  **Pagination.** List endpoints accept `limit`/`offset` and return `{items, total, limit, offset}`.  **Errors.** Every non-2xx body is `{detail, code, request_id}`. `code` is a stable value from a closed set (see the `ErrorResponse` schema\'s `code` enum) — branch on it rather than parsing `detail`. Quota rejections return `429` with a `Retry-After` header; transient lock contention returns a retryable `503`. Quote `request_id` (also the `x-request-id` response header) to support.  **Idempotency.** `POST /v1/workflow-runs` accepts an `idempotency_key` to dedupe retried run creation. `agent/ask` charges one message *before* running and does not refund a client-cancelled call. 
  *
  * The version of the OpenAPI document: 0.1.0
  * 
@@ -61,7 +61,7 @@ export interface AgentApiInterface {
     agentAskRequestOpts(requestParameters: AgentAskRequest): Promise<runtime.RequestOpts>;
 
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/system-jobs/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * @summary Agent Ask Handler
      * @param {AskRequest} askRequest 
      * @param {*} [options] Override http request option.
@@ -71,7 +71,7 @@ export interface AgentApiInterface {
     agentAskRaw(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AskResponse>>;
 
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/system-jobs/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     agentAsk(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AskResponse>;
@@ -145,7 +145,7 @@ export class AgentApi extends runtime.BaseAPI implements AgentApiInterface {
     }
 
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/system-jobs/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     async agentAskRaw(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AskResponse>> {
@@ -156,7 +156,7 @@ export class AgentApi extends runtime.BaseAPI implements AgentApiInterface {
     }
 
     /**
-     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/workflows/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
+     * Run a one-shot text agent request to completion and return the payload.  The request blocks until the underlying Temporal workflow finishes. Clients should set a generous HTTP timeout to accommodate tool-heavy runs.  Quota: consumes one MESSAGE before ``start_workflow``. Refund semantics distinguish cause:  * **Cancellation** (client disconnect → ``asyncio.CancelledError``,   OR explicit ``DELETE /v1/system-jobs/{id}`` while we await   ``handle.result()`` → Temporal-wrapped ``CancelledError``)   → **NO REFUND.** The user walked away or actively cancelled;   that\'s their volition. We still best-effort cancel the   workflow so the agent stops burning LLM tokens, but the   consume stays charged. Detection uses   ``temporalio.exceptions.is_cancelled_exception`` which spans   both forms. * Any other exception (pre-enqueue ``start_workflow`` raise,   Temporal failure, workflow-internal error) → **REFUND.** Server   / our-problem failures don\'t bill the user.
      * Agent Ask Handler
      */
     async agentAsk(requestParameters: AgentAskRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AskResponse> {

package/src/apis/ApiConnectionsApi.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 /**
  * Knowledge Stack API
- * Knowledge Stack backend API for authentication and knowledge management
+ * Knowledge Stack backend API for authentication and knowledge management.  ## Integrating (RPA / machine clients)  **Base URL.** Knowledge Stack is self-hosted — point at your own deployment host (see `servers`). The `localhost` entry is for local development only.  **Authentication.** Send `Authorization: Bearer <api-key>` on every request. Mint an API key once via `POST /v1/api-keys` from a signed-in browser session; the raw `sk-user-...` secret is returned **only** at creation, so store it then. A key inherits its owning user\'s live tenant role and path permissions — create RPA keys from a least-privilege user, and set `expires_at` for rotation. The `ks_uat` cookie scheme is browser-only and cannot be used by headless clients.  **Async work is polled, not pushed.** There are no outbound webhooks. - `POST /v1/documents/ingest` returns `201` immediately with a `workflow_id`;   poll `GET /v1/system-jobs/document_versions/{workflow_id}` until `status` is   terminal (anything other than `pending`/`processing`). The `Location` response   header points at this poll resource. - `POST /v1/workflow-runs/{run_id}/start` returns `202`; poll   `GET /v1/workflow-runs/{run_id}` until `execution_state` is `COMPLETED` or   `FAILED`. The `Location` header points at the run resource. - `POST /v1/agent/ask` is **synchronous** — it blocks until the agent finishes   and returns the answer inline. Use a generous HTTP timeout.  **Pagination.** List endpoints accept `limit`/`offset` and return `{items, total, limit, offset}`.  **Errors.** Every non-2xx body is `{detail, code, request_id}`. `code` is a stable value from a closed set (see the `ErrorResponse` schema\'s `code` enum) — branch on it rather than parsing `detail`. Quota rejections return `429` with a `Retry-After` header; transient lock contention returns a retryable `503`. Quote `request_id` (also the `x-request-id` response header) to support.  **Idempotency.** `POST /v1/workflow-runs` accepts an `idempotency_key` to dedupe retried run creation. `agent/ask` charges one message *before* running and does not refund a client-cancelled call. 
  *
  * The version of the OpenAPI document: 0.1.0
  * 

package/src/apis/ApiKeysApi.ts

@@ -2,7 +2,7 @@
 /* eslint-disable */
 /**
  * Knowledge Stack API
- * Knowledge Stack backend API for authentication and knowledge management
+ * Knowledge Stack backend API for authentication and knowledge management.  ## Integrating (RPA / machine clients)  **Base URL.** Knowledge Stack is self-hosted — point at your own deployment host (see `servers`). The `localhost` entry is for local development only.  **Authentication.** Send `Authorization: Bearer <api-key>` on every request. Mint an API key once via `POST /v1/api-keys` from a signed-in browser session; the raw `sk-user-...` secret is returned **only** at creation, so store it then. A key inherits its owning user\'s live tenant role and path permissions — create RPA keys from a least-privilege user, and set `expires_at` for rotation. The `ks_uat` cookie scheme is browser-only and cannot be used by headless clients.  **Async work is polled, not pushed.** There are no outbound webhooks. - `POST /v1/documents/ingest` returns `201` immediately with a `workflow_id`;   poll `GET /v1/system-jobs/document_versions/{workflow_id}` until `status` is   terminal (anything other than `pending`/`processing`). The `Location` response   header points at this poll resource. - `POST /v1/workflow-runs/{run_id}/start` returns `202`; poll   `GET /v1/workflow-runs/{run_id}` until `execution_state` is `COMPLETED` or   `FAILED`. The `Location` header points at the run resource. - `POST /v1/agent/ask` is **synchronous** — it blocks until the agent finishes   and returns the answer inline. Use a generous HTTP timeout.  **Pagination.** List endpoints accept `limit`/`offset` and return `{items, total, limit, offset}`.  **Errors.** Every non-2xx body is `{detail, code, request_id}`. `code` is a stable value from a closed set (see the `ErrorResponse` schema\'s `code` enum) — branch on it rather than parsing `detail`. Quota rejections return `429` with a `Retry-After` header; transient lock contention returns a retryable `503`. Quote `request_id` (also the `x-request-id` response header) to support.  **Idempotency.** `POST /v1/workflow-runs` accepts an `idempotency_key` to dedupe retried run creation. `agent/ask` charges one message *before* running and does not refund a client-cancelled call. 
  *
  * The version of the OpenAPI document: 0.1.0
  *