@kindgi/api 0.1.3 → 0.1.4-rc.0

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

@@ -40,7 +40,10 @@ export interface CostBinding {
      * Multi-dimensional aggregate rollup. `groupBy` may combine any
      * 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.
+     * 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>;
 }
@@ -146,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
@@ -174,6 +188,11 @@ export interface CostTokenTotals {
 }
 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;

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

@@ -16,4 +16,8 @@ export const COST_GROUP_DIMENSIONS = [
     '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;AA6JjC,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"}
+{"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

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

@@ -0,0 +1 @@
+{"version":3,"file":"derive-agent-version.d.ts","sourceRoot":"","sources":["../src/derive-agent-version.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,KAAK,EACV,KAAK,OAAO,EAKb,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAU,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,KAAK,EAAE,oBAAoB,EAAsB,MAAM,oBAAoB,CAAC;AAEnF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,4EAA4E;AAC5E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,yCAAyC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,gBAAgB,CAAC;CAChE;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AAK1E;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,yBAAyB,CAAC,CAgCpC;AAgFD;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,oBAAoB,EAC5B,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}

package/dist/derive-agent-version.js

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { MODEL_SETTINGS_SCHEMA, pinsDigest, settingsSchemaIssues, } from '@kindgi/agents';
+import { latestVersion, nextVersion } from '@kindgi/tools';
+import { activeAgentVersions } from './agent-pins.js';
+/** How many numbers after the highest a derive tries before it gives up. */
+const MAX_TRIES = 100;
+/**
+ * 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 async function deriveAgentVersion(input) {
+    const { agents, tenantId, agentId } = input;
+    const from = await agents.getVersion({ tenantId, agentId, version: input.from });
+    if (from === null)
+        return { kind: 'not-found' };
+    if (from.pins === undefined)
+        return { kind: 'unpinned' };
+    const issues = await swapIssues(input, from, from.pins);
+    if (issues.length > 0)
+        return { kind: 'invalid', issues };
+    const pins = {
+        tools: from.pins.tools,
+        prompts: { ...from.pins.prompts, ...(input.swaps.prompts ?? {}) },
+        settings: { ...from.pins.settings, ...(input.swaps.settings ?? {}) },
+    };
+    const digest = pinsDigest(pins);
+    if (digest === from.pinsDigest) {
+        return { kind: 'invalid', issues: [{ path: '/pins', message: 'no pin changes' }] };
+    }
+    const projectId = from.projectId ?? input.projectId;
+    if (projectId === undefined)
+        return { kind: 'no-project' };
+    const { unregisteredAt: _u, projectId: _p, derivedFrom: _d, ...definition } = from;
+    return publishNextFree(input, projectId, {
+        ...definition,
+        pins,
+        pinsDigest: digest,
+        derivedFrom: {
+            version: from.version,
+            reason: 'edited',
+            ...(input.label !== undefined && { label: input.label }),
+            ...(input.by !== undefined && { by: input.by }),
+        },
+    });
+}
+/** Publish the derived version under the first free patch after the agent's highest. */
+async function publishNextFree(input, projectId, derived) {
+    const { agents, tenantId, agentId } = input;
+    const active = await activeAgentVersions(agents, tenantId, agentId);
+    const highest = latestVersion(active.map((a) => a.version)) ??
+        derived.version;
+    let candidate = nextVersion(highest);
+    for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+        const agent = { ...derived, version: candidate };
+        const outcome = await agents.publish({
+            tenantId,
+            projectId,
+            agent,
+            enqueueTuples: input.tuplesFor(projectId),
+        });
+        if (outcome.kind === 'ok')
+            return { kind: 'ok', agent };
+        if (outcome.kind === 'project-not-found')
+            return { kind: 'project-not-found', projectId };
+        candidate = nextVersion(candidate);
+    }
+    throw new Error(`agent "${agentId}": no free version after ${highest}`);
+}
+/** What's wrong with the swaps, against the version's references and the block store. */
+async function swapIssues(input, from, pins) {
+    const issues = [];
+    const swaps = [
+        ...Object.entries(input.swaps.prompts ?? {}).map(([id, v]) => ['prompts', id, v]),
+        ...Object.entries(input.swaps.settings ?? {}).map(([id, v]) => ['settings', id, v]),
+    ];
+    if (swaps.length === 0)
+        return [{ path: '/pins', message: 'name at least one prompt or settings pin to swap' }];
+    for (const [kind, id, version] of swaps) {
+        const path = `/pins/${kind}/${id}`;
+        if (pins[kind][id] === undefined) {
+            issues.push({
+                path,
+                message: `agent version ${from.version} doesn't reference ${kind === 'prompts' ? 'prompt' : 'settings'} block "${id}"; adding a block is a code change`,
+            });
+            continue;
+        }
+        const problem = await blockProblem(input, from, kind, id, version);
+        if (problem !== undefined)
+            issues.push({ path, message: problem });
+    }
+    return issues;
+}
+async function blockProblem(input, from, kind, id, version) {
+    if (input.blocks === undefined)
+        return 'this runtime serves no data blocks';
+    const block = await input.blocks.getVersion({ tenantId: input.tenantId, blockId: id, version });
+    const what = `block "${id}" version ${version}`;
+    if (block === null)
+        return `${what} isn't published`;
+    if (block.unregisteredAt !== undefined)
+        return `${what} is unregistered`;
+    const wanted = kind === 'prompts' ? 'prompt' : 'settings';
+    if (block.kind !== wanted)
+        return `${what} is a ${block.kind} block, not ${wanted}`;
+    if (block.kind === 'settings' && from.modelSettings?.id === id) {
+        const issues = settingsSchemaIssues(block.content.values, MODEL_SETTINGS_SCHEMA);
+        if (issues.length > 0) {
+            return `${what} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 async function nextFreeAgentVersion(agents, tenantId, agentId, after) {
+    let candidate = nextVersion(after);
+    for (let tries = 0; candidate !== undefined && tries < MAX_TRIES; tries++) {
+        const held = await agents.getVersion({ tenantId, agentId, version: candidate });
+        if (held === null)
+            return candidate;
+        candidate = nextVersion(candidate);
+    }
+    return undefined;
+}
+//# sourceMappingURL=derive-agent-version.js.map