@kindgi/api 0.1.2 → 0.1.4-rc.0

package/dist/block-pins.d.ts

@@ -0,0 +1,22 @@
+import { type Agent } from '@kindgi/agents';
+import type { 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[];
+}
+/**
+ * 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 declare function resolveBlockPins(blocks: BlockRegistryBinding | undefined, tenantId: TenantId, agent: Agent): Promise<BlockPins>;
+//# sourceMappingURL=block-pins.d.ts.map

package/dist/block-pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-pins.d.ts","sourceRoot":"","sources":["../src/block-pins.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,KAAK,EAA+C,MAAM,gBAAgB,CAAC;AAEzF,OAAO,KAAK,EAAU,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;CAC3C;AAYD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,oBAAoB,GAAG,SAAS,EACxC,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,SAAS,CAAC,CAoCpB"}

package/dist/block-pins.js

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { MODEL_SETTINGS_SCHEMA, settingsSchemaIssues } from '@kindgi/agents';
+import { pickVersion } from '@kindgi/tools';
+/** 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, tenantId, agent) {
+    const prompts = {};
+    const settings = {};
+    const issues = [];
+    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) {
+    const refs = [];
+    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, block) {
+    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.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) {
+    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, tenantId, blockId) {
+    const versions = [];
+    let cursor;
+    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;
+}
+//# sourceMappingURL=block-pins.js.map

package/dist/block-pins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-pins.js","sourceRoot":"","sources":["../src/block-pins.ts"],"names":[],"mappings":"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"}

package/dist/cost-binding.d.ts

@@ -38,9 +38,12 @@ 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>;
 }
@@ -73,6 +76,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 {
     readonly runId?: string;
@@ -86,7 +91,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;
 }
 export interface CostRecordPage {
@@ -96,14 +114,18 @@ 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;
 }
 /**
  * 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' | 'runId' | 'category' | 'providerId' | 'day' | 'month' | 'tenant' | 'conversationId';
+export type CostGroupDimension = 'agentId' | 'runId' | 'category' | 'providerId' | 'day' | 'month' | 'tenant' | 'conversationId' | 'model' | 'servedModel' | 'projectId' | 'orgId' | 'rootRunId' | 'flowId';
 export declare const COST_GROUP_DIMENSIONS: readonly CostGroupDimension[];
 export interface CostAggregateInput {
     readonly tenantId: TenantId;
@@ -127,7 +149,18 @@ 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 declare const COST_AGGREGATE_DEFAULT_LIMIT = 1000;
+/** The largest `?limit=` the aggregate takes. */
+export declare const COST_AGGREGATE_MAX_LIMIT = 10000;
 /**
  * One row of the aggregate result. `key` maps every requested `groupBy`
  * dimension to its value for this group — `null` when the underlying
@@ -139,11 +172,30 @@ 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;
@@ -171,5 +223,48 @@ export interface CostRecord {
     readonly occurredAt: Timestamp;
     readonly metrics?: Readonly<Record<string, unknown>>;
     readonly attributes?: Readonly<Record<string, unknown>>;
+    /** 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>>;
+    };
 }
 //# sourceMappingURL=cost-binding.d.ts.map

package/dist/cost-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cost-binding.d.ts","sourceRoot":"","sources":["../src/cost-binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cost-binding.d.ts","sourceRoot":"","sources":["../src/cost-binding.ts"],"names":[],"mappings":"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"}

package/dist/cost-binding.js

@@ -9,5 +9,15 @@ export const COST_GROUP_DIMENSIONS = [
     'month',
     'tenant',
     'conversationId',
+    'model',
+    'servedModel',
+    'projectId',
+    'orgId',
+    'rootRunId',
+    'flowId',
 ];
+/** `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;
 //# sourceMappingURL=cost-binding.js.map

package/dist/cost-binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"cost-binding.js","sourceRoot":"","sources":["../src/cost-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiIjC,MAAM,CAAC,MAAM,qBAAqB,GAAkC;IAClE,SAAS;IACT,OAAO;IACP,UAAU;IACV,YAAY;IACZ,KAAK;IACL,OAAO;IACP,QAAQ;IACR,gBAAgB;CACjB,CAAC"}
+{"version":3,"file":"cost-binding.js","sourceRoot":"","sources":["../src/cost-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAgKjC,MAAM,CAAC,MAAM,qBAAqB,GAAkC;IAClE,SAAS;IACT,OAAO;IACP,UAAU;IACV,YAAY;IACZ,KAAK;IACL,OAAO;IACP,QAAQ;IACR,gBAAgB;IAChB,OAAO;IACP,aAAa;IACb,WAAW;IACX,OAAO;IACP,WAAW;IACX,QAAQ;CACT,CAAC;AAiCF,wDAAwD;AACxD,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AACjD,iDAAiD;AACjD,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC"}

package/dist/deploy-versions.d.ts

@@ -0,0 +1,58 @@
+import { type PinChange, type PinSet } from '@kindgi/agents';
+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>;
+}
+/**
+ * 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 declare function deployVersion<T extends PinnedDefinition>(input: DeployVersionInput<T>): Promise<DeployedVersionOutcome>;
+//# sourceMappingURL=deploy-versions.d.ts.map

package/dist/deploy-versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-versions.d.ts","sourceRoot":"","sources":["../src/deploy-versions.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAc,MAAM,gBAAgB,CAAC;AAGzE,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAEhF,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvE;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CAC5C,CAAC;AAEN,oGAAoG;AACpG,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;AAExD,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,gBAAgB;IAC5D,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3D;AAKD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,CAAC,SAAS,gBAAgB,EAC5D,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,sBAAsB,CAAC,CAsCjC"}

package/dist/deploy-versions.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { pinChanges } from '@kindgi/agents';
+import { canonicalize } from '@kindgi/schema';
+import { nextVersion } from '@kindgi/tools';
+/** 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(input) {
+    const { definition, pins, pinsDigest, existing } = input;
+    const authored = definition.version;
+    const key = definitionKey(definition);
+    const same = (v) => 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, key) {
+    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(input, reason, taken) {
+    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) {
+    const { version: _v, pins: _p, pinsDigest: _d, derivedFrom: _f, ...rest } = definition;
+    return canonicalize(rest);
+}
+//# sourceMappingURL=deploy-versions.js.map

package/dist/deploy-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-versions.js","sourceRoot":"","sources":["../src/deploy-versions.ts"],"names":[],"mappings":"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"}

package/dist/deployment-binding.d.ts

@@ -1,4 +1,5 @@
-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
  * row written by `POST /v1/deployments`. Mirrors the
@@ -118,11 +119,31 @@ export interface DeployedPrimitive {
     readonly id: string;
     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 {
     readonly tools: number;

package/dist/deployment-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployment-binding.d.ts","sourceRoot":"","sources":["../src/deployment-binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deployment-binding.d.ts","sourceRoot":"","sources":["../src/deployment-binding.ts"],"names":[],"mappings":"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"}

package/dist/derive-agent-version.d.ts

@@ -0,0 +1,69 @@
+import { type Agent, type AgentId } from '@kindgi/agents';
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { ProjectId, TenantId } from '@kindgi/types';
+import type { AgentRegistryBinding } from './agent-binding.js';
+import type { BlockRegistryBinding } from './block-binding.js';
+/** Which data-block pins to swap, by kind then block id → exact version. */
+export interface PinSwaps {
+    readonly prompts?: Readonly<Record<string, string>>;
+    readonly settings?: Readonly<Record<string, string>>;
+}
+export interface DeriveAgentVersionInput {
+    readonly agents: AgentRegistryBinding;
+    readonly blocks: BlockRegistryBinding | undefined;
+    readonly tenantId: TenantId;
+    readonly agentId: AgentId;
+    /** The version to derive from: it must be pinned. */
+    readonly from: string;
+    readonly swaps: PinSwaps;
+    /** A short label for the new version. */
+    readonly label?: string;
+    /** Who derived it (`user:<id>`). */
+    readonly by?: string;
+    /** The project, when the store doesn't record one on the version. */
+    readonly projectId?: ProjectId;
+    /** The authorization tuples for the new version, in the project it lands in. */
+    readonly tuplesFor: (projectId: ProjectId) => TupleEnqueueHook;
+}
+export interface SwapIssue {
+    readonly path: string;
+    readonly message: string;
+}
+export type DeriveAgentVersionOutcome = {
+    readonly kind: 'ok';
+    readonly agent: Agent;
+} | {
+    readonly kind: 'not-found';
+} | {
+    readonly kind: 'unpinned';
+} | {
+    readonly kind: 'invalid';
+    readonly issues: readonly SwapIssue[];
+} | {
+    readonly kind: 'no-project';
+} | {
+    readonly kind: 'project-not-found';
+    readonly projectId: ProjectId;
+};
+/**
+ * Derive a new agent version from a pinned one with some data-block
+ * pins swapped: an expert's edit (a new prompt or settings version)
+ * reaching an agent without a code change. The new version is the old
+ * one's bag with those pins swapped (`derivedFrom: { version, reason:
+ * 'edited', label, by }`), numbered the next free patch after the
+ * agent's highest version (versions never change).
+ *
+ * Only data-block pins swap: a swap must name a block the version
+ * already references (adding one is a code change), at a published,
+ * active version of the right kind (and, for the model-settings block,
+ * model settings). Tool pins come from code.
+ */
+export declare function deriveAgentVersion(input: DeriveAgentVersionInput): Promise<DeriveAgentVersionOutcome>;
+/**
+ * The first version after `after` that no version of the agent holds,
+ * active or unregistered (versions never change): what a refused
+ * publish of a taken number suggests, by the deploy rule's numbering.
+ * `undefined` when none is free within the tries.
+ */
+export declare function nextFreeAgentVersion(agents: AgentRegistryBinding, tenantId: TenantId, agentId: AgentId, after: string): Promise<string | undefined>;
+//# sourceMappingURL=derive-agent-version.d.ts.map