@kindgi/api 0.1.2 → 0.1.3

package/dist/openapi/operations.js

@@ -77,6 +77,13 @@ const TopLevelQueryParam = {
     description: 'When true, only runs that are not a child of another run.',
     schema: { type: 'boolean' },
 };
+const RunAgentIdQueryParam = {
+    name: 'agentId',
+    in: 'query',
+    required: false,
+    description: "Only this agent's turns, at any version. Turns that ran before Kindgi 0.1.3 don't name their agent and aren't matched.",
+    schema: { type: 'string', minLength: 1 },
+};
 const RunIncludeQueryParam = {
     name: 'include',
     in: 'query',
@@ -410,16 +417,51 @@ const CostToQueryParam = {
     name: 'to',
     in: 'query',
     required: false,
-    description: 'ISO 8601 timestamp; records with `occurredAt <= to`. Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window).',
+    description: 'ISO 8601 timestamp; records with `occurredAt < to` (exclusive). Required on `/v1/cost/aggregate` (or both endpoints omitted for default last-30-days window).',
     schema: { type: 'string', format: 'date-time' },
 };
 const CostGroupByQueryParam = {
     name: 'groupBy',
     in: 'query',
     required: true,
-    description: 'Comma-separated list of dimensions to aggregate over. Each value must be one of `agentId | runId | category | providerId | day | month | tenant | conversationId`. Duplicates collapse.',
+    description: "Comma-separated list of dimensions to aggregate over. Each value must be one of `agentId | runId | category | providerId | day | month | tenant | conversationId | model | servedModel | projectId | orgId | rootRunId | flowId`. `model` is the model actually called; `servedModel` the exact version the vendor reported; `orgId` the org of the record's project. Duplicates collapse.",
+    schema: { type: 'string' },
+};
+const CostModelQueryParam = {
+    name: 'model',
+    in: 'query',
+    required: false,
+    description: 'Filter model calls to this model, the one actually called (exact match).',
     schema: { type: 'string' },
 };
+const CostServedModelQueryParam = {
+    name: 'servedModel',
+    in: 'query',
+    required: false,
+    description: 'Filter model calls to the exact model version the vendor reported (exact match).',
+    schema: { type: 'string' },
+};
+const CostRootRunIdQueryParam = {
+    name: 'rootRunId',
+    in: 'query',
+    required: false,
+    description: 'Every record of the run tree whose root is this run: a flow run and the agent turns and sub-flows it started.',
+    schema: { type: 'string', format: 'uuid' },
+};
+const CostIncludeDescendantsQueryParam = {
+    name: 'includeDescendants',
+    in: 'query',
+    required: false,
+    description: "With `runId`: the run's records and those of every run it started, at any depth. `true` or `false` (default).",
+    schema: { type: 'boolean', default: false },
+};
+const CostIncludeQueryParam = {
+    name: 'include',
+    in: 'query',
+    required: false,
+    description: "Extra fields, comma-separated. `rawUsage`: each model call's usage object exactly as the vendor reported it.",
+    schema: { type: 'string', enum: ['rawUsage'] },
+};
 const ProviderIdPathParam = {
     name: 'providerId',
     in: 'path',
@@ -763,14 +805,17 @@ export const OPERATIONS = [
         parameters: [
             LimitQueryParam,
             CursorQueryParam,
+            ScopeKindQueryParam,
+            ScopeIdQueryParam,
             ParentRunIdQueryParam,
             TopLevelQueryParam,
+            RunAgentIdQueryParam,
             RunIncludeQueryParam,
         ],
         responses: {
             '200': { description: 'Page of runs.', schema: ref('RunCollectionPage') },
             ...CommonAuthErrors,
-            '400': ErrorResponse('Malformed cursor or filter.'),
+            '400': ErrorResponse('Malformed cursor, filter or scope.'),
         },
     },
     {
@@ -783,6 +828,7 @@ export const OPERATIONS = [
         security: 'bearer',
         parameters: [RunIdPathParam],
         responses: {
+            '400': ErrorResponse('`runId` is not a run id (a UUID).'),
             '200': { description: 'Run row.', schema: ref('Run') },
             ...CommonAuthErrors,
             '404': ErrorResponse('No run with that id under this tenant.'),
@@ -831,6 +877,7 @@ export const OPERATIONS = [
         security: 'bearer',
         parameters: [RunIdPathParam, JournalSinceQueryParam],
         responses: {
+            '400': ErrorResponse('`runId` is not a run id (a UUID).'),
             '200': { description: 'Journal page.', schema: ref('RunJournalPage') },
             ...CommonAuthErrors,
             '404': ErrorResponse('No run with that id under this tenant.'),
@@ -847,6 +894,7 @@ export const OPERATIONS = [
         security: 'bearer',
         parameters: [RunIdPathParam, LastEventIdParam],
         responses: {
+            '400': ErrorResponse('`runId` is not a run id (a UUID).'),
             '200': {
                 description: 'text/event-stream. Each frame is one RunEvent.',
                 contentType: 'text/event-stream',
@@ -867,6 +915,7 @@ export const OPERATIONS = [
         security: 'bearer-or-public-run',
         parameters: [RunIdPathParam],
         responses: {
+            '400': ErrorResponse('`runId` is not a run id (a UUID).'),
             '200': { description: "The run's progress.", schema: ref('RunProgress') },
             ...CommonAuthErrors,
             '404': ErrorResponse('No run with that id that the token may read.'),
@@ -883,6 +932,7 @@ export const OPERATIONS = [
         security: 'bearer-or-public-run',
         parameters: [RunIdPathParam, LastEventIdParam],
         responses: {
+            '400': ErrorResponse('`runId` is not a run id (a UUID).'),
             '200': {
                 description: 'text/event-stream. Each frame is one RunProgressEvent.',
                 contentType: 'text/event-stream',
@@ -1073,12 +1123,14 @@ export const OPERATIONS = [
         openapiPath: '/v1/approvals',
         operationId: 'approvals.list',
         summary: 'List approvals visible to the caller',
-        description: 'Requires the token to carry a `reviewerRole`. Role-scoped: reviewers only see approvals whose `requiredRole` rank ≤ their rank (standard < senior < admin).',
+        description: "Requires a reviewer: a token that carries a `reviewerRole`, or whose user is a registered reviewer (the roster gives the role). Role-scoped: reviewers only see approvals whose `requiredRole` rank ≤ their rank (standard < senior < admin). `scopeKind`/`scopeId` narrow to one project's approvals, or every project's in an org; approvals from before Kindgi 0.1.3 have no project and are listed only without a scope.",
         tags: ['approvals'],
         security: 'bearer',
         parameters: [
             LimitQueryParam,
             CursorQueryParam,
+            ScopeKindQueryParam,
+            ScopeIdQueryParam,
             ApprovalStatusQueryParam,
             ApprovalRequiredRoleQueryParam,
             CreatedAfterQueryParam,
@@ -1086,8 +1138,8 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Page of approvals.', schema: ref('ApprovalCollectionPage') },
             ...CommonAuthErrors,
-            '400': ErrorResponse('Malformed query parameter.'),
-            '403': ErrorResponse('Token lacks a reviewer role or asked for a tier above the caller.'),
+            '400': ErrorResponse('Malformed query parameter or scope.'),
+            '403': ErrorResponse("The caller isn't a reviewer, or asked for a tier above its own."),
         },
     },
     {
@@ -1096,14 +1148,14 @@ export const OPERATIONS = [
         openapiPath: '/v1/approvals/{approvalId}',
         operationId: 'approvals.get',
         summary: 'Fetch a single approval',
-        description: 'Returns 404 for ids that exist but require a higher role than the caller (avoids cross-tier existence leaks — see API-ROUTE-CONVENTIONS.md §2.4).',
+        description: 'Returns 404 for ids that exist but require a higher role than the caller (avoids cross-tier existence leaks — see API-ROUTE-CONVENTIONS.md §2.4). A decided approval carries its `decision`: what the reviewer decided, why, and who (`decidedBy`, `user:<userId>`).',
         tags: ['approvals'],
         security: 'bearer',
         parameters: [ApprovalIdPathParam],
         responses: {
             '200': { description: 'Approval.', schema: ref('Approval') },
             ...CommonAuthErrors,
-            '403': ErrorResponse('Token lacks a reviewer role.'),
+            '403': ErrorResponse("The caller isn't a reviewer."),
             '404': ErrorResponse('No approval with that id — or the caller cannot see it.'),
         },
     },
@@ -1113,7 +1165,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/approvals/{approvalId}/complete',
         operationId: 'approvals.complete',
         summary: 'Submit a decision on an approval',
-        description: 'Records the decision (`HitlBinding.submitReview`). When the approval carries a `waitTokenId` and the decision is `approve` or `reject`, also completes the waitpoint so the suspended run resumes.',
+        description: "Records the decision (`HitlBinding.submitReview`). When the approval carries a `waitTokenId` and the decision is `approve` or `reject`, also completes the waitpoint so the suspended run resumes, with `{ decided, rationale?, decidedBy, approvalId }`: the run's journal records who decided which approval (`decidedBy` is `user:<userId>`).",
         tags: ['approvals'],
         security: 'bearer',
         parameters: [ApprovalIdPathParam, IdempotencyKeyParam],
@@ -1206,7 +1258,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Signed audit bundle.', schema: ref('ExportAuditBundleResult') },
             ...CommonMutationErrors,
-            '403': ErrorResponse('Token lacks a reviewer role.'),
+            '403': ErrorResponse("The caller isn't a reviewer."),
             '404': ErrorResponse('Approval not found, signing key id unknown, or signing not configured on this deployment.'),
         },
     },
@@ -1648,12 +1700,14 @@ export const OPERATIONS = [
         openapiPath: '/v1/conversations',
         operationId: 'conversations.list',
         summary: 'List conversations',
-        description: 'Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`.',
+        description: "Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`, and `scopeKind`/`scopeId` for one project's conversations, or every project's in an org. Conversations from before Kindgi 0.1.3 have no project and are listed only without a scope.",
         tags: ['conversations'],
         security: 'bearer',
         parameters: [
             LimitQueryParam,
             CursorQueryParam,
+            ScopeKindQueryParam,
+            ScopeIdQueryParam,
             AgentIdQueryParam,
             ConversationStatusQueryParam,
         ],
@@ -1663,7 +1717,7 @@ export const OPERATIONS = [
                 schema: ref('ConversationCollectionPage'),
             },
             ...CommonAuthErrors,
-            '400': ErrorResponse('Malformed query parameter.'),
+            '400': ErrorResponse('Malformed query parameter or scope.'),
         },
     },
     {
@@ -1687,7 +1741,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/conversations',
         operationId: 'conversations.open',
         summary: 'Open a conversation',
-        description: 'Pins `(agentId, agentVersion)` at open time. `title` defaults to `"Untitled conversation"` when omitted; `scope` accepts arbitrary JSON.',
+        description: 'Pins `(agentId, agentVersion)` at open time. `title` defaults to `"Untitled conversation"` when omitted; `projectId` puts it in a project (lists filter by it; omitted, the Default project); `scope` accepts arbitrary JSON.',
         tags: ['conversations'],
         security: 'bearer',
         parameters: [IdempotencyKeyParam],
@@ -1986,12 +2040,14 @@ export const OPERATIONS = [
         openapiPath: '/v1/provenance',
         operationId: 'provenance.list',
         summary: 'List provenance records',
-        description: 'Cursor-paginated. Metadata rows only — clients fetch the DAG payload via `GET /v1/provenance/{runId}`. Fixed sort: `createdAt desc, id desc`. Filters: `?runId=`, `?agentId=`, `?createdAfter=`.',
+        description: "Cursor-paginated. Metadata rows only — clients fetch the DAG payload via `GET /v1/provenance/{runId}`. Fixed sort: `createdAt desc, id desc`. Filters: `?runId=`, `?agentId=`, `?createdAfter=`, and `scopeKind`/`scopeId` for one project's records, or every project's in an org (records from before Kindgi 0.1.3 have no project and are listed only without a scope).",
         tags: ['provenance'],
         security: 'bearer',
         parameters: [
             LimitQueryParam,
             CursorQueryParam,
+            ScopeKindQueryParam,
+            ScopeIdQueryParam,
             ProvenanceRunIdQueryParam,
             ProvenanceAgentIdQueryParam,
             ProvenanceCreatedAfterQueryParam,
@@ -1999,7 +2055,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Page of records.', schema: ref('ProvenanceCollectionPage') },
             ...CommonAuthErrors,
-            '400': ErrorResponse('Malformed cursor or `createdAfter` timestamp.'),
+            '400': ErrorResponse('Malformed cursor, `createdAfter` timestamp or scope.'),
         },
     },
     {
@@ -2473,7 +2529,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/cost/records',
         operationId: 'cost.records.list',
         summary: 'List cost records',
-        description: 'Cursor-paginated. Filters (all AND): `runId`, `agentId`, `conversationId`, `category`, `providerId`, `from`, `to`. Sort order is fixed: `occurredAt desc, id desc`. Records represent one accounted resource event each — LLM inference, tool invocation, storage write, sandbox execution, etc.',
+        description: "Cursor-paginated. Filters (all AND): `runId` (with `includeDescendants`, its whole subtree), `rootRunId`, `agentId`, `conversationId`, `category`, `providerId`, `model`, `servedModel`, `from`, `to`. Sort order is fixed: `occurredAt desc, id desc`. Records represent one accounted resource event each — a model call (`category` `llm.inference`: one record per call, with its model, usage and what the vendor said about it), tool invocation, storage write, sandbox execution, etc. `include=rawUsage` adds each model call's usage as the vendor reported it.",
         tags: ['cost'],
         security: 'bearer',
         parameters: [
@@ -2484,11 +2540,16 @@ export const OPERATIONS = [
             CostConversationIdQueryParam,
             CostCategoryQueryParam,
             CostProviderIdQueryParam,
+            CostModelQueryParam,
+            CostServedModelQueryParam,
+            CostRootRunIdQueryParam,
+            CostIncludeDescendantsQueryParam,
             CostFromQueryParam,
             CostToQueryParam,
             ScopeKindQueryParam,
             ScopeIdQueryParam,
             InheritQueryParam,
+            CostIncludeQueryParam,
         ],
         responses: {
             '200': { description: 'Page of cost records.', schema: ref('CostRecordCollectionPage') },
@@ -2504,7 +2565,7 @@ export const OPERATIONS = [
         summary: 'Fetch a cost record',
         tags: ['cost'],
         security: 'bearer',
-        parameters: [CostRecordIdPathParam],
+        parameters: [CostRecordIdPathParam, CostIncludeQueryParam],
         responses: {
             '200': { description: 'Cost record.', schema: ref('CostRecord') },
             ...CommonAuthErrors,
@@ -2517,7 +2578,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/cost/aggregate',
         operationId: 'cost.aggregate',
         summary: 'Aggregate cost across a time window',
-        description: 'Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId + ?inherit` narrow the aggregate to a specific scope — reconciles byte-for-byte with the same scoped `/records` list.',
+        description: "Primary consumer path for dashboards. `groupBy` is required (comma-separated dimensions from the closed set); time range is required (both `from` and `to`, or both omitted for the default last-30-days window echoed back in `timeRange`). Filters compose on top of the time window. `?scopeKind + ?scopeId` narrow the aggregate to a scope: `org` covers every project in the org, so one call sums an org's spend. Each group, and the total, carries its cost and its token sums (`tokens`). `inherit` has no effect on cost records, which always belong to a project.",
         tags: ['cost'],
         security: 'bearer',
         parameters: [
@@ -2529,6 +2590,10 @@ export const OPERATIONS = [
             CostAgentIdQueryParam,
             CostRunIdQueryParam,
             CostConversationIdQueryParam,
+            CostModelQueryParam,
+            CostServedModelQueryParam,
+            CostRootRunIdQueryParam,
+            CostIncludeDescendantsQueryParam,
             ScopeKindQueryParam,
             ScopeIdQueryParam,
             InheritQueryParam,