@kindgi/api 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/api",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "REST + SSE HTTP surface for Kindgi™. createApp assembles a Hono app serving the /v1/* REST API (bearer or session-token auth; OpenAPI 3.1 document at /v1/openapi.json) and an optional S3-compatible /s3/* surface (SigV4), over caller-plugged bindings for the runtime (runs, agents, flows, HITL, supervisor) and for storage. Route conventions: docs/API-ROUTE-CONVENTIONS.md.",
   "license": "Apache-2.0",
   "repository": {
@@ -18,7 +18,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./openapi.json": "./openapi.json",
     "./package.json": "./package.json"
@@ -31,31 +32,30 @@
     "openapi.json"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.1",
-    "@kindgi/audit-events": "0.1.1",
-    "@kindgi/compliance": "0.1.1",
-    "@kindgi/authz": "0.1.1",
-    "@kindgi/blob-binding": "0.1.1",
-    "@kindgi/capabilities": "0.1.1",
-    "@kindgi/crypto": "0.1.1",
-    "@kindgi/flow": "0.1.1",
-    "@kindgi/guardrails": "0.1.1",
-    "@kindgi/memory": "0.1.1",
-    "@kindgi/platform": "0.1.1",
-    "@kindgi/provenance": "0.1.1",
-    "@kindgi/runtime": "0.1.1",
-    "@kindgi/policy-contract": "0.1.1",
-    "@kindgi/schema": "0.1.1",
-    "@kindgi/tools": "0.1.1",
-    "@kindgi/types": "0.1.1",
+    "@kindgi/agents": "0.1.3",
+    "@kindgi/audit-events": "0.1.3",
+    "@kindgi/compliance": "0.1.3",
+    "@kindgi/authz": "0.1.3",
+    "@kindgi/blob-binding": "0.1.3",
+    "@kindgi/capabilities": "0.1.3",
+    "@kindgi/crypto": "0.1.3",
+    "@kindgi/flow": "0.1.3",
+    "@kindgi/guardrails": "0.1.3",
+    "@kindgi/memory": "0.1.3",
+    "@kindgi/platform": "0.1.3",
+    "@kindgi/provenance": "0.1.3",
+    "@kindgi/runtime": "0.1.3",
+    "@kindgi/policy-contract": "0.1.3",
+    "@kindgi/schema": "0.1.3",
+    "@kindgi/tools": "0.1.3",
+    "@kindgi/types": "0.1.3",
     "@scalar/hono-api-reference": "^0.12.2",
-    "drizzle-orm": "^0.36.4",
     "hono": "^4.6.14"
   },
   "devDependencies": {
-    "@kindgi/audit-events-inmemory": "0.1.1",
-    "@kindgi/specs": "0.1.1",
-    "@kindgi/testing": "0.1.1",
+    "@kindgi/audit-events-inmemory": "0.1.3",
+    "@kindgi/specs": "0.1.3",
+    "@kindgi/testing": "0.1.3",
     "@types/aws4": "^1.11.6",
     "@types/node": "^22.10.5",
     "aws4": "^1.13.2",
@@ -63,7 +63,7 @@
     "vitest": "^2.1.8"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "access": "public",

package/src/app.ts

@@ -955,7 +955,10 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
       authorizer,
     ),
   );
-  v1.route('/conversations', conversationsRouter(input.conversationBinding, runBinding));
+  v1.route(
+    '/conversations',
+    conversationsRouter(input.conversationBinding, runBinding, input.projectBinding),
+  );
   if (publicRunTokenLimits !== undefined) {
     v1.route(
       '/tokens/public',
@@ -1070,6 +1073,7 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
     identityRouter({
       ...(input.identityDirectory !== undefined && { directory: input.identityDirectory }),
       ...(input.sessionStore !== undefined && { sessionStore: input.sessionStore }),
+      ...(input.reviewerBinding !== undefined && { reviewerBinding: input.reviewerBinding }),
     }),
   );
   if (input.cost !== undefined) {

package/src/cost-binding.ts

@@ -42,13 +42,16 @@ export interface CostBinding {
   getRecord(input: CostGetRecordInput): Promise<CostRecord | null>;
   /**
    * Multi-dimensional aggregate rollup. `groupBy` may combine any
-   * subset of `agentId | runId | category | providerId | day | month
-   * | tenant | conversationId`; the binding returns one group per
-   * distinct key tuple within the required `from`..`to` window.
+   * subset of `COST_GROUP_DIMENSIONS`; the binding returns one group per
+   * distinct key tuple within the required `from`..`to` window, with its
+   * cost and token sums.
    */
   aggregate(input: CostAggregateInput): Promise<CostAggregateResult>;
 }
 
