@kindgi/api 0.1.2 → 0.1.4-rc.0

package/src/block-pins.ts

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type Agent, MODEL_SETTINGS_SCHEMA, settingsSchemaIssues } from '@kindgi/agents';
+import { pickVersion } from '@kindgi/tools';
+import type { Cursor, TenantId } from '@kindgi/types';
+
+import type { UnpinnableRef } from './agent-pins.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+
+/** The data-block versions an agent version pins, and the references that matched none. */
+export interface BlockPins {
+  readonly prompts: Readonly<Record<string, string>>;
+  readonly settings: Readonly<Record<string, string>>;
+  readonly issues: readonly UnpinnableRef[];
+}
+
+interface Ref {
+  readonly path: string;
+  readonly id: string;
+  readonly range: string;
+  readonly role: 'prompt' | 'settings' | 'model-settings';
+}
+
+/** Page size for reading a block's versions. */
+const VERSIONS_PAGE = 200;
+
+/**
+ * Pin the data blocks an agent references (its prompt block, settings
+ * blocks and model-settings block) when a version of it is published:
+ * each range resolves by `pickVersion` over the block's active versions,
+ * as a turn of an unpinned agent would. A reference that matches no
+ * published version, names a block of the other kind, or names model
+ * settings that aren't (`MODEL_SETTINGS_SCHEMA`) is an issue: the
+ * caller refuses the publish. So is any reference on a runtime with no
+ * block registry.
+ */
+export async function resolveBlockPins(
+  blocks: BlockRegistryBinding | undefined,
+  tenantId: TenantId,
+  agent: Agent,
+): Promise<BlockPins> {
+  const prompts: Record<string, string> = {};
+  const settings: Record<string, string> = {};
+  const issues: UnpinnableRef[] = [];
+  for (const ref of blockRefs(agent)) {
+    if (blocks === undefined) {
+      issues.push({
+        path: ref.path,
+        message: `${describe(ref)}: this runtime serves no data blocks`,
+      });
+      continue;
+    }
+    const available = await activeBlockVersions(blocks, tenantId, ref.id);
+    const pick = pickVersion(available, ref.range);
+    if (pick.kind !== 'ok') {
+      issues.push({
+        path: ref.path,
+        message:
+          available.length === 0
+            ? `${describe(ref)} has no published version; publish the block first`
+            : `${describe(ref)} has no published version in "${ref.range}" (published: ${available.join(', ')})`,
+      });
+      continue;
+    }
+    const block = await blocks.getVersion({ tenantId, blockId: ref.id, version: pick.version });
+    const problem =
+      block === null
+        ? `${describe(ref)} version ${pick.version} can't be read`
+        : misfit(ref, block);
+    if (problem !== undefined) {
+      issues.push({ path: ref.path, message: problem });
+      continue;
+    }
+    (ref.role === 'prompt' ? prompts : settings)[ref.id] = pick.version;
+  }
+  return { prompts, settings, issues };
+}
+
+function blockRefs(agent: Agent): Ref[] {
+  const refs: Ref[] = [];
+  if (typeof agent.instructions === 'object') {
+    refs.push({
+      path: '/instructions/version',
+      id: agent.instructions.prompt,
+      range: agent.instructions.version,
+      role: 'prompt',
+    });
+  }
+  for (const [i, s] of (agent.settings ?? []).entries()) {
+    refs.push({ path: `/settings/${i}/version`, id: s.id, range: s.version, role: 'settings' });
+  }
+  if (agent.modelSettings !== undefined) {
+    refs.push({
+      path: '/modelSettings/version',
+      id: agent.modelSettings.id,
+      range: agent.modelSettings.version,
+      role: 'model-settings',
+    });
+  }
+  return refs;
+}
+
+/** Why a block version can't serve its reference; undefined when it can. */
+function misfit(
+  ref: Ref,
+  block: { readonly kind: string; readonly version: string; readonly content: unknown },
+): string | undefined {
+  const wanted = ref.role === 'prompt' ? 'prompt' : 'settings';
+  if (block.kind !== wanted) return `${describe(ref)} is a ${block.kind} block`;
+  if (ref.role !== 'model-settings') return undefined;
+  const values = (block.content as { readonly values?: unknown }).values;
+  const issues = settingsSchemaIssues(values, MODEL_SETTINGS_SCHEMA);
+  return issues.length === 0
+    ? undefined
+    : `${describe(ref)} version ${block.version} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`;
+}
+
+function describe(ref: Ref): string {
+  const what =
+    ref.role === 'prompt'
+      ? 'prompt'
+      : ref.role === 'model-settings'
+        ? 'model-settings'
+        : 'settings';
+  return `${what} block "${ref.id}"`;
+}
+
+/** Every active version of a block, newest published first. */
+async function activeBlockVersions(
+  blocks: BlockRegistryBinding,
+  tenantId: TenantId,
+  blockId: string,
+): Promise<readonly string[]> {
+  const versions: string[] = [];
+  let cursor: Cursor | undefined;
+  do {
+    const page = await blocks.listVersions({
+      tenantId,
+      blockId,
+      limit: VERSIONS_PAGE,
+      ...(cursor !== undefined && { cursor }),
+    });
+    versions.push(...page.data.map((b) => b.version));
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return versions;
+}

package/src/cost-binding.ts

@@ -42,13 +42,19 @@ 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. With `limit`, a binding may return only the
+   * `limit` most expensive groups (`totalUsd` descending, ties by key)
+   * and the count before the cap in `totalGroups`; one that returns
+   * every group is capped by the route.
    */
   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 +86,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 +102,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 +129,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 +139,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 +151,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 +168,12 @@ export const COST_GROUP_DIMENSIONS: readonly CostGroupDimension[] = [
   'month',
   'tenant',
   'conversationId',
+  'model',
+  'servedModel',
+  'projectId',
+  'orgId',
+  'rootRunId',
+  'flowId',
 ];
 
 export interface CostAggregateInput {
@@ -161,8 +198,20 @@ export interface CostAggregateInput {
    * shape uniformity.
    */
   readonly inherit?: boolean;
+  /**
+   * The most groups the caller wants (`?limit=`, 1..`COST_AGGREGATE_MAX_LIMIT`,
+   * default `COST_AGGREGATE_DEFAULT_LIMIT`): the most expensive ones. A
+   * binding may cap in its query; the window's totals stay over every
+   * record either way.
+   */
+  readonly limit?: number;
 }
 
+/** `GET /v1/cost/aggregate`'s `?limit=` when absent. */
+export const COST_AGGREGATE_DEFAULT_LIMIT = 1000;
+/** The largest `?limit=` the aggregate takes. */
+export const COST_AGGREGATE_MAX_LIMIT = 10_000;
+
 /**
  * One row of the aggregate result. `key` maps every requested `groupBy`
  * dimension to its value for this group — `null` when the underlying
@@ -174,12 +223,32 @@ 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[];
+  /**
+   * How many groups there were before a cap: set by a binding that caps
+   * (`CostAggregateInput.limit`). Absent: `groups` is every group.
+   */
+  readonly totalGroups?: number;
   readonly totalUsd: number;
   readonly totalRecords: number;
+  readonly tokens: CostTokenTotals;
   readonly timeRange: {
     readonly from: Timestamp;
     readonly to: Timestamp;
@@ -210,4 +279,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/deploy-versions.ts

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type PinChange, type PinSet, pinChanges } from '@kindgi/agents';
+import { canonicalize } from '@kindgi/schema';
+import { nextVersion } from '@kindgi/tools';
+import type { VersionDerivation, VersionDerivationReason } from '@kindgi/types';
+
+/** A version a deploy registers with pins: an agent's or a flow's. */
+export interface PinnedDefinition {
+  readonly version: string;
+  readonly pins?: PinSet;
+  readonly pinsDigest?: string;
+  readonly derivedFrom?: VersionDerivation;
+}
+
+/**
+ * How a deploy registered one of its agents or flows, given its pins.
+ * A deploy never keeps a version's old pins and never refuses a
+ * routine deploy:
+ *
+ * - `registered`: the definition's version was free, and is now
+ *   registered with these pins;
+ * - `unchanged`: it's registered with the same definition and pins (or
+ *   its project is gone, which a deploy has always left as it is);
+ * - `reused`: an earlier deploy already registered this definition and
+ *   these pins under another number (`version`), so a redeploy changes
+ *   nothing;
+ * - `renumbered`: the definition's version is registered with other
+ *   pins or other content, and versions never change, so this deploy
+ *   registered the next free version in its line (`nextVersion`).
+ */
+export type DeployedVersionOutcome =
+  | { readonly kind: 'registered' | 'unchanged'; readonly version: string }
+  | {
+      readonly kind: 'reused' | 'renumbered';
+      readonly version: string;
+      readonly reason: VersionDerivationReason;
+      readonly pinChanges?: readonly PinChange[];
+    };
+
+/** What registering one version did: stored it, found the number taken, or left it (no project). */
+export type PublishOutcome = 'ok' | 'taken' | 'skipped';
+
+export interface DeployVersionInput<T extends PinnedDefinition> {
+  /** Names the definition in an error, e.g. `agent "acme.matcher"`. */
+  readonly label: string;
+  /** The definition as the pack has it, with no pins. */
+  readonly definition: T;
+  readonly pins: PinSet;
+  readonly pinsDigest: string;
+  /** Every active version registered under the definition's id. */
+  readonly existing: readonly T[];
+  /** Register one version. */
+  readonly publish: (version: T) => Promise<PublishOutcome>;
+}
+
+/** How many versions after the definition's a deploy tries before it gives up. */
+const MAX_RENUMBER = 100;
+
+/**
+ * Register a deployed agent or flow with its pins (see
+ * `DeployedVersionOutcome`): one rule for both, so they can't drift
+ * apart. Each definition is registered at most once per deploy, and a
+ * new version derives from the definition's version only, never from a
+ * version the same deploy created, so a change cascading from a tool
+ * through an agent into a flow ends within the one deploy.
+ */
+export async function deployVersion<T extends PinnedDefinition>(
+  input: DeployVersionInput<T>,
+): Promise<DeployedVersionOutcome> {
+  const { definition, pins, pinsDigest, existing } = input;
+  const authored = definition.version;
+  const key = definitionKey(definition);
+  const same = (v: T) => definitionKey(v) === key && v.pinsDigest === pinsDigest;
+
+  const atAuthored = existing.find((v) => v.version === authored);
+  if (atAuthored !== undefined && same(atAuthored)) return { kind: 'unchanged', version: authored };
+  if (atAuthored === undefined) {
+    const outcome = await input.publish({ ...definition, pins, pinsDigest });
+    if (outcome !== 'taken') {
+      return { kind: outcome === 'ok' ? 'registered' : 'unchanged', version: authored };
+    }
+    // Taken with no active version: an unregistered version holds the
+    // number. Register the next one.
+  }
+
+  const reason = derivationReason(atAuthored, key);
+  const changes =
+    reason === 'pins-changed' ? { pinChanges: pinChanges(atAuthored?.pins, pins) } : {};
+  const earlier = existing.find(same);
+  if (earlier !== undefined) {
+    return {
+      kind: 'reused',
+      version: earlier.version,
+      // An expert's edit reused by a deploy reports the deploy's own reason.
+      reason:
+        earlier.derivedFrom !== undefined && earlier.derivedFrom.reason !== 'edited'
+          ? earlier.derivedFrom.reason
+          : reason,
+      ...changes,
+    };
+  }
+  const taken = new Set(existing.map((v) => v.version));
+  const version = await registerNextFree(input, reason, taken);
+  return version === undefined
+    ? { kind: 'unchanged', version: authored }
+    : { kind: 'renumbered', version, reason, ...changes };
+}
+
+/** Why the definition's version can't be registered as it is. */
+function derivationReason(
+  atAuthored: PinnedDefinition | undefined,
+  key: string,
+): VersionDerivationReason {
+  if (atAuthored === undefined || definitionKey(atAuthored) !== key) return 'version-taken';
+  return atAuthored.pins === undefined ? 'unpinned' : 'pins-changed';
+}
+
+/**
+ * Register the definition with its pins under the first free version
+ * after its own (`nextVersion`), recording where it came from.
+ * `undefined` when it was left as it is (its project is gone).
+ */
+async function registerNextFree<T extends PinnedDefinition>(
+  input: DeployVersionInput<T>,
+  reason: VersionDerivationReason,
+  taken: ReadonlySet<string>,
+): Promise<string | undefined> {
+  const { definition, pins, pinsDigest } = input;
+  const authored = definition.version;
+  let candidate = nextVersion(authored);
+  for (let tries = 0; candidate !== undefined && tries < MAX_RENUMBER; tries++) {
+    if (!taken.has(candidate)) {
+      const outcome = await input.publish({
+        ...definition,
+        version: candidate,
+        pins,
+        pinsDigest,
+        derivedFrom: { version: authored, reason },
+      });
+      if (outcome === 'ok') return candidate;
+      if (outcome === 'skipped') return undefined;
+      // Taken: an unregistered version holds this one too.
+    }
+    candidate = nextVersion(candidate);
+  }
+  throw new Error(
+    `${input.label}: no free version after ${authored} to register its new pins under`,
+  );
+}
+
+/** A definition: everything but its version and what the runtime sets. */
+function definitionKey(definition: PinnedDefinition): string {
+  const { version: _v, pins: _p, pinsDigest: _d, derivedFrom: _f, ...rest } = definition;
+  return canonicalize(rest);
+}

package/src/deployment-binding.ts

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
-import type { Cursor, SigningKeyId, TenantId } from '@kindgi/types';
+import type { PinChange } from '@kindgi/agents';
+import type { Cursor, SigningKeyId, TenantId, VersionDerivationReason } from '@kindgi/types';
 
 /**
  * Caller-plugged surface for the deployment ledger — the audit anchor
@@ -127,11 +128,34 @@ export interface DeployedPrimitive {
   readonly version?: string;
 }
 
+/**
+ * An agent or flow a deployment shipped, under the version it's
+ * registered as. A deploy registers one under another version than its
+ * definition's when that version is registered already with other pins
+ * or content (versions never change); then `authoredVersion` is the
+ * definition's and `reason` says why.
+ */
+export interface DeployedVersion extends DeployedPrimitive {
+  /** The version the agent's definition names, when it differs from `version`. */
+  readonly authoredVersion?: string;
+  readonly reason?: VersionDerivationReason;
+  /** `true`: this deploy registered `version`; `false`: an earlier deploy did. */
+  readonly newVersion?: boolean;
+  /** For `pins-changed`: the pins that differ from `authoredVersion`'s. */
+  readonly pinChanges?: readonly PinChange[];
+}
+
+/** An agent a deployment shipped (`DeployedVersion`). */
+export type DeployedAgent = DeployedVersion;
+
+/** A flow a deployment shipped (`DeployedVersion`). */
+export type DeployedFlow = DeployedVersion;
+
 export interface DeploymentContents {
   readonly tools: readonly DeployedPrimitive[];
   readonly guardrails: readonly DeployedPrimitive[];
-  readonly agents: readonly DeployedPrimitive[];
-  readonly flows: readonly DeployedPrimitive[];
+  readonly agents: readonly DeployedAgent[];
+  readonly flows: readonly DeployedFlow[];
 }
 
 export interface DeploymentPrimitiveCounts {