@kindgi/api 0.1.2 → 0.1.3

package/src/openapi/operations.ts

@@ -140,6 +140,15 @@ const TopLevelQueryParam: ParameterSpec = {
   schema: { type: 'boolean' },
 };
 
+const RunAgentIdQueryParam: ParameterSpec = {
+  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: ParameterSpec = {
   name: 'include',
   in: 'query',
@@ -532,7 +541,7 @@ const CostToQueryParam: ParameterSpec = {
   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).',
+    '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' },
 };
 
@@ -541,10 +550,53 @@ const CostGroupByQueryParam: ParameterSpec = {
   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.',
+    "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: ParameterSpec = {
+  name: 'model',
+  in: 'query',
+  required: false,
+  description: 'Filter model calls to this model, the one actually called (exact match).',
   schema: { type: 'string' },
 };
 
+const CostServedModelQueryParam: ParameterSpec = {
+  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: ParameterSpec = {
+  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: ParameterSpec = {
+  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: ParameterSpec = {
+  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: ParameterSpec = {
   name: 'providerId',
   in: 'path',
@@ -951,14 +1003,17 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.'),
     },
   },
   {
@@ -971,6 +1026,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.'),
@@ -1022,6 +1078,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.'),
@@ -1039,6 +1096,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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',
@@ -1060,6 +1118,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.'),
@@ -1077,6 +1136,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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',
@@ -1278,12 +1338,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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).',
+      "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,
@@ -1291,8 +1353,8 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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."),
     },
   },
   {
@@ -1302,14 +1364,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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).',
+      '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.'),
     },
   },
@@ -1320,7 +1382,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.',
+      "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],
@@ -1418,7 +1480,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.',
       ),
@@ -1881,12 +1943,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'conversations.list',
     summary: 'List conversations',
     description:
-      'Cursor-paginated. Fixed sort: `openedAt desc, id desc`. Filters: `?agentId=`, `?status=open|closed`.',
+      "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,
     ],
@@ -1896,7 +1960,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
         schema: ref('ConversationCollectionPage'),
       },
       ...CommonAuthErrors,
-      '400': ErrorResponse('Malformed query parameter.'),
+      '400': ErrorResponse('Malformed query parameter or scope.'),
     },
   },
   {
@@ -1921,7 +1985,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.',
+      '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],
@@ -2243,12 +2307,14 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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=`.',
+      "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,
@@ -2256,7 +2322,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.'),
     },
   },
   {
@@ -2764,7 +2830,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.',
+      "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: [
@@ -2775,11 +2841,16 @@ export const OPERATIONS: readonly OperationSpec[] = [
       CostConversationIdQueryParam,
       CostCategoryQueryParam,
       CostProviderIdQueryParam,
+      CostModelQueryParam,
+      CostServedModelQueryParam,
+      CostRootRunIdQueryParam,
+      CostIncludeDescendantsQueryParam,
       CostFromQueryParam,
       CostToQueryParam,
       ScopeKindQueryParam,
       ScopeIdQueryParam,
       InheritQueryParam,
+      CostIncludeQueryParam,
     ],
     responses: {
       '200': { description: 'Page of cost records.', schema: ref('CostRecordCollectionPage') },
@@ -2795,7 +2866,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     summary: 'Fetch a cost record',
     tags: ['cost'],
     security: 'bearer',
-    parameters: [CostRecordIdPathParam],
+    parameters: [CostRecordIdPathParam, CostIncludeQueryParam],
     responses: {
       '200': { description: 'Cost record.', schema: ref('CostRecord') },
       ...CommonAuthErrors,
@@ -2809,7 +2880,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     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.',
+      "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: [
@@ -2821,6 +2892,10 @@ export const OPERATIONS: readonly OperationSpec[] = [
       CostAgentIdQueryParam,
       CostRunIdQueryParam,
       CostConversationIdQueryParam,
+      CostModelQueryParam,
+      CostServedModelQueryParam,
+      CostRootRunIdQueryParam,
+      CostIncludeDescendantsQueryParam,
       ScopeKindQueryParam,
       ScopeIdQueryParam,
       InheritQueryParam,