+// A binding throws when its store fails: the route answers 500. It never
+// answers a failed read with an empty page or zero sums.
+
 // -------- listRecords --------
 
 export interface CostListRecordsInput {
@@ -80,6 +83,8 @@ export interface CostListRecordsInput {
    * uniformity: scope-aware bindings share one filter shape.
    */
   readonly inherit?: boolean;
+  /** Add each record's `rawUsage`: the vendor's own usage object. */
+  readonly includeRawUsage?: boolean;
 }
 
 export interface CostRecordFilter {
@@ -94,7 +99,20 @@ export interface CostRecordFilter {
    */
   readonly category?: string;
   readonly providerId?: string;
+  /** The model actually called. */
+  readonly model?: string;
+  /** The exact model version the vendor reported. */
+  readonly servedModel?: string;
+  /** Every record of the run tree whose root is this run. */
+  readonly rootRunId?: string;
+  /**
+   * With `runId`: that run's records and those of every run it started,
+   * at any depth.
+   */
+  readonly includeDescendants?: boolean;
+  /** Inclusive. */
   readonly from?: Date;
+  /** Exclusive. */
   readonly to?: Date;
 }
 
@@ -108,6 +126,8 @@ export interface CostRecordPage {
 export interface CostGetRecordInput {
   readonly tenantId: TenantId;
   readonly recordId: string;
+  /** Add the record's `rawUsage`: the vendor's own usage object. */
+  readonly includeRawUsage?: boolean;
 }
 
 // -------- aggregate --------
@@ -116,7 +136,9 @@ export interface CostGetRecordInput {
  * Group dimensions the binding may aggregate over. `day` / `month` are
  * time bucketing on `occurredAt` (UTC calendar day / month). Every call
  * is tenant-scoped, so `tenant` always resolves to the caller's tenant
- * id.
+ * id. `model` is the model actually called; `servedModel` the exact
+ * version the vendor reported. `orgId` is the org of the record's
+ * project (`null` for a project in no org).
  */
 export type CostGroupDimension =
   | 'agentId'
@@ -126,7 +148,13 @@ export type CostGroupDimension =
   | 'day'
   | 'month'
   | 'tenant'
-  | 'conversationId';
+  | 'conversationId'
+  | 'model'
+  | 'servedModel'
+  | 'projectId'
+  | 'orgId'
+  | 'rootRunId'
+  | 'flowId';
 
 export const COST_GROUP_DIMENSIONS: readonly CostGroupDimension[] = [
   'agentId',
@@ -137,6 +165,12 @@ export const COST_GROUP_DIMENSIONS: readonly CostGroupDimension[] = [
   'month',
   'tenant',
   'conversationId',
+  'model',
+  'servedModel',
+  'projectId',
+  'orgId',
+  'rootRunId',
+  'flowId',
 ];
 
 export interface CostAggregateInput {
@@ -174,12 +208,27 @@ export interface CostAggregateGroup {
   readonly key: Readonly<Record<string, string | null>>;
   readonly count: number;
   readonly totalUsd: number;
+  readonly tokens: CostTokenTotals;
+}
+
+/**
+ * Token sums. `prompt` and `completion` are the totals; `cacheRead` /
+ * `cacheWrite` are parts of `prompt`, `reasoning` of `completion`
+ * (`0` where providers didn't report them).
+ */
+export interface CostTokenTotals {
+  readonly prompt: number;
+  readonly completion: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+  readonly reasoning: number;
 }
 
 export interface CostAggregateResult {
   readonly groups: readonly CostAggregateGroup[];
   readonly totalUsd: number;
   readonly totalRecords: number;
+  readonly tokens: CostTokenTotals;
   readonly timeRange: {
     readonly from: Timestamp;
     readonly to: Timestamp;
@@ -210,4 +259,46 @@ export interface CostRecord {
   readonly occurredAt: Timestamp;
   readonly metrics?: Readonly<Record<string, unknown>>;
   readonly attributes?: Readonly<Record<string, unknown>>;
+  // A model call (`category` `llm.inference`):
+  /** The call's id; its provenance node carries it too. */
+  readonly callId?: string;
+  readonly projectId?: string;
+  /** The root of the record's run tree. */
+  readonly rootRunId?: string;
+  readonly parentRunId?: string;
+  readonly agentVersion?: string;
+  /** The flow of the run tree's root. */
+  readonly flowId?: string;
+  /** The step that made the call, and the turn's step number. */
+  readonly nodeId?: string;
+  readonly step?: number;
+  /** What the call was for, beyond the turn's own model step (`guardrail-judge:<id>`). */
+  readonly purpose?: string;
+  /** The model actually called. */
+  readonly model?: string;
+  /** The exact model version the vendor reported. */
+  readonly servedModel?: string;
+  /** The router picked a fallback provider. */
+  readonly fallback?: boolean;
+  /** `ok`: the provider answered. `failed`: the call threw. */
+  readonly status?: 'ok' | 'failed';
+  readonly usage?: {
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly cacheReadTokens?: number;
+    readonly cacheWriteTokens?: number;
+    readonly reasoningTokens?: number;
+  };
+  readonly durationMs?: number;
+  readonly finishReason?: string;
+  readonly providerRequestId?: string;
+  /** HTTP attempts, the client's retries included. */
+  readonly attempts?: number;
+  readonly error?: { readonly message: string };
+  /** The vendor's own usage object (only when asked for: `include=rawUsage`). */
+  readonly rawUsage?: {
+    readonly provider: string;
+    readonly model: string;
+    readonly usage: Readonly<Record<string, unknown>>;
+  };
 }

package/src/hitl-binding.ts

@@ -12,6 +12,7 @@ import type { ReviewerRole } from '@kindgi/authz';
 import type {
   ApprovalId,
   Cursor,
+  ListScope,
   ProjectId,
   ProvenanceId,
   Result,
@@ -57,6 +58,12 @@ export interface Approval {
   readonly updatedAt: Timestamp;
   readonly decidedAt?: Timestamp;
   readonly expiresAt?: Timestamp;
+  /**
+   * The reviewer's decision, once one is recorded. Absent while the
+   * approval is open, and when it ended without one (it expired, or a
+   * timeout escalated it).
+   */
+  readonly decision?: ReviewDecisionRecord;
 }
 
 export interface ReviewDecision {
@@ -76,6 +83,8 @@ export interface ReviewDecision {
 export interface ListApprovalsBindingInput {
   readonly tenantId: TenantId;
   readonly limit: number;
+  /** Only one project's approvals, or every project's in an org. Absent: the tenant's. */
+  readonly scope?: ListScope;
   readonly status?: ApprovalStatus;
   readonly requiredRole?: ReviewerRole;
   readonly since?: Timestamp;
@@ -110,12 +119,18 @@ export type SubmitReviewBindingResult =
     };
 
 /**
- * A single review-decision row hydrated for the audit-bundle route.
- * `null` = the approval terminated without a recorded decision (e.g.
- * status `expired`).
+ * An approval's recorded decision: on the approval it decided
+ * (`Approval.decision`), and for the audit-bundle route. `null` from
+ * `loadReviewDecision` = the approval terminated without a recorded
+ * decision (e.g. status `expired`).
  */
 export interface ReviewDecisionRecord {
   readonly decision: ReviewDecisionKind;
+  /**
+   * Who decided, as an actor: `user:<userId>`, the reviewer's user.
+   * Absent from a binding that doesn't record it (the Kindgi runtime does).
+   */
+  readonly decidedBy?: string;
   readonly reviewerId: ReviewerId;
   readonly reviewerRoleAtDecision: ReviewerRole;
   readonly decidedAt: Timestamp;
@@ -163,7 +178,8 @@ export interface HitlBinding {
   /**
    * Hydrate the recorded decision row for an approval — used by the
    * audit-bundle route. Returns `null` when the approval terminated
-   * without a recorded decision (status `expired`).
+   * without a recorded decision (status `expired`). `getApproval` and
+   * `listApprovals` return the same decision on each approval.
    */
   loadReviewDecision(
     tenantId: TenantId,

package/src/index.ts

@@ -391,6 +391,7 @@ export type {
   CostRecord,
   CostRecordFilter,
   CostRecordPage,
+  CostTokenTotals,
 } from './cost-binding.js';
 export type {
   ToolGetInput,
@@ -550,6 +551,8 @@ export type {
   ListProvenanceRecordsInput,
   ListProvenanceRecordsResult,
   ProvenanceBinding,
+  CallUsage,
+  CallUsageByCallId,
   ProvenanceBindingError,
   ProvenanceListCursor,
   ProvenanceRecordSummary,

package/src/middleware/auth.ts

@@ -37,8 +37,9 @@ export interface TokenResolution {
    * middleware surfaces it as `c.get('reviewerRole')` and approvals
    * routes gate visibility / decisions on the `standard < senior < admin`
    * hierarchy. Absent for tokens that were never provisioned with a
-   * reviewer role — such tokens can still hit `/v1/runs` etc., but any
-   * approvals route returns `403 permission-denied`.
+   * reviewer role: the approvals routes then take the role the reviewer
+   * roster gives the token's user (`ReviewerBinding.resolveReviewerRole`),
+   * and return `403 permission-denied` when it gives none.
    */
   readonly reviewerRole?: ReviewerRole;
   /**

package/src/middleware/idempotency.ts

@@ -63,7 +63,11 @@ const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
  *   byte-identical (status, content-type, body).
  * - Cached hit with different body hash → 409
  *   `idempotency-key-body-mismatch`.
- * - Cache miss → run the handler, then store the response.
+ * - Cache miss → run the handler, then store the response when the
+ *   request took effect (a status below 400). A refusal (4xx) changed
+ *   nothing, and a failure (5xx) may be transient: neither is stored, so
+ *   a retry with the same key after fixing the cause runs again instead
+ *   of replaying the old error.
  *
  * The middleware sits AFTER auth so `tenantId` is available; the
  * cache key is namespaced by tenant so callers can't collide across
@@ -122,6 +126,8 @@ export function idempotencyMiddleware(
     await next();
 
     const res = c.res;
+    // Only what took effect is replayed; see the doc above.
+    if (res.status >= 400) return;
     const savedBody = await res.clone().text();
     const contentType = res.headers.get('Content-Type') ?? 'application/octet-stream';
     await store.set(cacheKey, {